@shipvo/mcp 0.0.7 → 0.0.9

package/README.md

@@ -10,12 +10,56 @@ Lets AI agents (Claude, Cursor, Claude Code, PiPilot…) **use a Shipvo app with
 
 Start the simulator first (`shipvo sim` in the app). The server asks the simulator which app it serves, so `open_app("<your app id>")` works; set `PN_APPS` (JSON) to override. If the simulator cannot be reached, only the sample app opens. The hosted version needs no local setup: `{ "url": "https://<host>/mcp/<key>" }`.
 
-Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `notifications`, `open_notification`, `device_log`, `end_session`, `owner_describe`, `owner_command`.
+Each `tap`, `type`, `scroll` and `back` result starts with a line `Change: none | content changed | new screen | scrolled`, then the screen. `type` also adds `Value of <ref>: "..."`. Pass `compact: true` to get only the added (`+`) and removed (`-`) lines when the change is `content changed`; refs match the full screen. If the server has no earlier screen for the session (for example after a reconnect), the first line is `Change: unknown`. The `content changed` / `new screen` split is a heuristic (under half the lines kept means a new screen), so on a short screen one change can read as `new screen`.
+
+`tap`, `type`, `scroll` and `back` also take optional fields to wait for the effect instead of sleeping:
+
+- `wait_for`: `{ ref }`, `{ text }` or `{ role, name }` that must appear on the screen, or add `gone: true` to wait for it to disappear. `text` and `name` match as substrings.
+- `settle: true`: wait until the screen stops changing (two reads 100 ms apart that are equal, ignoring ref numbers).
+- `timeout_ms`: the most time `wait_for` and `settle` may take together (default 2000, at most 30000). One read of the simulator can itself take up to the time limit below, so this is not a hard cap on the call.
+
+Refs are renumbered between screens, so with `gone: true` prefer `text` or `role` + `name` over `ref`.
+
+The result gets a line `Waited: matched | timed out after <ms> ms` and `structuredContent.waited = { matched, ms }`. On a timeout the action still happened: the result is the latest screen, it is not an error, and the action's own outcome (such as `delivered`) is unchanged. Without these fields the result is the same as before.
+
+**Time limit.** Every call to the simulator stops after 30 s; set `SHIPVO_SIM_TIMEOUT_MS` to change it. A call that gets no answer returns an error result (`isError: true`, code `sim_timeout`, also in `structuredContent`). The action may still have run and the session may still be alive, so call `screen` to see where it is. Timed-out actions are not retried.
+
+**Error codes.** A failed call has `isError: true` and `structuredContent: { ok: false, code, error }`. Some failures from other causes (for example a read-only key) have `code: null`; read `error`.
+
+| Code | Meaning | What the agent should do |
+| --- | --- | --- |
+| `no_session` | The simulator has no session with that id (it expired or was never opened). | Call `list_sessions`, or `open_app` again. |
+| `stale_ref` | The ref is not on the current screen, or the screen changed since it was read. | Call `screen` and use a ref from the new tree. |
+| `unknown_app` | The app id is not one this server or key can open. | Call `list_apps` and use an id from it. |
+| `sim_timeout` | The simulator did not answer in time. The action may have run. | Call `screen` to see where the app is. Do not repeat the action blindly. |
+| `needs_confirm` | An owner command that cannot be undone did nothing and returned a plan. | Show the plan to the owner, then call again with `confirm: true`. |
+| `bad_url` | `open_url` got a URL the app cannot take. | Fix the URL and call again. |
+| `no_url_listener` | The app is not listening for URLs. | Use the app's screens instead. |
+| `phone_locked` | The phone is locked, so tap, type, scroll and back were not sent. | Call `unlock`, then try again. |
+| `already_locked` | `lock` was called on a locked phone. | Call `unlock` if you want to use the app. |
+| `not_locked` | `unlock` was called on a phone that is not locked. | Carry on; nothing to do. |
+| `mock_invalid` | A network mock rule is not valid. | Fix the rule. |
+
+Tools: `list_apps`, `open_app`, `screen`, `tap`, `type`, `scroll`, `back`, `screenshot`, `set_device`, `push_notification`, `notifications`, `open_notification`, `device_log`, `export_test`, `end_session`, `owner_describe`, `owner_command`.
+
+`export_test { session }` is read-only. It turns the taps, typing, scrolls, `back` and `set_device` calls recorded in a session into a `@shipvo/test` script and returns the source. Targets are named by visible text; an ambiguous target becomes a `// TODO` comment, and a password-like field uses `process.env.SHIPVO_TEST_<LABEL>` so the typed value is never in the output. Only sessions opened through this server are recorded; an unknown session returns `no_session`. Steps are dropped when the session ends. `payment.pin` is removed from recorded `set_device` calls. Only labels and roles that look like a password, passcode or PIN are treated as secret; other secret-like fields (card number, token) are exported as typed. `type` with `enter: true` and `scroll` with a `ref` are recorded without the Enter or the ref, so a replay can differ from the session.
+
+**Owner commands that cannot be undone need `confirm: true`.** `owner_command` takes an optional `confirm`. `publish`, price changes, offers, deletes and API keys first return `{ code: "needs_confirm", plan }` and do nothing; call again with the same `args` and `confirm: true` to run. `agentPolicy` (`ask` default, `deny`, `allow`) and `agentDeny` in `shipvo.json` (read from `PN_APP_DIR` or the current folder) can only tighten the control plane's rules. Details: `docs/agents.md`.
 
 Native features work with no phone: the simulated device (see `@shipvo/device`) shows permission dialogs, the camera, the fingerprint prompt, payment prompts, notification banners and the share sheet as real dialogs in the tree; `set_device` decides what the phone has (location, a barcode in view, whether the fingerprint matches, whether a payment is approved, network off).
 
 The simulator shows only what a phone would: a horizontal rail lists the visible items, so agents swipe it (`scroll right` with the rail's ref) exactly as on a device. Measured against a real Android emulator and iPhone simulator, see `docs/parity-results.md`.
 
+## Did the action land?
+
+`tap`, `type`, `scroll` and `back` return `structuredContent` next to the usual text:
+
+- `delivery`: `"delivered"` or `"not_delivered"`.
+- On `not_delivered` (the result is also `isError`): `reason` is `stale_ref`, `not_visible`, `disabled` or `covered`, and `safe_to_retry` is `true` because nothing reached the app. Take a new `screen`, then retry.
+- `type` also returns `value`, the text the field holds after typing.
+
+`code`, `error` and the text result are unchanged. Other failures (for example `sim_timeout`) carry no `delivery` field: the action may have run, so call `screen` first.
+
 ## Remote (Streamable HTTP)
 
 Run the server where the simulator runs and put it behind HTTPS (a Cloudflare Tunnel is enough):
@@ -30,4 +74,12 @@ Clients connect with a URL instead of a command:
 { "mcpServers": { "shipvo": { "url": "https://sim.shipvo.dev/mcp", "headers": { "Authorization": "Bearer key-for-claude" } } } }
 ```
 
-Each client connection gets its own MCP session; each `open_app` gets its own phone. Requests without a valid key are refused. The hosted version at `sim.shipvo.dev` will issue keys per account with scopes (test, owner, read).
+The HTTP endpoint is stateless. There is no protocol session: each POST is handled on its own, and the `x-shipvo-*` scope headers are read per request, so a scope never carries over to another request. `GET` and `DELETE` on `/mcp` answer 405. Phones are separate: each `open_app` gets its own phone, and you pass its `session` as a tool argument.
+
+### Protocol versions
+
+- **2025-era clients** (`initialize`, then calls, with or without `Mcp-Session-Id`): work. `initialize` is answered, no session id is issued, and any `Mcp-Session-Id` a client sends is ignored.
+- **2026-07-28 clients**: `tools/list` and `tools/call` work with no session and no `initialize`. `server/discover` is answered (supported versions, tools capability, server info). A request counts as 2026-era if it calls `server/discover`, sends `Mcp-Method`, or names a 2026 protocol version in `params._meta`; those must carry `Mcp-Method` (and `Mcp-Name` for `tools/call`, `prompts/get`, `resources/read`) matching the body, or get a 400 JSON-RPC error. Requests with no 2026 marker are not checked. Not done yet: `ttlMs`/`cacheScope` on list results. `tools/list` order is fixed (registration order).
+- This package uses `@modelcontextprotocol/sdk` 1.x (the TypeScript SDK v2 is not stable on npm yet; 1.32.2 is `latest`). Tested by `test/http-stateless.test.ts`: discover without `initialize`, header/body mismatch, scope per request, 2025-era `initialize` clients. Stdio is unchanged.
+
+ Requests without a valid key are refused. The hosted version at `sim.shipvo.dev` will issue keys per account with scopes (test, owner, read).

package/dist/attach.d.ts

@@ -0,0 +1,30 @@
+export type RunInfo = {
+    port: number;
+    platform: "android" | "ios";
+    app: string;
+    token: string;
+    pid: number;
+};
+export type DriverMessage = {
+    id: number;
+    type: string;
+    [key: string]: unknown;
+};
+export type ScreenMessage = {
+    id?: number;
+    type?: string;
+    ok?: boolean;
+    error?: string;
+    code?: string;
+    screen?: string | null;
+    [key: string]: unknown;
+};
+/** Finds `.shipvo/run.json` in `cwd` or a parent, stopping after the git root. Returns it only if the pid is alive and the app matches. */
+export declare function findLiveRun(app: string, cwd?: string): RunInfo | undefined;
+export type Driver = {
+    request(type: string, args?: Record<string, unknown>, ms?: number): Promise<ScreenMessage>;
+    close(): void;
+    closed: boolean;
+};
+/** Connects as `driver`. Rejects if the socket cannot open within `ms`. */
+export declare function connectDriver(info: RunInfo, ms?: number): Promise<Driver>;

package/dist/attach.js

@@ -0,0 +1,81 @@
+// Attach to a live `shipvo run` phone. `open_app` reads `.shipvo/run.json`, and if the run is alive and is the
+// same app, drives it over the agent channel as the `driver`. The types below mirror
+// packages/cli/src/run-protocol.ts: MCP cannot import from the CLI (rootDir is src, and the CLI is not a dependency).
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+const alive = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === "EPERM";
+} };
+// Safety: run.json may come from a parent directory, but we only ever connect to 127.0.0.1 and send its token there.
+/** Finds `.shipvo/run.json` in `cwd` or a parent, stopping after the git root. Returns it only if the pid is alive and the app matches. */
+export function findLiveRun(app, cwd = process.cwd()) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const file = join(dir, ".shipvo", "run.json");
+        if (existsSync(file)) {
+            try {
+                const i = JSON.parse(readFileSync(file, "utf8"));
+                if (typeof i.port === "number" && typeof i.token === "string" && typeof i.pid === "number" && typeof i.app === "string" && i.app === app && alive(i.pid))
+                    return i;
+            }
+            catch { }
+            return undefined; // the nearest run.json decides
+        }
+        if (existsSync(join(dir, ".git")) || dirname(dir) === dir)
+            return undefined;
+        dir = dirname(dir);
+    }
+}
+/** Connects as `driver`. Rejects if the socket cannot open within `ms`. */
+export function connectDriver(info, ms = 3000) {
+    return new Promise((ok, fail) => {
+        if (typeof WebSocket === "undefined")
+            return fail(new Error("attach needs Node 22+ (no global WebSocket in this Node version)"));
+        const ws = new WebSocket(`ws://127.0.0.1:${info.port}/__shipvo/agent?role=driver&token=${encodeURIComponent(info.token)}`);
+        const pending = new Map();
+        let next = 1, opened = false;
+        const d = {
+            closed: false,
+            close: () => { try {
+                ws.close();
+            }
+            catch { } },
+            request: (type, args = {}, limit = 10000) => new Promise((res) => {
+                if (d.closed)
+                    return res({ ok: false, code: "attach_closed", error: "the shipvo run phone is gone: call open_app again" });
+                const id = next++;
+                const t = setTimeout(() => { pending.delete(id); res({ ok: false, code: "sim_timeout", error: `the live phone did not answer "${type}" within ${limit} ms. The action may still have run: call screen to see where it is.` }); }, limit);
+                pending.set(id, (m) => { clearTimeout(t); res(m); });
+                ws.send(JSON.stringify({ ...args, id, type }));
+            }),
+        };
+        const timer = setTimeout(() => { ws.close(); fail(new Error("timed out connecting to the shipvo run phone")); }, ms);
+        ws.onopen = () => { opened = true; clearTimeout(timer); ok(d); };
+        ws.onmessage = (e) => {
+            try {
+                const m = JSON.parse(String(e.data));
+                if (m.id !== undefined) {
+                    pending.get(m.id)?.(m);
+                    pending.delete(m.id);
+                }
+            }
+            catch { }
+        };
+        ws.onclose = () => {
+            d.closed = true;
+            for (const [id, f] of pending) {
+                f({ ok: false, code: "attach_closed", error: "the shipvo run phone closed the connection: call open_app again" });
+                pending.delete(id);
+            }
+            if (!opened) {
+                clearTimeout(timer);
+                fail(new Error("could not connect to the shipvo run phone"));
+            }
+        };
+        ws.onerror = () => { };
+    });
+}

