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

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  AndroidAppSchema,
   ArtifactPolicySchema,
   AuthReferenceSchema,
   CHECKS,
@@ -13,6 +14,7 @@ import {
   ExecutionEnvironmentSchema,
   FeatureSchema,
   FlowDocumentSchema,
+  IosAppSchema,
   MobileLane,
   PrerequisiteProblem,
   RecordedAssertionSchema,
@@ -45,6 +47,7 @@ import {
   nodeAt,
   normalizeStartUrl,
   openMobileSession,
+  openSessionOn,
   parseFlowDocument,
   performMobileStep,
   platformsOf,
@@ -65,7 +68,7 @@ import {
   textIndependent,
   validateActors,
   webCloudOf
-} from "./chunk-GLZFHC64.js";
+} from "./chunk-FIR6NOLA.js";
 
 // src/engine/machine.ts
 import fs from "fs";
@@ -73,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.50";
+var AGENT_VERSION = "0.1.0-beta.53";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -133,7 +136,7 @@ async function checkMachine() {
     }
   } catch {
   }
-  const { mobileDoctor: mobileDoctor2 } = await import("./dist-Z3WSTACX.js");
+  const { mobileDoctor: mobileDoctor2 } = await import("./dist-6GKVE5CL.js");
   return {
     agentVersion: AGENT_VERSION,
     node: process.versions.node,
@@ -232,7 +235,7 @@ function forgetConnection(service, env = process.env) {
 }
 var fingerprint = (secret2) => crypto2.createHash("sha256").update(secret2).digest("hex").slice(0, 12);
 
-// ../contracts/dist/chunk-S3GLB3QV.js
+// ../contracts/dist/chunk-NTBXG5EZ.js
 import { z } from "zod";
 var PROTOCOL_VERSION = 1;
 var PAIRING_CODE_TTL_MS = 5 * 60 * 1e3;
@@ -281,6 +284,9 @@ var CommandNameSchema = z.enum([
   // Reading a live phone session: its screen as a picture, and what is under
   // a point. Not effectful — a picture is far too big to keep as a result.
   "mobile.screen",
+  // The screen of whatever phone session is open on a platform — a run's,
+  // a recording's — as a picture, for the live mirror. Reading.
+  "mobile.peek",
   // What this computer has installed for web and phone testing. Reading.
   "machine.check"
 ]);
@@ -3960,7 +3966,7 @@ async function replayCase(opts) {
   let status2 = "passed";
   let error = null;
   const browserRows = occurrences.filter((o) => o.platform !== "android" && o.platform !== "ios");
-  const laneOf = new Map(sessionLanes(browserRows, opts.defaultActorId).map((plan, i) => [browserRows[i].occurrenceId, plan]));
+  const laneOf2 = new Map(sessionLanes(browserRows, opts.defaultActorId).map((plan, i) => [browserRows[i].occurrenceId, plan]));
   try {
     for (const [index, occurrence] of occurrences.entries()) {
       if (status2 !== "passed" || opts.signal?.aborted) {
@@ -4012,7 +4018,7 @@ async function replayCase(opts) {
       const navigates = navigatesFirst(occurrence);
       const who = occurrence.actorId ?? opts.defaultActorId ?? "default";
       const entry = resolveStartUrl(occurrence.baseUrl ?? baseUrl, occurrence.startPath ?? "/");
-      const plan = laneOf.get(occurrence.occurrenceId);
+      const plan = laneOf2.get(occurrence.occurrenceId);
       try {
         if (plan.opens && startOf(occurrence) === "fresh") await actors.restart(who, entry);
         else if (plan.opens) await actors.select(who, entry);
@@ -6157,7 +6163,7 @@ function toSummary(row) {
   };
 }
 
-// ../repository-store/dist/chunk-7ZZULR2K.js
+// ../repository-store/dist/chunk-QF7BTHZB.js
 var FLOWRIKI_DIR = ".flowriki";
 var FEATURES_DIR = `${FLOWRIKI_DIR}/features`;
 var CONFIG_PATH = `${FLOWRIKI_DIR}/config.json`;
@@ -6219,12 +6225,18 @@ function readEnvironments(raw) {
   const seen = /* @__PURE__ */ new Set();
   for (const entry of raw) {
     if (!entry || typeof entry !== "object") continue;
-    const { name, baseUrl } = entry;
+    const { name, baseUrl, android, ios } = entry;
     if (typeof name !== "string" || !name.trim()) continue;
     const key = name.trim().toLowerCase();
     if (seen.has(key)) continue;
     seen.add(key);
-    out.push({ name: name.trim(), baseUrl: typeof baseUrl === "string" ? baseUrl : "" });
+    const app = { android: AndroidAppSchema.safeParse(android), ios: IosAppSchema.safeParse(ios) };
+    out.push({
+      name: name.trim(),
+      baseUrl: typeof baseUrl === "string" ? baseUrl : "",
+      ...app.android.success ? { android: app.android.data } : {},
+      ...app.ios.success ? { ios: app.ios.data } : {}
+    });
   }
   return out;
 }
@@ -7982,6 +7994,105 @@ var BrowserBusy = class extends Error {
     this.name = "BrowserBusy";
   }
 };
+var LANES = ["web", "android", "ios"];
+var OneLane = class {
+  owner = null;
+  phase = "idle";
+  since = null;
+  /** Take the lane, or report who has it. Never awaits — that is the point. */
+  acquire(owner) {
+    if (this.owner !== null) {
+      return { ok: false, heldBy: this.owner, phase: this.phase };
+    }
+    this.owner = owner;
+    this.phase = "starting";
+    this.since = Date.now();
+    return { ok: true };
+  }
+  /** The holder finished starting and is now doing the thing. */
+  activate(owner) {
+    if (this.owner === owner) this.phase = "active";
+  }
+  /** The holder has begun shutting down. Still not idle: a second stop must
+   *  join the first rather than starting its own. */
+  beginRelease(owner) {
+    if (this.owner !== owner || this.phase === "stopping") return false;
+    this.phase = "stopping";
+    return true;
+  }
+  release(owner) {
+    if (this.owner !== owner) return;
+    this.owner = null;
+    this.phase = "idle";
+    this.since = null;
+  }
+  forceRelease() {
+    this.owner = null;
+    this.phase = "idle";
+    this.since = null;
+  }
+  state() {
+    return { owner: this.owner, phase: this.phase, since: this.since };
+  }
+};
+var BrowserLease = class {
+  lanes = { web: new OneLane(), android: new OneLane(), ios: new OneLane() };
+  /** The web lane's methods, as they always were: the browser coordinators
+   *  drive one platform and need not know about lanes. */
+  acquire(owner, lane = "web") {
+    return this.lanes[lane].acquire(owner);
+  }
+  activate(owner, lane = "web") {
+    this.lanes[lane].activate(owner);
+  }
+  beginRelease(owner, lane = "web") {
+    return this.lanes[lane].beginRelease(owner);
+  }
+  release(owner, lane = "web") {
+    this.lanes[lane].release(owner);
+  }
+  state(lane = "web") {
+    return this.lanes[lane].state();
+  }
+  /** One lane, bound: what a coordinator for that platform is handed. */
+  lane(lane) {
+    return this.lanes[lane];
+  }
+  /** Take several lanes at once — all or none, so a job on two platforms
+   *  never holds one while refused the other. */
+  acquireAll(owner, lanes) {
+    const taken = [];
+    for (const lane of new Set(lanes)) {
+      const claim = this.lanes[lane].acquire(owner);
+      if (!claim.ok) {
+        for (const had of taken) this.lanes[had].release(owner);
+        return { ok: false, lane, heldBy: claim.heldBy, phase: claim.phase };
+      }
+      taken.push(lane);
+    }
+    return { ok: true };
+  }
+  activateAll(owner, lanes) {
+    for (const lane of new Set(lanes)) this.lanes[lane].activate(owner);
+  }
+  releaseAll(owner, lanes) {
+    for (const lane of new Set(lanes)) this.lanes[lane].release(owner);
+  }
+  /** Drop every lane whoever holds it — shutdown, and nothing else. */
+  forceRelease() {
+    for (const lane of LANES) this.lanes[lane].forceRelease();
+  }
+  /** The sentence a refused caller is shown. Names what is happening and on
+   *  what, because "busy" leaves someone hunting for a window they cannot find. */
+  static refusal(heldBy, phase, lane = "web") {
+    const what = heldBy === "recording" ? "a recording" : heldBy === "debug" ? "a debug session" : "a run";
+    const where = lane === "web" ? "the browser" : lane === "android" ? "the Android phone" : "the iPhone";
+    if (phase === "starting") return `${what} is starting on ${where} \u2014 wait for it to open, or stop it first`;
+    if (phase === "stopping") return `${what} is still closing on ${where} \u2014 try again in a moment`;
+    return `${what} is already using ${where} \u2014 stop it before starting another`;
+  }
+};
+var laneOf = (platform) => platform === "android" || platform === "ios" ? platform : "web";
 var COMMANDS = /* @__PURE__ */ new Set([
   "play",
   "pause",
@@ -8158,11 +8269,12 @@ async function verifyFlowSteps(deps, opts) {
   const steps = (opts.steps ?? flow.steps).map((s2) => DraftStepSchema.parse(s2));
   if (!opts.verifyIds.length) return { results: [], error: null, failedAtStepId: null, ok: true };
   const baseUrl = store.baseUrlFor(flow);
-  const claim = deps.lease?.acquire("run");
+  const lane = laneOf(flow.platform);
+  const claim = deps.lease?.acquire("run", lane);
   if (claim && !claim.ok) {
-    throw new BrowserBusy(`the browser on this machine is in use (${claim.heldBy}, ${claim.phase})`);
+    throw new BrowserBusy(`${lane === "web" ? "the browser" : lane === "android" ? "the Android phone" : "the iPhone"} on this machine is in use (${claim.heldBy}, ${claim.phase})`);
   }
-  deps.lease?.activate("run");
+  deps.lease?.activate("run", lane);
   try {
     const secrets = store.readSecrets();
     if (isMobile(flow.platform)) {
@@ -8207,7 +8319,7 @@ async function verifyFlowSteps(deps, opts) {
       resolveSecret: (ref) => secrets[ref]
     });
   } finally {
-    deps.lease?.release("run");
+    deps.lease?.release("run", lane);
   }
 }
 function deliveredRun(delivered) {
@@ -8227,55 +8339,6 @@ function deliveredRun(delivered) {
     resolveFile: () => void 0
   };
 }
-var BrowserLease = class {
-  owner = null;
-  phase = "idle";
-  since = null;
-  /** Take the lease, or report who has it. Never awaits — that is the point. */
-  acquire(owner) {
-    if (this.owner !== null) {
-      return { ok: false, heldBy: this.owner, phase: this.phase };
-    }
-    this.owner = owner;
-    this.phase = "starting";
-    this.since = Date.now();
-    return { ok: true };
-  }
-  /** The holder finished starting and is now doing the thing. */
-  activate(owner) {
-    if (this.owner === owner) this.phase = "active";
-  }
-  /** The holder has begun shutting down. Still not idle: a second stop must
-   *  join the first rather than starting its own. */
-  beginRelease(owner) {
-    if (this.owner !== owner || this.phase === "stopping") return false;
-    this.phase = "stopping";
-    return true;
-  }
-  release(owner) {
-    if (this.owner !== owner) return;
-    this.owner = null;
-    this.phase = "idle";
-    this.since = null;
-  }
-  /** Drop the lease whoever holds it — shutdown, and nothing else. */
-  forceRelease() {
-    this.owner = null;
-    this.phase = "idle";
-    this.since = null;
-  }
-  state() {
-    return { owner: this.owner, phase: this.phase, since: this.since };
-  }
-  /** The sentence a refused caller is shown. Names what is happening, because
-   *  "busy" leaves someone hunting for a window they cannot find. */
-  static refusal(heldBy, phase) {
-    const what = heldBy === "recording" ? "a recording" : heldBy === "debug" ? "a debug session" : "a run";
-    if (phase === "starting") return `${what} is starting \u2014 wait for it to open, or stop it first`;
-    if (phase === "stopping") return `${what} is still closing \u2014 try again in a moment`;
-    return `${what} is already using the browser \u2014 stop it before starting another`;
-  }
-};
 
 // src/engine/checkouts.ts
 function resolveCheckouts(dirs) {
@@ -9232,11 +9295,12 @@ function executionHandlers(ctx) {
           detail: `this flow needs ${missing.length} secret value(s) that are not on this machine (${missing.map((m) => m.ref || m.field).join(", ")}) \u2014 set them on the machine that runs it`
         };
       }
-      const claim = lease?.acquire("run");
+      const lanes = [laneOf(flow.platform)];
+      const claim = lease?.acquireAll("run", lanes);
       if (claim && !claim.ok) {
-        return { ok: false, reason: "busy", detail: `the browser on this machine is in use (${claim.heldBy})` };
+        return { ok: false, reason: "busy", detail: BrowserLease.refusal(claim.heldBy, claim.phase, claim.lane) };
       }
-      lease?.activate("run");
+      lease?.activateAll("run", lanes);
       onActivity?.({ kind: "run", projectId: project.id, detail: flow.name });
       const aborter = new AbortController();
       cancels.set(command.id, { projectId: project.id, cancel: () => aborter.abort() });
@@ -9271,6 +9335,8 @@ function executionHandlers(ctx) {
           ok: true,
           result: {
             runId: outcome.run?.id ?? null,
+            // What it was called, for a service that only knew its id.
+            flowName: flow.name,
             // The WHOLE outcome, not a summary of it. A dashboard renders the
             // per-step report exactly as the local app does, and a result
             // carrying only counts makes that screen crash rather than degrade.
@@ -9286,7 +9352,7 @@ function executionHandlers(ctx) {
         if (typeof cancelKey === "string" && cancelKey.startsWith("suite:")) cancels.delete(cancelKey);
         if (runId) cancels.delete(runId);
         onActivity?.(null);
-        lease?.release("run");
+        lease?.releaseAll("run", lanes);
       }
     },
     /** Run a test case: several flows, one browser, in order.
@@ -9304,11 +9370,12 @@ function executionHandlers(ctx) {
       if (testCase.occurrences.length === 0) {
         return { ok: false, reason: "failed", detail: `"${testCase.name}" has no flows in it to run` };
       }
-      const claim = lease?.acquire("run");
+      const lanes = [...new Set(testCase.occurrences.map((o) => laneOf(o.platform)))];
+      const claim = lease?.acquireAll("run", lanes);
       if (claim && !claim.ok) {
-        return { ok: false, reason: "busy", detail: `the browser on this machine is in use (${claim.heldBy})` };
+        return { ok: false, reason: "busy", detail: BrowserLease.refusal(claim.heldBy, claim.phase, claim.lane) };
       }
-      lease?.activate("run");
+      lease?.activateAll("run", lanes);
       onActivity?.({ kind: "run", projectId: project.id, detail: testCase.name });
       const aborter = new AbortController();
       cancels.set(command.id, { projectId: project.id, cancel: () => aborter.abort() });
@@ -9347,6 +9414,8 @@ function executionHandlers(ctx) {
           ok: true,
           result: {
             runId: run?.id ?? null,
+            // What it was called, for a service that only knew its id.
+            caseName: testCase.name,
             // The whole outcome, per-flow groups included: a dashboard renders
             // the report from this, and a result carrying only counts makes
             // that screen crash rather than degrade.
@@ -9358,7 +9427,7 @@ function executionHandlers(ctx) {
         if (typeof cancelKey === "string" && cancelKey.startsWith("suite:")) cancels.delete(cancelKey);
         if (runId) cancels.delete(runId);
         onActivity?.(null);
-        lease?.release("run");
+        lease?.releaseAll("run", lanes);
       }
     },
     "run.cancel": async (command, project) => {
@@ -9726,6 +9795,7 @@ function assistantHandlers({ deps }) {
       const askId = randomUUID();
       const linked = foldersFor(project.id).filter((f) => f.exists).map((f) => f.path);
       const mode = command.args["mode"] === "ask" ? "ask" : command.args["mode"] === "do" ? "do" : void 0;
+      const brief = typeof command.args["brief"] === "string" && command.args["brief"].trim() ? command.args["brief"].slice(0, 4e4) : void 0;
       const started = assistant.ask({
         askId,
         prompt,
@@ -9733,6 +9803,7 @@ function assistantHandlers({ deps }) {
         projectName: project.name,
         ...linked.length ? { folders: linked } : {},
         ...mode ? { mode } : {},
+        ...brief ? { brief } : {},
         ...typeof sessionId === "string" ? { sessionId } : {},
         emit
       });
@@ -9769,7 +9840,9 @@ var runFile = (file2, args, timeoutMs) => new Promise((resolve2, reject) => {
     resolve2({ code, stdout: String(stdout), stderr: String(stderr) });
   });
 });
-var live = null;
+var live = /* @__PURE__ */ new Map();
+var liveById = (sessionId) => [...live.values()].find((l) => l.id === sessionId);
+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();
@@ -9795,8 +9868,9 @@ async function screenOf(l, withImage = false) {
 }
 function mobileHandlers(ctx) {
   const require2 = (command) => {
-    if (!live || command.args["sessionId"] !== live.id) throw new Error("that phone session has ended \u2014 open it again");
-    return live;
+    const l = liveById(command.args["sessionId"]);
+    if (!l) throw new Error("that phone session has ended \u2014 open it again");
+    return l;
   };
   return {
     // Everything this computer has for testing — web and phones — for the Guide.
@@ -9807,6 +9881,21 @@ function mobileHandlers(ctx) {
       const devices = await listDevices();
       return { ok: true, result: { devices, ...command.args["doctor"] === true ? { doctor: await mobileDoctor() } : {} } };
     },
+    // THE PHONE A RUN IS DRIVING, as a picture: whatever session is open on
+    // that platform — a run's, a recording's. Not effectful, never kept, and
+    // nothing when no phone is open: the mirror then shows that.
+    "mobile.peek": async (command) => {
+      const platform = command.args["platform"];
+      if (!isMobile(platform)) return { ok: false, reason: "failed", detail: "say which phone: android or ios" };
+      const session = live.get(platform)?.session ?? openSessionOn(platform);
+      if (!session) return { ok: true, result: { image: null } };
+      try {
+        const png = await session.screenshot();
+        return { ok: true, result: { image: png.toString("base64"), device: session.deviceName } };
+      } catch {
+        return { ok: true, result: { image: null } };
+      }
+    },
     "mobile.screen": async (command) => {
       try {
         const l = require2(command);
@@ -9823,14 +9912,21 @@ function mobileHandlers(ctx) {
     },
     "mobile.session": async (command, project) => {
       const op = String(command.args["op"] ?? "");
+      let claimed = null;
       try {
         if (op === "start") {
-          if (live) {
-            await live.session.close().catch(() => void 0);
-            live = null;
-          }
           const platform = command.args["platform"];
           if (!isMobile(platform)) return { ok: false, reason: "failed", detail: "say which phone: android or ios" };
+          const prior = live.get(platform);
+          if (prior) {
+            live.delete(prior.platform);
+            await prior.session.close().catch(() => void 0);
+            ctx.lease?.release(ownerOf(prior), prior.platform);
+          }
+          const owner = command.args["record"] === true ? "recording" : "debug";
+          const claim = ctx.lease?.acquire(owner, platform);
+          if (claim && !claim.ok) return { ok: false, reason: "busy", detail: BrowserLease.refusal(claim.heldBy, claim.phase, platform) };
+          claimed = { owner, platform };
           const config = command.args["config"] ?? {};
           const secrets = command.args["secrets"] ?? {};
           const device = command.args["device"] ? DeviceChoiceSchema.parse(command.args["device"]) : void 0;
@@ -9865,7 +9961,8 @@ function mobileHandlers(ctx) {
               ...auth?.profileId ? { signIn: auth } : {}
             };
           }
-          live = l2;
+          live.set(l2.platform, l2);
+          ctx.lease?.activate(owner, l2.platform);
           if (/^[a-z][\w+.-]*:\/\//i.test(startPath)) await session.openLink(startPath);
           const opening = [
             ...l2.draft?.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: l2.draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
@@ -9948,7 +10045,8 @@ function mobileHandlers(ctx) {
           return { ok: true, result: { steps: l.draft.steps } };
         }
         if (op === "stop" || op === "discard") {
-          live = null;
+          live.delete(l.platform);
+          ctx.lease?.release(ownerOf(l), l.platform);
           await l.session.close().catch(() => void 0);
           if (op === "discard" || !l.draft) return { ok: true, result: { ended: true } };
           const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -9972,6 +10070,7 @@ function mobileHandlers(ctx) {
         }
         return { ok: false, reason: "failed", detail: `unknown phone session operation "${op}"` };
       } catch (error) {
+        if (claimed && !live.has(claimed.platform)) ctx.lease?.release(claimed.owner, claimed.platform);
         return { ok: false, reason: "failed", detail: error.message.split("\n")[0] ?? "the phone session failed" };
       }
     }
@@ -10068,10 +10167,13 @@ var ASK_MODE_TOOLS = [
 function buildAskArgs(opts) {
   const ask = opts.mode === "ask";
   const folders = opts.folders ?? [];
+  const brief = opts.brief?.trim();
   const guidance = [
-    `You are the Flowriki assistant for the project "${opts.projectName}" (id ${opts.projectId}). Use the Flowriki tools, and pass projectId "${opts.projectId}" wherever a tool takes one. Start with project_brief: it is this project's memory.`,
+    `You are the Flowriki assistant for the project "${opts.projectName}" (id ${opts.projectId}). Use the Flowriki tools, and pass projectId "${opts.projectId}" wherever a tool takes one. ` + (brief ? "The project brief below is this project's memory for this job: read it first." : "Start with project_brief: it is this project's memory."),
     ask ? "ASK MODE: answer the question; change nothing. Cite what you rely on as [[testCase:<its id, tc_\u2026>]], [[knowledge:features/checkout.md]] or [[file:path/in/repo.ts]]." : "DO MODE: do what is asked, on Claude's working branch, for a person to review. Ask in the chat and wait before publishing, deleting, or sending anything to another system. End by writing a short summary of what you did with write_knowledge (memory/sessions/<date>-<topic>.md, append) so the next session knows.",
-    folders.length ? `The project's code is in ${folders.join(" and ")}. Read it with Read, Grep and Glob when it helps; you cannot change it.` : ""
+    folders.length ? `The project's code is in ${folders.join(" and ")}. Read it with Read, Grep and Glob when it helps; you cannot change it.` : "",
+    brief ? `
+${brief}` : ""
   ].filter(Boolean).join("\n");
   const flowriki = ask ? ASK_MODE_TOOLS.map((t) => `mcp__${MCP_SERVER_NAME}__${t}`) : [`mcp__${MCP_SERVER_NAME}`];
   const files = folders.length ? ["Read", "Grep", "Glob"] : [];

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

@@ -17,7 +17,7 @@ import path3 from "path";
 import fs4 from "fs";
 import path4 from "path";
 
-// ../test-model/dist/chunk-QDXJLOQJ.js
+// ../test-model/dist/chunk-I5COYCQ5.js
 import { z as z2 } from "zod";
 import { z } from "zod";
 var PLATFORMS = ["web", "android", "ios"];
@@ -86,8 +86,8 @@ var DeviceChoiceSchema = z.discriminatedUnion("kind", [
   }).strict()
 ]);
 var MobileConfigSchema = z.object({
-  android: AndroidAppSchema.optional(),
-  ios: IosAppSchema.optional(),
+  android: AndroidAppSchema.partial({ appPackage: true }).optional(),
+  ios: IosAppSchema.partial({ bundleId: true }).optional(),
   /** Between runs: keep the app's data (stays signed in), or start clean. */
   reset: z.enum(["keepData", "fresh"]).default("keepData"),
   /** Where runs go when nobody says — absent means whatever is available. */
@@ -98,6 +98,10 @@ var mobileOf = (config) => {
   const parsed = MobileConfigSchema.safeParse(config?.mobile ?? {});
   return parsed.success ? parsed.data : MobileConfigSchema.parse({});
 };
+var EnvironmentAppsSchema = z.object({
+  android: AndroidAppSchema.optional(),
+  ios: IosAppSchema.optional()
+});
 var DeviceInfoSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -1684,6 +1688,14 @@ var BugSchema = z7.object({
   updatedAt: z7.string()
 }).strict();
 var STOP = new Set("a an the and or of to in on for with by is are be as at it this that from user users can should must shall will when then given".split(" "));
+function exploreSummary(markdown) {
+  const screens = /^Screens:\s*(\d+)\s*$/im.exec(markdown)?.[1];
+  return {
+    exploredAt: /^Explored:\s*(\S+)\s*$/im.exec(markdown)?.[1] ?? null,
+    environment: /^Environment:\s*(.+?)\s*$/im.exec(markdown)?.[1] ?? null,
+    screens: screens ? Number(screens) : null
+  };
+}
 var CODEBASE_TAGS = ["all", "web", "android", "ios", "mobile", "other"];
 var CODEBASE_TAG_NAME = { all: "All combined", web: "Web", android: "Android", ios: "iOS", mobile: "Mobile", other: "Other" };
 var CodebaseIndexSchema = z8.object({
@@ -2518,11 +2530,11 @@ var CLOUD_HUBS = {
 function appOf(target) {
   if (target.platform === "android") {
     const app2 = target.mobile.android;
-    if (!app2) throw new Error("This project has no Android app set up \u2014 add it in Settings \u2192 Mobile.");
+    if (!app2?.appPackage) throw new Error("This environment has not named its Android app \u2014 add its package in Settings \u2192 Environments.");
     return { id: app2.appPackage, ...app2.appActivity ? { activity: app2.appActivity } : {}, ...app2.build ? { build: app2.build } : {} };
   }
   const app = target.mobile.ios;
-  if (!app) throw new Error("This project has no iOS app set up \u2014 add it in Settings \u2192 Mobile.");
+  if (!app?.bundleId) throw new Error("This environment has not named its iOS app \u2014 add its bundle ID in Settings \u2192 Environments.");
   return { id: app.bundleId, ...app.build ? { build: app.build } : {} };
 }
 async function localBuild(build) {
@@ -2556,6 +2568,10 @@ async function localCapabilities(target, udid, opts = {}) {
       "appium:appPackage": app.id,
       ...app.activity ? { "appium:appActivity": app.activity } : {},
       "appium:appWaitActivity": "*",
+      // 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 } : {},
+      ...opts.ports?.mjpeg ? { "appium:mjpegServerPort": opts.ports.mjpeg } : {},
       "appium:autoGrantPermissions": false,
       "appium:disableWindowAnimation": true,
       "appium:uiautomator2ServerLaunchTimeout": 12e4,
@@ -2572,6 +2588,8 @@ async function localCapabilities(target, udid, opts = {}) {
     "appium:bundleId": app.id,
     "appium:wdaLaunchTimeout": 24e4,
     "appium:wdaConnectionTimeout": 24e4,
+    ...opts.ports?.wda ? { "appium:wdaLocalPort": opts.ports.wda } : {},
+    ...opts.ports?.mjpeg ? { "appium:mjpegServerPort": opts.ports.mjpeg } : {},
     ...target.mobile.ios?.teamId ? { "appium:xcodeOrgId": target.mobile.ios.teamId, "appium:xcodeSigningId": "Apple Development" } : {}
   };
 }
@@ -3191,6 +3209,8 @@ async function checkMobileAssertion(session, a, timeoutMs = 3e3) {
   throw last;
 }
 var uploaded = /* @__PURE__ */ new Map();
+var OPEN = /* @__PURE__ */ new Map();
+var openSessionOn = (platform) => OPEN.get(platform) ?? null;
 var MobileSession = class _MobileSession {
   constructor(driver, platform, appId, deviceName, cloud) {
     this.driver = driver;
@@ -3231,6 +3251,7 @@ var MobileSession = class _MobileSession {
         throw new Error(`${CLOUD_PROVIDER_NAME[choice2.provider]} could not open ${choice2.device}: ${e.message}`);
       });
       const cloudSession = new _MobileSession(driver2, target.platform, app.id, choice2.device, true);
+      OPEN.set(target.platform, cloudSession);
       await cloudSession.settle(2e4);
       return cloudSession;
     }
@@ -3244,12 +3265,14 @@ var MobileSession = class _MobileSession {
     const endpoint = await appiumServer();
     const buildFile = app.build ? await localBuild(app.build) : null;
     say(`Opening the app on ${known.name}\u2026`);
-    const capabilities = await localCapabilities(target, udid, { buildFile });
+    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 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)})` : ""));
     });
     const session = new _MobileSession(driver, target.platform, app.id, known.name, false);
+    OPEN.set(target.platform, session);
     await session.terminateApp().catch(() => {
     });
     await session.launchApp().catch(() => {
@@ -3482,6 +3505,7 @@ var MobileSession = class _MobileSession {
     return { relPath: path4.basename(file), bytes: bytes.length };
   }
   async close() {
+    if (OPEN.get(this.platform) === this) OPEN.delete(this.platform);
     if (this.recording) await this.stopVideo(null);
     await this.driver.close();
   }
@@ -4053,6 +4077,8 @@ export {
   isMobile,
   stepRefusedOn,
   platformsOf,
+  AndroidAppSchema,
+  IosAppSchema,
   CLOUD_PROVIDERS,
   CLOUD_PROVIDER_NAME,
   DeviceChoiceSchema,
@@ -4086,6 +4112,7 @@ export {
   PrerequisiteProblem,
   expandForRun,
   DeliveredHelperSchema,
+  exploreSummary,
   CODEBASE_TAG_NAME,
   codebaseIndexOf,
   runWhereOf,
@@ -4137,6 +4164,7 @@ export {
   CheckError,
   textOf,
   checkMobileAssertion,
+  openSessionOn,
   MobileSession,
   MOBILE_TIMEOUTS,
   performMobileStep,

package/dist/cli.js

@@ -23,7 +23,7 @@ import {
   runtimeValue,
   start,
   status
-} from "./chunk-KRWHHKSS.js";
+} from "./chunk-6AR63WTN.js";
 import {
   CLOUD_PROVIDERS,
   CLOUD_PROVIDER_NAME,
@@ -32,6 +32,7 @@ import {
   RecordedStepSchema,
   checkMobileAssertion,
   codebaseIndexOf,
+  exploreSummary,
   isMobile,
   listDevices,
   locate,
@@ -48,7 +49,7 @@ import {
   screenLines,
   stepRefusedOn,
   targetFor
-} from "./chunk-GLZFHC64.js";
+} from "./chunk-FIR6NOLA.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -325,6 +326,10 @@ var ServiceClient = class {
     return this.call(this.scoped(`/bugs/${encodeURIComponent(id)}`, projectId), { method: "PATCH", body: JSON.stringify(body) });
   }
   // ── Knowledge, sources, requirements ──────────────────────
+  /** The project's brief for a job: its slice of the knowledge. */
+  brief(projectId, scope) {
+    return this.call(this.scoped("/brief", projectId, { ...scope.platform ? { platform: scope.platform } : {}, ...scope.features?.length ? { features: scope.features.join(",") } : {} }));
+  }
   knowledgePages(projectId) {
     return this.call(this.scoped("/knowledge", projectId));
   }
@@ -985,7 +990,7 @@ Review and publish it here: ${review}`;
   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");
+    if (!mobile) throw new Error("this project has no phone apps set up \u2014 turn on Android or iOS in Settings \u2192 Platforms");
     const resolvers = draft.signIn || draft.device?.kind === "cloud" ? await this.prepare() : null;
     this.mobile = await openMobileSession({
       platform,
@@ -1233,7 +1238,10 @@ codebase/<folder>.md, which must start "# <folder>", then "Commit: <full sha>"
 and "Learned: <yyyy-mm-dd>" lines: that is how the Knowledge screen shows it
 as learned. codebase.json says which platform's code each folder holds (Web,
 Android, iOS, Mobile, All combined, Other): read the web folder's page for a
-website test and the phone folder's for an app test. Keep what you learn with write_knowledge (features/<name>.md,
+website test and the phone folder's for an app test. explore/<platform>.md is
+what the assistant saw WALKING that platform \u2014 screens, the words on them,
+journeys, rules it saw refused, vocabulary: read it before writing a test for
+that platform, because it says what a person sees; the code does not. 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.
 
@@ -1412,7 +1420,7 @@ It is now the project these tools work on. Open it: ${service.origin}/projects/$
           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)"}
+          return `${p === "android" ? "Android" : "iOS"} app: ${app ?? "(not named \u2014 Settings \u2192 Environments)"}
   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(", ")}` : "") + `
   Runs: ${c.runWhere?.[p] === "cloud" ? "in the cloud" : "on this computer"}` + (chosen ? ` \u2014 ${chosen.kind === "local" ? chosen.name || chosen.id : `${CLOUD_PROVIDER_NAME[chosen.provider]}: ${chosen.device}`}` : "");
@@ -2009,11 +2017,19 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
     {
       name: "project_brief",
       title: "Read the project's memory",
-      description: "The project's own knowledge, in one call: About the product (product.md, and product/<web|android|ios>.md where a platform differs), memory/decisions.md, what each linked codebase folder was learned as and which platform's code it holds, and the list of feature pages and session summaries. Call it first in every conversation.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" } }, additionalProperties: false },
+      description: "The project's own knowledge, in one call: About the product (product.md, and product/<web|android|ios>.md where a platform differs), memory/decisions.md, what each linked codebase folder was learned as and which platform's code it holds, what each platform looked like when explored (explore/<platform>.md), and the list of feature pages and session summaries. Call it first in every conversation. With platform and/or features, the brief is the slice for that job: that platform's part and exploration, those features' notes, the code tagged for the platform, and who can sign in.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, platform: { type: "string", enum: ["web", "android", "ios"], description: "The platform the job is about." }, features: { type: "array", items: { type: "string" }, description: "The features (or case folders) the job is about, by name." } }, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
+        const platform = str(args["platform"]);
+        const features = Array.isArray(args["features"]) ? args["features"].filter((f) => typeof f === "string") : [];
+        if (platform || features.length) {
+          try {
+            return text((await service.brief(projectId, { ...platform ? { platform } : {}, features })).brief);
+          } catch {
+          }
+        }
         const { pages } = await service.knowledgePages(projectId);
         const read = async (path2) => pages.some((p) => p.path === path2) ? (await service.knowledgePage(projectId, path2)).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));
@@ -2023,7 +2039,12 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
           const holds = tags[p.path.slice("codebase/".length, -".md".length)]?.tags ?? [];
           return `- ${p.path}${holds.length ? ` (${holds.map((t) => CODEBASE_TAG_NAME[t]).join(", ")} code)` : ""}: ${(await read(p.path))?.split("\n").filter((l) => l.trim()).slice(0, 3).join(" \xB7 ") ?? ""}`;
         }));
-        const shown = /* @__PURE__ */ new Set(["product.md", "glossary.md", "memory/decisions.md", "product/web.md", "product/android.md", "product/ios.md", "codebase.json", ...codebases.map((p) => p.path)]);
+        const explored = pages.filter((p) => p.path.startsWith("explore/"));
+        const walks = await Promise.all(explored.map(async (p) => {
+          const s = exploreSummary(await read(p.path) ?? "");
+          return `- ${p.path}: explored ${s.exploredAt ?? "?"}${s.environment ? ` in ${s.environment}` : ""}${s.screens !== null ? `, ${s.screens} screens` : ""} \u2014 read it with knowledge_read before testing that platform`;
+        }));
+        const shown = /* @__PURE__ */ new Set(["product.md", "glossary.md", "memory/decisions.md", "product/web.md", "product/android.md", "product/ios.md", "codebase.json", ...codebases.map((p) => p.path), ...explored.map((p) => p.path)]);
         const parts = [
           product ? `## About the product (product.md)
 ${product}` : "No About the product yet \u2014 the person writes it on the Knowledge screen; offer to help draft it.",
@@ -2039,6 +2060,8 @@ ${glossary}` : "",
 ${decisions}` : "",
           codebases.length ? `## Codebase, as learned
 ${headers.join("\n")}` : "No codebase learned yet.",
+          walks.length ? `## The product, as explored
+${walks.join("\n")}` : "",
           `## Other pages
 ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") || "none"}`
         ];
@@ -2074,7 +2097,7 @@ ${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") |
     {
       name: "write_knowledge",
       title: "Write a knowledge page",
-      description: `Write what the project should remember, on Claude's working branch for review: product.md (About the product \u2014 the person's own description; write it only when they ask) and product/<web|android|ios>.md (what is particular to that platform's app), codebase/<folder>.md (what a linked folder holds \u2014 starting with "# <folder>", "Commit: <sha>" and "Learned: <yyyy-mm-dd>" lines, then routes, screens, forms and their validation, roles, APIs, flags; summarised, never copied code), features/<name>.md (screens, rules, quirks), memory/decisions.md (decisions and conventions), memory/sessions/<yyyy-mm-dd>-<topic>.md (what a job did). append: true adds to the end instead of replacing. Never a password, key or token \u2014 those are refused.`,
+      description: `Write what the project should remember, on Claude's working branch for review: product.md (About the product \u2014 the person's own description; write it only when they ask) and product/<web|android|ios>.md (what is particular to that platform's app), explore/<web|android|ios>.md (what you saw walking that platform: "# Explored: <Platform>", "Explored: <yyyy-mm-dd>", "Environment: <name>", "Screens: <n>" lines, then Screens, Journeys, Rules observed, Vocabulary, Suggested features), codebase/<folder>.md (what a linked folder holds \u2014 starting with "# <folder>", "Commit: <sha>" and "Learned: <yyyy-mm-dd>" lines, then routes, screens, forms and their validation, roles, APIs, flags; summarised, never copied code), features/<name>.md (screens, rules, quirks), memory/decisions.md (decisions and conventions), memory/sessions/<yyyy-mm-dd>-<topic>.md (what a job did). append: true adds to the end instead of replacing. Never a password, key or token \u2014 those are refused.`,
       inputSchema: {
         type: "object",
         properties: { projectId: { type: "string" }, path: { type: "string" }, content: { type: "string" }, append: { type: "boolean" }, branch: { type: "string" } },

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

@@ -31,6 +31,7 @@ import {
   mobileSetup,
   nodeAt,
   openMobileSession,
+  openSessionOn,
   performMobileStep,
   readScreen,
   replayMobileCase,
@@ -44,7 +45,7 @@ import {
   textOf,
   toolEnv,
   typesSecrets
-} from "./chunk-GLZFHC64.js";
+} from "./chunk-FIR6NOLA.js";
 export {
   AGENT_HOME,
   APPIUM_DIR,
@@ -77,6 +78,7 @@ export {
   mobileSetup,
   nodeAt,
   openMobileSession,
+  openSessionOn,
   performMobileStep,
   readScreen,
   replayMobileCase,

package/dist/engine.js

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

package/package.json

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