tapline-host 1.4.0 → 1.6.0

package/dist/runtime.js

@@ -0,0 +1,255 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { configDir, hostUrl, markPaired, pairedBefore, reachableHost, resolveConfig, screenshotMode, viewerMode, } from "./config.js";
+import { loadAccounts } from "./accounts.js";
+import { Confirmations } from "./confirm.js";
+import { ControlQueue } from "./control.js";
+import { isToolName, callTool } from "./dispatch.js";
+import { realRunner } from "./journeyexport.js";
+import { MapRegistry } from "./places.js";
+import { DEFAULT_POLICY, NO_POLICY, loadPolicy } from "./policy.js";
+import { TaplineHost } from "./server.js";
+import { restoreAnimations } from "./animations.js";
+import { TaplineTools } from "./tools.js";
+import { NO_UX_RULES, loadUxRules } from "./uxcheck.js";
+import { VIEWER_ACCEPTS, ViewerHub, viewerStatusForHost } from "./viewer.js";
+import { VIEWER_HTML } from "./viewer-page.js";
+/** How long a client of the thin call may stay silent before its tools (its report, its journey) are dropped. */
+export const CLIENT_IDLE_MS = 30 * 60 * 1000;
+/** What a queued call answers when its client left before it started (nobody reads it). */
+const CANCELLED = { content: [{ type: "text", text: "Error cancelled: the client left before this call started, so it never ran." }], isError: true };
+/** The client id of a thin call that names none. */
+export const ANONYMOUS_CLIENT = "anonymous";
+function stderrLog(message) {
+    process.stderr.write(`[tapline] ${message}\n`);
+}
+/** Opens a link in the default browser of this computer; false when that couldn't start. */
+function openInBrowser(link) {
+    try {
+        const [command, args] = process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", link.replace(/&/g, "^&")]]
+            : process.platform === "darwin"
+                ? ["open", [link]]
+                : ["xdg-open", [link]];
+        const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The wiring an MCP server and a standalone host share: the host, the person's confirmations, the live viewer on the
+ * host's port, the policy, the log folders and the 3 s control queue. Rejects with a plain message when an option is
+ * wrong or no port is free (the message's lines are for the log).
+ */
+export async function createRuntime(options = {}) {
+    const log = options.log ?? stderrLog;
+    const clock = options.clock ?? Date.now;
+    let screenshots;
+    let viewer;
+    let policy;
+    let uxRules = NO_UX_RULES;
+    // The safety policy (AGENT-TOOLS 1.8 §11): built in, from --policy FILE, or none with --no-policy. The user's UX
+    // house rules (1.12 §17.3): --ux-rules FILE; a bad file stops the host with a plain message.
+    screenshots = screenshotMode(options.screenshots, options.env);
+    viewer = viewerMode(options.viewer, options.env);
+    policy = options.noPolicy === true ? NO_POLICY : options.policy !== undefined ? loadPolicy(options.policy) : DEFAULT_POLICY;
+    if (options.uxRules !== undefined)
+        uxRules = loadUxRules(options.uxRules);
+    // The test accounts (AGENT-TOOLS 1.13 §18.6). A refused file still starts the server, with no accounts and the reason.
+    const accounts = options.accounts !== undefined ? await loadAccounts(options.accounts, options.gitProbe) : undefined;
+    if (accounts !== undefined && accounts.store === null)
+        log(accounts.blocked);
+    const config = await resolveConfig(options);
+    const clients = new Map();
+    const host = new TaplineHost({
+        ...(accounts?.store != null ? { redact: accounts.store.redact } : {}),
+        token: config.token,
+        port: config.port,
+        portFallback: config.portFallback,
+        hosts: config.hosts,
+        ...(options.api === true
+            ? {
+                api: async (tool, args, clientId, signal) => isToolName(tool) ? thinCall(tool, args, clientId, signal) : undefined,
+            }
+            : {}),
+    });
+    host.on("connect", () => markPaired(options.env));
+    host.on("connect", (s) => log(`app connected: ${s.app.name} (${s.id}) on ${s.device.name ?? s.device.platform}`));
+    host.on("disconnect", (s, reason) => log(`app disconnected: ${s.app.name} (${s.id}): ${reason}`));
+    host.on("warning", (message) => log(message));
+    for (const note of config.notes)
+        log(note);
+    let advertised = config.advertisedHost;
+    let listening;
+    try {
+        listening = await host.listen();
+        for (const { host: h, port } of listening.listening)
+            log(`listening on ws://${h}:${port}/`);
+        for (const { host: h, error } of listening.failed)
+            log(`could not listen on ${h}: ${error}`);
+        advertised = reachableHost(config, listening.listening);
+    }
+    catch (error) {
+        throw new Error(`failed to start: ${error instanceof Error ? error.message : String(error)}\n` +
+            "Every port tried is taken (other Tapline hosts?). Pick a free one with --port or TAPLINE_PORT.");
+    }
+    const port = host.boundPort() ?? config.port;
+    const url = hostUrl({ advertisedHost: advertised }, port);
+    log(`apps connect to ${url}; use the pair tool to connect a phone`);
+    // The live viewer rides on this host's port: local by default, the tailnet with --viewer remote.
+    const viewerToken = randomBytes(24).toString("base64url");
+    const remoteViewer = viewer === "remote" && config.tailscaleIp !== null;
+    const viewerHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`, ...(remoteViewer ? [`${config.tailscaleIp}:${port}`] : [])];
+    const viewerLinks = [
+        `http://127.0.0.1:${port}/viewer?token=${viewerToken}`,
+        ...(remoteViewer ? [`http://${config.tailscaleIp}:${port}/viewer?token=${viewerToken} (from your own devices on Tailscale)`] : []),
+    ];
+    const control = new ControlQueue();
+    const confirmations = new Confirmations();
+    let hub;
+    const openBrowser = options.openBrowser ?? openInBrowser;
+    // One map per app for every client of this host: places, roads and links grow as agents drive (§18.9).
+    const maps = new MapRegistry({ mapsDir: options.maps ?? join(configDir(options.env), "maps") });
+    const toolsOptions = {
+        maps,
+        ...(options.brief === true ? { brief: true } : {}),
+        policy,
+        uxRules,
+        ...(accounts !== undefined ? { accounts } : {}),
+        confirmations,
+        canConfirm: viewer !== "off",
+        connect: { url, name: config.name },
+        pairedBefore: () => pairedBefore(options.env),
+        pairImagePath: join(configDir(options.env), `pair-${port}.png`),
+        offerDir: join(configDir(options.env), "offers"),
+        screenshots,
+        screenshotDir: join(configDir(options.env), "shots"),
+        scriptsDir: join(configDir(options.env), "scripts"),
+        baselinesDir: join(configDir(options.env), "baselines"),
+        // Journey reports (AGENT-TOOLS 1.12 §17.5) and the user's own gh and git for `export`
+        journeysDir: join(configDir(options.env), "journeys"),
+        exportRunner: realRunner,
+        // The action log (AGENT-TOOLS 1.8 §12), unless --no-log
+        ...(options.noLog === true ? {} : { logDir: join(configDir(options.env), "log") }),
+        ...(viewer === "off"
+            ? {}
+            : {
+                control,
+                onAction: (action) => hub?.pushAction(action),
+                viewerLinks: () => viewerLinks,
+                openViewer: (link) => openBrowser(link),
+                viewerLinkToAgent: options.viewerLink === true || process.env["TAPLINE_VIEWER_LINK"] === "1",
+                viewerFeed: () => hub?.feed() ?? { on: false, quality: "balanced" },
+            }),
+    };
+    // The connection's own tools: what an MCP server uses, and what the live viewer's person input goes through.
+    const primary = new TaplineTools(host, toolsOptions);
+    /** Every call through `/api` is a thin call: the log says so, and the report flags a run of them (§16.1). */
+    function thinCall(tool, args, clientId, signal) {
+        // A thin call never uses the MCP server's tools: those hold its dialog and the OKs given for its calls.
+        const tools = toolsFor(clientId ?? ANONYMOUS_CLIENT);
+        // Calls that share a tools object run one after another: they share its per-call state (a run's account).
+        const before = lanes.get(tools) ?? Promise.resolve();
+        // A call whose client left while it waited in the line is dropped before it starts; a running one is told to stop waiting.
+        const answer = before.then(() => (signal.aborted ? CANCELLED : tools.withCall(signal, () => tools.asThinCall(() => callTool(tools, tool, args)))));
+        lanes.set(tools, answer.then(() => undefined, () => undefined));
+        return answer;
+    }
+    const lanes = new WeakMap();
+    function toolsFor(clientId) {
+        if (clientId === undefined)
+            return primary;
+        const now = clock();
+        for (const [id, entry] of clients) {
+            if (now - entry.lastUsed <= CLIENT_IDLE_MS)
+                continue;
+            entry.tools.dispose();
+            clients.delete(id);
+        }
+        const known = clients.get(clientId);
+        if (known !== undefined) {
+            known.lastUsed = now;
+            return known.tools;
+        }
+        // The call log names the agent by this id.
+        const tools = new TaplineTools(host, { ...toolsOptions, clientId: () => clientId, confirmScope: "api" });
+        clients.set(clientId, { tools, lastUsed: now });
+        return tools;
+    }
+    if (viewer !== "off") {
+        const live = new ViewerHub({
+            token: viewerToken,
+            html: VIEWER_HTML,
+            allowedHosts: () => viewerHosts,
+            allowRemote: remoteViewer,
+            accepts: [...VIEWER_ACCEPTS],
+            control,
+            setFeed: (on, quality) => {
+                void primary.setFeed(on, quality).then((outcome) => {
+                    // Without an app, or in the background, the status already says so (appStatus below).
+                    if (!outcome.ok && on && host.current() !== undefined && outcome.code !== "in_background") {
+                        live.setStatus({ detail: `The app can't stream its screen: ${outcome.message ?? ""}` });
+                    }
+                });
+            },
+            readOverlay: () => primary.readOverlay(),
+            runInput: async (input) => {
+                const outcome = await primary.personInput(input);
+                // The request reached the app: every client's refs from before it are stale.
+                if (outcome.action !== undefined)
+                    for (const entry of clients.values())
+                        entry.tools.noteViewerInput();
+                return outcome;
+            },
+            confirmations,
+        });
+        hub = live;
+        host.setHttpExtension(live);
+        host.on("frame", (session, frame) => {
+            if (host.current()?.id === session.id)
+                live.pushFrame(frame);
+        });
+        const appStatus = () => live.setStatus(viewerStatusForHost(host));
+        host.on("connect", appStatus);
+        host.on("disconnect", appStatus);
+        host.on("appState", appStatus);
+        host.on("notAnswering", appStatus);
+        host.on("answering", appStatus);
+        appStatus();
+        log(`live viewer: ${remoteViewer ? "this computer and your Tailscale devices" : "this computer only"} (the viewer tool opens it in a browser here)`);
+        // The link for the user's own devices: here in the log, never in an answer to the agent.
+        if (remoteViewer)
+            for (const link of viewerLinks.slice(1))
+                log(`live viewer for your devices: ${link}`);
+    }
+    if (screenshots === "file")
+        log(`screenshots are saved in ${join(configDir(options.env), "shots")} (newest 50 kept)`);
+    return {
+        host,
+        confirmations,
+        config,
+        listening,
+        url,
+        port,
+        viewerLinks,
+        remoteViewer,
+        toolsFor,
+        // The maps are written at most once a second while driving, and in full here.
+        close: async () => {
+            await maps.flushAll().catch(() => undefined);
+            // The phone is never left fast-forwarded with nobody watching (PLAN-1.6 F4, E8).
+            await restoreAnimations(host).catch(() => undefined);
+            for (const entry of clients.values())
+                entry.tools.dispose();
+            clients.clear();
+            primary.dispose();
+            await host.close();
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/script.d.ts

@@ -1,14 +1,8 @@
 import { z } from "zod";
 import { type Step } from "./run.js";
-/**
- * AGENT-TOOLS 1.8 §9.4: the shared script file, a saved batch both tools write and replay.
- *   {"format": "agent-tools-script", "version": 1, "name", "app", "fresh", "steps": [ {tool, …, expect?} ]}
- * Tapline records the app's methods as they run (press, type, …); this turns them into tool steps, and
- * still reads Tapline's own scripts from before 1.1.
- */
-export declare const sharedScriptSchema: z.ZodObject<{
-    format: z.ZodLiteral<"agent-tools-script">;
+export declare const sharedScriptV1Schema: z.ZodObject<{
     version: z.ZodLiteral<1>;
+    format: z.ZodLiteral<"agent-tools-script">;
     name: z.ZodString;
     app: z.ZodOptional<z.ZodString>;
     fresh: z.ZodOptional<z.ZodBoolean>;
@@ -26,9 +20,113 @@ export declare const sharedScriptSchema: z.ZodObject<{
             timeout: z.ZodOptional<z.ZodNumber>;
             under: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
         }, z.core.$strip>>;
+        if: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        optional: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
-export type SharedScript = z.infer<typeof sharedScriptSchema>;
+/** A route's variable: a name, or `account` (the test account a route types, §18.6). Never a value. */
+export declare const variableNameSchema: z.ZodString;
+/** AGENT-TOOLS 1.13 §18.5: version 2 adds where a route starts and ends, and the variables its steps use. */
+export declare const sharedScriptV2Schema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    start: z.ZodOptional<z.ZodString>;
+    end: z.ZodOptional<z.ZodString>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    format: z.ZodLiteral<"agent-tools-script">;
+    name: z.ZodString;
+    app: z.ZodOptional<z.ZodString>;
+    fresh: z.ZodOptional<z.ZodBoolean>;
+    steps: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+            value: z.ZodOptional<z.ZodString>;
+            matches: z.ZodOptional<z.ZodString>;
+            threshold: z.ZodOptional<z.ZodNumber>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            under: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>;
+        if: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export declare const sharedScriptSchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    format: z.ZodLiteral<"agent-tools-script">;
+    name: z.ZodString;
+    app: z.ZodOptional<z.ZodString>;
+    fresh: z.ZodOptional<z.ZodBoolean>;
+    steps: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+            value: z.ZodOptional<z.ZodString>;
+            matches: z.ZodOptional<z.ZodString>;
+            threshold: z.ZodOptional<z.ZodNumber>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            under: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>;
+        if: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    start: z.ZodOptional<z.ZodString>;
+    end: z.ZodOptional<z.ZodString>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    format: z.ZodLiteral<"agent-tools-script">;
+    name: z.ZodString;
+    app: z.ZodOptional<z.ZodString>;
+    fresh: z.ZodOptional<z.ZodBoolean>;
+    steps: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+            value: z.ZodOptional<z.ZodString>;
+            matches: z.ZodOptional<z.ZodString>;
+            threshold: z.ZodOptional<z.ZodNumber>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            timeout: z.ZodOptional<z.ZodNumber>;
+            under: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>;
+        if: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            gone: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        optional: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>]>;
+export type SharedScriptV1 = z.infer<typeof sharedScriptV1Schema>;
+export type SharedScriptV2 = z.infer<typeof sharedScriptV2Schema>;
+export type SharedScript = SharedScriptV1 | SharedScriptV2;
 /** Tapline's script before 1.1: the app's methods and their parameters. */
 export declare const legacyScriptSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -52,6 +150,12 @@ export interface MethodStep {
     /** Tapline: the screen's route when the step was recorded, checked on replay (a step field, not a parameter). */
     route?: string[];
 }
+/**
+ * The existing name that differs from `name` only in case, else null (AGENT-TOOLS 1.13.1 item 5). `home` and `HOME` are
+ * one file on Windows and macOS, so the second is refused before anything is written. It compares names, never the
+ * file system, so it means the same on every OS.
+ */
+export declare function caseTwin(name: string, existing: Iterable<string>): string | null;
 /** One recorded app call as a script step; null for calls a script doesn't keep. */
 export declare function toToolStep(step: MethodStep): Step | null;
 /**
@@ -59,7 +163,7 @@ export declare function toToolStep(step: MethodStep): Step | null;
  * label, with gone and timeout), so the script reads as "do this, then this must show".
  */
 export declare function scriptSteps(calls: MethodStep[]): Step[];
-export declare function fromLegacy(script: LegacyScript): SharedScript;
+export declare function fromLegacy(script: LegacyScript): SharedScriptV1;
 /** A script from a file's text, either format; null when it is neither. */
 export declare function readScript(text: string): SharedScript | null;
 /** A step a script can't keep: a ref (it doesn't survive a session). */

package/dist/script.js

@@ -6,14 +6,25 @@ import { stepSchema } from "./run.js";
  * Tapline records the app's methods as they run (press, type, …); this turns them into tool steps, and
  * still reads Tapline's own scripts from before 1.1.
  */
-export const sharedScriptSchema = z.object({
+const scriptBase = {
     format: z.literal("agent-tools-script"),
-    version: z.literal(1),
     name: z.string(),
     app: z.string().optional(),
     fresh: z.boolean().optional(),
     steps: z.array(stepSchema),
+};
+export const sharedScriptV1Schema = z.object({ ...scriptBase, version: z.literal(1) });
+/** A route's variable: a name, or `account` (the test account a route types, §18.6). Never a value. */
+export const variableNameSchema = z.string().regex(/^[A-Za-z_]\w*$/, "a variable's name is letters, digits and '_'");
+/** AGENT-TOOLS 1.13 §18.5: version 2 adds where a route starts and ends, and the variables its steps use. */
+export const sharedScriptV2Schema = z.object({
+    ...scriptBase,
+    version: z.literal(2),
+    start: z.string().min(1).optional(),
+    end: z.string().min(1).optional(),
+    variables: z.array(variableNameSchema).optional(),
 });
+export const sharedScriptSchema = z.union([sharedScriptV1Schema, sharedScriptV2Schema]);
 /** Tapline's script before 1.1: the app's methods and their parameters. */
 export const legacyScriptSchema = z.object({
     version: z.literal(1),
@@ -42,6 +53,23 @@ const TOOL_OF = {
     sleep: "wait",
     performance: "performance",
 };
+/** ASCII letters folded to lower case, and nothing else: names are ASCII, and `K` (Kelvin) is not a `k`. */
+function asciiLower(name) {
+    return name.replace(/[A-Z]/g, (letter) => String.fromCharCode(letter.charCodeAt(0) + 32));
+}
+/**
+ * The existing name that differs from `name` only in case, else null (AGENT-TOOLS 1.13.1 item 5). `home` and `HOME` are
+ * one file on Windows and macOS, so the second is refused before anything is written. It compares names, never the
+ * file system, so it means the same on every OS.
+ */
+export function caseTwin(name, existing) {
+    const others = [...existing];
+    // The exact name exists: it is the one meant, even when a twin from another OS sits next to it.
+    if (others.includes(name))
+        return null;
+    const folded = asciiLower(name);
+    return others.find((other) => asciiLower(other) === folded) ?? null;
+}
 /** The app's target (`testID`) as a tool target (`id`). */
 function toolTarget(target) {
     if (typeof target !== "object" || target === null)

package/dist/script.js.map

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

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from "node:events";
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
-import { type AppInfo, type DeviceInfo, type LogEntry } from "./protocol.js";
+import { type ApiHandler } from "./api.js";
+import { type AppInfo, type DeviceInfo, type LogEntry, type PlaceState } from "./protocol.js";
 export declare const CLOSE_REPLACED = 4010;
 export declare const CLOSE_SILENT = 4011;
 export interface SessionInfo {
@@ -16,6 +17,13 @@ export interface SessionInfo {
         state: string;
         at: number;
     };
+    /**
+     * The app's latest `place` event (AGENT-TOOLS 1.13 §18.11): route patterns, tab and layer, never params. `seenAt` is
+     * this host's clock when it arrived, the same computer's time as the tool that asks.
+     */
+    place?: PlaceState & {
+        seenAt: number;
+    };
     /** How the app reaches this host, from the address it connected from. */
     via?: "tailscale" | "wifi";
 }
@@ -105,11 +113,24 @@ export interface TaplineHostOptions {
      * (the report crosses the network, and the app passes on at most one touch per 500 ms). Default 1500 ms.
      */
     agentTouchSlackMs?: number;
+    /** Serves `POST /api/<tool>` (the thin call, AGENT-TOOLS 1.13 §18.10). Only a standalone `tapline host` sets it. */
+    api?: ApiHandler;
+    /**
+     * Scrubs the text of everything the app sends back (answers, errors, log lines, crashes) before anything else reads
+     * it: how test accounts' values stay out of every answer (AGENT-TOOLS 1.13 §18.6).
+     */
+    redact?: (text: string) => string;
 }
 /** The longest touch another tool may announce (`POST /agent-touch`), in milliseconds. */
 export declare const MAX_AGENT_TOUCH_MS = 10000;
 /** Whether a socket's peer is this computer. */
 export declare function isLoopback(address: string | undefined): boolean;
+/** The checks and the answer of `GET /place`, apart from the socket so a test can use a peer that isn't this computer. */
+export declare function handlePlaceRequest(req: IncomingMessage, res: ServerResponse, context: {
+    token: string;
+    loopback: boolean;
+    sessions: () => SessionInfo[];
+}): boolean;
 /**
  * Whether a peer is on this computer's own local network (or is this computer): private IPv4, link-local, IPv6
  * unique-local. Not Tailscale (100.64.0.0/10) and not the internet: the development offer stays on the Wi-Fi.
@@ -136,6 +157,11 @@ export interface DevOffer {
 export interface RequestOptions {
     sessionId?: string;
     timeoutMs?: number;
+    /**
+     * The answer comes back with account values still in it, for the host's own safety checks (the policy, the guard).
+     * It never goes outward: show it only through `redactOut`.
+     */
+    internal?: boolean;
 }
 export interface ListenResult {
     listening: Array<{
@@ -147,7 +173,7 @@ export interface ListenResult {
         error: string;
     }>;
 }
-export type TaplineErrorCode = "not_connected" | "timeout" | "reconnecting" | "not_answering" | "send_failed" | (string & {});
+export type TaplineErrorCode = "not_connected" | "timeout" | "reconnecting" | "not_answering" | "send_failed" | "off_route" | (string & {});
 /** An error from the host itself or relayed from the app (`code` is then the app's code). */
 export declare class TaplineError extends Error {
     readonly code: TaplineErrorCode;
@@ -161,6 +187,8 @@ interface HostEvents {
     frame: [session: SessionInfo, frame: AppFrame];
     /** The app went to the background or came back ("background", "active", "inactive"). */
     appState: [session: SessionInfo, state: string];
+    /** The app's photo picker handed over the armed test pictures (`media` with `picker`). */
+    pickerSkipped: [session: SessionInfo, count: number];
     /** A person touched the app's screen (the app saw a real touch; at most about two a second). */
     touch: [session: SessionInfo];
     /** A request to a connected app ended with `not_answering`. */
@@ -200,12 +228,16 @@ export declare class TaplineHost extends EventEmitter<HostEvents> {
     private readonly crashMap;
     private readonly crashLog;
     private crashSeq;
+    /** Requests that may have acted on the app (not reads, not dry runs), once past the checks that refuse before sending. */
+    private actingSent;
     private httpExtension;
+    private readonly api;
     /** Open after `pair`: development builds on the local network may fetch this code (one use, 10 minutes). */
     private devOffer;
     private sweeper;
     private listenCalled;
     private closed;
+    private readonly redact;
     constructor(options: TaplineHostOptions);
     /**
      * Another tool on this computer (Tapwright) is about to touch the phone for an agent, for about
@@ -217,6 +249,11 @@ export declare class TaplineHost extends EventEmitter<HostEvents> {
      * this computer, answered 204. Returns false for any other path.
      */
     private handleAgentTouch;
+    /**
+     * `GET /place?app=<app id>` with `Authorization: Bearer <the host token>` (AGENT-TOOLS 1.13 §18.11): only from this
+     * computer, answered from memory with no request to the phone. Returns false for any other path.
+     */
+    private handlePlace;
     /**
      * Starts listening on every configured address. When the port is taken and `portFallback`
      * allows it, moves on to the following ports. Rejects only if no address could bind.
@@ -269,6 +306,11 @@ export declare class TaplineHost extends EventEmitter<HostEvents> {
     } | undefined;
     /** The agent is about to end the app's connection on purpose (a reload): that is no crash. */
     expectEnd(sessionId: string, expected?: boolean): void;
+    /**
+     * How many requests that may have acted on an app were sent so far. A call whose mark didn't move did nothing, so
+     * it is safe to run it again (AGENT-TOOLS 1.13 §11.5).
+     */
+    actingMark(): number;
     /** The number of crash events so far; pass it to `crashEventsAfter` later. */
     crashMark(): number;
     /** Crash events after `seq`, oldest first; only those of the app `of` when it is given. */
@@ -284,6 +326,10 @@ export declare class TaplineHost extends EventEmitter<HostEvents> {
     private pushCrashEvent;
     private describeIds;
     private currentSession;
+    /** Whether account values are scrubbed from what the apps send (a test accounts file is loaded). */
+    get redacting(): boolean;
+    /** Scrubs a value (text and property names) the way every answer from an app is; for what an `internal` request gave. */
+    redactOut<T>(value: T): T;
     /** Sends a request to an app and resolves with its `result` (or rejects with a TaplineError). */
     request(method: string, params?: unknown, options?: RequestOptions): Promise<unknown>;
     private onConnection;