package/dist/change.d.ts

@@ -0,0 +1,4 @@
+export type Change = "none" | "content changed" | "new screen" | "scrolled";
+export declare function classify(prev: string | undefined, next: string, action: string): Change;
+export declare function compactDiff(prev: string, next: string): string;
+export declare function fieldValue(tree: string, ref: string): string | undefined;

package/dist/change.js

@@ -0,0 +1,51 @@
+const REF = /\s*\[ref=\w+\]/g;
+// A line without its ref, so a re-numbered but identical element counts as the same.
+const norm = (l) => l.replace(REF, "").trim();
+const lines = (t) => t.split("\n").filter((l) => l.trim());
+export function classify(prev, next, action) {
+    if (prev === undefined)
+        return "new screen";
+    const a = lines(prev).map(norm), b = lines(next).map(norm);
+    if (a.length === b.length && a.every((l, i) => l === b[i]))
+        return "none";
+    if (action === "scroll")
+        return "scrolled";
+    const seen = new Set(a);
+    const kept = b.filter((l) => seen.has(l)).length;
+    return b.length === 0 || kept / b.length < 0.5 ? "new screen" : "content changed";
+}
+// Added (+) and removed (-) lines. Added lines keep their refs from the new tree, so refs stay valid.
+export function compactDiff(prev, next) {
+    const count = (ls) => { const m = new Map(); for (const l of ls)
+        m.set(norm(l), (m.get(norm(l)) ?? 0) + 1); return m; };
+    const pl = lines(prev), nl = lines(next);
+    const pc = count(pl), nc = count(nl);
+    const out = [];
+    for (const l of pl) {
+        const n = nc.get(norm(l)) ?? 0;
+        if (n > 0)
+            nc.set(norm(l), n - 1);
+        else
+            out.push("- " + l.trim());
+    }
+    for (const l of nl) {
+        const n = pc.get(norm(l)) ?? 0;
+        if (n > 0)
+            pc.set(norm(l), n - 1);
+        else
+            out.push("+ " + l.trim());
+    }
+    return out.length ? out.join("\n") : "(same lines, new order)";
+}
+// The value of the field with this ref: the text after its attribute brackets and ":".
+// Handles more attributes after the ref ([ref=e3] [cursor=pointer]: Ana) and YAML-quoted lines.
+export function fieldValue(tree, ref) {
+    for (const raw of lines(tree)) {
+        const q = /^(\s*- )'(.*)'(:.*)?$/.exec(raw);
+        const l = (q ? q[1] + q[2].replace(/''/g, "'") + (q[3] ?? "") : raw).trim();
+        const m = new RegExp(`\\[ref=${ref}\\]((?: \\[[^\\]]*\\])*)(?::\\s*(.*))?$`).exec(l);
+        if (m)
+            return (m[2] ?? "").trim().replace(/^"(.*)"$/, "$1");
+    }
+    return undefined;
+}

package/dist/export.d.ts

@@ -0,0 +1,15 @@
+export type Step = {
+    action: "open" | "tap" | "type" | "scroll" | "back" | "set_device";
+    target?: {
+        text: string;
+        role: string;
+        matches: number;
+    };
+    text?: string;
+    fieldLabel?: string;
+    passwordLike?: boolean;
+    direction?: string;
+    device?: object;
+    changed?: boolean;
+};
+export declare function exportTest(app: string, steps: Step[]): string;

package/dist/export.js

@@ -0,0 +1,52 @@
+// JSON.stringify leaves U+2028 and U+2029 raw, but TypeScript treats them as line breaks.
+const q = (s) => JSON.stringify(s).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+// Comment text must stay on one line.
+const oneLine = (s) => s.replace(/[\r\n\u2028\u2029]+/g, " ");
+const envName = (label) => "SHIPVO_TEST_" + (label.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase() || "FIELD");
+const DIRECTIONS = ["down", "up", "left", "right"];
+function lineFor(s) {
+    const t = s.target;
+    switch (s.action) {
+        case "open": return [];
+        case "back": return ["await phone.back();"];
+        case "set_device": return [`await phone.device.set(${JSON.stringify(s.device ?? {}).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")});`];
+        case "scroll": {
+            const d = s.direction && DIRECTIONS.includes(s.direction) ? s.direction : "down";
+            return [`await phone.scroll(${q(d)});`];
+        }
+        case "tap":
+            if (!t)
+                return ["// TODO: tap without a target"];
+            if (t.matches > 1)
+                return [`// TODO: ambiguous target ${oneLine(q(t.text))}`];
+            return [`await phone.tap(${q(t.text)});`];
+        case "type": {
+            const label = s.fieldLabel ?? t?.text;
+            if (!label)
+                return ["// TODO: type without a field label"];
+            if (t && t.matches > 1)
+                return [`// TODO: ambiguous target ${oneLine(q(label))}`];
+            const value = s.passwordLike ? `process.env.${envName(label)}!` : q(s.text ?? "");
+            return [`await phone.type(${q(label)}, ${value});`];
+        }
+    }
+}
+export function exportTest(app, steps) {
+    const out = [
+        `import { test } from "@shipvo/test/vitest";`,
+        `import { openApp } from "@shipvo/test";`,
+        ``,
+        `test(${q(`recorded session for ${app}`)}, async () => {`,
+        `  const phone = await openApp({ app: ${q(app)} });`,
+    ];
+    for (const s of steps) {
+        const lines = lineFor(s);
+        for (const l of lines)
+            out.push("  " + l);
+        if (s.changed && lines.length && !lines[0].startsWith("//") && s.action !== "open") {
+            out.push("  await phone.waitFor(/\\S/); // TODO: name the text that should appear");
+        }
+    }
+    out.push("});", "");
+    return out.join("\n");
+}

