@foldspace_npm/harness 0.1.26 → 0.1.28

package/recipes/create-a-record/variants/actions/create_project.steps.ts

@@ -0,0 +1,160 @@
+// The step-by-step version: one question per card, then a final review card. Copy it
+// over agent/actions/create_project.ts when the README's "Which version" says so.
+//
+// 1. The deciding question - its answer decides which fields come next.
+// 2. Every field that applies, one per card, pre-filled from what the user said. They
+//    confirm or change each one with Continue.
+// 3. The review card: every value together; all but the first answer can still be edited.
+//    Only Create project writes.
+//
+// A step is skipped only when there is nothing to ask (one possible value, or a field
+// that does not apply). Every step has Cancel. An input card: render uses callback, so
+// the agent waits until callback runs, and every path calls it exactly once. Never set
+// awaitUserInput - it is not needed.
+
+import { projectFields, proposeProject, text, type Params, type Proposal } from "../projects";
+import { matchOption, type Field, type Option, type Values } from "../views/fields";
+import { KICKER, drawFailed, footerOf, mountCancelled, mountLoadFailure, mountProjectCard, type Callback } from "../views/project-card";
+import { runSteps } from "../views/steps";
+
+/** The deciding question. Each option says what choosing it means, so it is an option card. */
+const KINDS: Option[] = [
+  { value: "client", label: "Client project", caption: "Billed to a client. Asks who the client is and the hourly rate." },
+  { value: "internal", label: "Internal project", caption: "Work for your own team. No client, no billing." },
+];
+
+/** Each field's step asks a question. A field missing here uses its label. */
+const QUESTIONS: Record<string, string> = {
+  kind: "What type of project is this?",
+  name: "What should the project be called?",
+  key: "What short key should it have?",
+  owner: "Who owns it?",
+  client: "Who is the client?",
+  hourly_rate: "What is the hourly rate?",
+  status: "What status does it start in?",
+  description: "Anything to add as a description?",
+  private: "Should only members see it?",
+  notify_members: "Should members get an email when it is created?",
+};
+
+const RATE_PATTERN = /^\d+(\.\d{1,2})?$/;
+
+type StepParams = Params & { kind?: string; client?: string; hourly_rate?: string | number };
+
+type StepProposal = Proposal & {
+  /** "" when the user's words did not settle it: the first step starts with nothing chosen. */
+  kind?: string;
+  client?: string;
+  hourly_rate?: string;
+};
+
+/** The fields only one kind of project has. */
+function fieldsFor(kind: string, proposal: StepProposal): Field[] {
+  if (kind !== "client") return [];
+  return [
+    { key: "client", label: "Client", kind: "text", value: proposal.client ?? "", maxLength: 120, required: true },
+    {
+      key: "hourly_rate",
+      label: "Hourly rate",
+      kind: "text",
+      value: proposal.hourly_rate ?? "",
+      maxLength: 10,
+      hint: "Optional. A number, e.g. 150.",
+      check: (value) => (RATE_PATTERN.test(value) ? null : "A number, e.g. 150 or 150.50."),
+    },
+  ];
+}
+
+/** The proposal as the steps left it: what the review card starts from. */
+function answered(proposal: StepProposal, values: Values): StepProposal {
+  const str = (key: string, fallback?: string) => (values[key] === undefined ? fallback : String(values[key]));
+  return {
+    ...proposal,
+    name: str("name", proposal.name),
+    key: str("key", proposal.key),
+    owner_value: str("owner", proposal.owner_value),
+    status: str("status", proposal.status),
+    description: str("description", proposal.description),
+    private: values.private === undefined ? proposal.private : values.private === true,
+    notify_members: values.notify_members === undefined ? proposal.notify_members : values.notify_members === true,
+    client: str("client", proposal.client),
+    hourly_rate: str("hourly_rate", proposal.hourly_rate),
+  };
+}
+
+export const create_project = {
+  // Reads and proposes, exactly as the all-at-once version does, plus the deciding answer,
+  // the client and the rate when the user already gave them. Writes nothing.
+  execute: async (params: StepParams = {}): Promise<StepProposal> => {
+    const proposal = await proposeProject(params);
+    if (!proposal.success) return proposal;
+    const rate = String(params.hourly_rate ?? "").trim();
+    return {
+      ...proposal,
+      kind: matchOption(text(params.kind, 40), KINDS),
+      client: text(params.client, 120),
+      hourly_rate: RATE_PATTERN.test(rate) ? rate : "",
+    };
+  },
+
+  render: (proposal: StepProposal | undefined, host: HTMLElement, header: HTMLElement, callback: Callback) => {
+    try {
+      if (!proposal?.success) return mountLoadFailure(host, proposal, callback);
+      const footer = footerOf(proposal);
+      const cancel = () => mountCancelled(host, header, proposal, callback);
+      const failed = (error: unknown) => drawFailed(host, callback, error);
+      const guarded = (draw: () => void) => {
+        try {
+          draw();
+        } catch (error) {
+          failed(error);
+        }
+      };
+
+      // 1. The deciding question. Pre-chosen only when the user said it.
+      runSteps(host, header, {
+        kicker: KICKER,
+        footer,
+        lastLabel: "Continue",
+        steps: [{ question: QUESTIONS.kind, field: { key: "kind", label: "Type", kind: "choice", value: proposal.kind ?? "", options: KINDS, required: true } }],
+        onCancel: cancel,
+        onFailed: failed,
+        onDone: (chosen, kindEdited) =>
+          guarded(() => {
+            const kind = String(chosen.kind);
+            const label = KINDS.find((option) => option.value === kind)?.label ?? KICKER;
+            const extra = fieldsFor(kind, proposal);
+
+            // 2. Every field that applies to this kind, one per card.
+            runSteps(host, header, {
+              kicker: label,
+              footer,
+              firstNumber: 2,
+              steps: projectFields(proposal, extra).map((field) => ({ question: QUESTIONS[field.key] ?? field.label, field })),
+              onCancel: cancel,
+              onFailed: failed,
+              onDone: (values, fieldsEdited) =>
+                guarded(() => {
+                  // 3. The review card: every value together, all but the kind editable (it is a fact
+                  //    there), written only on Create project.
+                  const reviewed = answered(proposal, values);
+                  mountProjectCard(host, header, reviewed, callback, {
+                    kicker: `${label} · Review`,
+                    fields: fieldsFor(kind, reviewed),
+                    facts: [["Type", label]],
+                    edited: [...kindEdited, ...fieldsEdited],
+                    draft: (final) => ({
+                      kind,
+                      clientName: kind === "client" ? String(final.client ?? "").trim() || null : null,
+                      hourlyRate: kind === "client" && final.hourly_rate ? Number(final.hourly_rate) : null,
+                    }),
+                  });
+                }),
+            });
+          }),
+      });
+    } catch (error) {
+      drawFailed(host, callback, error);
+    }
+  },
+};

