@foldspace_npm/harness 0.1.27 → 0.1.29

package/recipes/lookup-then-view/fixtures/accounts.json

@@ -0,0 +1,319 @@
+{
+ "accounts": [
+  {
+   "id": "acct_1",
+   "name": "Northwind Traders",
+   "industry": "Logistics",
+   "city": "Seattle",
+   "state": "WA"
+  },
+  {
+   "id": "acct_2",
+   "name": "Acme Corporation",
+   "industry": "Technology",
+   "city": "Austin",
+   "state": "TX"
+  },
+  {
+   "id": "acct_3",
+   "name": "Acme Logistics",
+   "industry": "Logistics",
+   "city": "Denver",
+   "state": "CO"
+  },
+  {
+   "id": "acct_4",
+   "name": "Fabrikam",
+   "industry": null,
+   "city": null,
+   "state": null
+  },
+  {
+   "id": "acct_5",
+   "name": "Contoso Branch 01",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_6",
+   "name": "Contoso Branch 02",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_7",
+   "name": "Contoso Branch 03",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_8",
+   "name": "Contoso Branch 04",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_9",
+   "name": "Contoso Branch 05",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_10",
+   "name": "Contoso Branch 06",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_11",
+   "name": "Contoso Branch 07",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_12",
+   "name": "Contoso Branch 08",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_13",
+   "name": "Contoso Branch 09",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_14",
+   "name": "Contoso Branch 10",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_15",
+   "name": "Contoso Branch 11",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_16",
+   "name": "Contoso Branch 12",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_17",
+   "name": "Contoso Branch 13",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_18",
+   "name": "Contoso Branch 14",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_19",
+   "name": "Contoso Branch 15",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_20",
+   "name": "Contoso Branch 16",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_21",
+   "name": "Contoso Branch 17",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_22",
+   "name": "Contoso Branch 18",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_23",
+   "name": "Contoso Branch 19",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_24",
+   "name": "Contoso Branch 20",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_25",
+   "name": "Contoso Branch 21",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_26",
+   "name": "Contoso Branch 22",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_27",
+   "name": "Contoso Branch 23",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_28",
+   "name": "Contoso Branch 24",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_29",
+   "name": "Contoso Branch 25",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_30",
+   "name": "Contoso Branch 26",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_31",
+   "name": "Contoso Branch 27",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_32",
+   "name": "Contoso Branch 28",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_33",
+   "name": "Contoso Branch 29",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_34",
+   "name": "Contoso Branch 30",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_35",
+   "name": "Contoso Branch 31",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_36",
+   "name": "Contoso Branch 32",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_37",
+   "name": "Contoso Branch 33",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_38",
+   "name": "Contoso Branch 34",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_39",
+   "name": "Contoso Branch 35",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_40",
+   "name": "Contoso Branch 36",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  },
+  {
+   "id": "acct_41",
+   "name": "Contoso Branch 37",
+   "industry": "Retail",
+   "city": "Chicago",
+   "state": "IL"
+  },
+  {
+   "id": "acct_42",
+   "name": "Contoso Branch 38",
+   "industry": "Manufacturing",
+   "city": "Portland",
+   "state": "OR"
+  },
+  {
+   "id": "acct_43",
+   "name": "Contoso Branch 39",
+   "industry": "Education",
+   "city": "Miami",
+   "state": "FL"
+  },
+  {
+   "id": "acct_44",
+   "name": "Contoso Branch 40",
+   "industry": "Finance",
+   "city": "Phoenix",
+   "state": "AZ"
+  },
+  {
+   "id": "acct_45",
+   "name": "Contoso Branch 41",
+   "industry": "Healthcare",
+   "city": "Boston",
+   "state": "MA"
+  }
+ ]
+}

package/recipes/lookup-then-view/fixtures/overview.ok.json