package/dist/record.d.ts

@@ -0,0 +1,12 @@
+export type Found = {
+    text: string;
+    role: string;
+    matches: number;
+    passwordLike: boolean;
+};
+export declare const unquoteLine: (raw: string) => string;
+export declare const parse: (raw: string) => {
+    role: string;
+    text: string;
+} | undefined;
+export declare function findTarget(tree: string | undefined, ref: string): Found | undefined;

package/dist/record.js

@@ -0,0 +1,28 @@
+export const unquoteLine = (raw) => {
+    const q = /^(\s*- )'(.*)'(:.*)?$/.exec(raw);
+    return q ? q[1] + q[2].replace(/''/g, "'") + (q[3] ?? "") : raw;
+};
+export const parse = (raw) => {
+    const m = /^\s*- ([\w-]+)(?: ("(?:[^"\\]|\\.)*"))?/.exec(unquoteLine(raw));
+    if (!m)
+        return undefined;
+    let text = "";
+    try {
+        text = m[2] ? JSON.parse(m[2]) : "";
+    }
+    catch {
+        text = m[2].slice(1, -1);
+    }
+    return { role: m[1], text };
+};
+export function findTarget(tree, ref) {
+    if (!tree)
+        return undefined;
+    const lines = tree.split("\n");
+    const mine = lines.find((l) => unquoteLine(l).includes(`[ref=${ref}]`));
+    const t = mine && parse(mine);
+    if (!t || !t.text)
+        return undefined;
+    const matches = lines.filter((l) => parse(l)?.text === t.text).length;
+    return { ...t, matches, passwordLike: /pass(word|code)|\bpin\b/i.test(`${t.role} ${t.text}`) };
+}

package/dist/recorder.d.ts

@@ -0,0 +1,52 @@
+export type Format = "9:16" | "16:9" | "1:1";
+export declare const SIZES: Record<Format, {
+    width: number;
+    height: number;
+}>;
+export type Chapter = {
+    t: number;
+    caption: string;
+};
+export type Recording = {
+    file: string;
+    duration_s: number;
+    width: number;
+    height: number;
+    chapters: Chapter[];
+};
+export declare class RecorderError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare class Recorder {
+    private browser?;
+    private page?;
+    private ff?;
+    private loop?;
+    private t0;
+    private running;
+    private starting;
+    private stopping;
+    private ffErr;
+    private done?;
+    private chapters;
+    private file;
+    private size;
+    private fps;
+    get active(): boolean;
+    start(o: {
+        url: string;
+        format?: Format;
+        fps?: 30 | 60;
+        title?: string;
+        dir?: string;
+    }): Promise<{
+        file: string;
+        width: number;
+        height: number;
+    }>;
+    private grab;
+    marker(caption: string): Chapter;
+    stop(): Promise<Recording>;
+    private cleanup;
+}

package/dist/recorder.js

@@ -0,0 +1,143 @@
+// Records the phone frame page to an MP4. Playwright takes screenshots while a session runs; ffmpeg encodes them.
+// Frames carry wall-clock timestamps, so the video lasts as long as the recording even when screenshots are slow.
+// The recording clock (duration_s, chapter times) and the video both start at the first frame.
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const SIZES = {
+    "9:16": { width: 1080, height: 1920 }, "16:9": { width: 1920, height: 1080 }, "1:1": { width: 1080, height: 1080 },
+};
+export class RecorderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class Recorder {
+    browser;
+    page;
+    ff;
+    loop;
+    t0 = 0;
+    running = false;
+    starting = false;
+    stopping = false;
+    ffErr = "";
+    done;
+    chapters = [];
+    file = "";
+    size = SIZES["9:16"];
+    fps = 30;
+    get active() { return this.running || this.starting || this.stopping; }
+    async start(o) {
+        if (this.active)
+            throw new RecorderError("recording_active", "a recording is already running: call record_stop first");
+        this.starting = true;
+        try {
+            this.size = SIZES[o.format ?? "9:16"];
+            this.fps = o.fps ?? 30;
+            this.chapters = [];
+            this.ffErr = "";
+            const dir = resolve(o.dir ?? join(process.cwd(), ".shipvo", "recordings"));
+            mkdirSync(dir, { recursive: true });
+            const slug = (o.title ?? "recording").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "recording";
+            this.file = join(dir, `${slug}-${new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14)}.mp4`);
+            let pw;
+            try {
+                const mod = "playwright";
+                pw = await import(mod);
+            }
+            catch {
+                throw new RecorderError("recorder_unavailable", "recording needs Playwright: run `npm i -D playwright && npx playwright install chromium`");
+            }
+            try {
+                this.browser = await pw.chromium.launch(process.env.SHIPVO_CHROMIUM ? { executablePath: process.env.SHIPVO_CHROMIUM } : {});
+            }
+            catch (e) {
+                throw new RecorderError("recorder_unavailable", `could not launch Chromium: run \`npx playwright install chromium\` (${e.message.split("\n")[0]})`);
+            }
+            this.page = await this.browser.newPage({ viewport: this.size });
+            try {
+                await this.page.goto(o.url, { waitUntil: "load" });
+            }
+            catch (e) {
+                throw new RecorderError("frame_unreachable", `could not open the phone frame page ${o.url}: ${e.message.split("\n")[0]}`);
+            }
+            this.ff = spawn("ffmpeg", ["-y", "-loglevel", "error", "-use_wallclock_as_timestamps", "1", "-f", "image2pipe", "-c:v", "mjpeg", "-i", "-",
+                "-vf", `fps=${this.fps},scale=${this.size.width}:${this.size.height},format=yuv420p`, "-c:v", "libx264", "-preset", "veryfast", "-movflags", "+faststart", this.file], { stdio: ["pipe", "ignore", "pipe"] });
+            this.ff.stderr.on("data", (d) => { this.ffErr += d; });
+            this.ff.stdin.on("error", () => { });
+            this.done = new Promise((r) => { this.ff.on("error", (e) => { this.ffErr += e.message; r(-1); }); this.ff.on("close", r); });
+            await this.grab();
+            // The video timeline starts when ffmpeg gets the first frame, not before the first (slow) screenshot.
+            this.t0 = Date.now();
+            this.running = true;
+            this.starting = false;
+            this.loop = (async () => { while (this.running)
+                await this.grab(); })();
+            return { file: this.file, ...this.size };
+        }
+        catch (e) {
+            await this.cleanup();
+            throw e;
+        }
+    }
+    async grab() {
+        try {
+            const b = await this.page.screenshot({ type: "jpeg", quality: 90 });
+            if (this.ff?.stdin?.writable)
+                this.ff.stdin.write(b);
+        }
+        catch { }
+    }
+    marker(caption) {
+        if (!this.running)
+            throw new RecorderError("no_recording", "no recording is running: call record_start first");
+        const last = this.chapters.at(-1)?.t ?? -0.001;
+        const c = { t: Math.max(Math.round(Date.now() - this.t0) / 1000, Math.round((last + 0.001) * 1000) / 1000), caption };
+        this.chapters.push(c);
+        return c;
+    }
+    async stop() {
+        if (!this.running)
+            throw new RecorderError("no_recording", "no recording is running: call record_start first");
+        this.running = false;
+        this.stopping = true;
+        try {
+            const { file, size, chapters, ff, done, t0 } = this;
+            await this.loop;
+            await this.grab();
+            const duration_s = Math.round((Date.now() - t0)) / 1000;
+            ff.stdin.end();
+            const code = await done;
+            const err = this.ffErr;
+            const out = { file, duration_s, ...size, chapters };
+            await this.cleanup();
+            if (code !== 0)
+                throw new RecorderError("encode_failed", `ffmpeg failed${code === -1 ? " to start (is it installed?)" : ""}: ${err.trim().slice(0, 300)}`);
+            return out;
+        }
+        finally {
+            this.stopping = false;
+        }
+    }
+    async cleanup() {
+        this.running = false;
+        this.starting = false;
+        try {
+            await this.loop;
+        }
+        catch { }
+        try {
+            this.ff?.stdin?.end();
+            this.ff?.kill();
+        }
+        catch { }
+        try {
+            await this.browser?.close();
+        }
+        catch { }
+        this.browser = this.page = this.ff = this.loop = undefined;
+    }
+}

package/dist/server.js

