@foldspace_npm/harness 0.1.26 → 0.1.28

package/recipes/server-rendered-forms/agent/forms.ts

@@ -0,0 +1,192 @@
+// Reading a server-rendered form and building the body a browser would post.
+// The form is read live at run time, so the hidden fields the app expects (its
+// CSRF token, a nonce, a form id) go along unchanged; the fields to fill are
+// found by their labels. Nothing here touches the network; api/pages.ts does.
+
+export type Field = { name: string; label: string; type: string; value: string };
+export type FoundForm = { doc: Document; form: Element; fields: Field[] };
+
+const clean = (text: string | null | undefined) => (text ?? "").replace(/[*\s]+/g, " ").trim();
+
+/** The label a person sees next to a field, lower-cased - or "" when there is none. */
+export function labelText(doc: Document, field: Element): string {
+  const id = field.getAttribute("id");
+  const byFor = id ? doc.querySelector(`label[for="${id.replace(/"/g, '\\"')}"]`) : null;
+  const label = byFor ?? field.closest("label");
+  const own = clean(label?.textContent).toLowerCase();
+  if (own) return own;
+  return clean(field.getAttribute("aria-label") || field.getAttribute("placeholder")).toLowerCase();
+}
+
+/** The form on the page that has a field with this label, or null (a sign-in page, for one). */
+export function findForm(doc: Document, hasField: RegExp): FoundForm | null {
+  for (const form of Array.from(doc.querySelectorAll("form"))) {
+    const controls = Array.from(form.querySelectorAll("input,textarea,select"));
+    if (!controls.some((field) => hasField.test(labelText(doc, field)))) continue;
+    const fields = controls
+      .map((field) => ({
+        name: field.getAttribute("name") ?? "",
+        label: labelText(doc, field),
+        type: (field.getAttribute("type") ?? field.tagName.toLowerCase()).toLowerCase(),
+        value: valueOf(field),
+      }))
+      .filter((field) => field.name);
+    return { doc, form, fields };
+  }
+  return null;
+}
+
+function valueOf(field: Element): string {
+  if (field.tagName === "TEXTAREA") return field.textContent ?? "";
+  if (field.tagName === "SELECT") {
+    const chosen = field.querySelector("option[selected]") ?? field.querySelector("option");
+    return chosen?.getAttribute("value") ?? chosen?.textContent ?? "";
+  }
+  return field.getAttribute("value") ?? "";
+}
+
+/** The field a person would type into for this label, or null. Hidden fields are never matched. */
+export function fieldByLabel(found: FoundForm, pattern: RegExp): Field | null {
+  return found.fields.find((field) => field.type !== "hidden" && pattern.test(field.label)) ?? null;
+}
+
+/**
+ * What the browser sends when the submit button is pressed: every named,
+ * enabled field - hidden ones included, file inputs left out - with the values
+ * given here on top. An unchecked box, a radio group nobody chose and a
+ * multiple list with nothing chosen send nothing, as in a browser; nor does a
+ * field in a disabled fieldset.
+ */
+export function formBody(found: FoundForm, values: Record<string, string>): URLSearchParams {
+  const body = new URLSearchParams();
+  for (const field of Array.from(found.form.querySelectorAll("input,textarea,select"))) {
+    const name = field.getAttribute("name");
+    if (!name || field.hasAttribute("disabled") || field.closest("fieldset[disabled]")) continue;
+    const type = (field.getAttribute("type") ?? "").toLowerCase();
+    if (type === "submit" || type === "button" || type === "reset" || type === "image" || type === "file") continue;
+    // A box or radio with no value of its own sends "on", as in a browser.
+    const ownValue = field.getAttribute("value") ?? "on";
+    if (name in values) {
+      if (type === "radio" || type === "checkbox") {
+        if (ownValue === values[name]) body.append(name, values[name]);
+        continue;
+      }
+      if (!body.has(name)) body.append(name, values[name]);
+      continue;
+    }
+    if (type === "checkbox" || type === "radio") {
+      if (field.hasAttribute("checked")) body.append(name, ownValue);
+      continue;
+    }
+    // A multiple list sends each chosen option, and nothing when none is chosen.
+    if (field.tagName === "SELECT" && field.hasAttribute("multiple")) {
+      for (const option of Array.from(field.querySelectorAll("option[selected]"))) {
+        body.append(name, option.getAttribute("value") ?? (option.textContent ?? "").replace(/\s+/g, " ").trim());
+      }
+      continue;
+    }
+    body.append(name, valueOf(field));
+  }
+  const submit = found.form.querySelector("[type=submit][name],button[name]:not([type])");
+  if (submit?.getAttribute("name")) body.append(submit.getAttribute("name")!, submit.getAttribute("value") ?? "");
+  return body;
+}
+
+/** Where the form posts, as a full address. */
+export function formAction(found: FoundForm, pageUrl: string): string {
+  return new URL(found.form.getAttribute("action") || pageUrl, pageUrl).toString();
+}
+
+export type Enctype = "urlencoded" | "multipart";
+export function formEnctype(found: FoundForm): Enctype {
+  return /multipart/i.test(found.form.getAttribute("enctype") ?? "") ? "multipart" : "urlencoded";
+}
+
+/** The same body as multipart/form-data, for forms that declare it. */
+export function asMultipart(body: URLSearchParams): FormData {
+  const data = new FormData();
+  body.forEach((value, name) => data.append(name, value));
+  return data;
+}
+
+/**
+ * Validation messages on a re-rendered form: the detail, not just the banner.
+ * A banner with a success, info or notice class, or with "success" in its
+ * text, is skipped; any other banner counts as an error.
+ */
+export function formErrors(doc: Document): string[] {
+  const messages: string[] = [];
+  const add = (text: string | null | undefined) => {
+    const line = (text ?? "").replace(/\s+/g, " ").replace(/^×\s*/, "").trim();
+    if (line && line.length < 400 && !messages.includes(line)) messages.push(line);
+  };
+  const banners = ".alert-danger,.alert-error,.alert,.errors,.error_explanation,#error_explanation,.flash-error,[role=alert]";
+  for (const box of Array.from(doc.querySelectorAll(banners))) {
+    if (box.matches(".alert-success,.alert-info,.notice,.flash-notice") || /success/i.test(box.textContent ?? "")) continue;
+    const items = Array.from(box.querySelectorAll("li"));
+    if (items.length) items.forEach((item) => add(item.textContent));
+    else add(box.textContent);
+  }
+  const inline = ".help-block.error,.help-inline,.invalid-feedback,.error-message,.field-error,[aria-invalid=true] + .help";
+  for (const node of Array.from(doc.querySelectorAll(inline))) add(node.textContent);
+  for (const wrap of Array.from(doc.querySelectorAll(".field_with_errors,.has-error,[aria-invalid=true]"))) {
+    const field = wrap.matches("input,textarea,select") ? wrap : wrap.querySelector("input,textarea,select");
+    const label = field ? labelText(doc, field) : "";
+    if (label && !messages.some((line) => line.toLowerCase().includes(label))) add(`The ${label} field was marked as not valid.`);
+  }
+  return messages.slice(0, 8);
+}
+
+/** A 400 or 422 answer to a form post: the app refused the form, and its page says why. */
+export function refusedForm(status: number): boolean {
+  return status === 400 || status === 422;
+}
+
+/**
+ * Did the write land? `created` only when the app did not refuse the form, the
+ * answer came from a different path than the form page, the same form (found
+ * by the same label, posting where this one posted) is not on it, and
+ * formErrors found nothing there. Anything else is `not_created`, with the
+ * messages formErrors found. A form on the answer page that posts elsewhere -
+ * the new record's own edit form, or a quick-add box in the header, say - is
+ * not the form again.
+ */
+export function judgeSubmit(
+  formUrl: string,
+  answer: { url: string; html: string; status?: number },
+  knownBy: RegExp,
+  postedTo: string,
+): { status: "created" | "not_created"; url: string; errors: string[] } {
+  const doc = new DOMParser().parseFromString(answer.html, "text/html");
+  const errors = formErrors(doc);
+  const refused = refusedForm(answer.status ?? 200);
+  const movedOn = new URL(answer.url).pathname !== new URL(formUrl).pathname;
+  // Every form with the label counts, not only the first on the page.
+  const postedPath = new URL(postedTo).pathname;
+  const formAgain = Array.from(doc.querySelectorAll("form")).some(
+    (form) =>
+      Array.from(form.querySelectorAll("input,textarea,select")).some((field) => knownBy.test(labelText(doc, field))) &&
+      new URL(form.getAttribute("action") || answer.url, answer.url).pathname === postedPath,
+  );
+  return !refused && movedOn && !formAgain && !errors.length
+    ? { status: "created", url: answer.url, errors: [] }
+    : { status: "not_created", url: answer.url, errors };
+}
+
+/** Rows of a table on a server-rendered list page: header names -> cell text. */
+export function tableRows(doc: Document, tableSelector = "table"): Record<string, string>[] {
+  const table = doc.querySelector(tableSelector);
+  if (!table) return [];
+  const headers = Array.from(table.querySelectorAll("thead th, thead td")).map((cell) => clean(cell.textContent));
+  const rows: Record<string, string>[] = [];
+  for (const row of Array.from(table.querySelectorAll("tbody tr, tr"))) {
+    const cells = Array.from(row.querySelectorAll("td"));
+    if (!cells.length) continue;
+    const record: Record<string, string> = {};
+    cells.forEach((cell, index) => {
+      record[headers[index] || `column${index + 1}`] = clean(cell.textContent);
+    });
+    rows.push(record);
+  }
+  return rows;
+}

