@foldspace_npm/harness 0.1.27 → 0.1.28

package/recipes/pick-from-a-list/README.md

@@ -5,21 +5,22 @@ list, picks one, and the choice goes back to the agent.
 
 **Proven by 1 production build**, which split this from
 [`find-by-name`](../find-by-name/) on purpose: *asking is a decision the agent
-makes, not a side effect of looking something up.* A lookup that draws a widget
+makes, not a side effect of looking something up.* A lookup that draws a card
 puts a selection in front of someone who only asked a question.
 
 In Agent Studio: an action with key `choose_project`, optional string parameters
 `name` (narrow the list to what the user said) and `purpose` (shown above the
-list: "Which project for *the export*?").
+list: "Which project for *the export*?"). Instructions to set: "No emoji. Quote
+totals and counts exactly as returned; never work them out."
 
 ## What it does
 
 | Situation | What happens |
 |---|---|
-| Projects to choose from | the card; the agent **waits** (`awaitUserInput: true`) |
+| Projects to choose from | an input card: `render` uses `callback`, so the agent **waits** until the user picks one, chooses "None of these" or cancels - each calls `callback` once |
 | The name matched nothing | falls back to the whole list — an empty picker cannot be answered |
-| The account has no projects | **no card**; the result goes straight back |
-| The list could not be loaded | **no card**, `success: false` — never "no projects" for someone who has hundreds |
+| The account has no projects | a one-line card that says so; the result goes straight back |
+| The list could not be loaded | the failure, drawn with `renderFailure`, goes straight back with `success: false` - never "no projects" for someone who has hundreds |
 | The user picks one | `chosenByUser: true` and the project |
 | "None of these" | what was offered, so the agent can ask what they meant |
 | Cancel | `cancelled: true` — and the card says so, so it is not left looking live |
@@ -30,7 +31,7 @@ list: "Which project for *the export*?").
 |---|---|
 | `agent/api/projects.ts`, `agent/projects.ts` | Same as `find-by-name` — keep the two recipes on one copy so their shortlists agree |
 | `agent/actions/choose_project.ts` | The entity and the wording |
-| `agent/views/picker.ts` | What a row shows. Re-sample `brand.ts` from the host page |
+| `agent/views/picker.ts` | What a row shows. `brand.ts` here is a placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one |
 
 ## What that build learned the hard way
 

package/recipes/pick-from-a-list/agent/actions/choose_project.ts

@@ -1,11 +1,13 @@
-// Asks the user which project to work with, and waits for the answer.
+// An input card: asks the user which project to work with, and the agent
+// waits for the answer.
 //
 // This exists so that asking is a decision the agent makes, not a side effect of
 // looking something up. find_project_id answers questions and must never put a
-// widget in front of someone who only asked one.
+// card in front of someone who only asked one.
 
 import { listProjects } from "../api/projects";
 import { toSummary, type ProjectSummary } from "../projects";
+import { renderEmpty, renderFailure, type FailureReason } from "../utils";
 import { mountProjectPicker } from "../views/picker";
 
 /** One screen of projects. */
@@ -25,7 +27,7 @@ type ChooseProjectResult = {
   success: boolean;
   message?: string;
   error?: string;
-  reason?: string;
+  reason?: FailureReason;
   data?: ChooseProjectData;
 };
 
@@ -67,7 +69,8 @@ export const choose_project = {
     if (projects.length === 0) {
       return {
         success: false,
-        error: "The project list could not be loaded just now.",
+        error: "The project list could not be loaded.",
+        reason: "server",
         data: { askable: false, total },
       };
     }
@@ -89,9 +92,10 @@ export const choose_project = {
     };
   },
 