@@ -3,26 +3,35 @@
 //   PN_SIM=http://localhost:4545  PN_CONTROL=https://api.shipvo.dev  PN_OWNER_TOKEN=...  shipvo-mcp
 // Remote (Streamable HTTP, what Claude, ChatGPT, Cursor connect to over the network):
 //   shipvo-mcp --http 8787  with PN_API_KEYS="key1,key2" (Authorization: Bearer <key>) → POST/GET/DELETE /mcp
-// Tools: list_apps, open_app, screen, tap, type, scroll, back, screenshot, end_session (UI simulator);
+// Tools: list_apps, open_app, screen, tap, type, scroll, back, screenshot, export_test, end_session (UI simulator);
 //        owner_describe, owner_command (the app's live content, prices, orders: owner token required).
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import http from "node:http";
-import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
 import { z } from "zod";
+import { classify, compactDiff, fieldValue } from "./change.js";
+import { exportTest } from "./export.js";
+import { findTarget } from "./record.js";
+import { Recorder, RecorderError } from "./recorder.js";
+import { connectDriver, findLiveRun } from "./attach.js";
+import { satisfied, sameTree, wantsMatch } from "./wait.js";
 const SIM = (process.env.PN_SIM ?? "http://localhost:4545").replace(/\/$/, "");
 const CONTROL = (process.env.PN_CONTROL ?? "https://api.shipvo.dev").replace(/\/$/, "");
 const OWNER_TOKEN = process.env.PN_OWNER_TOKEN ?? "";
 // Apps this server can open. Hosted: the account's apps. Local: the app the simulator serves (it is asked on
 // first use), or PN_APPS (JSON) to override. Falls back to the sample app when the simulator cannot be reached.
 const TIDE = { tide: { name: "Tide & Tackle", description: "Fishing-supplies shop in Douala: catalogue, cart, promo codes, delivery slots, cash or mobile money." } };