package/recipes/server-rendered-forms/fixtures/form.errors.html

@@ -0,0 +1,9 @@
+<!doctype html><html><body>
+<div class="alert alert-danger">Unable to create record, there is 1 error</div>
+<form action="/records" method="post">
+  <input type="hidden" name="_token" value="nonce-8f3a">
+  <div class="field_with_errors"><label for="rec_title">Title *</label><input id="rec_title" name="record[title]" type="text" value=""></div>
+  <span class="help-block error">Title can't be blank</span>
+  <input type="submit" name="commit" value="Create record">
+</form>
+</body></html>

package/recipes/server-rendered-forms/fixtures/form.html

@@ -0,0 +1,17 @@
+<!doctype html><html><body>
+<h1>New record</h1>
+<form action="/records" method="post">
+  <input type="hidden" name="_token" value="nonce-8f3a">
+  <input type="hidden" name="_form" value="add">
+  <label for="rec_title">Title *</label><input id="rec_title" name="record[title]" type="text">
+  <label for="rec_desc">Description</label><textarea id="rec_desc" name="record[description]"></textarea>
+  <fieldset><legend>Visibility</legend>
+    <label><input type="radio" name="record[visibility]" value="everyone"> Everyone</label>
+    <label><input type="radio" name="record[visibility]" value="team"> My team</label>
+  </fieldset>
+  <label><input type="checkbox" name="record[notify]" value="1"> Notify followers</label>
+  <label><input type="checkbox" name="record[archived]" value="1" checked> Archived</label>
+  <select name="record[kind]"><option value="note">Note</option><option value="task" selected>Task</option></select>
+  <input type="submit" name="commit" value="Create record">
+</form>
+</body></html>