@@ -0,0 +1,122 @@
+{
+ "account": {
+  "id": "acct_1",
+  "name": "Northwind Traders",
+  "industry": "Logistics",
+  "website": "https://www.northwind.example",
+  "city": "Seattle",
+  "state": "WA",
+  "employeeCount": 500,
+  "annualRevenue": 42000000,
+  "currency": "USD",
+  "owner": {
+   "name": "Dana Reyes",
+   "email": "dana@example.com"
+  }
+ },
+ "opportunities": [
+  {
+   "id": "o1",
+   "name": "Enterprise Platform Upgrade",
+   "amount": 125000,
+   "stage": "negotiation",
+   "probability": 70,
+   "closeDate": "2026-10-14"
+  },
+  {
+   "id": "o2",
+   "name": "Q1 License Renewal",
+   "amount": "50000",
+   "stage": "proposal",
+   "probability": 50,
+   "closeDate": "2026-09-20"
+  },
+  {
+   "id": "o3",
+   "name": "API Integration Package",
+   "amount": 35000,
+   "stage": "discovery",
+   "probability": 20,
+   "closeDate": "2026-12-10"
+  },
+  {
+   "id": "o4",
+   "name": "Training Add-on",
+   "amount": 8000,
+   "stage": "qualification",
+   "probability": 30,
+   "closeDate": null
+  },
+  {
+   "id": "o5",
+   "name": "Pilot (lost)",
+   "amount": 90000,
+   "stage": "closed_lost",
+   "probability": 0,
+   "closeDate": "2026-06-01"
+  }
+ ],
+ "contacts": [
+  {
+   "id": "c1",
+   "firstName": "Sam",
+   "lastName": "Lee",
+   "title": "Operations Lead",
+   "email": "sam@example.com",
+   "phone": "(415) 555-0142"
+  },
+  {
+   "id": "c2",
+   "firstName": "Priya",
+   "lastName": "Nair",
+   "title": "VP Procurement",
+   "email": "priya@example.com",
+   "phone": null,
+   "primary": true
+  },
+  {
+   "id": "c3",
+   "firstName": "Jordan",
+   "lastName": "Kim",
+   "title": null,
+   "email": "jordan@example.com"
+  },
+  {
+   "id": "c4",
+   "firstName": "Alex",
+   "lastName": "Moreno",
+   "title": "IT Manager",
+   "email": "alex@example.com"
+  }
+ ],
+ "cases": [
+  {
+   "id": "k1",
+   "title": "Invoices not syncing",
+   "priority": "critical",
+   "status": "open",
+   "createdAt": "2026-09-28"
+  },
+  {
+   "id": "k2",
+   "title": "SSO login loop",
+   "priority": "medium",
+   "status": "in_progress",
+   "createdAt": "2026-09-21"
+  },
+  {
+   "id": "k3",
+   "title": "Old ticket",
+   "priority": "low",
+   "status": "closed",
+   "createdAt": "2026-05-01"
+  }
+ ],
+ "meetings": [
+  {
+   "id": "m1",
+   "title": "Quarterly review",
+   "startTime": "2026-10-03T15:00:00Z"
+  }
+ ]
+}

package/recipes/lookup-then-view/fixtures/overview.unsigned.json

@@ -0,0 +1,14 @@
+{
+ "account": {
+  "id": null,
+  "name": null
+ },
+ "opportunities": [
+  {
+   "id": "o1",
+   "name": "Renewal",
+   "amount": 18000,
+   "stage": "proposal"
+  }
+ ]
+}

package/recipes/lookup-then-view/recipe.json

@@ -0,0 +1,11 @@
+{
+  "title": "Look up, then show",
+  "level": "L2",
+  "family": "lookup-then-view",
+  "kind": "action",
+  "action": "find_account",
+  "actions": ["find_account", "show_account_overview"],
+  "entry": "agent/actions/find_account.ts",
+  "outcome": "The user names an account. One match: its card, no question asked. Several or none: a searchable, paged list, one click to choose - then the card",
+  "provenBy": 1
+}

package/recipes/lookup-then-view/studio/find_account.json

@@ -0,0 +1,10 @@
+{
+  "action_key": "find_account",
+  "display_name": "Find account",
+  "description": "Finds the account the user asked to see and returns its id. With one clear match it answers at once; with several, or none, it shows the user a searchable list and returns the one they choose.",
+  "parameters": [
+    { "name": "name", "description": "The account name, or part of it, exactly as the user said it.", "dataType": "STRING", "required": true }
+  ],
+  "confirmation_required": false,
+  "instructions": "Call this when the user asks to see an account by name. The result says found, chosen, none_of_these, cancelled or failed. On found or chosen, call show_account_overview with that accountId straight away - do not ask the user to confirm, and do not repeat the account's details. On none_of_these, ask the user which account they mean. On cancelled, stop. On failed, the card already says why: say so in one short sentence and stop. Never guess an id, and never show ids to the user. No emoji."
+}

