@shipvo/mcp 0.0.6 → 0.0.8

package/README.md

@@ -8,14 +8,55 @@ Lets AI agents (Claude, Cursor, Claude Code, PiPilot…) **use a Shipvo app with
   "env": { "PN_SIM": "http://localhost:4545", "PN_OWNER_TOKEN": "…optional…" } } } }
 ```
 
-Start the simulator first (`shipvo sim` in the app). The hosted version needs no local setup: `{ "url": "https://<host>/mcp/<key>" }`.
+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. |
+| `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 +71,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`. Not done yet: `server/discover`, the `Mcp-Method`/`Mcp-Name` headers, `ttlMs`/`cacheScope` on list results. `tools/list` order is fixed (registration order).
+- This package uses `@modelcontextprotocol/sdk` 1.x. 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/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/server.js

@@ -3,31 +3,103 @@
 //   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 { 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: one app served by the simulator.
-const APPS = process.env.PN_APPS ? JSON.parse(process.env.PN_APPS)
-    : { tide: { name: "Tide & Tackle", description: "Fishing-supplies shop in Douala: catalogue, cart, promo codes, delivery slots, cash or mobile money." } };
+// 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: "{}", signal: AbortSignal.timeout(simTimeoutMs()) });
+        if (r.ok) {
+            const out = {};
+            for (const a of (await r.json()).apps ?? [])
+                out[a.id] = { name: a.name ?? a.id, description: "The app this simulator serves." };
+            if (Object.keys(out).length)
+                return out;
+        }
+    }
+    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 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.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) => { };
@@ -39,8 +111,9 @@ System sheets (permission dialogs, the camera, the fingerprint prompt, payment p
 Finish a task by checking the final screen says what you expected (for example "Order placed"). Call end_session when done to get a report.` });
     // 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 = (id) => (keyApps ? keyApps.includes(id) : !!APPS[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 }) => {
+    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() }, RO, async ({ query }) => {
+        const APPS = await localApps();
         const ids = keyApps ?? Object.keys(APPS);
         const q = (query ?? "").toLowerCase();
         let dir = {};
@@ -63,55 +136,132 @@ 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 }) => {
+    }, WR, async ({ app, session, seed_cart, dark }) => {
         const id = app.split("@")[0];
-        if (!allowed(id))
-            throw new Error(keyApps ? `this key opens: ${keyApps.join(", ")}` : `unknown app "${id}". Apps: ${Object.keys(APPS).join(", ")}`);
+        if (!(await allowed(id)))
+            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 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() });
+        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"}\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 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("After the action, 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");
+    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 sim("/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 sim("/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, { 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 sim("/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 sim("/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 sim("/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 sim("/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");
+        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 }) => {
+    }, WR, async ({ session, ...device }) => { need(session); const r = await sim("/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 sim("/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 sim("/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 sim("/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 sim("/act", { session, action: "open_url", url })); });
+    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 sim("/act", { session, action: "device_log" }); if (!r.ok)
+        return result(session, r); 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() }, WR, async ({ session, ...device }) => { need(session); return result(session, await sim("/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);
+        // 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;
@@ -119,12 +269,37 @@ 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));
     });
+    // 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))
@@ -132,7 +307,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;
@@ -145,12 +320,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);
@@ -164,30 +341,38 @@ 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);
+        // 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 = undefined;
-        if (req.method === "POST") {
+        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 }));
+        }
+        // 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.6",
+  "version": "0.0.8",
   "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.",
@@ -14,7 +14,8 @@
   },
   "devDependencies": {
     "typescript": "^5.6.3",
-    "@types/node": "^22.8.0"
+    "@types/node": "^22.8.0",
+    "vitest": "^2.1.4"
   },
   "keywords": [
     "mcp",
@@ -45,6 +46,7 @@
   },
   "mcpName": "io.github.shipvo/shipvo",
   "scripts": {
-    "build": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
   }
 }