@flowriki/agent 0.1.0-beta.44 → 0.1.0-beta.46

package/dist/cli.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 import {
   AGENT_VERSION,
+  CLOUD_PROVIDERS,
+  CLOUD_PROVIDER_NAME,
+  MobileLane,
   RecordedStepSchema,
   authenticationResolver,
   checkAssertion,
+  checkMobileAssertion,
   closeRunSession,
   connect,
   connectionFor,
@@ -12,18 +16,32 @@ import {
   executeStep,
   fieldNames,
   helperRunner,
+  isMobile,
+  listDevices,
+  locate,
   mirrorCheckTargets,
+  mobileDoctor,
+  mobileOf,
+  mobileSetup,
+  openMobileSession,
   openRunSession,
   parseGherkin,
+  performMobileStep,
+  platformsOf,
   prepareBrowsers,
   replayCase,
   replayFlow,
+  replayMobileCase,
   resolveCheckouts,
   resolveService,
+  runMobileSteps,
   runtimeValue,
+  screenLines,
   start,
-  status
-} from "./chunk-E24RRF2Q.js";
+  status,
+  stepRefusedOn,
+  targetFor
+} from "./chunk-LIURHWRP.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -154,10 +172,12 @@ var ServiceClient = class {
   catalog(projectId) {
     return this.call(`/api/agent/catalog?projectId=${encodeURIComponent(projectId)}`);
   }
-  prepare(projectId, steps, signIn) {
+  /** `cloud` asks for that device farm's access key too, for a flow written
+   *  on one of its phones. */
+  prepare(projectId, steps, signIn, extra = {}) {
     return this.call(`/api/agent/prepare?projectId=${encodeURIComponent(projectId)}`, {
       method: "POST",
-      body: JSON.stringify({ steps, ...signIn ? { signIn } : {} })
+      body: JSON.stringify({ steps, ...signIn ? { signIn } : {}, ...extra.cloud ? { cloud: extra.cloud } : {} })
     });
   }
   /** This person's open branches that Claude wrote on this project. */
@@ -230,6 +250,17 @@ var ServiceClient = class {
       { method: "POST", body: JSON.stringify(body) }
     );
   }