package/recipes/lookup-then-view/studio/show_account_overview.json

@@ -0,0 +1,15 @@
+{
+  "action_key": "show_account_overview",
+  "display_name": "Show account overview",
+  "description": "Shows one account as a card: who it is, open pipeline, deals, people and open cases.",
+  "parameters": [
+    {
+      "name": "accountId",
+      "description": "The account's id. Never guessed and never taken from the user's words: get it from find_account.",
+      "dataType": "STRING",
+      "required": true
+    }
+  ],
+  "confirmation_required": false,
+  "instructions": "The result is the data the card was drawn from - every open deal, person and open case, not only the ones it lists - or a failure: success false, with the reason. Answer follow-up questions about this account 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."
+}

package/recipes/opportunities-at-risk/README.md

@@ -6,9 +6,9 @@
 
 The app decides what "at risk" means, on the server. In that build it was: stalled 14+ days, past its close date, low probability in a late stage, critical support cases on the account, no recent meetings — each reason comes back as a short label and the card shows them as tags. The action does not re-judge anything; it draws what the API says.
 
-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 the empty state ("No opportunities are at risk.") is on the card, not in a message. The count, the total and the average 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, the average and the rows (no rows when the card says "No opportunities are at risk."), or the failure (`success: false`, `error` and `reason`). So `execute` returns what the card draws, with each row's id, and nothing else. The count, the total and the average are computed in code from the rows.
 
-In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters.
+In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters. Its `instructions`: "Answer follow-up questions about these opportunities 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,11 +16,11 @@ In Agent Studio: an action with key `show_opportunities_at_risk` and no paramete
 |---|---|
 | `agent/api/opportunities.ts` | Mock path and envelope. Find the app's own "needs attention" list — the one with reasons per row |
 | `agent/opportunities.ts` | Which fields a row carries. Totals stay computed here |