package/recipes/server-rendered-forms/fixtures/list.html

@@ -0,0 +1,9 @@
+<!doctype html><html><body>
+<table class="records">
+  <thead><tr><th>Title</th><th>Kind</th><th>Updated</th></tr></thead>
+  <tbody>
+    <tr><td><a href="/records/1">Quarterly review</a></td><td>Task</td><td>Sep 29, 2026</td></tr>
+    <tr><td><a href="/records/2">Welcome note</a></td><td>Note</td><td>Sep 28, 2026</td></tr>
+  </tbody>
+</table>
+</body></html>

package/recipes/server-rendered-forms/fixtures/record.html

@@ -0,0 +1,4 @@
+<!doctype html><html><body>
+<div class="alert alert-success">Record was successfully created</div>
+<h1>Quarterly review</h1>
+</body></html>

package/recipes/server-rendered-forms/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Server-rendered pages and forms",
+  "level": "L4",
+  "family": "server-rendered",
+  "kind": "action",
+  "action": "create_record_via_form",
+  "entry": "agent/actions/create_record_via_form.ts",
+  "outcome": "On a product that renders its pages on the server and has no JSON API, records are read off its pages and a record is created through the same form a person would fill in",
+  "provenBy": 1
+}

package/recipes/several-hosts/README.md