+  updateRequest(projectId, id) {
+    return this.call(
+      `/api/agent/update-requests/${encodeURIComponent(id)}?projectId=${encodeURIComponent(projectId)}`
+    );
+  }
+  proposeUpdates(projectId, id, body) {
+    return this.call(
+      `/api/agent/update-requests/${encodeURIComponent(id)}/proposals?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+  }
   readCases(projectId, refs) {
     const ids = refs.filter((r) => /^tc_/.test(r.trim()));
     const names = refs.filter((r) => !/^tc_/.test(r.trim()));
@@ -350,7 +381,31 @@ var STEP_TIMEOUT_MS = 1e4;
 var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b/i;
 var TYPED = "typed_";
 var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
-var ACTIONS = ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"];
+var ACTIONS = [
+  "click",
+  "dblclick",
+  "rightclick",
+  "hover",
+  "fill",
+  "select",
+  "check",
+  "press",
+  "navigate",
+  "back",
+  "forward",
+  // On a phone: a tap is a click, and these have no web equivalent.
+  "tap",
+  "longPress",
+  "swipe",
+  "scroll",
+  "hideKeyboard",
+  "launchApp",
+  "terminateApp",
+  "resetApp",
+  "background",
+  "rotate",
+  "permission"
+];
 var isAction = (value) => ACTIONS.includes(String(value));
 var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
 function scopeOf(within) {
@@ -393,6 +448,24 @@ function numberDuplicates(tree) {
     return `${l}  [nth ${at} of ${total} with this name]`;
   }).join("\n");
 }
+function deviceFrom(said, platform, devices, mobile) {
+  const want = said?.trim();
+  if (!want) return mobile?.devices[platform];
+  const lower = want.toLowerCase();
+  const mine = devices.filter((d) => d.platform === platform);
+  const local = mine.find((d) => d.id.toLowerCase() === lower || d.name.toLowerCase() === lower) ?? mine.find((d) => d.name.toLowerCase().includes(lower));
+  if (local) return { kind: "local", id: local.id, name: local.name };
+  const farm = /^([^:]+):\s*(.+?)(?:\s+(\d+(?:\.\d+)*))?$/.exec(want);
+  const provider = farm && CLOUD_PROVIDERS.find((p) => p === farm[1].trim().toLowerCase().replace(/\s+/g, "") || CLOUD_PROVIDER_NAME[p].toLowerCase() === farm[1].trim().toLowerCase());
+  if (farm && provider) {
+    if (!mobile?.cloud.some((c) => c.provider === provider)) throw new Error(`${CLOUD_PROVIDER_NAME[provider]} is not connected to this project \u2014 add it in Settings \u2192 Mobile`);
+    return { kind: "cloud", provider, device: farm[2].trim(), ...farm[3] ? { osVersion: farm[3] } : {} };
+  }
+  throw new Error(`no ${platform === "ios" ? "iOS" : "Android"} device called "${want}" \u2014 connected: ${mine.map((d) => d.name).join(", ") || "none"}`);
+}
+async function devicesSummary() {
+  return listDevices().catch(() => []);
+}
 function describeRows(rows) {
   return rows.map((r) => [
     `Row ${r.row}: "${r.flow}" (${r.browser})`,
@@ -420,6 +493,26 @@ function describe(step) {
       return `check ${step.proposals.map((p) => `${p.kind}${p.op && p.op !== "equals" ? ` ${p.op}` : ""} "${String(p.value)}"${p.target?.name ? ` on ${p.target.role} "${p.target.name}"` : ""}`).join(", ")}`;
     case "useHelper":
       return `use helper ${step.name || step.helper?.helperId} \u2192 {{${step.helper?.saveAs}}}${step.helper?.then === "open" ? ", then open it" : ""}`;
+    case "swipe":
+      return `swipe ${step.value}${target ? ` on ${target}` : ""}`;
+    case "scroll":
+      return target ? `scroll to ${target}` : `scroll ${step.value}`;
+    case "longPress":
+      return `long-press ${target}${where}`;
+    case "hideKeyboard":
+      return "hide the keyboard";
+    case "launchApp":
+      return "open the app";
+    case "terminateApp":
+      return "close the app";
+    case "resetApp":
+      return "clear the app's data and open it";
+    case "background":
+      return `send the app to the background for ${step.value || 3}s`;
+    case "rotate":
+      return `rotate to ${step.value}`;
+    case "permission":
+      return `${step.value === "deny" ? "deny" : "allow"} the permission prompt`;
     default:
       return `${step.type} ${target}${where}`;
   }
@@ -433,6 +526,8 @@ var AuthoringSession = class {
   opts;
   run = null;
   page = null;
+  /** The phone, when the flow being written runs on one. */
+  mobile = null;
   values = /* @__PURE__ */ new Map();
   resolvers = null;
   lastTree = null;
@@ -454,7 +549,11 @@ var AuthoringSession = class {
     return out;
   }
   get open() {
-    return this.run !== null;
+    return this.run !== null || this.mobile !== null;
+  }
+  requireMobile() {
+    if (!this.mobile || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { mobile: this.mobile, draft: this.draft };
   }
   requireOpen() {
     if (!this.run || !this.page || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
@@ -465,7 +564,12 @@ var AuthoringSession = class {
    *  helper or sign-in appears, never kept beyond this process. */
   async prepare(extra = []) {
     const draft = this.draft;
-    const prepared = await this.service.prepare(draft.projectId, withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]), draft.signIn ?? null);
+    const prepared = await this.service.prepare(
+      draft.projectId,
+      withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]),
+      draft.signIn ?? null,
+      draft.device?.kind === "cloud" ? { cloud: draft.device.provider } : {}
+    );
     const runHelper = helperRunner(prepared.helpers, prepared.secrets);
     this.resolvers = {
       resolveAuth: authenticationResolver(prepared.authentications),
@@ -487,6 +591,7 @@ var AuthoringSession = class {
     this.values = /* @__PURE__ */ new Map();
     this.typed = /* @__PURE__ */ new Map();
     this.lastTree = null;
+    if (isMobile(input.platform)) return this.startMobile(input.platform, catalog);
     const base = this.baseUrl();
     this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
     this.page = this.run.page;
@@ -549,17 +654,7 @@ var AuthoringSession = class {
    * the page is new, the page itself, capped. read_page is always the whole
    * thing. */
   async view(full) {
-    const { page, draft } = this.requireOpen();
-    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
-    const tree = numberDuplicates(labelTree(
-      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
-      await fieldNames(page)
-    ));
-    const title = await page.title().catch(() => "");
-    const head = `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
-Steps so far: ${draft.steps.length}
-
-`;
+    const { tree, head } = this.mobile ? await this.mobileTree() : await this.webTree();
     const before = this.lastTree;
     this.lastTree = tree;
     const cap = (t, max) => t.length > max ? `${t.slice(0, max)}
@@ -584,8 +679,24 @@ ${removed.join("\n")}` : "",
       "(changes since the last step \u2014 read_page shows the whole page)"
     ].filter(Boolean).join("\n");
   }
+  async webTree() {
+    const { page, draft } = this.requireOpen();
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    const tree = numberDuplicates(labelTree(
+      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
+      await fieldNames(page)
+    ));
+    const title = await page.title().catch(() => "");
+    return { tree, head: `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
   /** Do one thing on the page, and keep it as a step if it worked. */
   async act(input) {
+    if (this.mobile) return this.mobileAct(input);
+    const refused = stepRefusedOn(input.action === "tap" ? "click" : input.action, "web");
+    if (refused) throw new Error(refused);
     const { page, draft, run } = this.requireOpen();
     const navigating = input.action === "navigate" || input.action === "back" || input.action === "forward";
     if (!navigating && input.action !== "press" && !(input.role && input.name)) {
@@ -639,6 +750,7 @@ ${await this.view(false)}`;
   }
   /** Check something about the page now, and keep the check if it holds. */
   async check(input) {
+    if (this.mobile) return this.mobileCheck(input);
     const { page, draft } = this.requireOpen();
     if ((input.kind === "heading" || input.kind === "message" || input.kind === "screen") && input.op && input.op !== "equals" && !input.role) {
       throw new Error(`a ${input.kind} check without role and name matches the whole ${input.kind} \u2014 give its full text with op equals, or name the element (role + name) and use kind "text" with op ${input.op}`);
@@ -674,6 +786,7 @@ ${await this.view(false)}`;
   /** Get a value from outside the page — an email code, a 2FA code, a text,
    *  an API reply — and keep the step that gets it. */
   async useHelper(input) {
+    if (this.mobile) return this.mobileHelper(input);
     const { page, draft, run } = this.requireOpen();
     const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
     if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
@@ -725,7 +838,8 @@ ${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
   /** Drop a step from the draft. The browser is not wound back — replay to
    *  see the flow as it now stands. */
   remove(number) {
-    const { draft } = this.requireOpen();
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
     if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
     const [gone] = draft.steps.splice(number - 1, 1);
     return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
@@ -735,6 +849,7 @@ ${this.list()}`;
   /** Run the whole draft from the start, in a browser of its own, the way a
    *  run will — the proof the steps work together, not just one at a time. */
   async replay() {
+    if (this.mobile) return this.mobileReplay();
     const { draft } = this.requireOpen();
     if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
     const resolvers = await this.prepare();
@@ -750,7 +865,8 @@ ${lines.join("\n")}`;
   }
   /** Save the draft as a flow on a new branch, for a person to review. */
   async save(title, where = {}) {
-    const { draft } = this.requireOpen();
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
     if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
     if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
       throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
@@ -766,6 +882,7 @@ ${lines.join("\n")}`;
       name: draft.name,
       ...draft.featureId ? { featureId: draft.featureId } : { featureName: draft.featureName },
       startPath: draft.startPath,
+      ...isMobile(draft.platform) ? { platform: draft.platform } : {},
       steps: withoutTyped(checksOff),
       ...draft.signIn ? { signIn: draft.signIn } : {},
       ...draft.after?.length ? { prerequisites: draft.after.map((a) => ({ flowId: a.flowId })) } : {}
@@ -799,8 +916,26 @@ ${describeRows(built.rows)}`;
     const prepared = await this.service.prepare(projectId, steps, null);
     const runHelper = helperRunner(prepared.helpers, prepared.secrets);
     const base = catalog.baseUrl;
-    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
-    const outcome = await replayCase({
+    const phoneRows = testCase.occurrences.filter((o) => isMobile(o.platform));
+    if (!base && phoneRows.length < testCase.occurrences.length) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    const laneOptions = {
+      mobile: catalog.mobile ?? mobileOf(null),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      resolveAuth: authenticationResolver(prepared.authentications),
+      ...runHelper ? { runHelper } : {}
+    };
+    const lane = phoneRows.length ? new MobileLane(laneOptions) : null;
+    const opened = /* @__PURE__ */ new Set();
+    const outcome = phoneRows.length === testCase.occurrences.length ? await replayMobileCase({ ...laneOptions, occurrences: testCase.occurrences, ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {} }) : await replayCase({
+      ...lane ? {
+        runElsewhere: (occurrence, ctx) => {
+          if (!isMobile(occurrence.platform)) return null;
+          const key = occurrence.actorId ?? testCase.defaultActorId ?? "default";
+          const first = !opened.has(key);
+          opened.add(key);
+          return lane.run(occurrence, { deviceKey: key, first, ...ctx });
+        }
+      } : {},
       occurrences: testCase.occurrences,
       ...testCase.actors ? { actors: testCase.actors } : {},
       ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {},
@@ -809,7 +944,7 @@ ${describeRows(built.rows)}`;
       resolveAuth: authenticationResolver(prepared.authentications),
       resolveSecret: (ref) => prepared.secrets[ref],
       ...runHelper ? { runHelper } : {}
-    });
+    }).finally(() => lane?.close());
     const lines = outcome.occurrences.map((o, i) => {
       const failed = o.steps.find((st) => st.status === "failed");
       const why = o.status === "failed" ? `: ${failed ? `step "${failed.name || failed.type}" \u2014 ${(failed.detail ?? "").split("\n")[0]}` : (o.error ?? "").split("\n")[0]}` : "";
@@ -829,11 +964,196 @@ Review and publish it here: ${review}`;
   }
   async close() {
     const run = this.run;
+    const mobile = this.mobile;
     this.run = null;
     this.page = null;
+    this.mobile = null;
     this.resolvers = null;
+    if (mobile) await mobile.close().catch(() => void 0);
     if (run) await closeRunSession(run, { passed: true }).catch(() => void 0);
   }
+  // ── On a phone ────────────────────────────────────────────────────────
+  /** Open the project's app on the chosen phone, signed in and brought to
+   *  where the flow starts, as on the web. */
+  async startMobile(platform, catalog) {
+    const draft = this.draft;
+    const mobile = catalog.mobile;
+    if (!mobile) throw new Error("this project has no phone apps set up \u2014 turn on Android or iOS in Settings \u2192 Mobile");
+    const resolvers = draft.signIn || draft.device?.kind === "cloud" ? await this.prepare() : null;
+    this.mobile = await openMobileSession({
+      platform,
+      mobile,
+      ...draft.device ? { device: draft.device } : {},
+      ...resolvers ? { resolveSecret: resolvers.resolveSecret } : {}
+    });
+    const opening = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? []
+    ];
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await this.mobile.openLink(draft.startPath);
+    if (opening.length) {
+      const ready = await this.prepare(draft.preparation ?? []);
+      const done = await runMobileSteps(this.mobile, opening, { values: this.values, ...ready });
+      if (done.status !== "passed") throw new Error(`The app could not be brought to where this flow starts: ${done.error}`);
+    }
+    return this.snapshot();
+  }
+  async mobileTree() {
+    const { mobile, draft } = this.requireMobile();
+    mobile.changed();
+    let screen = await mobile.screen();
+    if (screen.nodes.length === 0) screen = await mobile.settle(8e3);
+    const where = await mobile.currentScreenName();
+    const tree = numberDuplicates(screenLines(screen)) || "(nothing on the screen can be read \u2014 the app may still be loading, or draws without accessibility labels)";
+    return { tree, head: `Screen: ${screen.app || mobile.appId} on ${mobile.deviceName}${where ? ` \u2014 ${where}` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
+  mobileResolvers() {
+    return {
+      values: this.values,
+      ...this.resolvers ?? {},
+      resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref)
+    };
+  }
+  async mobileAct(input) {
+    const { mobile, draft } = this.requireMobile();
+    const type = input.action === "tap" ? "click" : input.action;
+    const refused = stepRefusedOn(type, mobile.platform);
+    if (refused) throw new Error(refused);
+    const needsElement = ["click", "longPress", "fill", "select", "check"].includes(type);
+    if (needsElement && !(input.role && (input.name || input.nth !== void 0))) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((type === "fill" || type === "select" || type === "navigate") && input.value === void 0) throw new Error(`${input.action} needs a value`);
+    let target = { role: "", name: "" };
+    let password = false;
+    if (input.role) {
+      const asked = { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} };
+      try {
+        const found = await locate(mobile, asked, STEP_TIMEOUT_MS, { scroll: type !== "swipe" });
+        target = { ...targetFor(found.screen, found.node), ...asked };
+        password = found.node.password;
+      } catch (error) {
+        const said = error.message.split("\n")[0] ?? "";
+        const several = /elements match/.test(said) ? "\nSeveral elements share this role and name. Pass nth (0 = the first, in the order read_page lists them) to say which one." : "";
+        throw new Error(`That did not work, and was not kept: ${said}${several}
+
+${await this.view(false)}`);
+      }
+    }
+    const secret = type === "fill" && (input.secret ?? (password || SECRET_WORDS.test(input.name ?? "")));
+    const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
+    if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
+    const value = secret ? "" : type === "check" ? input.value === "false" ? "false" : "true" : type === "swipe" || type === "scroll" && !input.role ? (input.value || "up").toLowerCase() : input.value ?? "";
+    const step = RecordedStepSchema.parse({
+      id,
+      type,
+      ...target,
+      value,
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
+      legacySelector: "",
+      proposals: []
+    });
+    try {
+      await performMobileStep(mobile, step, this.mobileResolvers());
+    } catch (error) {
+      if (secret) this.typed.delete(`${TYPED}${id}`);
+      throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
+
+${await this.view(false)}`);
+    }
+    await new Promise((r) => setTimeout(r, 600));
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.view(false)}`;
+  }
+  async mobileCheck(input) {
+    const { mobile, draft } = this.requireMobile();
+    if (input.kind === "url" || input.kind === "title") throw new Error(`a phone app has no ${input.kind === "url" ? "address" : "page title"} \u2014 check text on the screen (message), a heading's text, or an element`);
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkMobileAssertion(mobile, { ...assertion, value: expected }, 5e3);
+    } catch (error) {
+      throw new Error(`That is not true of the screen right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse(mirrorCheckTargets([{
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    }])[0]);
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  async mobileHelper(input) {
+    const { mobile, draft } = this.requireMobile();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    await this.prepare([step]);
+    let got;
+    try {
+      got = await performMobileStep(mobile, step, this.mobileResolvers());
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got?.value ?? ""}" (${got?.detail ?? ""}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.view(false)}` : "");
+  }
+  /** The whole flow again from the app's start, on the same phone — a phone
+   *  holds one session at a time, so the app is closed and opened rather than
+   *  a second device started. */
+  async mobileReplay() {
+    const { mobile, draft } = this.requireMobile();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
+      ...draft.steps
+    ];
+    await mobile.terminateApp().catch(() => void 0);
+    await mobile.launchApp();
+    await mobile.settle();
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await mobile.openLink(draft.startPath);
+    const outcome = await runMobileSteps(mobile, steps, { values: /* @__PURE__ */ new Map(), ...resolvers, resolveSecret: (ref) => this.typed.get(ref) ?? resolvers.resolveSecret(ref) });
+    this.lastTree = null;
+    const lines = outcome.results.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    return `${outcome.status === "passed" ? "The whole flow passed from the app's start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
   /** Let a click's consequences land before the page is read again. */
   async settle() {
     const page = this.page;
@@ -905,16 +1225,45 @@ as learned. Keep what you learn with write_knowledge (features/<name>.md,
 memory/decisions.md, a session summary), on Claude's branch for review \u2014
 never a password, key or token.
 
+UPDATING TEST CASES: when asked to update test cases (upd_\u2026), read the
+request with read_update_request, then propose_case_updates with each changed
+case's complete new steps \u2014 keep what the change does not touch word for
+word, so the person sees exactly what moved. Leave out cases that need no
+change. You never change a test case yourself; the person accepts.
+
 CONVERTING A SPREADSHEET: when asked to convert an import (imp_\u2026), read
 every part with read_import_file, then save_import_cases in batches. Group
 cases into features by product area (a sheet or section usually is one). Each
 case is one scenario: name it after what it proves. Steps: preconditions and
 setup as Given; ONE action per When / And \u2014 split steps that do several
 things; each expected result as Then / And, after the action it follows.
-Keep every case and every step's meaning, and its id from the file in row;
-never invent a step or drop one. Rows that are not test cases (titles,
+Keep every case and every step's meaning, and its id from the file in row \u2014
+that id is how a later import of the same file knows the case is already
+there; never invent a step or drop one. A case found in several sheets is
+converted once. Use the project's existing feature names (project_catalog)
+when a case belongs in one, rather than a new look-alike. Rows that are not test cases (titles,
 notes, empty) are left out. Say in note what you could not convert.
 
+PHONE APPS (Android, iOS): a project can test its Android and iOS apps as well
+as, or instead of, a website \u2014 project_catalog says which, names the app, and
+lists the phones connected to this computer. start_flow with platform
+"android" or "ios" opens the app on a phone (device: a name from the catalog,
+"BrowserStack: Samsung Galaxy S23", or nothing for whatever is connected).
+read_page then reads the SCREEN as roles and names, just like a page, and act
+and add_check work the same way. On a phone: tap (= click) a button, fill a
+textbox, swipe up/down/left/right (value; on an element, or the screen), scroll
+to an element (role + name) or by direction, longPress, back (Android only),
+hideKeyboard, permission (value "allow" or "deny") for a system prompt, and
+launchApp / terminateApp / resetApp / background (value: seconds) / rotate
+(value: portrait or landscape). navigate opens a deep link. Never tap by
+position \u2014 use the role and name; [id=\u2026] on a line is the app's own id for it,
+and is used automatically. A phone app has no URL or page title: check a
+message (text on the screen), an element's text, or that something is visible.
+The app keeps its data between runs unless the project says otherwise, so a
+sign-in step is skipped when the app is already signed in. A test case can
+mix rows on a phone with rows in a browser (a customer orders in the app, an
+admin approves on the website).
+
 HOW TO WORK:
 1. Call project_catalog. Reuse what exists \u2014 published, and on Claude's working
    branch \u2014 rather than writing it again.
@@ -1043,9 +1392,23 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
         const c = await catalogOf(projectId, true);
-        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps)`).join("\n");
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps${isMobile(f.platform) ? `, ${f.platform}` : ""})`).join("\n");
+        const platforms = platformsOf(c);
+        const phones = platforms.android || platforms.ios ? await devicesSummary() : [];
+        const phoneLines = ["android", "ios"].filter((p) => platforms[p]).map((p) => {
+          const app = p === "android" ? c.mobile?.android?.appPackage : c.mobile?.ios?.bundleId;
+          const here = phones.filter((d) => d.platform === p);
+          const farms = (c.mobile?.cloud ?? []).map((f) => CLOUD_PROVIDER_NAME[f.provider]);
+          const chosen = c.mobile?.devices[p];
+          return `${p === "android" ? "Android" : "iOS"} app: ${app ?? "(not set up \u2014 Settings \u2192 Mobile)"}
+  Phones on this computer: ${here.length ? here.map((d) => `${d.name}${d.state === "ready" ? "" : ` (${d.state})`}`).join(", ") : "none"}` + (farms.length ? `
+  Cloud device farms: ${farms.join(", ")}` : "") + (chosen ? `
+  Runs go to: ${chosen.kind === "local" ? chosen.name || chosen.id : `${CLOUD_PROVIDER_NAME[chosen.provider]}: ${chosen.device}`}` : "");
+        });
         return text([
-          `Project ${projectId}. Base URL: ${c.baseUrl || "(not set)"}`,
+          `Project ${projectId}. Tests: ${[platforms.web && "web", platforms.android && "Android app", platforms.ios && "iOS app"].filter(Boolean).join(", ")}.`,
+          platforms.web ? `Base URL: ${c.baseUrl || "(not set)"}` : "",
+          ...phoneLines,
           c.environments.length ? `Environments: ${c.environments.map((e) => `${e.name} ${e.baseUrl}`).join(", ")}` : "",
           `
 Features:${c.features.length ? "" : " none yet"}`,
@@ -1075,13 +1438,15 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
     {
       name: "start_flow",
       title: "Start writing a flow",
-      description: "Open a browser on this computer at the project's app and start a new flow. Returns the page. Closes any flow that was being written.",
+      description: "Open a browser on this computer at the project's app \u2014 or, with platform android or ios, the project's phone app on a phone \u2014 and start a new flow. Returns the page or screen. Closes any flow that was being written.",
       inputSchema: {
         type: "object",
         properties: {
           name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
           feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
-          startPath: { type: "string", description: 'Where it starts, relative to the base URL. Default "/".' },
+          startPath: { type: "string", description: `Where it starts, relative to the base URL. Default "/". On a phone: a deep link to open, or leave out for the app's first screen.` },
+          platform: { type: "string", enum: ["web", "android", "ios"], description: "Where the flow runs. Default: web, or the project's only platform." },
+          device: { type: "string", description: `Phones only: a phone from project_catalog by name, or a cloud farm's as "BrowserStack: Samsung Galaxy S23". Default: the project's choice, then whatever is connected.` },
           after: {
             type: "array",
             items: { type: "string" },
@@ -1111,16 +1476,23 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
         }
         const asked = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
         const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
+        const platforms = platformsOf(catalog);
+        const enabled = ["web", "android", "ios"].filter((p) => platforms[p]);
+        const platform = str(args["platform"]) ?? (enabled.length === 1 ? enabled[0] : enabled.includes("web") ? "web" : void 0);
+        if (!platform) throw new Error(`this project tests ${enabled.join(" and ")} \u2014 say which with platform`);
+        if (!platforms[platform]) throw new Error(`this project does not test ${platform === "web" ? "a website" : `an ${platform === "ios" ? "iOS" : "Android"} app`} \u2014 turn it on in Settings first`);
+        const device = isMobile(platform) ? deviceFrom(str(args["device"]), platform, await devicesSummary(), catalog.mobile) : void 0;
         const page = await session.start({
           projectId,
+          ...isMobile(platform) ? { platform, ...device ? { device } : {} } : {},
           ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
           name: str(args["name"]) ?? "Untitled flow",
           ...feature ? { featureId: feature.id } : { featureName: featureAsked },
-          startPath: str(args["startPath"]) || "/",
+          startPath: str(args["startPath"]) || (isMobile(platform) ? "" : "/"),
           ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
         }, catalog);
         const after = plan?.prerequisites.length ? ` It starts after ${plan.prerequisites.map((p) => `"${p.name}"`).join(" \u2192 ")}, which ran first.` : "";
-        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} The browser is open.
+        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} ${isMobile(platform) ? "The app is open on the phone." : "The browser is open."}
 
 ${page}`);
       }
@@ -1128,7 +1500,7 @@ ${page}`);
     {
       name: "read_page",
       title: "Read the page",
-      description: "The current page as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
+      description: "The current page \u2014 or phone screen \u2014 as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async () => text(await session.snapshot())
@@ -1136,11 +1508,11 @@ ${page}`);
     {
       name: "act",
       title: "Do one thing on the page",
-      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value. back/forward: nothing.`,
+      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value (on a phone, a deep link). back/forward: nothing. PHONE ONLY: tap (role + name), longPress (role + name), swipe (value up/down/left/right, optionally on role + name), scroll (to role + name, or value up/down), hideKeyboard, permission (value allow/deny), launchApp, terminateApp, resetApp, background (value: seconds), rotate (value portrait/landscape).`,
       inputSchema: {
         type: "object",
         properties: {
-          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"] },
+          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward", "tap", "longPress", "swipe", "scroll", "hideKeyboard", "permission", "launchApp", "terminateApp", "resetApp", "background", "rotate"] },
           role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox, checkbox, combobox." },
           name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
           within: { type: "string", description: "When the name is not unique: the name of the region, dialog, form or navigation that holds it." },
@@ -1152,7 +1524,7 @@ ${page}`);
         additionalProperties: false
       },
       run: async (args) => {
-        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward");
+        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward \u2014 or on a phone tap, longPress, swipe, scroll, hideKeyboard, permission, launchApp, terminateApp, resetApp, background, rotate");
         return text(await session.act({
           action: args["action"],
           ...str(args["role"]) ? { role: str(args["role"]) } : {},
@@ -1167,7 +1539,7 @@ ${page}`);
     {
       name: "add_check",
       title: "Add a check",
-      description: "Assert something about the page as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message. Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
+      description: "Assert something about the page (or phone screen) as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message (text shown anywhere \u2014 on a phone, the way to check a screen). Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1401,6 +1773,53 @@ ${got.text}`);
         return text(`Saved ${saved.added} more \u2014 ${saved.total} test cases so far.${saved.done ? " Done: the person can now look them over and import them." : " Keep going, and pass done: true with the last batch."}`);
       }
     },
+    {
+      name: "read_update_request",
+      title: "Read what should change in some test cases",
+      description: "Read a request to update test cases (its id is upd_\u2026): what the person wants changed, and each test case as it is now \u2014 its id, feature, name and business steps.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, request: { type: "string", description: "upd_\u2026" } }, required: ["request"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const r = await service.updateRequest(projectId, str(args["request"]) ?? "");
+        return text([
+          `What should change: ${r.instruction}`,
+          ...r.cases.map((c) => [`
+${c.feature} \u203A ${c.name} (${c.id})`, ...c.businessSteps.length ? c.businessSteps.map((s) => `  ${s.keyword} ${s.text}`) : ["  (no steps written)"]].join("\n"))
+        ].join("\n"));
+      }
+    },
+    {
+      name: "propose_case_updates",
+      title: "Propose new steps for test cases",
+      description: "Propose the new business steps for test cases in an update request (upd_\u2026): for each case changed, its id and ALL its steps as Given / When / Then / And lines (the whole case, not only what changed). Cases that need no change are left out. The person sees each before and after and accepts the ones they want; nothing changes until they do. done: true with the last batch; note: anything you could not do.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          request: { type: "string", description: "upd_\u2026" },
+          updates: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { case: { type: "string", description: "The test case's id, tc_\u2026" }, steps: { type: "array", items: { type: "string" } }, note: { type: "string", description: "Why, in a few words." } },
+              required: ["case", "steps"],
+              additionalProperties: false
+            }
+          },
+          done: { type: "boolean" },
+          note: { type: "string" }
+        },
+        required: ["request", "updates"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const updates = Array.isArray(args["updates"]) ? args["updates"] : [];
+        const r = await service.proposeUpdates(projectId, str(args["request"]) ?? "", { updates, ...args["done"] === true ? { done: true } : {}, ...typeof args["note"] === "string" ? { note: args["note"] } : {} });
+        return text(`Proposed new steps for ${r.proposed} of ${r.of} test cases.${r.done ? " Done: the person can now accept them." : " Pass done: true with the last batch."}`);
+      }
+    },
     {
       name: "read_test_cases",
       title: "Read test cases",
@@ -1654,7 +2073,7 @@ ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") |
     {
       name: "close_browser",
       title: "Close the browser",
-      description: "Close the browser and drop the flow being written, unsaved.",
+      description: "Close the browser \u2014 or the app on the phone \u2014 and drop the flow being written, unsaved.",
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
       annotations: { destructiveHint: true },
       run: async () => {
@@ -1725,6 +2144,10 @@ ${bold("USAGE")}
   flowriki-agent doctor             diagnose setup problems
   flowriki-agent prepare            download the browser recording needs
   flowriki-agent disconnect         forget this computer's credential
+  flowriki-agent mobile setup       install what testing Android and iOS apps
+                                    needs (Appium and its drivers)
+  flowriki-agent mobile doctor      is this computer ready to test phones
+  flowriki-agent mobile devices     the phones, emulators and simulators here
   flowriki-agent mcp                Flowriki as tools for Claude \u2014 started by
                                     Claude Code or Claude Desktop, not by you:
                                     claude mcp add flowriki -- flowriki-agent mcp
@@ -1920,6 +2343,42 @@ Run \`flowriki-agent --help\`.`);
       }
       return 0;
     }