package/recipes/find-by-name/README.md

@@ -9,7 +9,9 @@ user genuinely has to choose, that is a different action —
 [`pick-from-a-list`](../pick-from-a-list/).
 
 In Agent Studio: an action with key `find_project_id` and one optional string
-parameter `name` — *the name, or part of the name, the user said*.
+parameter `name` - *the name, or part of the name, the user said*. Instructions
+to set: "No emoji. Quote totals and counts exactly as returned; never work them
+out."
 
 ## What it returns
 

package/recipes/find-by-name/agent/actions/find_project_id.ts

@@ -1,7 +1,7 @@
 // Resolver: a name the user said → the id every other project action needs.
 //
 // It answers questions and never asks one. "How many projects do I have?" gets
-// a count, not a widget demanding a selection — asking is choose_project.
+// a count, not a card demanding a selection - asking is choose_project.
 
 import { listProjects } from "../api/projects";
 import { classify, MATCH_RANK, nearMatches, toSummary, type MatchType, type ProjectSummary } from "../projects";

package/recipes/lookup-then-view/README.md

@@ -0,0 +1,73 @@
+# Look up, then show - L2
+
+**The user says** "show me Northwind". **The user sees** Northwind's card, and was asked nothing, because there is one Northwind. "Show me Acme", with two Acmes: a list to pick from, with search and pages, and one click opens the card. A name nobody has: the same list, the closest names first (from the first 50 accounts).
+
+**Proven by 1 production build** (a CRM: account lookup, account overview). This recipe keeps its shape and fixes what it got wrong (**What that build learned the hard way**, below).
+
+## Two actions, and why they chain by themselves
+
+| Action | Input | What makes the chain |
+|---|---|---|
+| `find_account` | `name`, **required**: "exactly as the user said it" | It is the only thing that produces an account id |
+| `show_account_overview` | `accountId`, **required**: "never guessed and never taken from the user's words: get it from `find_account`" | The agent sees a required id the user cannot give, and the action that produces it |
+
+**Why this lookup asks.** The user asked to *see* one account, so choosing which one is part of the answer. When an id only feeds another question or a write, keep the two jobs apart instead: `find-by-name` answers and never asks, and `pick-from-a-list` asks when the user has to choose.
+
+**Only the id is required on the card's action.** Do not add a required account *name* to it as well. The agent would fill both from the user's sentence and skip the lookup.
+
+`studio/*.json` are the two `create_action` payloads, word for word. Change only the entity's name (**Adapt it**); add `agent_id`, and pass `parameters` as a JSON string.
+
+| `find_account` answers | What the agent does (Studio instructions) | The user sees |
+|---|---|---|
+| `found` + id | calls `show_account_overview`, no question | the card, straight away |
+| `chosen` + id | the same | the list, one click, then the card |
+| `none_of_these` | asks which account they mean | a question |
+| `cancelled` | stops | nothing more |
+| `failed` | says so in one short sentence and stops | the card, saying why |
+
+`find_account` is an input card: its `render` uses `callback`, and that is what makes the agent wait for the answer. Every path calls it exactly once - at once on one match or a failure, and from the list when the user chooses, picks "None of these" or cancels. `show_account_overview` is a view card: its `render` takes no `callback` or `cancel`, so once the card is drawn the agent gets "Shown to the user. The user has not acted on it." plus everything `execute` returned - the facts the card draws from (every open deal, person and open case, not only the three on screen), or the failure the card draws. That is how the agent can answer a question about the account it just showed. To change what the agent gets, change `execute`, not the card. Neither action sets `awaitUserInput`.
+
+## The pick-one card (`views/pick-one.ts`)
+
+The card for "which one did you mean?". It is not specific to accounts; use it for any record.
+
+| | |
+|---|---|
+| Long lists | one page on screen (`pageSize`, 8 in `find_account`); Previous / Next, "9-16 of 143" |
+| Search | asks the app again as the user types (after 250 ms); the newest answer wins |
+| One click | clicking a row chooses it. `confirm: true` adds an Open button instead, for choices that should be deliberate |
+| No match | the closest names first (`find_account` picks them from the first 50 accounts, `WIDE`), "Browse all" behind them |
+| Answers | a choice, "None of these" or "Cancel" - exactly one, ever |
+| Afterwards | the card shrinks to "Chosen: Northwind Traders", so the history reads right |
+
+## The account card (`views/account.ts`)
+
+A view card, laid out to be read in five seconds at chat width:
+
+| Part | Shows | Rules |
+|---|---|---|
+| Who | name, industry, size, place, website, owner | The website is shown as plain text, not a link: the card never sends the user out of the app |
+| The money | open pipeline, weighted pipeline, open deals, open cases | Short in the tile ($1.2M) with the exact amount in the tooltip. Weighted is each deal times its probability. Both totals are in whole units, as the card shows them. All of it is computed in code |
+| Deals | the biggest open deals | Stage as a chip; "Closes in 12 days", or "Close date passed …" in amber; the amount right-aligned in full, probability under it |
+| People | the primary contact first | Name, then title · email · phone, as text |
+| Open cases | critical and urgent ones marked red, high ones amber | Shown only when there are any |
+
+Missing is "-", never 0: a deal amount nobody entered is not $0. Money uses the account's own currency, without cents. Formatting lives in `views/format.ts`, so every card in the project says it the same way.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/accounts.ts` | The app's account search (name, page) and record call. If the search has no paging, page the result here |
+| `agent/accounts.ts` | Which fields a row and the card carry. `resolve` stays |
+| `agent/views/brand.ts` | A placeholder: keep the one `npx foldspace observe styles --write` wrote - it has every key the cards read. If the project has none yet, run that command first; do not copy this one |
+| `studio/*.json` | The entity's name in the words; the inputs and the rules stay |
+
+## What that build learned the hard way
+
+- **Declare the input fully, or the chain does not happen.** An id marked optional, or described only as "the id", leaves the agent guessing, or asking the user for an id they do not have.
+- **Ties go to the user.** Two Acmes never resolve to the first one. Only an exact name, or the only result, answers at once.
+- **The user chooses on a card, not in chat.** That build listed several matches as numbered text with the raw ids, and the agent asked in chat; the pick-one list replaces both.
+- **Nothing found is an answer**, never a failure and never "try again" - that build's failure told the agent to "try a shorter search term".
+- **Send the agent only what it needs**: the answer carries the id and the name; the list rows carry industry and place - never the whole row.
+- **The chain lives in Agent Studio**, not in the tool response. "Now call show_account_overview" inside a response is an instruction in data (**Rules**, 1).