-| `agent/views/at-risk.ts` | The card. `brand.ts` matches the agent's white panel; put the agent's primary colour in `accent` |
+| `agent/views/at-risk.ts` | The card. `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
 
 - **A list has nothing to prove who it belongs to.** An account has an id and a name; a list does not. The build answered signed-out calls with a 401, which `apiFetch` already reports as `signed_out`. What the code still checks is that a 200 is the list at all — the rows array has to be there. ⚠️ If the app you are on answers a signed-out call with a 200 and an empty list, that check is not enough; find something in the response that only a signed-in user gets.
 - **Empty is an answer.** Zero at risk is drawn as a card that says so — never as a failure, and never as a hint about what to do next.
-- **Rows are not links.** The production build made every name clickable through a message its own single-page app listened for. No other app does; on any other product the click would do nothing. Open a record with a navigation route instead.
-- **The agent cannot see the card.** In the production build the render also handed the rows to the agent through `callback`, so it could answer "tell me more about the second one". That path is not in this recipe: with `awaitUserInput` off the platform does not deliver it, and a view-only action's data does not reach the model by design. If the agent needs the rows, that is a second, data-only action.
+- **Rows are not links.** The production build made every name clickable through a message its own single-page app listened for. No other app does; on any other product the click would do nothing. Open a record with a navigation route instead, with the id the agent got for that row.
+- **The agent answers from what `execute` returns.** The production build called `callback` with the rows so that the agent could answer "tell me more about the second one". A view card needs no `callback` for that: the agent gets everything `execute` returned, rows included.

package/recipes/opportunities-at-risk/agent/actions/show_opportunities_at_risk.ts

@@ -1,7 +1,11 @@
-// View-only card. Do not set awaitUserInput: the model is told only that the
-// information was displayed, so the card carries every fact — including "nothing
-// is at risk". A failed or signed-out call is drawn with renderFailure, never as
-// a count of zero.
+// 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 what the card
+// draws, with each row's id, and nothing else: the count, the total, the
+// average and the rows (the agent can answer "tell me more about the second
+// one", or say that nothing is at risk), or the failure the card draws
+// instead. A failed or signed-out call is
+// drawn with renderFailure, never as a count of zero.
 
 import { getOpportunitiesAtRisk } from "../api/opportunities";
 import { isAtRiskList, toAtRisk, type AtRiskOverview } from "../opportunities";
@@ -10,7 +14,6 @@ import { mountOpportunitiesAtRisk } from "../views/at-risk";
 
 type ShowResult = {
   success: boolean;
-  message?: string;
   error?: string;
   reason?: FailureReason;
   data?: AtRiskOverview;
@@ -26,8 +29,7 @@ export const show_opportunities_at_risk = {
     if (!isAtRiskList(res.data)) {
       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: toAtRisk(res.data) };
+    return { success: true, data: toAtRisk(res.data) };
   },
 
   render: (result: ShowResult | undefined, host: HTMLElement, header: HTMLElement) => {

package/recipes/opportunities-at-risk/agent/opportunities.ts

@@ -1,6 +1,8 @@
 // The count, the total and the average are computed here, from the rows the API
 // returned. The model does not add them, and the card does not trust a total the
-// server sent alongside rows that may disagree with it.
+// server sent alongside rows that may disagree with it. 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 { AtRiskPayload } from "./api/opportunities";
 
@@ -10,13 +12,12 @@ export type AtRiskOpportunity = {
   accountName: string | null;
   value: number;
   stage: string | null;
-  closeDate: string | null;
-  daysSinceUpdate: number | null;
   risks: string[];
 };
 
 export type AtRiskOverview = {
-  metrics: { count: number; totalValue: number; avgDaysStalled: number };
+  /** avgDaysStalled is null when no row says how long it has stalled - never 0. */
+  metrics: { count: number; totalValue: number; avgDaysStalled: number | null };
   opportunities: AtRiskOpportunity[];
 };
 
@@ -49,20 +50,20 @@ function toNumber(value: number | string | null | undefined): number {
 }
 
 export function toAtRisk(payload: AtRiskPayload): AtRiskOverview {
-  const opportunities = (payload.deals ?? []).map((row) => ({
+  const deals = payload.deals ?? [];
+  const opportunities = deals.map((row) => ({
     id: row.id?.trim() || "",
     name: row.name?.trim() || "Untitled",
     accountName: row.account?.name?.trim() || null,
     value: toNumber(row.value),
     stage: row.stage?.trim() || null,
-    closeDate: row.closeDate?.trim() || null,
-    daysSinceUpdate:
-      typeof row.daysSinceUpdate === "number" && Number.isFinite(row.daysSinceUpdate) ? row.daysSinceUpdate : null,
     risks: (row.risks ?? []).filter((risk): risk is string => typeof risk === "string" && risk.trim() !== ""),
   }));
 
-  const stalled = opportunities.map((row) => row.daysSinceUpdate).filter((days): days is number => days !== null);
-  const avgDaysStalled = stalled.length ? Math.round(stalled.reduce((sum, days) => sum + days, 0) / stalled.length) : 0;
+  const stalled = deals
+    .map((row) => row.daysSinceUpdate)
+    .filter((days): days is number => typeof days === "number" && Number.isFinite(days));
+  const avgDaysStalled = stalled.length ? Math.round(stalled.reduce((sum, days) => sum + days, 0) / stalled.length) : null;
 
   return {
     metrics: {

package/recipes/opportunities-at-risk/agent/views/at-risk.ts

@@ -86,7 +86,7 @@ export function mountOpportunitiesAtRisk(host: HTMLElement, header: HTMLElement,
   stats.append(
     stat("At risk", String(metrics.count)),
     stat("Total value", formatMoney(metrics.totalValue), true),
-    stat("Avg days stalled", String(metrics.avgDaysStalled)),
+    stat("Avg days stalled", metrics.avgDaysStalled === null ? "-" : String(metrics.avgDaysStalled)),
   );
   card.append(stats);
 

package/recipes/opportunities-at-risk/agent/views/brand.ts

@@ -1,24 +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",
-  warn: "#B45309",
-  warnInk: "#FEF3C7",
-  row: "#F9FAFB",
+  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;