+// Every call to the simulator has a time limit (default 30 s, SHIPVO_SIM_TIMEOUT_MS to change it).
+const simTimeoutMs = () => { const n = Number(process.env.SHIPVO_SIM_TIMEOUT_MS); return Number.isFinite(n) && n > 0 ? n : 30000; };
 async function localApps() {
     if (process.env.PN_APPS)
         return JSON.parse(process.env.PN_APPS);
     try {
-        const r = await fetch(SIM + "/apps", { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+        const r = await fetch(SIM + "/apps", { method: "POST", headers: { "content-type": "application/json" }, body: "{}", signal: AbortSignal.timeout(simTimeoutMs()) });
         if (r.ok) {
             const out = {};
             for (const a of (await r.json()).apps ?? [])
@@ -34,21 +43,87 @@ async function localApps() {
     catch { }
     return TIDE;
 }
+// A call that gets no answer in time returns ok:false with code sim_timeout (a typed error for this one tool
+// call). It is never retried: the action may have run, so the agent should call `screen` and look.
 async function sim(path, body) {
-    const r = await fetch(SIM + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
-    if (!r.ok)
-        throw new Error(`simulator ${path} -> ${r.status}. Is it running at ${SIM}?`);
-    return r.json();
+    const ms = simTimeoutMs();
+    let r;
+    try {
+        r = await fetch(SIM + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(ms) });
+        if (!r.ok)
+            throw new Error(`simulator ${path} -> ${r.status}. Is it running at ${SIM}?`);
+        return (await r.json());
+    }
+    catch (e) {
+        if (e?.name !== "TimeoutError")
+            throw e;
+        const what = path === "/act" && typeof body.action === "string" ? `action "${body.action}"` : `request ${path}`;
+        return { ok: false, code: "sim_timeout", error: `the simulator did not answer ${what} within ${ms} ms. The action may still have run and the session may still be alive: call screen to see where it is.` };
+    }
+}
+const recorder = new Recorder();
+// Sessions attached to a live `shipvo run` phone. Module level: HTTP mode builds a server per request.
+const attached = new Map();
+const ATTACH_TYPES = new Set(["screen", "tap", "type", "scroll", "back"]);
+// One action on a session: through the driver connection when attached, else the simulator.
+async function act(body) {
+    const d = attached.get(String(body.session));
+    if (!d)
+        return sim("/act", body);
+    const { session: _s, action, ...args } = body;
+    if (!ATTACH_TYPES.has(String(action)))
+        return { ok: false, code: "not_supported_attached", error: `"${action}" is not available on the live shipvo run phone yet. Use screen, tap, type, scroll or back, or open a headless session with attach: "never".` };
+    const m = await d.request(String(action), args);
+    return { ok: m.ok !== false && !m.error, screen: m.screen ?? null, error: m.error, code: m.code };
 }
 const sessions = new Map();
+// Last tree per session id. Separate from `sessions` so it works for ids this server never opened.
+const trees = new Map();
+// Recorded steps per session, for export_test. Dropped when the session ends.
+const steps = new Map();
+// Tool annotations (MCP hints): clients use them to decide what to run without asking.
+const RO = { readOnlyHint: true, destructiveHint: false };
+const WR = { readOnlyHint: false, destructiveHint: false };
+const DEST = { readOnlyHint: false, destructiveHint: true };
 const text = (t) => ({ content: [{ type: "text", text: t }] });
-const result = (sid, r) => { const s = sessions.get(sid); if (s)
-    s.steps++; return text(r.ok ? (r.screen ?? "") : `Error${r.code ? ` [${r.code}]` : ""}: ${r.error}${/no session/.test(String(r.error)) ? " (sessions expire with the phone; call open_app again)" : ""}\n\nScreen now:\n${r.screen ?? ""}`); };
+// Action result with a "Change:" line on top. Compares this tree with the session's last one.
+// compact: on "content changed", return only the added/removed lines instead of the full tree.
+const acted = (sid, action, r, o = {}) => {
+    if (!r.ok || r.screen == null)
+        return result(sid, r);
+    const prev = trees.get(sid);
+    trees.set(sid, r.screen);
+    const change = prev === undefined ? "unknown (no earlier screen to compare)" : classify(prev, r.screen, action);
+    if (o.step)
+        steps.get(sid)?.push({ ...o.step, changed: prev === undefined ? undefined : change !== "none" });
+    const head = [`Change: ${change}`];
+    if (o.waited)
+        head.push(`Waited: ${o.waited.matched ? "matched" : "timed out"} after ${o.waited.ms} ms`);
+    if (action === "type" && o.ref) {
+        const v = fieldValue(r.screen, o.ref);
+        head.push(v !== undefined ? `Value of ${o.ref}: ${JSON.stringify(v)}` : `Value of ${o.ref}: not shown`);
+    }
+    const body = o.compact && change === "content changed" && prev !== undefined ? `Changed lines (+ added, - removed; refs as on the full screen):\n${compactDiff(prev, r.screen)}` : r.screen;
+    const res = result(sid, { ...r, screen: head.join("\n") + "\n\n" + body });
+    const value = action === "type" ? (r.value ?? fieldValue(r.screen, o.ref ?? "")) : undefined;
+    return { ...res, structuredContent: { delivery: r.delivery ?? "delivered", ...(value !== undefined ? { value } : {}), ...(o.waited ? { waited: o.waited } : {}) } };
+};
+const result = (sid, r) => {
+    const s = sessions.get(sid);
+    if (s)
+        s.steps++;
+    if (r.ok)
+        return text(r.screen ?? "");
+    const t = `Error${r.code ? ` [${r.code}]` : ""}: ${r.error}${/no session/.test(String(r.error)) ? " (sessions expire with the phone; call open_app again)" : ""}${r.screen ? `\n\nScreen now:\n${r.screen}` : ""}`;
+    return { ...text(t), isError: true, structuredContent: { ok: false, code: r.code ?? null, error: r.error ?? null, ...(r.delivery ? { delivery: r.delivery, reason: r.reason, safe_to_retry: r.safe_to_retry === true } : {}) } };
+};
 // Sessions live in the simulator; this map only tracks step counts. A client may reconnect between calls
 // (ChatGPT does), so an unknown id is forwarded and the simulator answers if it knows it.
 const need = (_sid) => { };
+const SERVER_VERSION = "0.0.4";
+const SUPPORTED_VERSIONS = ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 function makeServer(ctx = {}) {
-    const server = new McpServer({ name: "shipvo", version: "0.0.4" }, { instructions: `You can use Shipvo apps the way a person uses them on a phone, without a phone.
+    const server = new McpServer({ name: "shipvo", version: SERVER_VERSION }, { instructions: `You can use Shipvo apps the way a person uses them on a phone, without a phone.
 Call open_app to get a session and the first screen. The screen is an accessibility tree: every button, field and text, with a [ref=eN]. Act with tap/type/scroll/back using refs, and read the screen that comes back each time.
 Only what is on screen is listed, like a phone: a horizontal product rail shows a few items, so "scroll right" on the rail (its ref) to see more; "scroll down" the page for the rest.
 System sheets (permission dialogs, the camera, the fingerprint prompt, payment prompts, notification banners, the share sheet) appear in the tree like any other screen: answer them by tapping, as a person would. Use set_device to decide what the phone has (a barcode in front of the camera, a location, whether the fingerprint matches, whether the payment is approved, network off) before the app asks for it.
@@ -56,7 +131,7 @@ Finish a task by checking the final screen says what you expected (for example "
     // ctx.app: the app(s) this key opens, comma-separated (the beta app plus any the key owner has registered).
     const keyApps = ctx.app ? ctx.app.split(",").map((s) => s.trim()).filter(Boolean) : null;
     const allowed = async (id) => (keyApps ? keyApps.includes(id) : !!(await localApps())[id]);
-    server.tool("list_apps", "Apps this server can open, with what each one does. Optional query filters by name, description or category (e.g. 'shop', 'douala').", { query: z.string().optional() }, async ({ query }) => {
+    server.tool("list_apps", "Apps this server can open, with what each one does. Optional query filters by name, description or category (e.g. 'shop', 'douala').", { query: z.string().optional() }, RO, async ({ query }) => {
         const APPS = await localApps();
         const ids = keyApps ?? Object.keys(APPS);
         const q = (query ?? "").toLowerCase();
@@ -80,55 +155,183 @@ Finish a task by checking the final screen says what you expected (for example "
         session: z.string().optional().describe("Session name (default: generated). One session is one phone."),
         seed_cart: z.array(z.object({ product_id: z.string().optional(), id: z.string().optional(), quantity: z.number().int().positive().optional(), qty: z.number().int().positive().optional() }).refine((l) => (l.product_id ?? l.id) && (l.quantity ?? l.qty), "each line needs product_id (or id) and quantity (or qty)")).optional().describe("Start with these items already in the cart (test shortcut). Each line: { product_id, quantity }; { id, qty } also works."),
         dark: z.boolean().optional().describe("Dark mode"),
-    }, async ({ app, session, seed_cart, dark }) => {
+        attach: z.enum(["auto", "never", "always"]).optional().describe("'auto' (default): drive the phone of a live `shipvo run` in this project if there is one, else a headless session. 'never': always headless. 'always': error if there is no live `shipvo run`."),
+    }, WR, async ({ app, session, seed_cart, dark, attach }) => {
         const id = app.split("@")[0];
         if (!(await allowed(id)))
-            throw new Error(keyApps ? `this key opens: ${keyApps.join(", ")}` : `unknown app "${id}". Apps: ${Object.keys(await localApps()).join(", ")}`);
+            return result("", { ok: false, code: "unknown_app", error: keyApps ? `this key opens: ${keyApps.join(", ")}` : `unknown app "${id}". Apps: ${Object.keys(await localApps()).join(", ")}` });
         if (ctx.scope === "read")
             throw new Error("this key is read-only: it cannot open sessions");
         const sid = session ?? `${id}-${Date.now().toString(36)}`;
+        const mode = attach ?? "auto";
+        const live = mode === "never" ? undefined : findLiveRun(id);
+        if (mode === "always" && !live)
+            return result("", { ok: false, code: "no_live_run", error: `no live shipvo run for "${id}" found in this directory or its parents (.shipvo/run.json missing, stale, or for another app). Start \`shipvo run android\` or \`shipvo run ios\`, or use attach: "auto".` });
+        let attachNote = "";
+        if (live) {
+            try {
+                const d = await connectDriver(live);
+                attached.get(sid)?.close();
+                attached.set(sid, d);
+                const r = await act({ session: sid, action: "screen" });
+                if (!r.ok) {
+                    attached.delete(sid);
+                    d.close();
+                    if (mode === "always")
+                        return result(sid, r);
+                    attachNote = ` (live run found but attach failed: ${r.error ?? r.code ?? "unknown error"})`;
+                }
+                else {
+                    sessions.set(sid, { app: id, steps: 0, startedAt: Date.now() });
+                    steps.set(sid, [{ action: "open" }]);
+                    if (r.screen != null)
+                        trees.set(sid, r.screen);
+                    else
+                        trees.delete(sid);
+                    return text(`session: ${sid}\napp: ${id} release: local\nmode: attached to the live shipvo run phone\n\n${r.screen ?? ""}`);
+                }
+            }
+            catch (e) {
+                if (mode === "always")
+                    return result("", { ok: false, code: "attach_failed", error: e.message });
+                attachNote = ` (live run found but attach failed: ${e.message})`;
+            }
+        }
         const r = await sim("/session", { session: sid, app, seed_cart: seed_cart?.map((l) => ({ ...l, product_id: l.product_id ?? l.id, quantity: l.quantity ?? l.qty })), dark });
+        if (r.code === "sim_timeout")
+            return result(sid, r);
         sessions.set(sid, { app: id, steps: 0, startedAt: Date.now() });
-        return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\n\n${r.screen ?? ""}`);
+        steps.set(sid, [{ action: "open" }]);
+        if (r.screen != null)
+            trees.set(sid, r.screen);
+        else
+            trees.delete(sid);
+        return text(`session: ${sid}\napp: ${id} release: ${r.release ?? "local"}\nmode: headless session${attachNote}\n\n${r.screen ?? ""}`);
     });
-    server.tool("list_sessions", "Open simulator sessions (phones) on this server: id, app, release and when each started. Use to resume after a reconnect.", {}, async () => {
+    server.tool("list_sessions", "Open simulator sessions (phones) on this server: id, app, release and when each started. Use to resume after a reconnect.", {}, RO, async () => {
         const r = await sim("/sessions", {});
+        if (r.code === "sim_timeout")
+            return result("", r);
         const rows = (r.sessions ?? []).filter((s) => !keyApps || keyApps.includes(s.app));
         return text(rows.length ? rows.map((s) => `${s.session}: ${s.app} release ${s.release}${s.started_at ? ` since ${s.started_at}` : ""}`).join("\n") : "no open sessions");
     });
     const sid = z.string().describe("Session from open_app");
+    const compact = z.boolean().optional().describe("When the change is 'content changed', return only the added/removed lines, not the whole screen");
+    const CH = " The result starts with 'Change: none | content changed | new screen | scrolled'.";
+    const ASYNC = " Work that starts on a tap (paying, saving, loading) can finish after this returns, so the screen may show 'Paying...' or a spinner. Do not report that as the result: pass wait_for with the text you expect (and gone: true for the spinner), or settle: true, before you read the outcome or do anything else.";
+    const waitFor = z.object({ ref: z.string().regex(/^e\d+$/).optional(), text: z.string().optional(), role: z.string().optional(), name: z.string().optional(), gone: z.boolean().optional() })
+        .refine((w) => wantsMatch(w), "give ref, text, or role and name").optional()
+        .describe("Use after any action that starts work. Wait until this appears (a ref, a text, or role+name), or disappears with gone: true. The result says Waited: matched or timed out.");
+    const timeoutMs = z.number().int().min(0).max(30000).optional().describe("How long wait_for and settle may take, in ms (default 2000)");
+    const settle = z.boolean().optional().describe("Wait until the screen stops changing (two equal reads 100 ms apart), up to timeout_ms. Use after any action that starts work. A slow result can still follow a pause, so prefer wait_for when you know the expected text.");
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    // Poll the screen after an action. Returns the latest result and what happened. On timeout the action result is kept as is.
+    async function waiting(session, r, w) {
+        if (!r.ok || r.screen == null || (!w.wait_for && !w.settle))
+            return { r };
+        const t0 = Date.now(), limit = w.timeout_ms ?? 2000, left = () => limit - (Date.now() - t0);
+        let cur = r, matched = true;
+        const read = async () => { const n = await act({ session, action: "screen" }); if (n.ok && n.screen != null)
+            cur = { ...cur, screen: n.screen }; return n.ok && n.screen != null; };
+        if (w.wait_for) {
+            matched = satisfied(cur.screen, w.wait_for);
+            while (!matched && left() > 0) {
+                await sleep(Math.min(100, left()));
+                if (await read())
+                    matched = satisfied(cur.screen, w.wait_for);
+            }
+        }
+        if (w.settle && matched) {
+            matched = false;
+            while (left() > 0) {
+                await sleep(Math.min(100, left()));
+                const before = cur.screen;
+                if (await read() && sameTree(before, cur.screen)) {
+                    matched = true;
+                    break;
+                }
+            }
+        }
+        return { r: cur, waited: { matched, ms: Date.now() - t0 } };
+    }
     const ref = z.string().regex(/^e\d+$/).describe("Element ref from the screen, e.g. e42");
-    server.tool("screen", "The current screen as an accessibility tree with refs.", { session: sid }, async ({ session }) => { need(session); return result(session, await sim("/act", { session, action: "screen" })); });
-    server.tool("tap", "Tap a button, link or choice by ref. Returns the new screen.", { session: sid, ref }, async ({ session, ref }) => { need(session); return result(session, await sim("/act", { session, action: "tap", ref })); });
-    server.tool("type", "Type into a text field by ref (replaces its content). Returns the new screen.", { session: sid, ref, text: z.string(), enter: z.boolean().optional().describe("Press Enter afterwards") }, async ({ session, ref, text: t, enter }) => { need(session); return result(session, await sim("/act", { session, action: "type", ref, text: t, enter })); });
-    server.tool("scroll", "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen.", { session: sid, direction: z.enum(["down", "up", "left", "right"]), ref: ref.optional().describe("Scroll inside this element (a rail or list); omit for the page") }, async ({ session, direction, ref }) => { need(session); return result(session, await sim("/act", { session, action: "scroll", direction, ref })); });
-    server.tool("back", "Go back one screen.", { session: sid }, async ({ session }) => { need(session); return result(session, await sim("/act", { session, action: "back" })); });
-    server.tool("screenshot", "A PNG of the phone screen (for checking layout, colours, images). The tree from `screen` is usually enough to act.", { session: sid }, async ({ session }) => {
+    server.tool("screen", "The current screen as an accessibility tree with refs.", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "screen" }); if (r.ok && r.screen != null)
+        trees.set(session, r.screen); return result(session, r); });
+    server.tool("tap", "Tap a button, link or choice by ref. Returns the new screen." + CH + ASYNC, { session: sid, ref, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "tap", ref }), { wait_for, timeout_ms, settle }); return acted(session, "tap", w.r, { waited: w.waited, compact, step: { action: "tap", target: findTarget(trees.get(session), ref) } }); });
+    server.tool("type", "Type into a text field by ref (replaces its content). Returns the new screen." + CH + " Also gives the field's value after typing.", { session: sid, ref, text: z.string(), enter: z.boolean().optional().describe("Press Enter afterwards"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, ref, text: t, enter, compact, wait_for, timeout_ms, settle }) => { need(session); const tgt = findTarget(trees.get(session), ref); const w = await waiting(session, await act({ session, action: "type", ref, text: t, enter }), { wait_for, timeout_ms, settle }); return acted(session, "type", w.r, { waited: w.waited, compact, ref, step: { action: "type", target: tgt, fieldLabel: tgt?.text, passwordLike: tgt?.passwordLike, text: t } }); });
+    server.tool("scroll", "Scroll the page (down/up) or a horizontal rail (right/left, give the rail's ref). Returns the new screen." + CH, { session: sid, direction: z.enum(["down", "up", "left", "right"]), ref: ref.optional().describe("Scroll inside this element (a rail or list); omit for the page"), compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, direction, ref, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "scroll", direction, ref }), { wait_for, timeout_ms, settle }); return acted(session, "scroll", w.r, { waited: w.waited, compact, step: { action: "scroll", direction } }); });
+    server.tool("back", "Go back one screen." + CH, { session: sid, compact, wait_for: waitFor, timeout_ms: timeoutMs, settle }, WR, async ({ session, compact, wait_for, timeout_ms, settle }) => { need(session); const w = await waiting(session, await act({ session, action: "back" }), { wait_for, timeout_ms, settle }); return acted(session, "back", w.r, { waited: w.waited, compact, step: { action: "back" } }); });
+    server.tool("screenshot", "A PNG of the phone screen (for checking layout, colours, images). The tree from `screen` is usually enough to act.", { session: sid }, RO, async ({ session }) => {
         need(session);
-        const r = await sim("/act", { session, action: "screenshot" });
-        if (!r.ok || !r.path)
-            throw new Error(r.error ?? "no screenshot");
+        const r = await act({ session, action: "screenshot" });
+        if (!r.ok)
+            return result(session, r);
+        if (!r.path)
+            throw new Error("no screenshot");
         return { content: [{ type: "image", data: readFileSync(r.path).toString("base64"), mimeType: "image/png" }, { type: "text", text: r.screen ?? "" }] };
     });
     // The simulated device: what the phone has, and what happens to it.
-    server.tool("set_device", "Change what the simulated phone has: location, a barcode in front of the camera, permission states, whether the fingerprint will match, whether a payment will be approved, network on/off. Takes effect for the next action.", {
+    server.tool("set_device", "Change what the simulated phone has: location, the address book (contacts), calendar events, files for the file picker, a barcode in front of the camera, permission states, whether the fingerprint will match, whether a payment will be approved, network on/off. Takes effect for the next action.", {
         session: sid,
         location: z.object({ latitude: z.number(), longitude: z.number(), accuracy: z.number().optional() }).optional(),
         camera: z.object({ barcode: z.object({ type: z.string(), data: z.string() }).nullable().optional(), delayMs: z.number().optional() }).optional(),
-        permissions: z.object({ camera: z.enum(["granted", "denied", "undetermined"]).optional(), location: z.enum(["granted", "denied", "undetermined"]).optional(), notifications: z.enum(["granted", "denied", "undetermined"]).optional() }).optional(),
+        permissions: z.object({ camera: z.enum(["granted", "denied", "undetermined"]).optional(), location: z.enum(["granted", "denied", "undetermined"]).optional(), notifications: z.enum(["granted", "denied", "undetermined"]).optional(), contacts: z.enum(["granted", "denied", "undetermined"]).optional(), calendar: z.enum(["granted", "denied", "undetermined"]).optional() }).optional(),
+        contacts: z.array(z.object({ id: z.string(), name: z.string(), phoneNumbers: z.array(z.string()).optional(), emails: z.array(z.string()).optional() })).optional().describe("Replace the address book the app can read (needs contacts permission)"),
+        calendar: z.array(z.object({ id: z.string(), title: z.string(), start: z.string().describe("ISO 8601"), end: z.string().describe("ISO 8601"), allDay: z.boolean().optional(), location: z.string().optional(), notes: z.string().optional() })).optional().describe("Replace the calendar events the app can read (needs calendar permission)"),
+        files: z.array(z.object({ name: z.string(), mimeType: z.string(), content: z.string().describe("The file's text") })).optional().describe("Replace the files the file picker offers"),
         biometrics: z.object({ enrolled: z.boolean().optional(), nextResult: z.enum(["success", "fail", "cancel"]).optional() }).optional(),
         payment: z.object({ nextResult: z.enum(["approve", "decline", "timeout", "insufficient_funds"]).optional(), pin: z.string().optional() }).optional(),
         online: z.boolean().optional(),
-    }, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "set_device", device })); });
-    server.tool("push_notification", "Deliver a push notification to the simulated phone; it appears as a banner the agent can tap.", { session: sid, title: z.string(), body: z.string(), data: z.record(z.unknown()).optional() }, async ({ session, title, body, data }) => { need(session); return result(session, await sim("/act", { session, action: "push_notification", title, body, data })); });
-    server.tool("notifications", "The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).", { session: sid }, async ({ session }) => { need(session); return text(JSON.stringify((await sim("/act", { session, action: "notifications" })).notifications ?? [], null, 2)); });
-    server.tool("open_notification", "Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.", { session: sid, id: z.string().optional() }, async ({ session, id }) => { need(session); return result(session, await sim("/act", { session, action: "open_notification", id })); });
-    server.tool("device_log", "What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.", { session: sid }, async ({ session }) => { need(session); const r = await sim("/act", { session, action: "device_log" }); return text(JSON.stringify({ note: "Everything here is simulated: no real biometric check or money movement took place.", capabilities: r.capabilities, log: r.log ?? [] }, null, 2)); });
-    server.tool("device_reset", "Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.", { session: sid, platform: z.enum(["android", "ios"]).optional(), api: z.number().optional() }, async ({ session, ...device }) => { need(session); return result(session, await sim("/act", { session, action: "device_reset", device })); });
-    server.tool("end_session", "Close the session and get a report: steps taken, and the orders the app sent to its backend during the session.", { session: sid }, async ({ session }) => {
+        source: z.enum(["auto", "simulated"]).optional().describe("\"simulated\" forces the simulated camera, microphone and location even when a person could grant the real ones, for reproducible runs"),
+        microphone: z.object({ level: z.number().min(0).max(1).optional() }).optional(),
+    }, WR, async ({ session, ...device }) => { need(session); const r = await act({ session, action: "set_device", device }); if (r.ok)
+        steps.get(session)?.push({ action: "set_device", device: device.payment?.pin === undefined ? device : { ...device, payment: { ...device.payment, pin: undefined } } }); return result(session, r); });
+    server.tool("push_notification", "Deliver a push notification to the simulated phone; it appears as a banner the agent can tap. The app receives it only if notification permission is granted; otherwise nothing is delivered.", { session: sid, title: z.string(), body: z.string(), data: z.record(z.unknown()).optional() }, WR, async ({ session, title, body, data }) => {
+        need(session);
+        const r = await act({ session, action: "push_notification", title, body, data });
+        // The simulator answers ok when permission blocks the push, so say so: otherwise it looks like a delivery.
+        if (r.ok && r.delivered === false)
+            return result(session, { ...r, screen: `Not delivered: notification permission is not granted (use set_device permissions.notifications).\n\n${r.screen ?? ""}` });
+        return result(session, r);
+    });
+    server.tool("notifications", "The notification shade: notifications delivered to the simulated phone in this session (their banners vanish after 5 s, like a heads-up on a real phone).", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "notifications" }); if (!r.ok)
+        return result(session, r); return text(JSON.stringify(r.notifications ?? [], null, 2)); });
+    server.tool("open_notification", "Tap a notification from the shade (newest if no id is given): the app handles it exactly as if its banner was tapped.", { session: sid, id: z.string().optional() }, WR, async ({ session, id }) => { need(session); return result(session, await act({ session, action: "open_notification", id })); });
+    server.tool("open_url", "Open a deep link (such as myapp://item/3) in the running app, as a push tap, auth callback or share link would. Fails with no_url_listener if the app does not listen for URLs.", { session: sid, url: z.string().describe("The URL to deliver, e.g. myapp://item/3") }, { title: "Open a deep link", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, async ({ session, url }) => { need(session); return result(session, await act({ session, action: "open_url", url })); });
+    server.tool("lock", "Press the power button: the simulated phone locks and shows the lock screen. The app and its screen are kept. While locked, tap, type, scroll and back fail with phone_locked. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "lock" })); });
+    server.tool("unlock", "Swipe up on the lock screen. Returns to the same screen as before the lock. Fails with not_locked if the phone is not locked. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "unlock" })); });
+    server.tool("restart", "Restart the simulated phone from the power menu: a boot screen, then the app starts fresh (cold start). Storage is kept. Returns the first screen. Logged in device_log as simulated.", { session: sid }, WR, async ({ session }) => { need(session); return result(session, await act({ session, action: "restart" })); });
+    server.tool("device_log", "What the app did with the device in this session: permission prompts and answers, location reads, scans, fingerprint checks, payments, notifications, shares.", { session: sid }, RO, async ({ session }) => { need(session); const r = await act({ session, action: "device_log" }); if (!r.ok)
+        return result(session, r); return text(JSON.stringify({ note: "Entries marked source \"simulated\" are simulated: no real biometric check or money movement took place. Camera, microphone and location readings marked source \"real\" came from the browser's hardware.", capabilities: r.capabilities, log: r.log ?? [] }, null, 2)); });
+    server.tool("device_reset", "Put the simulated phone back to a known state (permissions undetermined, default location, nothing in front of the camera, log cleared), optionally with a new profile.", { session: sid, platform: z.enum(["android", "ios"]).optional(), api: z.number().optional() }, WR, async ({ session, ...device }) => { need(session); return result(session, await act({ session, action: "device_reset", device })); });
+    server.tool("export_test", "Turn the steps taken in this session (tap, type, scroll, back, set_device) into a @shipvo/test script and return its source. Read-only. Targets are named by their visible text; ambiguous ones become TODO comments and password fields use an environment variable instead of the typed value.", { session: sid }, RO, async ({ session }) => {
+        const rec = steps.get(session), s = sessions.get(session);
+        if (!rec || !s)
+            return result(session, { ok: false, code: "no_session", error: `no session '${session}': call open_app first` });
+        return text(exportTest(s.app, rec));
+    });
+    server.tool("end_session", "Close the session and get a report: steps taken, and the orders the app sent to its backend during the session.", { session: sid }, DEST, async ({ session }) => {
         need(session);
+        const live = attached.get(session);
+        if (live) {
+            const s = sessions.get(session);
+            live.close();
+            attached.delete(session);
+            sessions.delete(session);
+            trees.delete(session);
+            steps.delete(session);
+            return text(JSON.stringify({ session, app: s?.app, mode: "attached", steps: s?.steps ?? 0, seconds: Math.round((Date.now() - (s?.startedAt ?? Date.now())) / 1000) }, null, 2));
+        }
+        // The simulator is the source of truth: end a session it lists even if this server did not open it; otherwise no_session.
+        const listed = await sim("/sessions", {});
+        if (!listed.ok)
+            return result(session, listed);
+        if (!(listed.sessions ?? []).some((x) => x.session === session))
+            return result(session, { ok: false, code: "no_session", error: `no session '${session}': call open_app first` });
         const s = sessions.get(session) ?? { app: session.split("-")[0], steps: 0, startedAt: Date.now() };
         sessions.delete(session);
+        trees.delete(session);
+        steps.delete(session);
         let orders = [];
         try {
             orders = JSON.parse(readFileSync(`${process.env.PN_SIM_DIR ?? "/tmp/pn-ui"}/${session}.json`, "utf8")).orders;
@@ -136,12 +339,71 @@ Finish a task by checking the final screen says what you expected (for example "
         catch { }
         return text(JSON.stringify({ session, app: s.app, steps: s.steps, seconds: Math.round((Date.now() - s.startedAt) / 1000), orders }, null, 2));
     });
+    // Record the phone frame page to an MP4 (one recording per server). Page: SHIPVO_FRAME_URL, default the simulator's root.
+    const recFail = (e) => { if (e instanceof RecorderError)
+        return result("", { ok: false, code: e.code, error: e.message }); throw e; };
+    server.tool("record_start", "Start recording the phone frame to an MP4 under .shipvo/recordings/. Use record_marker for chapters and record_stop to finish.", {
+        format: z.enum(["9:16", "16:9", "1:1"]).optional().describe("Video shape (default 9:16: 1080x1920; 16:9 is 1920x1080; 1:1 is 1080x1080)"),
+        fps: z.union([z.literal(30), z.literal(60)]).optional().describe("Frames per second (default 30)"),
+        title: z.string().optional().describe("Used in the file name"),
+    }, WR, async ({ format, fps, title }) => {
+        try {
+            const r = await recorder.start({ url: process.env.SHIPVO_FRAME_URL ?? SIM + "/", format, fps, title });
+            return { ...text(`recording to ${r.file} (${r.width}x${r.height})`), structuredContent: r };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
+    server.tool("record_marker", "Add a chapter at the current time of the running recording.", { caption: z.string().min(1) }, WR, async ({ caption }) => {
+        try {
+            const c = recorder.marker(caption);
+            return { ...text(`marker at ${c.t}s: ${c.caption}`), structuredContent: c };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
+    server.tool("record_stop", "Stop the recording and write the MP4. Returns the file, duration in seconds, size and chapters.", {}, WR, async () => {
+        try {
+            const r = await recorder.stop();
+            return { ...text(JSON.stringify(r, null, 2)), structuredContent: r };
+        }
+        catch (e) {
+            return recFail(e);
+        }
+    });
+    // Publish the app's web build to here.now (no account) through the CLI, which builds, wraps and checks for secrets.
+    server.tool("publish_preview", "Build the app in PN_APP_DIR (or the current folder) with the simulated device and publish a shareable web preview to here.now, no account. The link is PUBLIC and expires in 24 hours; claimUrl keeps it. Returns { url, claimUrl, expiresAt }. Needs @shipvo/cli (npx).", {}, { title: "Publish a public preview", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async () => {
+        if (ctx.scope && ctx.scope !== "owner" && ctx.scope !== "test")
+            throw new Error(`this key has scope "${ctx.scope}": it cannot publish a preview`);
+        const cwd = process.env.PN_APP_DIR || process.cwd();
+        const out = await new Promise((resolve, reject) => execFile("npx", ["-y", "@shipvo/cli", "preview", "--json"], { cwd, timeout: 600000, maxBuffer: 4 << 20 }, (err, so, se) => (err ? reject(new Error(String(se || err.message).trim().split("\n").slice(-3).join(" "))) : resolve(so))));
+        const r = JSON.parse(out.trim().split("\n").pop() ?? "{}");
+        const sc = { url: r.url, claimUrl: (r.claimUrl ?? null), expiresAt: (r.expiresAt ?? null) };
+        return { ...text(JSON.stringify({ ...sc, note: "Public link, expires in 24 hours unless claimUrl is opened and the owner signs in to here.now. Share claimUrl byte for byte." }, null, 2)), structuredContent: sc };
+    });
     // Owner side: the same typed commands the admin at /app/<id>/admin uses.
-    server.tool("owner_describe", "List the owner commands of an app (content, prices, offers, orders, publish). Needs PN_OWNER_TOKEN.", { app: z.string() }, async ({ app }) => {
+    server.tool("owner_describe", "List the owner commands of an app (content, prices, offers, orders, publish). Needs PN_OWNER_TOKEN.", { app: z.string() }, RO, async ({ app }) => {
         const r = await fetch(`${CONTROL}/app/${app}/api/describe`);
         return text(await r.text());
     });
-    server.tool("owner_command", "Run an owner command against the live app (changes are audited; `publish` makes them live on every phone within seconds).", { app: z.string(), command: z.string(), args: z.record(z.unknown()).optional() }, async ({ app, command, args }) => {
+    // The owner's agent rules from shipvo.json (agentPolicy, agentDeny) in PN_APP_DIR or the current folder. Sent to the control plane, which only lets them tighten its own rules.
+    function agentRules() {
+        try {
+            const c = JSON.parse(readFileSync(join(process.env.PN_APP_DIR || process.cwd(), "shipvo.json"), "utf8"));
+            const h = {};
+            if (["ask", "deny", "allow"].includes(c.agentPolicy))
+                h["x-shipvo-agent-policy"] = c.agentPolicy;
+            if (Array.isArray(c.agentDeny) && c.agentDeny.length)
+                h["x-shipvo-agent-deny"] = c.agentDeny.map(String).join(",");
+            return h;
+        }
+        catch {
+            return {};
+        }
+    }
+    server.tool("owner_command", "Run an owner command against the live app (changes are audited). Commands that cannot be undone or reach users (publish, prices, offers, deletes, API keys) do nothing and return { code: \"needs_confirm\", plan } first: show the plan to the owner, then call again with the same args and confirm: true.", { app: z.string(), command: z.string(), args: z.record(z.unknown()).optional(), confirm: z.boolean().optional().describe("true to run a command that returned needs_confirm; pass the same args") }, DEST, async ({ app, command, args, confirm }) => {
         if (ctx.scope && ctx.scope !== "owner")
             throw new Error(`this key has scope "${ctx.scope}": owner commands need an owner key`);
         if (keyApps && !keyApps.includes(app))
@@ -149,7 +411,7 @@ Finish a task by checking the final screen says what you expected (for example "
         const token = ctx.ownerToken || OWNER_TOKEN;
         if (!token)
             throw new Error("owner commands are not enabled on this server.");
-        const r = await fetch(`${CONTROL}/app/${app}/api/command`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${token}` }, body: JSON.stringify({ name: command, args: args ?? {} }) });
+        const r = await fetch(`${CONTROL}/app/${app}/api/command`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${token}`, ...agentRules() }, body: JSON.stringify({ name: command, args: { ...Object.fromEntries(Object.entries(args ?? {}).filter(([k]) => k !== "confirm")), ...(confirm === true ? { confirm: true } : {}) } }) });
         return text(await r.text());
     });
     return server;
@@ -162,12 +424,14 @@ if (argi < 0) {
 else {
     const port = Number(process.argv[argi + 1] || 8787);
     const keys = new Set((process.env.PN_API_KEYS ?? "").split(",").map((k) => k.trim()).filter(Boolean));
-    const transports = new Map();
+    // Stateless (MCP 2026-07-28, and fine for 2025-era clients): no protocol session. Every request gets its own
+    // McpServer and transport, built from that request's x-shipvo-* headers, so scope never outlives the request.
+    // Simulator sessions are separate: they live in the simulator and travel as the `session` tool argument.
     const httpServer = http.createServer(async (req, res) => {
         const url = new URL(req.url ?? "/", "http://x");
         if (url.pathname === "/health") {
             res.writeHead(200, { "content-type": "application/json" });
-            return res.end(JSON.stringify({ ok: true, sessions: transports.size }));
+            return res.end(JSON.stringify({ ok: true }));
         }
         if (url.pathname !== "/mcp") {
             res.writeHead(404);
@@ -181,30 +445,63 @@ else {
                 return res.end(JSON.stringify({ error: "invalid_api_key" }));
             }
         }
-        const sid = req.headers["mcp-session-id"];
-        let transport = sid ? transports.get(sid) : undefined;
-        if (!transport) {
-            if (req.method !== "POST") {
-                res.writeHead(400);
-                return res.end("missing session");
-            }
-            transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, transport); } });
-            transport.onclose = () => { for (const [id, t] of transports)
-                if (t === transport)
-                    transports.delete(id); };
-            // One McpServer per client connection. Behind sim.shipvo.dev the Worker has checked the key and says which
-            // app and scope it grants; locally there are no such headers and every app is allowed.
-            const scope = req.headers["x-shipvo-scope"];
-            await makeServer({ app: req.headers["x-shipvo-app"] || undefined, publicApps: req.headers["x-shipvo-public"] || undefined, scope, ownerToken: req.headers["x-shipvo-owner-token"] || undefined }).connect(transport);
-        }
-        let body = undefined;
-        if (req.method === "POST") {
+        // No server-initiated streams and nothing to close without sessions.
+        if (req.method !== "POST") {
+            res.writeHead(405, { allow: "POST", "content-type": "application/json" });
+            return res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed: this server is stateless, use POST" }, id: null }));
+        }
+        let body;
+        try {
             let raw = "";
             for await (const ch of req)
                 raw += ch;
             body = raw ? JSON.parse(raw) : undefined;
         }
-        await transport.handleRequest(req, res, body);
+        catch {
+            res.writeHead(400, { "content-type": "application/json" });
+            return res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }));
+        }
+        // MCP 2026-07-28: answer server/discover, and refuse requests whose Mcp-Method/Mcp-Name headers disagree with the body.
+        const bad = (code, message, id = null) => { res.writeHead(400, { "content-type": "application/json" }); return res.end(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id })); };
+        const msg = body && typeof body === "object" && !Array.isArray(body) ? body : undefined;
+        if (msg && typeof msg.method === "string") {
+            const hm = req.headers["mcp-method"], hn = req.headers["mcp-name"];
+            const meta = (msg.params?._meta ?? {});
+            const pv = Object.entries(meta).find(([k]) => /protocolversion$/i.test(k))?.[1];
+            const era2026 = msg.method === "server/discover" || hm !== undefined || (typeof pv === "string" && pv >= "2026-07-28");
+            if (era2026) {
+                if (hm === undefined)
+                    return bad(-32001, "Missing Mcp-Method header", msg.id ?? null);
+                if (hm !== msg.method)
+                    return bad(-32001, `Header mismatch: Mcp-Method is '${hm}' but the body method is '${msg.method}'`, msg.id ?? null);
+                const nameKey = msg.method === "tools/call" || msg.method === "prompts/get" ? "name" : msg.method === "resources/read" ? "uri" : undefined;
+                const want = nameKey ? msg.params?.[nameKey] : undefined;
+                if (nameKey && hn === undefined)
+                    return bad(-32001, "Missing Mcp-Name header", msg.id ?? null);
+                if (hn !== undefined && hn !== want)
+                    return bad(-32001, `Header mismatch: Mcp-Name is '${hn}' but the body says '${String(want)}'`, msg.id ?? null);
+            }
+            if (msg.method === "server/discover") {
+                res.writeHead(200, { "content-type": "application/json" });
+                return res.end(JSON.stringify({ jsonrpc: "2.0", id: msg.id ?? null, result: { supportedVersions: SUPPORTED_VERSIONS, capabilities: { tools: { listChanged: false } }, serverInfo: { name: "shipvo", version: SERVER_VERSION } } }));
+            }
+        }
+        // Behind sim.shipvo.dev the Worker has checked the key and says which app and scope it grants; locally
+        // there are no such headers and every app is allowed. A client's mcp-session-id header is ignored.
+        const h = (n) => req.headers[n] || undefined;
+        const server = makeServer({ app: h("x-shipvo-app"), publicApps: h("x-shipvo-public"), scope: h("x-shipvo-scope"), ownerToken: h("x-shipvo-owner-token") });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on("close", () => { void transport.close(); void server.close(); });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (e) {
+            if (!res.headersSent) {
+                res.writeHead(500, { "content-type": "application/json" });
+                res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: "Internal error" }, id: null }));
+            }
+        }
     });
     httpServer.listen(port, () => console.error(`Shipvo MCP over HTTP on http://localhost:${port}/mcp (${keys.size ? keys.size + " key(s)" : "no auth"})`));
 }

package/dist/wait.d.ts

@@ -0,0 +1,15 @@
+export type WaitFor = {
+    ref?: string;
+    text?: string;
+    role?: string;
+    name?: string;
+    gone?: boolean;
+};
+export type Waited = {
+    matched: boolean;
+    ms: number;
+};
+export declare function present(tree: string, w: WaitFor): boolean;
+export declare const wantsMatch: (w: WaitFor) => boolean;
+export declare const satisfied: (tree: string, w: WaitFor) => boolean;
+export declare const sameTree: (a: string, b: string) => boolean;

package/dist/wait.js

@@ -0,0 +1,17 @@
+// wait_for and settle: pure matching on screen trees. No I/O.
+import { parse, unquoteLine } from "./record.js";
+// True when the thing wait_for describes is on the screen (ignoring `gone`).
+export function present(tree, w) {
+    const ls = tree.split("\n").filter((l) => l.trim());
+    if (w.ref)
+        return ls.some((l) => unquoteLine(l).includes(`[ref=${w.ref}]`));
+    if (w.text)
+        return ls.some((l) => (parse(l)?.text ?? "").includes(w.text));
+    if (w.role && w.name)
+        return ls.some((l) => { const p = parse(l); return !!p && p.role === w.role && p.text.includes(w.name); });
+    return false;
+}
+export const wantsMatch = (w) => !!(w.ref || w.text || (w.role && w.name));
+export const satisfied = (tree, w) => present(tree, w) !== !!w.gone;
+// Two reads are equal when they differ only in ref numbers.
+export const sameTree = (a, b) => a.replace(/\s*\[ref=\w+\]/g, "") === b.replace(/\s*\[ref=\w+\]/g, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/mcp",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "license": "Apache-2.0",
   "description": "MCP server that lets AI agents open, see and operate Shipvo apps without a phone: a phone-sized simulator of the real app, plus the app's typed commands and owner API.",
@@ -15,7 +15,8 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "@types/node": "^22.8.0",
-    "vitest": "^2.1.4"
+    "vitest": "^2.1.4",
+    "playwright": "1.63.0"
   },
   "keywords": [
     "mcp",
@@ -45,6 +46,14 @@
     "node": ">=20"
   },
   "mcpName": "io.github.shipvo/shipvo",
+  "peerDependencies": {
+    "playwright": ">=1.50"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "vitest run"