package/recipes/lookup-then-view/agent/accounts.ts

@@ -0,0 +1,174 @@
+// Turning what the API returns into what the agent and the cards need.
+// Totals are computed here, from the API's own numbers - never by the agent.
+
+import type { AccountRow, OverviewPayload } from "./api/accounts";
+import { rankBy } from "./utils";
+
+/** Only what is needed to tell two accounts apart - never the whole row. */
+export type AccountSummary = { accountId: string; name: string; industry: string | null; place: string | null };
+
+export function toSummary(row: AccountRow): AccountSummary {
+  const place = [row.city, row.state].map((part) => part?.trim()).filter(Boolean).join(", ");
+  return { accountId: row.id, name: row.name, industry: row.industry?.trim() || null, place: place || null };
+}
+
+type Strength = "exact" | "starts_with" | "contains";
+const RANK: Record<Strength, number> = { exact: 0, starts_with: 1, contains: 2 };
+
+function strength(name: string, query: string): Strength | null {
+  const a = name.trim().toLowerCase();
+  const b = query.trim().toLowerCase();
+  if (!b) return null;
+  if (a === b) return "exact";
+  if (a.startsWith(b)) return "starts_with";
+  if (a.includes(b)) return "contains";
+  return null;
+}
+
+/**
+ * One when a single account matches best; many when the best matches tie -
+ * showing the wrong account is worse than asking; none when nothing matched.
+ * `total` is the server's own count, so "many" is right even past one page.
+ */
+export function resolve(rows: AccountSummary[], query: string, total = rows.length): "one" | "many" | "none" {
+  if (!rows.length) return "none";
+  if (total > rows.length) return "many";
+  const ranked = rows
+    .map((account) => strength(account.name, query))
+    .filter((at): at is Strength => at !== null)
+    .sort((a, b) => RANK[a] - RANK[b]);
+  if (!ranked.length) return rows.length === 1 ? "one" : "many";
+  return ranked.filter((at) => at === ranked[0]).length === 1 && (ranked[0] === "exact" || rows.length === 1) ? "one" : "many";
+}
+
+/** How alike two words are, 0..1: shared letter pairs (Dice). "northwnd" and "northwind" score 0.8. */
+export function likeness(a: string, b: string): number {
+  const pairs = (word: string) => {
+    const clean = word.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+    const out: string[] = [];
+    for (let i = 0; i < clean.length - 1; i += 1) out.push(clean.slice(i, i + 2));
+    return out;
+  };
+  const left = pairs(a);
+  const right = pairs(b);
+  if (!left.length || !right.length) return 0;
+  const pool = [...right];
+  let shared = 0;
+  for (const pair of left) {
+    const at = pool.indexOf(pair);
+    if (at >= 0) {
+      shared += 1;
+      pool.splice(at, 1);
+    }
+  }
+  return (2 * shared) / (left.length + right.length);
+}
+
+/**
+ * A typo, a half-remembered word: the closest names, as suggestions - never
+ * as a resolution. The SDK's fuzzy match first (through rankBy); when it has
+ * nothing - or the SDK is not on the page - each name and each word in it is
+ * compared with what the user typed.
+ */
+export function nearMatches(rows: AccountSummary[], query: string, limit = 5): AccountSummary[] {
+  const ranked = rankBy(rows, query, { searchKeys: ["name"], idOf: (row) => row.accountId, limit });
+  if (ranked.length) return ranked;
+  return rows
+    .map((row) => ({ row, score: Math.max(likeness(row.name, query), ...row.name.split(/\s+/).map((word) => likeness(word, query))) }))
+    .filter((entry) => entry.score >= 0.5)
+    .sort((x, y) => y.score - x.score)
+    .slice(0, limit)
+    .map((entry) => entry.row);
+}
+
+// ---------------------------------------------------------------- the overview
+
+export type Deal = { name: string; amount: number | null; stage: string | null; probability: number | null; closeDate: string | null };
+export type Person = { name: string; title: string | null; email: string | null; phone: string | null; primary: boolean };
+export type Case = { title: string; priority: string | null; createdAt: string | null };
+
+export type Overview = {
+  account: {
+    accountId: string;
+    name: string;
+    industry: string | null;
+    website: string | null;
+    place: string | null;
+    employeeCount: number | null;
+    currency: string;
+    owner: string | null;
+  };
+  metrics: {
+    openPipeline: number;
+    weightedPipeline: number;
+    openDeals: number;
+    openCases: number;
+    criticalCases: number;
+  };
+  deals: Deal[];
+  people: Person[];
+  cases: Case[];
+};
+
+const OPEN = (stage: string | null) => !/^closed/i.test(stage ?? "");
+const num = (value: unknown): number | null => {
+  const parsed = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  return typeof parsed === "number" && Number.isFinite(parsed) ? parsed : null;
+};
+const text = (value: string | null | undefined) => value?.trim() || null;
+
+/** Critical or urgent. High is not: the card marks it amber, and it is not counted as critical. */
+export const isCritical = (priority: string | null): boolean => /^(critical|urgent)$/i.test(priority?.trim() ?? "");
+
+/** A 200 without both an id and a name is a signed-out answer, not an empty account. */
+export function isAccount(payload: OverviewPayload): boolean {
+  return Boolean(text(payload.account?.id) && text(payload.account?.name));
+}
+
+export function toOverview(payload: OverviewPayload): Overview {
+  const a = payload.account ?? {};
+  const deals: Deal[] = (payload.opportunities ?? []).map((row) => ({
+    name: text(row.name) ?? "Untitled deal",
+    amount: num(row.amount),
+    stage: text(row.stage),
+    probability: num(row.probability),
+    closeDate: text(row.closeDate),
+  }));
+  const open = deals.filter((deal) => OPEN(deal.stage));
+  const people: Person[] = (payload.contacts ?? [])
+    .map((row) => ({
+      name: [text(row.firstName), text(row.lastName)].filter(Boolean).join(" ") || "Unnamed contact",
+      title: text(row.title),
+      email: text(row.email),
+      phone: text(row.phone),
+      primary: row.primary === true,
+    }))
+    .sort((x, y) => Number(y.primary) - Number(x.primary));
+  const cases: Case[] = (payload.cases ?? [])
+    .filter((row) => !/^(closed|resolved)/i.test(row.status ?? ""))
+    .map((row) => ({ title: text(row.title) ?? "Untitled case", priority: text(row.priority), createdAt: text(row.createdAt) }));
+  const place = [text(a.city), text(a.state)].filter(Boolean).join(", ");
+  return {
+    account: {
+      accountId: String(a.id).trim(),
+      name: String(a.name).trim(),
+      industry: text(a.industry),
+      website: text(a.website),
+      place: place || null,
+      employeeCount: num(a.employeeCount),
+      currency: /^[A-Z]{3}$/.test(text(a.currency) ?? "") ? (text(a.currency) as string) : "USD",
+      owner: text(a.owner?.name),
+    },
+    metrics: {
+      // Whole units, as the card shows them: the agent quotes these exactly.
+      openPipeline: Math.round(open.reduce((sum, deal) => sum + (deal.amount ?? 0), 0)),
+      weightedPipeline: Math.round(open.reduce((sum, deal) => sum + (deal.amount ?? 0) * ((deal.probability ?? 0) / 100), 0)),
+      openDeals: open.length,
+      openCases: cases.length,
+      criticalCases: cases.filter((row) => isCritical(row.priority)).length,
+    },
+    deals: open.sort((x, y) => (y.amount ?? 0) - (x.amount ?? 0)),
+    people,
+    cases,
+  };
+}