-  awaitUserInput: true,
-
-  // `result` is what execute RETURNED, not the action's params.
+  // `result` is what execute RETURNED, not the action's params. An input
+  // card: render uses callback, so the agent waits for it. Every path calls
+  // it once - a failure or an empty account at once, the list when the user
+  // picks, chooses "None of these" or cancels.
   render: (
     result: ChooseProjectResult | undefined,
     host: HTMLElement,
@@ -101,9 +105,20 @@ export const choose_project = {
     const data = result?.data;
     const projects = data?.projects ?? [];
 
-    // Nothing to ask about — hand the result back rather than showing an empty
-    // card the user cannot answer.
-    if (!result || result.success === false || data?.askable === false || projects.length === 0) {
+    // Nothing to ask about: draw one line that says why, never an empty picker
+    // the user cannot answer, and hand the result straight back.
+    if (!result || result.success === false) {
+      renderFailure(host, {
+        ok: false,
+        status: 0,
+        error: result?.error ?? "The project list could not be loaded.",
+        reason: result?.reason ?? "server",
+      });
+      callback(result, true);
+      return;
+    }
+    if (data?.askable === false || projects.length === 0) {
+      renderEmpty(host, "This account has no projects yet.");
       callback(result, true);
       return;
     }
@@ -113,7 +128,7 @@ export const choose_project = {
     // Say what is actually on screen.
     const subtitle =
       data?.narrowed && data.query
-        ? `${showing} project${showing === 1 ? "" : "s"} match "${data.query}".`
+        ? `Showing ${showing} project${showing === 1 ? "" : "s"} matching "${data.query}".`
         : showing < total
           ? `Showing ${showing} of ${total}.`
           : `${total} project${total === 1 ? "" : "s"} to choose from.`;
@@ -150,7 +165,7 @@ export const choose_project = {
         callback(
           {
             success: true,
-            message: "The user rejected every project on the list.",
+            message: "The user chose none of the projects on the list.",
             data: { chosenByUser: false, offered: offered.map((p) => p.name) },
           },
           true,

package/recipes/pick-from-a-list/agent/views/brand.ts

@@ -1,14 +1,35 @@
-// Neutral placeholders. SAMPLE the real values from computed styles on the host
-// page and record where each came from in docs/app-profile.md. Never edit by eye.
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
 
 export const brand = {
-  text: "rgb(17, 24, 39)",
-  muted: "rgb(107, 114, 128)",
-  primary: "rgb(37, 99, 235)",
-  border: "rgb(229, 231, 235)",
-  tint: "rgb(243, 244, 246)",
-  surface: "rgb(255, 255, 255)",
+  surface: "#FFFFFF",
+  surface2: "#F5F6FA",
+  text: "#111827",
+  muted: "#6B7280",
+  border: "#E5E7EB",
+  accent: "#2563EB",
+  accentText: "#FFFFFF",
+  font: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
   radius: "8px",
   size: { base: "14px", small: "12px" },
-  font: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
+  accentDeep: "#2538D6",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  bad: "#B91C1C",
+  primary: "#2563EB",
+  tint: "#F3F4F6",
+  disabled: "#9CA3AF",
+  money: "#047857",
+  ok: "#047857",
+  deals: "#2563EB",
+  contacts: "#2538D6",
+  cases: "#B45309",
 } as const;

package/recipes/pick-from-a-list/agent/views/picker.ts

@@ -81,7 +81,7 @@ export function mountProjectPicker(host: HTMLElement, header: HTMLElement, optio
   }
 
   const none = button("fs-pick-row", "None of these");
-  none.append(el("span", "fs-pick-meta", "Tell the assistant what you meant"));
+  none.append(el("span", "fs-pick-meta", "Say in the chat what you meant"));
   none.addEventListener("click", () => select(none, { kind: "other" }));
   rows.push(none);
   card.append(none);
@@ -96,8 +96,8 @@ export function mountProjectPicker(host: HTMLElement, header: HTMLElement, optio
       title.textContent = "Project selected";
       subtitle.textContent = done.project.name;
     } else if (done.kind === "other") {
-      title.textContent = "Sent to the assistant";
-      subtitle.textContent = "None of these projects.";
+      title.textContent = "None of these";
+      subtitle.textContent = "No project chosen from this list.";
     } else {
       title.textContent = "Cancelled";
       subtitle.textContent = "No project chosen.";

package/recipes/prepare-for-a-meeting/README.md

@@ -4,13 +4,13 @@
 
 **Proven by 1 production build.**
 
-One request loads the meeting, the account, the opportunities, the open cases, and past notes. Counts and the pipeline total are computed in code. Those facts are passed to `runTask` as `data`. There is no `prompt`: the task agent's instructions are created in Agent Studio. The key in this recipe, `__observe_me_summary`, is a placeholder — replace it with the key you publish. ⚠️ Check `list_task_agents` first; if the MCP has no tool to create one, the task agent is created by hand in Agent Studio and this recipe waits for it.
+One request loads the meeting, the account, the opportunities, the open cases, and past notes. Counts and the pipeline total are computed in code. Those facts are passed to `runTask` as `data`. There is no `prompt`: the instructions live on the task agent. `TASK_KEY` (`__observe_me_summary`) is a placeholder for the key of a published task agent - `runTask` resolves no other. Check `list_task_agents` first. One fits if it summarises a meeting from the facts in `data` and answers in text, or in JSON with a `summary` string - `readSummary` takes the text or that field, and a JSON answer without it gives `summary: null`. If one fits, put its key in `TASK_KEY`, and publish it with `publish_task_agent` if it is still a draft. If none fits, create one with `create_task_agent`: `response_type` `TEXT`, and instructions that write a meeting summary from the facts in `data`. It starts as a draft: publish it with `publish_task_agent`, then put its key (`api_name`) in `TASK_KEY`. Creating and publishing each change the customer's Foldspace account: ask the human before each.
 
 If `runTask` is missing or throws, `summary` is null and the message says a summary was not produced. The gathered facts still come back.
 
-A meeting with no account id and no account name is `signed_out`, not a pipeline of zero.
+A meeting whose account lacks an id or a name is `signed_out`, not a pipeline of zero.
 
-In Agent Studio: an action with key `prepare_for_meeting` and one string parameter `meetingId`. Also a task agent whose key matches `TASK_KEY`.
+In Agent Studio: an action with key `prepare_for_meeting` and one string parameter `meetingId`, described as "The meeting's id. Never taken from the user's words: get it from `<meetings action key>`." Replace `<meetings action key>` with the key of this agent's action that returns meeting ids; if the agent has none, build that action first - `find-by-name` has the shape. Instructions to set: "No emoji. Quote totals and counts exactly as returned; never work them out." The task agent is the one in `TASK_KEY` (above).
 
 ## Adapt it
 
@@ -18,7 +18,7 @@ In Agent Studio: an action with key `prepare_for_meeting` and one string paramet
 |---|---|
 | `agent/api/meetings.ts` | Mock path and envelope. Find a real API that returns a similar shape |
 | `agent/meetings.ts` | Which facts the summary needs. Totals stay computed here |
-| `agent/actions/prepare_for_meeting.ts` | `TASK_KEY`, after the task agent exists in Agent Studio |
+| `agent/actions/prepare_for_meeting.ts` | `TASK_KEY`: the published task agent's key |
 
 ## What that build learned the hard way
 

package/recipes/prepare-for-a-meeting/agent/actions/prepare_for_meeting.ts

@@ -1,12 +1,12 @@
 // Gather the meeting, then ask the task agent to summarise it. `data` is facts
-// only. The task agent's instructions live in Agent Studio, under the key below.
+// only. The instructions live on the task agent whose key is below.
 // If the task agent does not answer, the facts still come back and summary is null.
 
 import { getMeetingPrep } from "../api/meetings";
 import { belongsToSignedInUser, toPrep, type MeetingPrep } from "../meetings";
 import { getAgent } from "../utils";
 
-/** Replace with the task-agent key created in Agent Studio. */
+/** Replace with the published task agent's key (its `api_name`) - see the README. */
 const TASK_KEY = "__observe_me_summary";
 
 type PrepResult = {
@@ -35,7 +35,7 @@ export const prepare_for_meeting = {
   execute: async (params: { meetingId?: string }): Promise<PrepResult> => {
     const meetingId = typeof params?.meetingId === "string" ? params.meetingId.trim() : "";
     if (!meetingId) {
-      return { success: false, error: "meetingId was not provided.", reason: "config" };
+      return { success: false, error: "No meeting was given.", reason: "config" };
     }
 
     const res = await getMeetingPrep(meetingId);

package/recipes/records-list/README.md

@@ -4,11 +4,11 @@
 
 **Proven by 1 production build**, where the first version was a five-column table: at chat width (~400px) the columns collapsed and it looked wrong. Rows fixed it. This is the base layout for any list of records — contacts, projects, tickets — not just accounts.
 
-The card is view-only. `awaitUserInput` stays off. For a component that only shows something, the model is told that the information was displayed — nothing `execute` returned and nothing the card drew. So "No accounts yet." is on the card, not in a message. The count and the total are computed in code from the rows.
+A view card: `render` takes no `callback` and the action sets no `awaitUserInput`. As soon as the card is drawn, the agent gets "Shown to the user. The user has not acted on it." plus exactly what `execute` returned - the count, the total and the rows (no rows when the card says "No accounts yet."), or the failure (`success: false`, `error` and `reason`). So `execute` returns the list the card draws, with each row's id, and nothing else. The count and the total are computed in code from the rows.
 
-The palette matches the agent's panel (white, with the agent's primary colour for the marks), not the page: a card sampled from a dark app sits badly in a white panel. Put the agent's own `primaryColor` in `brand.ts`.
+`brand.ts` here is a placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one.
 
-In Agent Studio: an action with key `list_accounts` and no parameters.
+In Agent Studio: an action with key `list_accounts` and no parameters. Its `instructions`: "Answer follow-up questions about these accounts from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
 
 ## Adapt it
 
@@ -16,12 +16,12 @@ In Agent Studio: an action with key `list_accounts` and no parameters.
 |---|---|
 | `agent/api/accounts.ts` | Mock path and envelope. Find the call the app's own list screen makes — a bare array or a wrapped one both work |
 | `agent/accounts.ts` | The two facts and the number a row carries |
-| `agent/views/list.ts` | The card. `brand.ts`: the agent's primary colour in `accent` |
+| `agent/views/list.ts` | The card |
 
 ## What that build learned the hard way
 
 - **Rows, not a table.** Five columns in a 400px panel is a table nobody can read. Name, two facts, one number.
 - **A list has nothing to prove whose it is.** An account has an id and a name; a list does not. The build answered signed-out calls with a 401 (which `apiFetch` maps to `signed_out`); what the code still checks is that a 200 is the list at all. ⚠️ If the app answers a signed-out call with a 200 and an empty array, find something in the response only a signed-in user gets.
 - **Empty is an answer.** Zero rows draws a card that says so — never a failure.
-- **Match the panel.** The first card copied the app's dark theme (sampled with `observe styles` while the app was in dark mode) and landed in a white panel.
-- **Rows are not links.** Open a record with a navigation route.
+- **Match the panel.** The first card copied the app's dark theme and landed in the agent's white panel. `observe styles --write` keeps the panel's white surface and, on a dark app, neutral text and borders - so keep the file it wrote.
+- **Rows are not links.** Open a record with a navigation route, with the id the agent got for that row.

package/recipes/records-list/agent/accounts.ts

@@ -1,5 +1,7 @@
 // Row shapes, and the total the header shows - computed here from the rows,
-// never by the model.
+// never by the model. A row carries what the card draws, plus the record's id
+// so the agent can open it with a navigation route; the agent gets all of it
+// once the card is drawn. The card shows no ids.
 
 import type { AccountsPayload } from "./api/accounts";
 

package/recipes/records-list/agent/actions/list_accounts.ts

@@ -1,7 +1,9 @@
-// View-only card. Do not set awaitUserInput: the model is told only that the
-// information was displayed, so the card carries every fact - including "no
-// accounts yet". A failed or signed-out call is drawn with renderFailure,
-// never as an empty list.
+// A view card: render takes no callback and the action sets no
+// awaitUserInput. As soon as the card is drawn, the agent is told it was shown
+// and gets everything execute returned - so execute returns the list the card
+// draws ("no accounts yet" included), with each row's id, and nothing else,
+// or the failure the card draws instead. A failed or signed-out call is drawn with renderFailure, never
+// as an empty list.
 
 import { getAccounts } from "../api/accounts";
 import { rowsOf, toList, type AccountsList } from "../accounts";
@@ -10,7 +12,6 @@ import { mountAccountsList } from "../views/list";
 
 type ListResult = {
   success: boolean;
-  message?: string;
   error?: string;
   reason?: FailureReason;
   data?: AccountsList;
@@ -29,8 +30,7 @@ export const list_accounts = {
     if (rowsOf(res.data) === null) {
       return { success: false, error: "Not signed in.", reason: "signed_out" };
     }
-    // `message` never reaches the model for a view-only action; it is for the console.
-    return { success: true, message: "Displayed.", data: toList(res.data) };
+    return { success: true, data: toList(res.data) };
   },
 
   render: (result: ListResult | undefined, host: HTMLElement, header: HTMLElement) => {

package/recipes/records-list/agent/views/brand.ts

@@ -1,23 +1,35 @@
-// The card lives in the agent's panel, which is white by default (the agent's
-// theme: backgroundColor #FFFFFF, primaryColor for accents) - so the palette
-// matches the panel, not the page. Plain hex/rgba only: the panel saves every
-// card to history as an image drawn with html2canvas, which cannot read
-// oklch()/lab()/color-mix(). Take `accent` from the agent's own primaryColor
-// (get_agent_settings); re-sample font and radius from the page if you want
-// them to match; swap for a dark set only when the panel itself is dark.
+// Placeholder with the keys of the agent/views/brand.ts that
+// `npx foldspace observe styles --write` writes. When you copy this recipe,
+// keep the project's own brand.ts; if it has none yet, run that command.
 
 export const brand = {
   surface: "#FFFFFF",
-  headerStart: "#F0F1FE",
-  border: "#E5E7EB",
+  surface2: "#F5F6FA",
   text: "#374151",
-  textStrong: "#111827",
   muted: "#6B7280",
-  faint: "#9CA3AF",
+  border: "#E5E7EB",
   accent: "#3248F2",
-  money: "#047857",
-  row: "#F9FAFB",
-  rowHover: "#F3F4F6",
+  accentText: "#FFFFFF",
   font: 'Roboto, -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
   radius: "8px",
+  size: { base: "14px", small: "12px" },
+  textStrong: "#111827",
+  faint: "#9CA3AF",
+  row: "#F9FAFB",
+  tableHead: "#F3F4F6",
+  accentDeep: "#2538D6",
+  accentSoft: "#EEF0FE",
+  headerStart: "#F0F1FE",
+  good: "#047857",
+  warn: "#B45309",
+  warnInk: "#FEF3C7",
+  bad: "#B91C1C",
+  primary: "#3248F2",
+  tint: "#F3F4F6",
+  disabled: "#9CA3AF",
+  money: "#047857",
+  ok: "#047857",
+  deals: "#3248F2",
+  contacts: "#2538D6",
+  cases: "#B45309",
 } as const;

package/recipes/server-rendered-forms/README.md

@@ -0,0 +1,35 @@
+# Server-rendered pages and forms - L4
+
+**The product renders its pages on the server.** There is no JSON API behind the screen: the page is the data, and a record is created by posting the same form a person fills in. Many admin tools and multi-page apps work this way.
+
+**Proven by 1 production build**: three kinds of record created and messages sent through server-rendered forms, each verified by a real chat turn and the result appearing in the app.
+
+## What this recipe gives
+
+| Piece | What it does |
+|---|---|
+| `agent/api/pages.ts` | `readPage(path)` and `submitForm(action, body)` - each returns the page the app answered with and its address, read from inside the app on its own host, or a failure with its `reason`. A refused form (400 or 422) is an answer, not a failure |
+| `agent/forms.ts` → `findForm`, `fieldByLabel`, `formBody` | Recognise the form by a field's **label**, fill values by label, and build the body the browser would send, file inputs left out: the app's own hidden fields (its token, its form id) go along unchanged; an unchecked box, a radio group nobody chose, a multiple list with nothing chosen and a field in a disabled fieldset send nothing. Field names are never guessed |
+| `agent/forms.ts` → `judgeSubmit`, `formErrors` | Judge the answer page: `created` or `not_created`. A 400 or 422 answer is always `not_created`. The app's own validation messages come back as data |
+| `agent/forms.ts` → `tableRows` | A list page's table as rows, for a card like `records-list` |
+| `agent/actions/create_record_via_form.ts` | The write, end to end. It hands back `created` with the address of the record's page, `not_created` with the app's messages, or a failure with its `reason` |
+
+**Always behind approval.** This is a write. Before you publish it, either run the write from the approve button of an input card (`upload-contacts` writes only on Import), or set `confirmation_required: true` on the action. Such a card calls `callback` with what the write returned, and `callback` or `cancel` on every other path - declining, closing, failing. That is what makes the agent wait for the user; a path that never calls back leaves the agent waiting until the user presses stop. Testing it writes too, in their account: run it only as **Ask only what reads** (**Rules**, 4) allows.
+
+In Agent Studio: an action with key `create_record_via_form`, a required string parameter `title` and an optional string parameter `description`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/actions/create_record_via_form.ts` | `FORM_PATH` (the form's page), `KNOWN_BY` (the label the form is recognised by) and the patterns in `LABELS` (the labels the values go to). Each key in `LABELS` is a parameter of the action: a field of your own needs a parameter in Agent Studio, a key in `LABELS` and its value in `given`. An answer with a password field reads as a sign-in page (`signed_out`): if the app's record page has one of its own (a user's page with a set-password form), match that check to the app's sign-in path instead |
+| `agent/forms.ts` → `formErrors` | When you know the app's own error markup, add it; otherwise keep the defaults. Never submit the form yourself: ask the human to submit it once in the test window with a required field left empty, then run `npx foldspace observe screenshot` to see what the app says. A screenshot shows the words, not the markup, and no harness command reads a page's markup, so whether the defaults catch those words cannot be checked. If the browser itself stops the empty field (its own bubble on the field), nothing reaches the app and there are no words to see. Either way it is a gap: register it (**Rules**, 9), with the app's words when you saw them |
+
+## What that build learned the hard way
+
+- **Read the form at run time.** The token changes per page. Load the form, take every hidden field from it, post it back.
+- **Fill by label, not by name.** Names like `record[title]` are the app's business; the label is what a person sees, and what you record in `docs/app-profile.md`.
+- **Created means the app moved on and showed no error.** `judgeSubmit` says `created` only when all four hold: the app did not refuse the form (400 or 422); the answer came from a different path than the form page; the same form (found by `KNOWN_BY`, posting where this one posted) is not on it; and `formErrors` found nothing there. The action then reads a created answer with a password field as a sign-in page (`signed_out`). Three answers still read wrong. As created: a 200 page from another path that turns the form down without showing it, in error markup the defaults miss. As not created, though the record was made: a confirmation in an `.alert` or `[role=alert]` box with no success, info or notice class and without the word "success"; and any page that carries the same form again, such as a list page with its own add form. Before publishing, fit `formErrors` to the app as **Adapt it** says. If the app answers a create with a page that carries the form again, also make `judgeSubmit` read the app's own sign of success - its success banner, or the new record's address.
+- **A form built by script is a different case.** When the served HTML has only a shell and the fields appear after a script runs, `findForm` finds no form in what `readPage` returns, and the action stops with "The form was not on its page." (`server`) before posting anything. Such a form usually sends its own fetch or XHR call, and `foldspace observe` names a write it sees only by method and path (`writesSeen`), never its body, so what the form sends cannot be read. That is a gap (**Rules**, 9).
+- **One host at a time.** Code on a page reads its own host only. For a product on several hosts, see `several-hosts`: an action asked from the wrong host says which page it needs.
+- **A multi-page app reloads on every navigation.** The agent carries on by itself, on the same host and across hosts.

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

@@ -0,0 +1,62 @@
+// A write on a server-rendered app: load the form a person would fill in, put
+// the values in by label, post it as the browser would, and judge the answer
+// with judgeSubmit. No card here, so before publishing put it behind approval:
+// the approve button of a card that calls callback with the write's result,
+// and callback or cancel on every other path (the agent waits until one of
+// them runs), or confirmation_required: true on the action.
+// The result is state: created with the address of the record's page, or not
+// created, with the app's own validation messages.
+
+import { parsePage, readPage, submitForm } from "../api/pages";
+import { asMultipart, fieldByLabel, findForm, formAction, formBody, formEnctype, judgeSubmit } from "../forms";
+
+/** ADAPT: the form page, the field the form is recognised by, and the labels the values go to - one key per parameter. */
+export const FORM_PATH = "/__observe_me/records/new";
+const KNOWN_BY = /^title/;
+const LABELS = { title: /^title/, description: /^description/ } as const;
+
+export const create_record_via_form = {
+  execute: async (params: { title?: string; description?: string }) => {
+    const title = typeof params?.title === "string" ? params.title.trim() : "";
+    const description = typeof params?.description === "string" ? params.description.trim() : "";
+    if (!title) return { success: false, error: "No title was given.", reason: "config" };
+
+    const page = await readPage(FORM_PATH);
+    if (!page.ok) return { success: false, error: page.error, reason: page.reason };
+    const doc = parsePage(page.data.html);
+    const found = findForm(doc, KNOWN_BY);
+    if (!found) {
+      // Never guess field names. Sent to another page, or shown a password field
+      // on this one: a sign-in page, so signed out. Otherwise the served page has
+      // no such form: the app changed, or it builds the form by script (README).
+      const movedAway = new URL(page.data.url).pathname !== new URL(FORM_PATH, page.data.url).pathname;
+      const signIn = movedAway || doc.querySelector("input[type=password]") !== null;
+      return signIn
+        ? { success: false, error: "The app showed another page instead of the form.", reason: "signed_out", data: { url: page.data.url } }
+        : { success: false, error: "The form was not on its page.", reason: "server", data: { url: page.data.url } };
+    }
+    // Each LABELS key takes the parameter of the same name; a key with no value here leaves its field as the form served it.
+    const given: Record<string, string> = { title, description };
+    const values: Record<string, string> = {};
+    for (const [key, pattern] of Object.entries(LABELS)) {
+      const field = fieldByLabel(found, pattern);
+      const value = given[key] ?? "";
+      if (field && value) values[field.name] = value;
+    }
+    if (!Object.keys(values).length) {
+      return { success: false, error: "The form did not offer the fields this action fills.", reason: "config" };
+    }
+    const body = formBody(found, values);
+    const action = formAction(found, page.data.url);
+    const answer = await submitForm(action, formEnctype(found) === "multipart" ? asMultipart(body) : body);
+    if (!answer.ok) return { success: false, error: answer.error, reason: answer.reason };
+    const outcome = judgeSubmit(page.data.url, answer.data, KNOWN_BY, action);
+    // A password field on an answer that reads as created is a sign-in page, not
+    // the record. ADAPT when the app's record page has one of its own (README).
+    if (outcome.status === "created" && parsePage(answer.data.html).querySelector("input[type=password]")) {
+      return { success: false, error: "The app showed a sign-in page instead of the record.", reason: "signed_out", data: { url: answer.data.url } };
+    }
+    return { success: true, message: outcome.status === "created" ? "Created." : "Not created.", data: outcome };
+  },
+};
+

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

@@ -0,0 +1,57 @@
+// A product that renders its pages on the server: there is no JSON API to call,
+// the page IS the data, and a record is created by posting the same form a
+// person fills in. Everything here runs inside the page with the user's own
+// session - no separate browser, no copied cookies. It can only reach the
+// host it runs on; for a product on several hosts see recipes/several-hosts.
+
+import { refusedForm } from "../forms";
+import { httpFailure, networkFailure, type ApiResult } from "../utils";
+
+export type Page = { html: string; url: string; status: number };
+
+/** GET a page as the browser would - same session, redirects followed. */
+export async function readPage(path: string, timeoutMs = 20_000): Promise<ApiResult<Page>> {
+  return request(path, { headers: { accept: "text/html" } }, timeoutMs, "The page could not be loaded.", false);
+}
+
+/**
+ * POST a form as the browser would. The answer is the page that came back, and
+ * where it came from. A refused form (400 or 422) is an answer too: its page
+ * carries the app's messages, and judgeSubmit reads them.
+ */
+export async function submitForm(action: string, body: FormData | URLSearchParams, timeoutMs = 20_000): Promise<ApiResult<Page>> {
+  return request(action, { method: "POST", body, headers: { accept: "text/html" } }, timeoutMs, "The app answered the form with an error.", true);
+}
+
+async function request(url: string, init: RequestInit, timeoutMs: number, failed: string, isForm: boolean): Promise<ApiResult<Page>> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, credentials: "include", redirect: "follow", signal: controller.signal });
+    const html = await res.text();
+    if (!res.ok && !(isForm && refusedForm(res.status))) {
+      const failure = httpFailure(res, failed);
+      // The agent gets what happened, never what to do.
+      if (failure.reason === "signed_out") failure.error = "Your session has expired.";
+      if (failure.reason === "rate_limited") failure.error = "Too many requests right now.";
+      return failure;
+    }
+    return { ok: true, status: res.status, data: { html, url: res.url, status: res.status } };
+  } catch (error) {
+    // A form post with no answer, or an answer that could not be read (a redirect
+    // to another host is blocked), may still have landed, so both its sentences
+    // say that is not known.
+    return networkFailure(
+      error,
+      isForm ? "The app did not answer in time, so it is not known whether the form went through." : "The page took too long.",
+      isForm ? "No answer from the app could be read, so it is not known whether the form went through." : "The page could not be read.",
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The page as a document, parsed off-screen - nothing is added to the page the user sees. */
+export function parsePage(html: string): Document {
+  return new DOMParser().parseFromString(html, "text/html");
+}