+    case "mobile": {
+      const sub = positionals[1] ?? "doctor";
+      const report = (found) => {
+        for (const [title, lines] of [["Appium", found.appium], ["Android", found.android], ["iOS", found.ios]]) {
+          console.log(bold(title));
+          for (const line of lines) {
+            console.log(`  ${line.ok ? green("\u2713") : red("\u2717")} ${line.item.padEnd(15)} ${line.ok ? dim(line.detail) : line.detail}`);
+            if (!line.ok && line.fix) console.log(`    ${yellow("\u2192")} ${line.fix}`);
+          }
+        }
+        console.log(`
+  Android ${found.androidReady ? green("ready") : yellow("not ready")}   iOS ${found.iosReady ? green("ready") : yellow("not ready")}`);
+        return found.androidReady || found.iosReady ? 0 : 1;
+      };
+      if (sub === "setup") return report(await mobileSetup((line) => console.log(dim(`  ${line}`))));
+      if (sub === "doctor") {
+        const found = await mobileDoctor();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return found.androidReady || found.iosReady ? 0 : 1;
+        }
+        return report(found);
+      }
+      if (sub === "devices") {
+        const found = await listDevices();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return 0;
+        }
+        if (!found.length) console.log(yellow("  No phones, emulators or simulators found."));
+        for (const d of found) console.log(`  ${d.state === "ready" ? green("\u25CF") : dim("\u25CB")} ${d.name.padEnd(28)} ${dim(`${d.platform === "ios" ? "iOS" : "Android"} ${d.osVersion} \xB7 ${d.kind}${d.state === "ready" ? "" : ` \xB7 ${d.state}`}`)}`);
+        return 0;
+      }
+      console.error(`unknown: mobile ${sub} \u2014 use setup, doctor or devices`);
+      return 2;
+    }
     case "projects": {
       const { projects: found, skipped } = resolveCheckouts(projects.length ? projects : [process.cwd()]);
       for (const p of found) console.log(`  ${p.name}  ${dim(p.root)}`);