package/recipes/lookup-then-view/agent/actions/find_account.ts

@@ -0,0 +1,108 @@
+// The lookup half. A name in; the account's id out - and when the name is not
+// enough, the user chooses.
+//
+//   one clear match   ->  answers "found" at once; nothing to click
+//   several matches   ->  the pick-one list: search, pages, one click
+//   no match          ->  the same list, closest names (of the first 50) first,
+//                          all accounts behind
+//
+// Whatever happens, the answer is state - found, chosen, none_of_these,
+// cancelled or failed - never an instruction. Agent Studio holds what to do
+// next: on found or chosen, show_account_overview with the id, without asking.
+// An input card: render uses callback, and that is what makes the agent wait
+// for the answer. Every path calls it exactly once. No awaitUserInput.
+
+import { searchAccounts } from "../api/accounts";
+import { nearMatches, resolve, toSummary, type AccountSummary } from "../accounts";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountPickOne, type PickRow } from "../views/pick-one";
+
+/** A page that fits in the chat panel without scrolling it away. */
+export const PAGE_SIZE = 8;
+/** How many accounts the closest names are picked from when nothing matched. */
+const WIDE = 50;
+
+type Lookup =
+  | { status: "one"; query: string; account: AccountSummary }
+  | { status: "many"; query: string; total: number; accounts: AccountSummary[] }
+  | { status: "none"; query: string; suggested: AccountSummary[]; total: number; accounts: AccountSummary[] };
+
+type FindResult = { success: boolean; error?: string; reason?: FailureReason; data?: Lookup };
+type Callback = (value: unknown, disableOnSubmit?: boolean) => void;
+
+const toRow = (account: AccountSummary): PickRow => ({
+  id: account.accountId,
+  primary: account.name,
+  secondary: [account.industry, account.place].filter(Boolean).join("  ·  ") || null,
+});
+
+export const find_account = {
+  execute: async (params: { name?: string }): Promise<FindResult> => {
+    const query = typeof params?.name === "string" ? params.name.trim() : "";
+    if (!query) return { success: false, error: "No account name was given.", reason: "config" };
+
+    const res = await searchAccounts({ search: query, limit: PAGE_SIZE });
+    if (!res.ok) {
+      console.warn("[find_account]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason };
+    }
+    const accounts = res.data.accounts.map(toSummary);
+    const status = resolve(accounts, query, res.data.total);
+    if (status === "one") {
+      // The exact name when there is one - the app may list it after a longer name.
+      const account = accounts.find((row) => row.name.trim().toLowerCase() === query.toLowerCase()) ?? accounts[0];
+      return { success: true, data: { status, query, account } };
+    }
+    if (status === "many") return { success: true, data: { status, query, total: res.data.total, accounts } };
+
+    // Nothing matched: the closest names among the first WIDE accounts, then
+    // every account behind them.
+    const wide = await searchAccounts({ limit: WIDE });
+    if (!wide.ok) return { success: false, error: wide.error, reason: wide.reason };
+    const everyone = wide.data.accounts.map(toSummary);
+    return {
+      success: true,
+      data: { status, query, suggested: nearMatches(everyone, query), total: wide.data.total, accounts: everyone.slice(0, PAGE_SIZE) },
+    };
+  },
+
+  render: (result: FindResult | undefined, host: HTMLElement, header: HTMLElement, callback: Callback) => {
+    if (!result?.success || !result.data) {
+      renderFailure(host, {
+        ok: false,
+        status: 0,
+        error: result?.error ?? "The accounts could not be loaded.",
+        reason: result?.reason ?? "server",
+      });
+      callback({ success: false, status: "failed", reason: result?.reason ?? "server" }, true);
+      return;
+    }
+    const found = result.data;
+
+    if (found.status === "one") {
+      const line = document.createElement("div");
+      line.textContent = `Found: ${found.account.name}`;
+      host.textContent = "";
+      host.append(line);
+      callback({ success: true, status: "found", accountId: found.account.accountId, name: found.account.name }, true);
+      return;
+    }
+
+    mountPickOne(host, header, {
+      title: "Which account?",
+      note: found.status === "many" ? `${found.total} matches for "${found.query}"` : `No account matches "${found.query}"`,
+      query: found.status === "many" ? found.query : "",
+      placeholder: "Search accounts",
+      initial: { rows: found.accounts.map(toRow), total: found.total },
+      suggested: found.status === "none" ? found.suggested.map(toRow) : undefined,
+      pageSize: PAGE_SIZE,
+      fetchPage: async (query, offset) => {
+        const page = await searchAccounts({ search: query, offset, limit: PAGE_SIZE });
+        return page.ok ? { rows: page.data.accounts.map(toSummary).map(toRow), total: page.data.total } : { error: page.error };
+      },
+      onChoose: (row) => callback({ success: true, status: "chosen", accountId: row.id, name: row.primary }, true),
+      onNone: () => callback({ success: true, status: "none_of_these", query: found.query }, true),
+      onCancel: () => callback({ success: true, status: "cancelled" }, true),
+    });
+  },
+};

package/recipes/lookup-then-view/agent/actions/show_account_overview.ts

@@ -0,0 +1,42 @@
+// The view half. Its one input, accountId, is required, and its description in
+// Agent Studio says the id comes from find_account - that is what makes the
+// agent look a name up first, by itself. A view card: render takes no callback
+// or cancel, and the action sets no awaitUserInput. Once the card is drawn, the
+// agent is told it was shown and gets everything execute returned - so execute
+// returns the facts the card draws from (every open deal, person and open case,
+// not only the three on screen), or the failure the card draws instead.
+
+import { getAccountOverview } from "../api/accounts";
+import { isAccount, toOverview, type Overview } from "../accounts";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountAccount } from "../views/account";
+
+type ShowResult = { success: boolean; error?: string; reason?: FailureReason; data?: Overview };
+
+export const show_account_overview = {
+  execute: async (params: { accountId?: string }): Promise<ShowResult> => {
+    const accountId = typeof params?.accountId === "string" ? params.accountId.trim() : "";
+    if (!accountId) return { success: false, error: "No account was chosen.", reason: "config" };
+    const res = await getAccountOverview(accountId);
+    if (!res.ok) {
+      // The card's own words for a missing account, so the agent gets what the card shows.
+      const error = res.reason === "not_found" ? "That account could not be found." : res.error;
+      return { success: false, error, reason: res.reason };
+    }
+    if (!isAccount(res.data)) return { success: false, error: "Not signed in.", reason: "signed_out" };
+    return { success: true, data: toOverview(res.data) };
+  },
+
+  render: (result: ShowResult | undefined, host: HTMLElement, header: HTMLElement) => {
+    if (!result?.success || !result.data) {
+      renderFailure(host, {
+        ok: false,
+        status: 0,
+        error: result?.error ?? "The account could not be loaded.",
+        reason: result?.reason ?? "server",
+      });
+      return;
+    }
+    mountAccount(host, header, result.data);
+  },
+};