@@ -1,35 +1,32 @@
 # One product, several hosts
 
-**The product lives on more than one host** — `www.`, `analyze.`, `communicate.`, `admin.` under one domain — **and the agent should work on all of them.**
+**The product lives on more than one host** - `www.example.com`, `app.example.com`, `reports.example.com`, `admin.example.com` - **and the agent should work on all of them.**
 
 **Proven by 1 production build**, which met each part of this the hard way, one at a time.
 
 ## Find out at the start
 
-`npx foldspace observe menu` names the hosts a page links to that belong to the same product and that this project does not cover (`otherHosts`, `hostsHint`). `init` covers only the host you gave it. Tell the human which hosts you found and ask for a yes before adding the pattern (`"*.example.com"`) to `hosts` in `foldspace.dev.json`; then `npm run inject` and attach again. After that you open screens on the other hosts yourself: `npx foldspace observe screen --goto https://analyze.example.com/reports`.
+`npx foldspace observe menu` names the hosts a page links to that belong to the same product and that this project does not cover (`otherHosts`, `hostsHint`). `init` covers the host you gave it and that host's subdomains, not its sibling hosts. Tell the human which hosts you found and ask for a yes before adding the pattern (`"*.example.com"`) to `hosts` in `foldspace.dev.json`. On a yes: add it, then `npx foldspace attach --stop`, `npm run inject`, and attach again with the flags it ran with (`--daemon`, plus `--bootstrap` or `--replace` if it had one) - a running attach keeps the hosts it started with. After that you open screens on the other hosts yourself: `npx foldspace observe screen --goto https://reports.example.com/`. On a no: build only on the hosts the project covers.
 
 ## What this recipe gives
 
 | Piece | What it does |
 |---|---|
-| `wrongHost(tool)` | First line of an action. On the right host: `null`. On another: `{ status: "wrong_page", required_page, current_page }`, and no request is made |
-| `installResumeAcrossHosts()` | **A registered workaround.** After the agent moves the user to the right host, the conversation carries on there by itself |
+| `wrongHost(part)` | First line of an action. On the right host: `null`. On another: `{ status: "wrong_page", required_page, current_page }`, and no request is made |
 
-In Agent Studio, each action's instructions say: *on `wrong_page`, navigate to that tool's route, then call the action again.* Give each tool a navigation route with a full address.
+The SDK does the rest. After the agent moves the user to another host under the same domain (`reports.example.com` from `app.example.com`), the user, their conversations and the agent's turn carry across: the SDK keeps its resume note in a cookie on that shared domain (SDK of 2026-10-04, PLG-5962). ⚠️ Not when the page's Foldspace install sets the SDK option `fullDomainCookie`: the SDK then keeps its cookies - the user's session and the resume note - on the host that wrote them, so the agent does not carry on after the move. The option is not in the public docs; this was read from the SDK script. If the install sets it, tell the human in one sentence that the agent does not carry on after it moves someone to another host, and add a row for it under Workarounds in `docs/app-profile.md`. This recipe is the guard for an action asked from the wrong host.
+
+In Agent Studio, add to each guarded action's instructions: *On `wrong_page`, navigate to the route for the page named in `required_page`, then call this action again.* Give each part of the product a navigation route with a full address.
 
 ## Adapt it
 
 | File | Change |
 |---|---|
