@flowriki/agent 0.1.0-beta.53 → 0.1.0-beta.56

package/dist/{chunk-6AR63WTN.js → chunk-H3YHYPVE.js}

@@ -68,7 +68,7 @@ import {
   textIndependent,
   validateActors,
   webCloudOf
-} from "./chunk-FIR6NOLA.js";
+} from "./chunk-O34WXNH6.js";
 
 // src/engine/machine.ts
 import fs from "fs";
@@ -76,7 +76,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.53";
+var AGENT_VERSION = "0.1.0-beta.56";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -136,7 +136,7 @@ async function checkMachine() {
     }
   } catch {
   }
-  const { mobileDoctor: mobileDoctor2 } = await import("./dist-6GKVE5CL.js");
+  const { mobileDoctor: mobileDoctor2 } = await import("./dist-RDJIIBQV.js");
   return {
     agentVersion: AGENT_VERSION,
     node: process.versions.node,
@@ -8857,7 +8857,7 @@ var AgentLink = class {
     this.opts.onStatus?.(status2, detail);
   }
   async start() {
-    const backoff = this.opts.backoff ?? [250, 500, 1e3, 2e3, 5e3];
+    const backoff = this.opts.backoff ?? [250, 500, 1e3, 2e3, 5e3, 1e4, 2e4, 3e4];
     const sleep2 = this.opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     let attempt = 0;
     while (!this.stopped) {
@@ -8878,8 +8878,9 @@ var AgentLink = class {
         socket.send(JSON.stringify(this.opts.agent.hello()));
         this.unsubscribe = this.opts.agent.journal.subscribe(() => this.flush());
         this.setStatus("connected");
-        attempt = 0;
+        const since = Date.now();
         await closed;
+        if (Date.now() - since > 1e4) attempt = 0;
         this.unsubscribe?.();
         this.unsubscribe = null;
         this.socket = null;
@@ -9846,8 +9847,11 @@ var ownerOf = (l) => l.draft ? "recording" : "debug";
 var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|\bpin\b|cvv|cvc/i;
 async function screenOf(l, withImage = false) {
   l.session.changed();
-  const screen = await l.session.screen();
-  const png = withImage ? await l.session.screenshot() : null;
+  const [screen, png, where] = await Promise.all([
+    l.session.screen(),
+    withImage ? l.session.preview() : Promise.resolve(null),
+    l.session.currentScreenName()
+  ]);
   return {
     ...png ? { image: png.toString("base64") } : {},
     width: screen.size.width,
@@ -9862,7 +9866,7 @@ async function screenOf(l, withImage = false) {
       ...n2.value ? { value: n2.password ? "\u2022\u2022\u2022" : n2.value } : {},
       ...n2.id ? { id: n2.id } : {}
     })),
-    where: await l.session.currentScreenName(),
+    where,
     device: l.session.deviceName
   };
 }
@@ -9890,7 +9894,7 @@ function mobileHandlers(ctx) {
       const session = live.get(platform)?.session ?? openSessionOn(platform);
       if (!session) return { ok: true, result: { image: null } };
       try {
-        const png = await session.screenshot();
+        const png = await session.preview(720);
         return { ok: true, result: { image: png.toString("base64"), device: session.deviceName } };
       } catch {
         return { ok: true, result: { image: null } };
@@ -10003,18 +10007,18 @@ function mobileHandlers(ctx) {
             if (op === "run" || step.type === "signIn" || step.type === "assert") {
               const done = await runMobileSteps(l.session, [step], { values: l.values, resolveSecret: l.resolveSecret, resolveAuth: l.resolveAuth, ...l.runHelper ? { runHelper: l.runHelper } : {} });
               const result = done.results[0];
-              if (op === "run") return { ok: true, result: { result: result ?? null, screen: await screenOf(l) } };
+              if (op === "run") return { ok: true, result: { result: result ?? null } };
               if (done.status !== "passed") throw new Error(result?.detail ?? done.error ?? "it did not work");
             } else {
               await performMobileStep(l.session, step, { values: l.values, resolveSecret: l.resolveSecret, resolveAuth: l.resolveAuth, ...l.runHelper ? { runHelper: l.runHelper } : {} });
             }
           } catch (error) {
             if (secret2) l.typed.delete(ref);
-            return { ok: true, result: { kept: false, error: error.message.split("\n")[0], screen: await screenOf(l) } };
+            return { ok: true, result: { kept: false, error: error.message.split("\n")[0] } };
           }
-          await new Promise((r) => setTimeout(r, 500));
+          await new Promise((r) => setTimeout(r, 300));
           l.draft?.steps.push(step);
-          return { ok: true, result: { kept: true, step, durationMs: Date.now() - t0, steps: l.draft?.steps ?? [], screen: await screenOf(l) } };
+          return { ok: true, result: { kept: true, step, durationMs: Date.now() - t0, steps: l.draft?.steps ?? [] } };
         }
         if (op === "check") {
           const assertion = RecordedStepSchema.shape.proposals.element.parse({ enabled: true, ...command.args["assertion"] });
@@ -10260,9 +10264,10 @@ function eventsFromLine(askId, line) {
 function createClaudeCli(options) {
   const spawn2 = options.spawn ?? nodeSpawn;
   const binary = options.binary ?? process.env["FLOWRIKI_CLAUDE_BIN"] ?? "claude";
-  const maxAskMs = options.maxAskMs ?? 30 * 6e4;
+  const maxAskMs = options.maxAskMs ?? 60 * 6e4;
   const scratchRoot2 = options.scratchRoot ?? path42.join(os22.tmpdir(), "flowriki-claude");
-  let current = null;
+  const running = /* @__PURE__ */ new Map();
+  const MAX_AT_ONCE = 3;
   let cancelled = null;
   function capture(args, timeoutMs = 15e3) {
     return new Promise((resolve2) => {
@@ -10304,7 +10309,7 @@ function createClaudeCli(options) {
       return { installed: true, version: version.out.trim().split(/\s+/)[0] ?? null, ...parsed };
     },
     connect(emit) {
-      if (current) return { started: false, detail: "The assistant is busy answering a question." };
+      if (running.size > 0) return { started: false, detail: "The assistant is busy answering a question." };
       let child;
       try {
         child = spawn2(binary, ["auth", "login"], { stdio: ["ignore", "pipe", "pipe"] });
@@ -10334,88 +10339,107 @@ function createClaudeCli(options) {
       return { started: true };
     },
     ask(ask) {
-      if (current) return { started: false, detail: "The assistant is already answering a question on this machine." };
+      if (running.size >= MAX_AT_ONCE) return { started: false, detail: `The assistant is already answering ${MAX_AT_ONCE} questions on this machine \u2014 wait for one to finish.` };
       fs43.mkdirSync(scratchRoot2, { recursive: true, mode: 448 });
-      const dir = fs43.mkdtempSync(path42.join(scratchRoot2, "ask-"));
+      const dir = path42.join(scratchRoot2, `project-${ask.projectId.replace(/[^A-Za-z0-9_-]/g, "_")}`);
+      fs43.mkdirSync(dir, { recursive: true, mode: 448 });
       const mcpConfigPath = path42.join(dir, "mcp.json");
       fs43.writeFileSync(
         mcpConfigPath,
         JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: { command: options.mcp.command, args: options.mcp.args } } }),
         { mode: 384 }
       );
-      let child;
-      try {
-        child = spawn2(
-          binary,
-          buildAskArgs({
-            prompt: ask.prompt,
-            mcpConfigPath,
-            projectId: ask.projectId,
-            projectName: ask.projectName,
-            ...ask.sessionId ? { sessionId: ask.sessionId } : {},
-            ...ask.folders?.length ? { folders: ask.folders } : {},
-            ...ask.mode ? { mode: ask.mode } : {}
-          }),
-          // THE SCRATCH FOLDER, not the project: nothing here to read or write.
-          { cwd: dir, stdio: ["ignore", "pipe", "pipe"] }
-        );
-      } catch {
-        fs43.rmSync(dir, { recursive: true, force: true });
-        return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
-      }
-      current = { askId: ask.askId, child };
-      let buffer = "", stderr = "", sawDone = false, ended = false;
-      const handleLine = (line) => {
-        for (const event of eventsFromLine(ask.askId, line)) {
-          if (event.name === "assistant.done") sawDone = true;
-          ask.emit(event.name, event.data);
-        }
-      };
-      const end = (ok, detail) => {
-        if (ended) return;
-        ended = true;
-        clearTimeout(timer);
-        if (buffer.trim()) handleLine(buffer);
-        if (!sawDone) ask.emit("assistant.done", { askId: ask.askId, ok, result: detail });
-        current = null;
-        fs43.rmSync(dir, { recursive: true, force: true });
-      };
-      const timer = setTimeout(() => {
-        child.kill("SIGTERM");
-        end(false, `Stopped after ${Math.max(1, Math.round(maxAskMs / 6e4))} minutes. Whatever it saved so far is on the Branches page \u2014 send \u201Ccontinue\u201D to carry on.`);
-      }, maxAskMs);
-      timer.unref?.();
-      child.stdout?.on("data", (chunk) => {
-        buffer += chunk.toString();
-        let at;
-        while ((at = buffer.indexOf("\n")) >= 0) {
-          handleLine(buffer.slice(0, at));
-          buffer = buffer.slice(at + 1);
-        }
-      });
-      child.stderr?.on("data", (chunk) => {
-        stderr = (stderr + chunk.toString()).slice(-2e3);
-      });
-      child.on("error", () => end(false, "The assistant\u2019s command-line tool could not be started."));
-      child.on(
-        "close",
-        (code) => end(
-          code === 0,
-          cancelled === ask.askId ? "Stopped." : code === 0 ? "" : stderr.trim().split("\n").slice(-3).join(" ") || `The assistant stopped (exit ${code ?? "?"}).`
-        )
-      );
-      return { started: true };
+      return launch(ask, dir, mcpConfigPath, ask.sessionId);
     },
     cancel(askId) {
-      if (!current || current.askId !== askId) return false;
+      const child = running.get(askId);
+      if (!child) return false;
       cancelled = askId;
-      current.child.kill("SIGTERM");
-      const child = current.child;
+      child.kill("SIGTERM");
       setTimeout(() => child.kill("SIGKILL"), 3e3).unref?.();
       return true;
     },
-    busy: () => current !== null
+    /** Full — no room for another question — rather than "something runs":
+     *  a second conversation is welcome while the first works. */
+    busy() {
+      return running.size >= MAX_AT_ONCE;
+    }
   };
+  function launch(ask, dir, mcpConfigPath, sessionId) {
+    let child;
+    try {
+      child = spawn2(
+        binary,
+        buildAskArgs({
+          prompt: ask.prompt,
+          mcpConfigPath,
+          projectId: ask.projectId,
+          projectName: ask.projectName,
+          ...sessionId ? { sessionId } : {},
+          ...ask.folders?.length ? { folders: ask.folders } : {},
+          ...ask.mode ? { mode: ask.mode } : {},
+          ...ask.brief ? { brief: ask.brief } : {}
+        }),
+        // THE SCRATCH FOLDER, not the project: nothing here to read or write.
+        { cwd: dir, stdio: ["ignore", "pipe", "pipe"] }
+      );
+    } catch {
+      return { started: false, detail: "The assistant\u2019s command-line tool could not be started." };
+    }
+    running.set(ask.askId, child);
+    let buffer = "", stderr = "", sawDone = false, ended = false;
+    let silentFailure = false;
+    const handleLine = (line) => {
+      for (const event of eventsFromLine(ask.askId, line)) {
+        if (event.name === "assistant.done" && event.data["ok"] === false && !String(event.data["result"] ?? "").trim()) {
+          silentFailure = true;
+          continue;
+        }
+        if (event.name === "assistant.done") sawDone = true;
+        ask.emit(event.name, event.data);
+      }
+    };
+    const end = (ok, detail) => {
+      if (ended) return;
+      ended = true;
+      clearTimeout(timer);
+      if (buffer.trim()) handleLine(buffer);
+      running.delete(ask.askId);
+      if (silentFailure && sessionId && /no conversation found/i.test(stderr) && cancelled !== ask.askId) {
+        const again = launch(ask, dir, mcpConfigPath, void 0);
+        if (again.started) return;
+      }
+      if (!sawDone) {
+        const why = detail || stderr.trim().split("\n").filter((l) => l && !/^Warning:/.test(l)).slice(-3).join(" ") || "The assistant stopped without saying why.";
+        ask.emit("assistant.done", { askId: ask.askId, ok: ok && !silentFailure, result: ok && !silentFailure ? "" : why });
+      }
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      end(false, `Stopped after ${Math.max(1, Math.round(maxAskMs / 6e4))} minutes. Whatever it saved so far is on the Branches page \u2014 send \u201Ccontinue\u201D to carry on.`);
+    }, maxAskMs);
+    timer.unref?.();
+    child.stdout?.on("data", (chunk) => {
+      buffer += chunk.toString();
+      let at;
+      while ((at = buffer.indexOf("\n")) >= 0) {
+        handleLine(buffer.slice(0, at));
+        buffer = buffer.slice(at + 1);
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = (stderr + chunk.toString()).slice(-2e3);
+    });
+    child.on("error", () => end(false, "The assistant\u2019s command-line tool could not be started."));
+    child.on(
+      "close",
+      (code) => end(
+        code === 0,
+        cancelled === ask.askId ? "Stopped." : code === 0 ? "" : stderr.trim().split("\n").filter((l) => l && !/^Warning:/.test(l)).slice(-3).join(" ") || `The assistant stopped (exit ${code ?? "?"}).`
+      )
+    );
+    return { started: true };
+  }
 }
 function createAgentRuntime(options) {
   const lease = new BrowserLease();
@@ -10847,6 +10871,7 @@ export {
   executeStep,
   replayCase,
   fieldNames,
+  flowrikiHome,
   helperRunner,
   resolveCheckouts,
   start,

package/dist/{chunk-FIR6NOLA.js → chunk-O34WXNH6.js}

@@ -14,7 +14,9 @@ import { spawn as spawn2 } from "child_process";
 import fs3 from "fs";
 import os3 from "os";
 import path3 from "path";
+import { execFile as execFile2 } from "child_process";
 import fs4 from "fs";
+import os4 from "os";
 import path4 from "path";
 
 // ../test-model/dist/chunk-I5COYCQ5.js
@@ -2566,8 +2568,15 @@ async function localCapabilities(target, udid, opts = {}) {
       "appium:automationName": "UiAutomator2",
       ...common,
       "appium:appPackage": app.id,
-      ...app.activity ? { "appium:appActivity": app.activity } : {},
+      ...app.activity ?? opts.activity ? { "appium:appActivity": app.activity ?? opts.activity } : {},
       "appium:appWaitActivity": "*",
+      // THE APP IS STARTED BY US, NOT BY THE DRIVER. A session opens, then the
+      // app is closed and opened the way its icon does (activateApp), from
+      // its first screen. The driver's own launch needs ONE launcher activity
+      // and fails on a build that has several ("Intent matches multiple
+      // activities") — a dev build with a debug launcher, typically — while
+      // the icon's way never has to choose.
+      "appium:autoLaunch": false,
       // Its own ports: two phones on one Appium each need their own driver
       // server and picture stream, or the second session steals the first's.
       ...opts.ports?.system ? { "appium:systemPort": opts.ports.system } : {},
@@ -2647,7 +2656,7 @@ async function cloudDevices(account, key) {
     if (!res.ok) throw new Error(`${account.provider} answered ${res.status}.`);
     return res.json();
   };
-  const platformOf = (os4) => /android/i.test(os4) ? "android" : /ios/i.test(os4) ? "ios" : null;
+  const platformOf = (os5) => /android/i.test(os5) ? "android" : /ios/i.test(os5) ? "ios" : null;
   const out = [];
   if (account.provider === "browserstack") {
     for (const d of await get("https://api-cloud.browserstack.com/app-automate/devices.json")) {
@@ -2661,11 +2670,11 @@ async function cloudDevices(account, key) {
       if (p) out.push({ name: d.name, platform: p, osVersion: d.osVersion });
     }
   } else {
-    for (const os4 of ["android", "ios"]) {
-      const listed = await get(`https://mobile-api.lambdatest.com/mobile-automation/api/v1/list?region=us&os=${os4}`);
+    for (const os5 of ["android", "ios"]) {
+      const listed = await get(`https://mobile-api.lambdatest.com/mobile-automation/api/v1/list?region=us&os=${os5}`);
       for (const [, devices] of Object.entries(listed)) {
         if (!Array.isArray(devices)) continue;
-        for (const d of devices) out.push({ name: d.deviceName, platform: os4, osVersion: d.platformVersion });
+        for (const d of devices) out.push({ name: d.deviceName, platform: os5, osVersion: d.platformVersion });
       }
     }
   }
@@ -3232,7 +3241,7 @@ var MobileSession = class _MobileSession {
     if (target.device.kind === "cloud") {
       const choice2 = target.device;
       const account = target.mobile.cloud.find((c) => c.provider === choice2.provider);
-      if (!account) throw new Error(`${CLOUD_PROVIDER_NAME[choice2.provider]} is not connected \u2014 add it in Settings \u2192 Mobile.`);
+      if (!account) throw new Error(`${CLOUD_PROVIDER_NAME[choice2.provider]} is not connected \u2014 add it in Settings \u2192 Platforms.`);
       const key = opts.resolveSecret?.(account.keyRef);
       if (!key) throw new Error(`The ${CLOUD_PROVIDER_NAME[choice2.provider]} access key is not available to this run.`);
       let appRef = null;
@@ -3266,7 +3275,8 @@ var MobileSession = class _MobileSession {
     const buildFile = app.build ? await localBuild(app.build) : null;
     say(`Opening the app on ${known.name}\u2026`);
     const ports = target.platform === "android" ? { system: await freePort(), mjpeg: await freePort() } : { wda: await freePort(), mjpeg: await freePort() };
-    const capabilities = await localCapabilities(target, udid, { buildFile, ports });
+    const activity = target.platform === "android" && !app.activity && !buildFile ? await launchActivityOf(udid, app.id) : null;
+    const capabilities = await localCapabilities(target, udid, { buildFile, ports, ...activity ? { activity } : {} });
     const driver = await WebDriverSession.create(endpoint, capabilities).catch((e) => {
       const tail = appiumLog().filter((l) => /error/i.test(l)).slice(-2).join(" ");
       throw new Error(explainStartFailure(e.message, target.platform) + (tail ? ` (${tail.slice(0, 300)})` : ""));
@@ -3313,6 +3323,16 @@ var MobileSession = class _MobileSession {
     }
     return png;
   }
+  /** The screen as a picture to LOOK at — the recorder's mirror, the run
+   *  page's live phone — at most `maxPx` on its longer side. A phone's own
+   *  resolution is three to four times what a mirror draws, and every byte
+   *  of it crosses the control channel each time; on macOS `sips` shrinks it
+   *  in a few milliseconds, elsewhere the full picture is sent. Evidence
+   *  files keep the full size. */
+  async preview(maxPx = 900) {
+    const png = await this.screenshot();
+    return shrink(png, maxPx);
+  }
   /** Android: the activity on screen. iOS has none worth reading. */
   async currentScreenName() {
     if (this.platform !== "android") return "";
@@ -3443,7 +3463,7 @@ var MobileSession = class _MobileSession {
     await this.terminateApp().catch(() => {
     });
     await this.driver.execute("mobile: clearApp", this.appArg()).catch((e) => {
-      throw new Error(`This device cannot clear the app's data (${e.message}). Reinstall it, or choose "Start clean" in Settings \u2192 Mobile.`);
+      throw new Error(`This device cannot clear the app's data (${e.message}). Reinstall it, or choose "Start clean" in Settings \u2192 Platforms.`);
     });
     await this.launchApp();
   }
@@ -3510,6 +3530,33 @@ var MobileSession = class _MobileSession {
     await this.driver.close();
   }
 };
+async function launchActivityOf(udid, appPackage) {
+  const adb = adbPath();
+  if (!adb) return null;
+  try {
+    const out = await run(adb, ["-s", udid, "shell", "cmd", "package", "query-activities", "--brief", "-a", "android.intent.action.MAIN", "-c", "android.intent.category.LAUNCHER", appPackage], 1e4, await toolEnv());
+    const found = out.split("\n").map((l) => l.trim()).filter((l) => l.startsWith(`${appPackage}/`)).map((l) => l.slice(appPackage.length + 1));
+    return found.length === 1 ? found[0] : null;
+  } catch {
+    return null;
+  }
+}
+async function shrink(png, maxPx) {
+  if (process.platform !== "darwin") return png;
+  const dir = fs4.mkdtempSync(path4.join(os4.tmpdir(), "flowriki-shot-"));
+  const file = path4.join(dir, "s.png");
+  try {
+    fs4.writeFileSync(file, png);
+    await new Promise((resolve, reject) => {
+      execFile2("/usr/bin/sips", ["-Z", String(maxPx), file], { timeout: 5e3 }, (error) => error ? reject(error) : resolve());
+    });
+    return fs4.readFileSync(file);
+  } catch {
+    return png;
+  } finally {
+    fs4.rmSync(dir, { recursive: true, force: true });
+  }
+}
 var ANDROID_KEYS = {
   enter: 66,
   return: 66,
@@ -3532,11 +3579,14 @@ function explainStartFailure(message, platform) {
     return `Appium's ${platform === "android" ? "Android (uiautomator2)" : "iOS (xcuitest)"} driver is not installed \u2014 run \`flowriki-agent mobile setup\`.`;
   }
   if (/is not installed|does not exist or is not accessible|Activity name .* cannot be found|App with bundle identifier .* unknown/i.test(message)) {
-    return "The app is not installed on that device. Install it, or add its build (.apk / .ipa / .app) in Settings \u2192 Mobile.";
+    return "The app is not installed on that device. Install it, or add its build (.apk / .ipa / .app) to the environment in Settings \u2192 Environments.";
+  }
+  if (/Intent matches multiple activities/i.test(message)) {
+    return "The app has more than one launch screen, and the driver could not choose. Set the Android app's First screen (e.g. .MainActivity) on the environment in Settings \u2192 Environments.";
   }
   if (/JAVA_HOME/i.test(message)) return "Java is needed for Android tests \u2014 install a JDK (Android Studio includes one).";
   if (/ANDROID_HOME|ANDROID_SDK_ROOT/i.test(message)) return "The Android SDK was not found \u2014 install Android Studio.";
-  if (/xcodebuild|WebDriverAgent/i.test(message)) return `Appium could not start its helper on the iPhone: ${message}. For a real iPhone, set your Apple team id in Settings \u2192 Mobile.`;
+  if (/xcodebuild|WebDriverAgent/i.test(message)) return `Appium could not start its helper on the iPhone: ${message}. For a real iPhone, set your Apple team id in Settings \u2192 Platforms.`;
   return `The app could not be opened: ${message}`;
 }
 var MOBILE_TIMEOUTS = { step: 15e3, assertion: 5e3 };
@@ -3799,7 +3849,7 @@ async function chooseDevice(platform, mobile, asked, where) {
   const picked = pickDevice(devices, platform);
   if (picked) return picked;
   const farm = mobile.cloud[0];
-  if (farm) throw new Error(`No ${platform === "ios" ? "iPhone or simulator" : "Android phone or emulator"} is connected to this computer. Choose a ${farm.provider} device in Settings \u2192 Mobile, or connect one.`);
+  if (farm) throw new Error(`No ${platform === "ios" ? "iPhone or simulator" : "Android phone or emulator"} is connected to this computer. Choose a ${farm.provider} device in Settings \u2192 Platforms, or connect one.`);
   throw new Error(platform === "ios" ? "No iPhone or simulator is available \u2014 install Xcode for simulators, or plug in an iPhone." : "No Android phone or emulator is available \u2014 start an emulator in Android Studio, or plug in a phone with USB debugging on.");
 }
 async function openMobileSession(opts) {
@@ -4166,6 +4216,7 @@ export {
   checkMobileAssertion,
   openSessionOn,
   MobileSession,
+  shrink,
   MOBILE_TIMEOUTS,
   performMobileStep,
   runMobileSteps,

package/dist/cli.js

@@ -13,6 +13,7 @@ import {
   doctor,
   executeStep,
   fieldNames,
+  flowrikiHome,
   helperRunner,
   openRunSession,
   prepareBrowsers,
@@ -23,7 +24,7 @@ import {
   runtimeValue,
   start,
   status
-} from "./chunk-6AR63WTN.js";
+} from "./chunk-H3YHYPVE.js";
 import {
   CLOUD_PROVIDERS,
   CLOUD_PROVIDER_NAME,
@@ -47,9 +48,10 @@ import {
   replayMobileCase,
   runMobileSteps,
   screenLines,
+  slugify,
   stepRefusedOn,
   targetFor
-} from "./chunk-FIR6NOLA.js";
+} from "./chunk-O34WXNH6.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -145,8 +147,14 @@ var ServiceClient = class {
   get origin() {
     return this.connection.service;
   }
-  async call(path2, init = {}) {
-    const res = await this.fetcher(`${this.connection.service}${path2}`, {
+  /** One request to the service, retried when the service — or the proxy in
+   *  front of it — says it is too busy. A 429 or a 503 from the edge means
+   *  the request was never handled, so trying again is safe for any method;
+   *  a 502/504 is retried only when nothing could have happened (a GET).
+   *  Backing off here, inside the tool, is what keeps the model from asking
+   *  again every two seconds and making the limit worse. */
+  async call(path3, init = {}, attempt = 0) {
+    const res = await this.fetcher(`${this.connection.service}${path3}`, {
       ...init,
       headers: {
         "x-flowriki-device": this.connection.deviceId,
@@ -161,9 +169,18 @@ var ServiceClient = class {
     } catch {
     }
     if (!res.ok) {
+      const method = String(init.method ?? "GET").toUpperCase();
+      const busy = res.status === 429 || res.status === 503 || method === "GET" && (res.status === 502 || res.status === 504);
+      if (busy && attempt < 4) {
+        const asked = Number(res.headers.get("retry-after"));
+        const wait = Math.min(15e3, res.headers.get("retry-after") !== null && Number.isFinite(asked) && asked >= 0 ? asked * 1e3 : 1e3 * 2 ** attempt);
+        await new Promise((r) => setTimeout(r, wait));
+        return this.call(path3, init, attempt + 1);
+      }
       if (res.status === 404 && !("error" in body)) {
         throw new Error("the Flowriki service does not offer this yet \u2014 it may need updating");
       }
+      if (busy) throw new Error(`the Flowriki service is too busy right now (${res.status}) and stayed so after several tries \u2014 wait a minute before asking again, and do not retry in a loop`);
       throw new Error(String(body["error"] ?? `the service answered ${res.status}`));
     }
     return body;
@@ -288,9 +305,9 @@ var ServiceClient = class {
   }
   // ── Manual cycles and bugs: the dashboard's own routes, behind this
   // machine's credential, so the assistant can do what a person can. ──────
-  scoped(path2, projectId, extra = {}) {
+  scoped(path3, projectId, extra = {}) {
     const query = new URLSearchParams({ projectId, ...extra });
-    return `/api/agent${path2}?${query}`;
+    return `/api/agent${path3}?${query}`;
   }
   cycles(projectId) {
     return this.call(this.scoped("/cycles", projectId));
@@ -333,8 +350,8 @@ var ServiceClient = class {
   knowledgePages(projectId) {
     return this.call(this.scoped("/knowledge", projectId));
   }
-  knowledgePage(projectId, path2) {
-    return this.call(this.scoped("/knowledge/page", projectId, { path: path2 }));
+  knowledgePage(projectId, path3) {
+    return this.call(this.scoped("/knowledge/page", projectId, { path: path3 }));
   }
   writeKnowledge(projectId, body) {
     return this.call(`/api/agent/knowledge?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(body) });
@@ -375,6 +392,8 @@ var ServiceClient = class {
 };
 
 // src/mcp/session.ts
+import fs from "fs";
+import path from "path";
 var MAX_TREE = 14e3;
 var MAX_STEP_VIEW = 6e3;
 function topLevelBlocks(tree) {
@@ -529,7 +548,7 @@ function describe(step) {
       return `${step.type} ${target}${where}`;
   }
 }
-var AuthoringSession = class {
+var AuthoringSession = class _AuthoringSession {
   constructor(service, opts = {}) {
     this.service = service;
     this.opts = opts;
@@ -546,6 +565,9 @@ var AuthoringSession = class {
   /** Values typed into secret fields, by their `typed:` reference. */
   typed = /* @__PURE__ */ new Map();
   draft = null;
+  /** The steps as last replayed from the start and passed — a save of the
+   *  same steps needs no second replay. Cleared by any change to them. */
+  verified = null;
   catalog = null;
   /** Text going back to Claude, with every secret typed here masked — a
    *  password box's value is in the page's tree, and a careless form puts it
@@ -595,15 +617,107 @@ var AuthoringSession = class {
     if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
     return base;
   }
-  /** Open a browser for a new flow, signed in first if asked. */
-  async start(input, catalog) {
+  /** Open a browser for a new flow, signed in first if asked.
+   *
+   * A DRAFT LEFT BEHIND IS PICKED UP. Every kept step is written to disk as
+   * it is kept, so a flow interrupted — the program stopped, the limit hit,
+   * the agent restarted — is not lost: starting the same flow again replays
+   * what was kept and carries on from there, unless `fresh` says start over. */
+  async start(input, catalog, opts = {}) {
     await this.close();
     this.catalog = catalog;
     this.draft = { ...input, steps: [] };
     this.values = /* @__PURE__ */ new Map();
     this.typed = /* @__PURE__ */ new Map();
     this.lastTree = null;
-    if (isMobile(input.platform)) return this.startMobile(input.platform, catalog);
+    this.verified = null;
+    const left = opts.fresh ? null : this.readDraft(input.projectId, input.name);
+    if (opts.fresh) this.dropDraft(input.projectId, input.name);
+    const opened = isMobile(input.platform) ? await this.startMobile(input.platform, catalog) : await this.startWeb(input, catalog);
+    if (!left?.steps.length) return opened;
+    return this.resume(left.steps, opened);
+  }
+  /** The steps of an earlier attempt, performed again in the open session
+   *  and kept as they pass; the first that fails is where the person — or
+   *  the model — takes over. */
+  async resume(steps, opened) {
+    const draft = this.draft;
+    let failed = null;
+    for (const step of steps) {
+      try {
+        if (this.mobile) {
+          const done = await runMobileSteps(this.mobile, [step], this.mobileResolvers());
+          if (done.status !== "passed") throw new Error(done.results[0]?.detail ?? done.error ?? "it did not work");
+        } else {
+          const { page, run } = this.requireOpen();
+          this.page = await executeStep(page, step, {
+            pages: run.pages,
+            values: this.values,
+            baseUrl: this.baseUrl(),
+            ...this.resolvers ?? {},
+            resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref),
+            timeoutMs: STEP_TIMEOUT_MS,
+            navigationTimeoutMs: 45e3
+          });
+          await this.settle();
+        }
+        draft.steps.push(step);
+        this.checkpoint();
+      } catch (error) {
+        failed = `${describe(step)} \u2014 ${error.message.split("\n")[0]}`;
+        break;
+      }
+    }
+    this.checkpoint();
+    const kept = draft.steps.length;
+    const head = failed ? `Resumed "${draft.name}": ${kept} of ${steps.length} earlier steps are back; the next one did not work this time and was dropped (${failed}). Carry on from here.` : `Resumed "${draft.name}": its ${kept} earlier step${kept === 1 ? "" : "s"} ${kept === 1 ? "is" : "are"} back. Carry on from here.`;
+    const view = this.mobile ? await this.snapshot() : opened.includes("\n") ? await this.snapshot() : opened;
+    return `${head}
+
+${view}`;
+  }
+  // ── Drafts on disk ──────────────────────────────────────────────────────
+  static draftFile(projectId, name) {
+    return path.join(flowrikiHome(), "drafts", projectId.replace(/[^A-Za-z0-9_-]/g, "_"), `${slugify(name) || "flow"}.json`);
+  }
+  /** Written after every kept step: the draft as it stands, never a typed
+   *  secret (those stay in memory until the vault has them). */
+  checkpoint() {
+    const draft = this.draft;
+    if (!draft) return;
+    this.verified = null;
+    try {
+      const file = _AuthoringSession.draftFile(draft.projectId, draft.name);
+      fs.mkdirSync(path.dirname(file), { recursive: true, mode: 448 });
+      const { preparation: _p, ...rest } = draft;
+      fs.writeFileSync(file, JSON.stringify({ ...rest, steps: withoutTyped(draft.steps), savedAt: (/* @__PURE__ */ new Date()).toISOString() }), { mode: 384 });
+    } catch {
+    }
+  }
+  readDraft(projectId, name) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(_AuthoringSession.draftFile(projectId, name), "utf8"));
+      const steps = (raw.steps ?? []).map((s) => RecordedStepSchema.parse(s));
+      return { steps };
+    } catch {
+      return null;
+    }
+  }
+  dropDraft(projectId, name) {
+    try {
+      fs.rmSync(_AuthoringSession.draftFile(projectId, name), { force: true });
+    } catch {
+    }
+  }
+  /** Close and forget the flow being written: close_browser means it. */
+  async closeAndDrop() {
+    const draft = this.draft;
+    await this.close();
+    if (draft) this.dropDraft(draft.projectId, draft.name);
+    this.draft = null;
+  }
+  async startWeb(input, catalog) {
+    void catalog;
     const base = this.baseUrl();
     this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
     this.page = this.run.page;
@@ -756,6 +870,7 @@ ${await this.view(false)}`);
     }
     await this.settle();
     draft.steps.push(step);
+    this.checkpoint();
     return `Step ${draft.steps.length} kept: ${describe(step)}.
 
 ${await this.view(false)}`;
@@ -793,6 +908,7 @@ ${await this.view(false)}`;
       proposals: [assertion]
     }])[0]);
     draft.steps.push(step);
+    this.checkpoint();
     return `Step ${draft.steps.length} kept: ${describe(step)}.`;
   }
   /** Get a value from outside the page — an email code, a 2FA code, a text,
@@ -835,6 +951,7 @@ ${await this.view(false)}`;
     }
     await this.settle();
     draft.steps.push(step);
+    this.checkpoint();
     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)}` : "");
@@ -854,6 +971,7 @@ ${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
     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);
+    this.checkpoint();
     return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
 
 ${this.list()}`;
@@ -872,17 +990,34 @@ ${this.list()}`;
     ];
     const outcome = await replayFlow({ steps, baseUrl: this.baseUrl(), startPath: draft.startPath, headless: true, ...resolvers });
     const lines = outcome.steps.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    if (outcome.status === "passed") this.verified = signatureOf(draft.steps);
     return `${outcome.status === "passed" ? "The whole flow passed from the start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
 ${lines.join("\n")}`;
   }
-  /** Save the draft as a flow on a new branch, for a person to review. */
-  async save(title, where = {}) {
+  /** Save the draft as a flow on a new branch, for a person to review.
+   *
+   * REPLAYED FIRST. A flow that was only ever performed step by step, with
+   * pauses to look, has not been shown to run as a test runs it; so unless
+   * the same steps already passed a replay, they are replayed from the
+   * start now, and a flow that fails is not saved — the failing step is
+   * named instead. `force` saves anyway, for a person who knows. */
+  async save(title, where = {}, opts = {}) {
     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");
     }
+    let replayed = "";
+    if (!opts.force && this.verified !== signatureOf(draft.steps)) {
+      const report = await this.replay();
+      if (!/^The whole flow passed/.test(report)) {
+        throw new Error(`Not saved: replayed from the start, the flow did not pass.
+${report}
+Fix the step that failed (remove_step, then act again) and save again \u2014 or save_flow with force: true to keep it as it is.`);
+      }
+      replayed = " It was replayed from the start first and passed.";
+    }
     const checksOff = draft.steps.map((step) => step.type === "assert" ? { ...step, proposals: step.proposals.map((p) => ({ ...p, enabled: false })) } : step);
     const checkCount = checksOff.filter((step) => step.type === "assert").length;
     const secretValues = {};
@@ -908,7 +1043,8 @@ ${lines.join("\n")}`;
     const note = others.length ? `
 Claude has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 gather_branches puts them into this one, for one review.` : "";
     const after = draft.after?.length ? ` It starts after ${draft.after.map((a) => `"${a.name}"`).join(", ")}.` : "";
-    return `${what} ${where_}.${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 a test case switches on the ones it is about. Nothing is published yet.
+    this.dropDraft(draft.projectId, draft.name);
+    return `${what} ${where_}.${replayed}${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 a test case switches on the ones it is about. Nothing is published yet.
 Review and publish it here: ${review}${note}`;
   }
   /** A test case built from flows, without saving: its rows and every check,
@@ -1080,6 +1216,7 @@ ${await this.view(false)}`);
     }
     await new Promise((r) => setTimeout(r, 600));
     draft.steps.push(step);
+    this.checkpoint();
     return `Step ${draft.steps.length} kept: ${describe(step)}.
 
 ${await this.view(false)}`;
@@ -1113,6 +1250,7 @@ ${await this.view(false)}`;
       proposals: [assertion]
     }])[0]);
     draft.steps.push(step);
+    this.checkpoint();
     return `Step ${draft.steps.length} kept: ${describe(step)}.`;
   }
   async mobileHelper(input) {
@@ -1141,6 +1279,7 @@ ${await this.view(false)}`;
       throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
     }
     draft.steps.push(step);
+    this.checkpoint();
     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)}` : "");
@@ -1163,6 +1302,7 @@ ${await this.view(false)}` : "");
     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;
+    if (outcome.status === "passed") this.verified = signatureOf(draft.steps);
     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")}`;
@@ -1175,6 +1315,9 @@ ${lines.join("\n")}`;
     await page.waitForTimeout(300);
   }
 };
+function signatureOf(steps) {
+  return JSON.stringify(steps.map((s) => [s.id, s.type, s.role, s.name, s.value, s.nth ?? null, s.proposals.map((p) => [p.kind, p.value, p.enabled])]));
+}
 
 // src/mcp/tools.ts
 var INSTRUCTIONS = `Flowriki tools write UI tests by driving a real browser on this computer.
@@ -1195,6 +1338,9 @@ THE MODEL \u2014 get this right before recording anything:
   something different.
 - A flow records checks (add_check) that prove each thing happened, but they
   are SAVED SWITCHED OFF: which ones matter depends on the test.
+- Every kept step is written down as it is kept: if you are stopped, start_flow
+  with the same name picks the flow up where it was (fresh: true starts over).
+  save_flow replays the flow from the start first and refuses one that fails.
 - A TEST CASE is the test. It strings flows together as rows (in the same
   browser, or a new one for a second person) and switches on the checks it is
   about. Build it with preview_case, then save_case \u2014 which runs it first.
@@ -1479,6 +1625,7 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
             required: ["profileId"],
             additionalProperties: false
           },
+          fresh: { type: "boolean", description: "Start over, ignoring a draft of this flow left by an earlier attempt. By default the earlier steps are replayed and kept, and recording carries on from there." },
           projectId: { type: "string" }
         },
         required: ["name", "feature"],
@@ -1510,7 +1657,7 @@ Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
           ...feature ? { featureId: feature.id } : { featureName: featureAsked },
           startPath: str(args["startPath"]) || (isMobile(platform) ? "" : "/"),
           ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
-        }, catalog);
+        }, catalog, { ...args["fresh"] === true ? { fresh: true } : {} });
         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} ${isMobile(platform) ? "The app is open on the phone." : "The browser is open."}
 
@@ -1632,20 +1779,21 @@ ${page}`);
     {
       name: "save_flow",
       title: "Save the flow to a branch",
-      description: "Save the flow onto Claude's working branch for this project (made on the first save), for a person to review and publish. Saving the same name again replaces the earlier version there. Returns the review link. Refused if the flow checks nothing.",
+      description: "Save the flow onto Claude's working branch for this project (made on the first save), for a person to review and publish. Saving the same name again replaces the earlier version there. The flow is replayed from the start first, as a test run will run it, unless the same steps already passed replay_flow; one that fails is not saved and the failing step is named. Returns the review link. Refused if the flow checks nothing.",
       inputSchema: {
         type: "object",
         properties: {
           title: { type: "string", description: "The branch's title, used only when a new branch is started." },
           branch: { type: "string", description: "Optional: a branch id (chg_\u2026) from list_my_branches to save onto instead." },
-          newBranch: { type: "boolean", description: "Start a separate branch instead of the working one. Only when the person asks for separate reviews." }
+          newBranch: { type: "boolean", description: "Start a separate branch instead of the working one. Only when the person asks for separate reviews." },
+          force: { type: "boolean", description: "Save even though the replay from the start failed \u2014 only when the person asked for it as it is." }
         },
         additionalProperties: false
       },
       run: async (args) => text(await session.save(str(args["title"]), {
         ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {},
         ...args["newBranch"] === true ? { newBranch: true } : {}
-      }))
+      }, { ...args["force"] === true ? { force: true } : {} }))
     },
     {
       name: "list_my_branches",
@@ -2031,7 +2179,7 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
           }
         }
         const { pages } = await service.knowledgePages(projectId);
-        const read = async (path2) => pages.some((p) => p.path === path2) ? (await service.knowledgePage(projectId, path2)).content : null;
+        const read = async (path3) => pages.some((p) => p.path === path3) ? (await service.knowledgePage(projectId, path3)).content : null;
         const [product, glossary, decisions, web, android, ios, tagged] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md", "product/web.md", "product/android.md", "product/ios.md", "codebase.json"].map(read));
         const codebases = pages.filter((p) => p.path.startsWith("codebase/"));
         const tags = codebaseIndexOf(tagged).folders;
@@ -2122,8 +2270,7 @@ ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") |
       inputSchema: { type: "object", properties: {}, additionalProperties: false },
       annotations: { destructiveHint: true },
       run: async () => {
-        await session.close();
-        session.draft = null;
+        await session.closeAndDrop();
         return text("Closed.");
       }
     }
@@ -2315,14 +2462,14 @@ function serveWithUpgrades(tools, info, opts) {
 }
 
 // src/updates.ts
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path2 from "path";
 var CACHE_MS = 30 * 60 * 1e3;
 async function latestPublished(opts = {}) {
-  const file = path.join(dataDir(), "latest-agent.json");
+  const file = path2.join(dataDir(), "latest-agent.json");
   if (!opts.fresh) {
     try {
-      const kept = JSON.parse(fs.readFileSync(file, "utf8"));
+      const kept = JSON.parse(fs2.readFileSync(file, "utf8"));
       if (kept.version && kept.at && Date.now() - kept.at < CACHE_MS) return kept.version;
     } catch {
     }
@@ -2333,8 +2480,8 @@ async function latestPublished(opts = {}) {
     const version = (await res.json()).version ?? null;
     if (version) {
       try {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify({ version, at: Date.now() }));
+        fs2.mkdirSync(path2.dirname(file), { recursive: true });
+        fs2.writeFileSync(file, JSON.stringify({ version, at: Date.now() }));
       } catch {
       }
     }

package/dist/{dist-6GKVE5CL.js → dist-RDJIIBQV.js}

@@ -40,12 +40,13 @@ import {
   run,
   runMobileSteps,
   screenLines,
+  shrink,
   stopAppium,
   targetFor,
   textOf,
   toolEnv,
   typesSecrets
-} from "./chunk-FIR6NOLA.js";
+} from "./chunk-O34WXNH6.js";
 export {
   AGENT_HOME,
   APPIUM_DIR,
@@ -87,6 +88,7 @@ export {
   runMobileSteps,
   run as runTool,
   screenLines,
+  shrink,
   stopAppium,
   targetFor,
   textOf,

package/dist/engine.js

@@ -9,8 +9,8 @@ import {
   resolveCheckouts,
   start,
   status
-} from "./chunk-6AR63WTN.js";
-import "./chunk-FIR6NOLA.js";
+} from "./chunk-H3YHYPVE.js";
+import "./chunk-O34WXNH6.js";
 export {
   AGENT_VERSION,
   browsersReady,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowriki/agent",
-  "version": "0.1.0-beta.53",
+  "version": "0.1.0-beta.56",
   "description": "Run Flowriki UI tests on your own computer. Connects this machine to your Flowriki account.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",