package/recipes/lookup-then-view/agent/api/accounts.ts

@@ -0,0 +1,68 @@
+// Mock API. These paths are not a real product. Find the app's own account
+// search and its account record call, and replace paths and envelopes with
+// what you observed. `__observe_me` cannot succeed until you do.
+//
+// The search takes a name and a page. When the app's search has no paging
+// (it returns every match at once), keep the call and cut the page here -
+// `rows.slice(offset, offset + limit)`, with `total` the count of all matches.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type AccountRow = {
+  id: string;
+  name: string;
+  industry?: string | null;
+  city?: string | null;
+  state?: string | null;
+};
+
+export type AccountPage = { accounts: AccountRow[]; total: number };
+
+export async function searchAccounts(
+  options: { search?: string; offset?: number; limit?: number } = {},
+): Promise<ApiResult<AccountPage>> {
+  const query = new URLSearchParams();
+  if (options.search) query.set("search", options.search);
+  query.set("offset", String(Math.max(0, options.offset ?? 0)));
+  query.set("limit", String(options.limit && options.limit > 0 ? options.limit : 20));
+  const res = await apiFetch<{ items?: AccountRow[]; total?: number }>(`/__observe_me/accounts?${query}`);
+  if (!res.ok) return res;
+  const rows = Array.isArray(res.data?.items) ? res.data.items : [];
+  return { ok: true, status: res.status, data: { accounts: rows, total: typeof res.data?.total === "number" ? res.data.total : rows.length } };
+}
+
+export type OverviewPayload = {
+  account?: {
+    id?: string | null;
+    name?: string | null;
+    industry?: string | null;
+    website?: string | null;
+    city?: string | null;
+    state?: string | null;
+    employeeCount?: number | null;
+    currency?: string | null;
+    owner?: { name?: string | null; email?: string | null } | null;
+  } | null;
+  opportunities?: Array<{
+    id?: string | null;
+    name?: string | null;
+    amount?: number | string | null;
+    stage?: string | null;
+    probability?: number | null;
+    closeDate?: string | null;
+  }> | null;
+  contacts?: Array<{
+    id?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    title?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    primary?: boolean | null;
+  }> | null;
+  cases?: Array<{ id?: string | null; title?: string | null; priority?: string | null; status?: string | null; createdAt?: string | null }> | null;
+};
+
+export async function getAccountOverview(accountId: string): Promise<ApiResult<OverviewPayload>> {
+  return apiFetch<OverviewPayload>(`/__observe_me/accounts/${encodeURIComponent(accountId)}/overview`);
+}