-| `agent/hosts.ts` → `TOOLS` | The product's tools and how to recognise each one's host (and path, if two tools share a host) |
-| `agent/actions/index.ts` | `installResumeAcrossHosts()` once, next to the registry |
+| `agent/hosts.ts` → `PARTS` | The parts of the product and how to recognise each one's host (and path, if two share a host) |
 | each action | `const wrong = wrongHost("reports"); if (wrong) return { success: true, ...wrong };` before any request |
-| `docs/app-profile.md` → Workarounds | One row for the resume workaround: what, why, `agent/hosts.ts`, verified or assumed, "goes when PLG-5962 ships" |
 
 ## What that build learned the hard way
 
-- **An action can only read the host it runs on.** Asked from Analyze, a Communicate action failed its first read in 150 ms. That is the browser, not the app.
-- **Who the user is, and their conversations, do carry across hosts** — Foldspace keeps the identity on the shared domain. What does not carry is the agent *continuing its turn* after it navigated: the note it leaves itself is kept per host, and the page that is leaving reports the navigation as finished.
-- **Reopening the conversation is not enough.** The first attempt restored the note on the new host; the right chat opened and nothing happened. It took a message to start the next turn — it shows as a user bubble, "Continue on this page."
-- **Ask the browser for the shared domain.** Counting dots gets `.co.uk` wrong.
-- **Remove it when the SDK carries on by itself.** This is Foldspace's to fix, not the customer's code to keep.
+- **An action reads only what the page it runs on may read.** Asked from the reports host, a messages action failed its first read in 150 ms. That is the browser, not the app.
+- **Who the user is, and their conversations, carry across hosts** - Foldspace keeps the identity on the shared domain (not with `fullDomainCookie`, above).
+- **The agent's turn did not carry across until PLG-5962.** The build handed the conversation over itself, in a cookie on the shared domain (`installResumeAcrossHosts`). The SDK does it now. If a project still has that code, remove it, its call in `agent/actions/index.ts` and its row under Workarounds in `docs/app-profile.md`. ⚠️ Left running alongside the SDK's own resume, it would send an extra "Continue on this page." from the user and start a second turn (read from the code, not seen live).

package/recipes/several-hosts/agent/hosts.ts

@@ -1,146 +1,29 @@
-// One product, several hosts (www. / analyze. / communicate. / admin. ...).
+// One product, several hosts (www. / app. / reports. / admin. ...).
 //
-// Two facts decide everything here:
-//   1. An action runs inside the page, and a page may only read its own host.
-//      Asked from the wrong host, the request cannot succeed - so say which
-//      page is needed instead of failing (`wrongHost`).
-//   2. WORKAROUND - registered in docs/app-profile.md, goes when PLG-5962 ships.
-//      When the agent moves the user to another host, the SDK does not carry
-//      on with the turn: its resume note is kept per host, and the page that
-//      is leaving reports the navigation as done. The user and the
-//      conversation do carry over; only the "carry on" is lost. So the
-//      conversation id is handed across in a 60-second cookie on the domain
-//      the hosts share, and the new page reopens it and starts the next turn
-//      (`installResumeAcrossHosts`). Established on a live build, 2026-09-25.
-
-import { getAgent } from "./utils";
-
-/** ADAPT: the tools of this product and the host each one lives on. */
-export const TOOLS: Record<string, { label: string; onThisHost: (hostname: string, path: string) => boolean }> = {
-  reports: { label: "Reports", onThisHost: (hostname) => hostname.startsWith("analyze.") },
-  messages: { label: "Messages", onThisHost: (hostname) => hostname.startsWith("communicate.") },
+// An action runs inside the page, and a page reads another host's signed-in
+// data only if that host allows it. When it does not, the request from the
+// wrong host fails - so say which page is needed instead (`wrongHost`). The
+// agent moves the user there with a navigation route, and the SDK carries the
+// user, their conversation and the agent's turn across to another host under
+// the same domain (PLG-5962, SDK of 2026-10-04; the README names the one SDK
+// option that stops it).
+
+/** ADAPT: the parts of this product and the host each one lives on. */
+export const PARTS: Record<string, { label: string; onThisHost: (hostname: string, path: string) => boolean }> = {
+  reports: { label: "Reports", onThisHost: (hostname) => hostname.startsWith("reports.") },
+  messages: { label: "Messages", onThisHost: (hostname) => hostname.startsWith("app.") },
 };
 
 export type WrongPage = { status: "wrong_page"; required_page: string; current_page: string };
 
-let resumeExpected = false;
-
 /**
- * First line of every action that reads or writes one tool: null on the right
- * host, otherwise the state to hand back - no request is made. The action's
- * Studio instructions say: on `wrong_page`, navigate to that tool's route,
- * then call the action again.
+ * First line of every action that reads or writes one part of the product:
+ * null on the right host, otherwise the state to hand back - no request is
+ * made. The action's Studio instructions say: on `wrong_page`, navigate to the
+ * route for the page named in `required_page`, then call this action again.
  */
-export function wrongHost(tool: keyof typeof TOOLS): WrongPage | null {
-  const wanted = TOOLS[tool];
+export function wrongHost(part: keyof typeof PARTS): WrongPage | null {
+  const wanted = PARTS[part];
   if (!wanted || wanted.onThisHost(window.location.hostname, window.location.pathname)) return null;
-  resumeExpected = true;
   return { status: "wrong_page", required_page: wanted.label, current_page: window.location.hostname };
 }
-
-// ---------------------------------------------------------------- the workaround
-
-const SDK_NAV_KEY = "_eucera_nav"; // the SDK's own resume note (per host)
-const COOKIE = "fs_resume";
-const TTL_SECONDS = 60;
-export const RESUME_MESSAGE = "Continue on this page.";
-
-type Carried = { conversationId: string; origin: string; expiry: number };
-
-function readCookie(name: string): string | null {
-  const hit = document.cookie.split("; ").find((entry) => entry.startsWith(`${name}=`));
-  return hit ? hit.slice(name.length + 1) : null;
-}
-
-/**
- * The widest domain the browser lets this page set a cookie on - the domain
- * the product's hosts share. Asked of the browser, the way the SDK does it:
- * guessing from the number of dots gets `.co.uk` wrong.
- */
-export function sharedCookieDomain(): string | null {
-  const labels = window.location.hostname.split(".");
-  if (labels.length < 2) return null;
-  const probe = "fs_domain_probe";
-  for (let from = labels.length - 1; from >= 0; from -= 1) {
-    const domain = labels.slice(from).join(".");
-    document.cookie = `${probe}=1; domain=${domain}; path=/; max-age=30`;
-    if (readCookie(probe) === "1") {
-      document.cookie = `${probe}=; domain=${domain}; path=/; max-age=0`;
-      return domain;
-    }
-  }
-  return null;
-}
-
-/** The page that is leaving: hand the conversation id to the next host. */
-function carryOut(): void {
-  if (!resumeExpected) return;
-  try {
-    const raw = window.localStorage.getItem(SDK_NAV_KEY);
-    if (!raw) return;
-    const record = JSON.parse(raw) as { payload?: { conversationId?: string }; normalizedUrl?: string };
-    const conversationId = record.payload?.conversationId;
-    if (!conversationId || !record.normalizedUrl || !/^https?:\/\//.test(record.normalizedUrl)) return;
-    const target = new URL(record.normalizedUrl);
-    const domain = sharedCookieDomain();
-    // Only to another host of the same product - never off the shared domain.
-    if (!domain || target.origin === window.location.origin) return;
-    if (target.hostname !== domain && !target.hostname.endsWith(`.${domain}`)) return;
-    const carried: Carried = { conversationId, origin: target.origin, expiry: Date.now() + TTL_SECONDS * 1000 };
-    const secure = window.location.protocol === "https:" ? "; secure" : "";
-    document.cookie = `${COOKIE}=${encodeURIComponent(JSON.stringify(carried))}; domain=${domain}; path=/; max-age=${TTL_SECONDS}; samesite=lax${secure}`;
-  } catch (error) {
-    console.warn("[several-hosts] could not hand the conversation over", error);
-  }
-}
-
-function waitForAgent(timeoutMs: number): Promise<any | null> {
-  const started = Date.now();
-  return new Promise((resolve) => {
-    const tick = () => {
-      const agent = getAgent();
-      if (agent && typeof agent.message === "function") return resolve(agent);
-      if (Date.now() - started > timeoutMs) return resolve(null);
-      setTimeout(tick, 250);
-    };
-    tick();
-  });
-}
-
-/** The page that arrives: reopen the conversation and start its next turn. */
-async function bringIn(waitMs: number, settleMs: number): Promise<"resumed" | "nothing" | "no_agent"> {
-  try {
-    const value = readCookie(COOKIE);
-    if (!value) return "nothing";
-    const domain = sharedCookieDomain();
-    // Used once: whatever happens next, the note is gone.
-    if (domain) document.cookie = `${COOKIE}=; domain=${domain}; path=/; max-age=0`;
-    const carried = JSON.parse(decodeURIComponent(value)) as Carried;
-    if (carried.origin !== window.location.origin || carried.expiry < Date.now()) return "nothing";
-    const agent = await waitForAgent(waitMs);
-    if (!agent) {
-      console.warn("[several-hosts] the agent did not appear; the conversation was not resumed");
-      return "no_agent";
-    }
-    // The chat frame has to load before it can switch conversation and send.
-    await new Promise((resolve) => setTimeout(resolve, settleMs));
-    agent.selectConversation(carried.conversationId);
-    agent.message(RESUME_MESSAGE);
-    return "resumed";
-  } catch (error) {
-    console.warn("[several-hosts] could not resume the conversation", error);
-    return "nothing";
-  }
-}
-
-let installed: Promise<"resumed" | "nothing" | "no_agent"> | null = null;
-
-/** Call once from agent/actions/index.ts, next to the registry. Safe to call twice. */
-export function installResumeAcrossHosts({ waitMs = 20_000, settleMs = 2_500 } = {}): Promise<
-  "resumed" | "nothing" | "no_agent"
-> {
-  if (installed) return installed;
-  installed = bringIn(waitMs, settleMs);
-  window.addEventListener("pagehide", carryOut);
-  return installed;
-}

package/recipes/several-hosts/fixtures/wrong-page.json

@@ -0,0 +1,6 @@
+{
+  "note": "This recipe makes no network calls. What wrongHost(\"reports\") hands back when the user is on app.example.com:",
+  "status": "wrong_page",
+  "required_page": "Reports",
+  "current_page": "app.example.com"
+}

package/recipes/several-hosts/recipe.json

@@ -2,9 +2,9 @@
   "title": "One product, several hosts",
   "level": "any",
   "family": "several-hosts",
-  "kind": "page-setup",
+  "kind": "guard",
   "entry": "agent/hosts.ts",
-  "setup": { "import": "installResumeAcrossHosts", "from": "../hosts" },
-  "outcome": "An action asked from the wrong host says so instead of failing, and the conversation carries on after the agent moves the user to the right host",
+  "guard": { "import": "wrongHost", "from": "../hosts", "part": "reports" },
+  "outcome": "An action asked from the wrong host says which page it needs instead of failing",
   "provenBy": 1
 }

package/recipes/swap-the-login-method/README.md

@@ -16,13 +16,21 @@ because the browser session was missing.
 ## Adapt it
 
 Copy the variant you need over your project's `agent/utils.ts`. Actions keep
-importing from `../utils`, so nothing else changes — that is what the seam is
-for.
+importing from `../utils`; the variant re-exports every helper the recipes
+import.
+
+`getAuthToken` is among them, but returns null with either variant: neither
+passes `AUTH_SOURCE` to `configure`. So `who-is-the-user` compiles on these
+apps and identifies no one. To identify the user, change its `sessionIdentity`
+to read the id from where you **observed** it: a user object in
+`localStorage`, or an app call that describes the signed-in person, not the
+account (check it against a second account member first, as that recipe
+says). If you observed neither, leave the user anonymous.
 
 | In the file | Change |
 |---|---|
 | `SESSION_STORAGE_KEY`, `SESSION_HEADER` | The key and header name you **observed** |
-| The cookies variant's extra headers | Only what you observed the app sending. One build needed `x-requested-with`; most do not |
+| `EXTRA_HEADERS` in the cookies variant | What you **observed** the app sending besides the cookies; most apps send none |
 | `API_BASE` in `constants.ts` | For a same-origin app, the app's own origin. Empty stays a failure on purpose, so a guessed host cannot look like success |
 
 ## What those builds learned the hard way
@@ -36,5 +44,8 @@ for.
   inside an object. Strip the quotes; one app switched between the first two.
 - **With cookies there is no token to check first**, so "signed out" is only
   known from the 401. Let it through as `signed_out` instead of pre-empting it.
-- **Do not `export *`** alongside your own `apiFetch` — name what you re-export,
-  so the default cannot come back by accident.
+- **Name what you re-export; never `export *`.** The harness's own helpers
+  that call the app's API return a config failure here, because the variants
+  set no `authSource`. Naming each one makes a new harness helper a choice -
+  re-export it, or give it its own version like `apiFetch` - instead of a
+  silent re-export.

package/recipes/swap-the-login-method/agent/utils.ts

@@ -24,8 +24,17 @@ export async function apiFetch<T = unknown>(
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<T>> {
+  // Empty API_BASE is a failure on purpose: a guessed host cannot look like
+  // success. `error` is drawn on the card and read by the agent - it says what
+  // is true; the builder's hint goes in `detail`, which only the console sees.
   if (!API_BASE) {
-    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+    return {
+      ok: false,
+      status: 0,
+      reason: "config",
+      error: "This is not set up yet.",
+      detail: "API_BASE is not set - capture the app's XHR first.",
+    };
   }
   const session = readSession();
   if (!session) return { ok: false, status: 401, reason: "signed_out", error: "Not signed in." };
@@ -54,8 +63,45 @@ export async function apiFetch<T = unknown>(
   }
 }
 
-// Everything else still comes from the harness. Named, NOT `export *` — that
-// would put the default apiFetch back next to this one.
+/** The same sign-in as `apiFetch`, for a file: the answer comes back as bytes. */
+export async function apiFetchBinary(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<Uint8Array>> {
+  if (!API_BASE) {
+    return {
+      ok: false,
+      status: 0,
+      reason: "config",
+      error: "This is not set up yet.",
+      detail: "API_BASE is not set - capture the app's XHR first.",
+    };
+  }
+  const session = readSession();
+  if (!session) return { ok: false, status: 401, reason: "signed_out", error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: { [SESSION_HEADER]: session, ...(init.headers ?? {}) },
+    });
+    if (!res.ok) return httpFailure(res, "That file could not be returned.");
+    return { ok: true, status: res.status, data: new Uint8Array(await res.arrayBuffer()) };
+  } catch (error) {
+    return networkFailure(error, "Download timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else comes from the harness, by name. Give a helper that calls
+// the app's API its own version above, as apiFetch and apiFetchBinary have:
+// the harness's returns a config failure here, because this file sets no
+// `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
   getAgent,
   armAllInstances,
@@ -69,5 +115,8 @@ export {
   renderError,
   renderFatal,
   renderFailure,
+  httpFailure,
+  networkFailure,
+  getAuthToken,
 } from "@foldspace_npm/harness/runtime";
 export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";