@foldspace_npm/harness 0.1.38 → 0.1.39

package/CLAUDE.md

@@ -779,7 +779,8 @@ Each of these cost a real build.
   callback, cancel, readyState)` decides which: a `render` that uses
   `callback`, `cancel` or `readyState` is an input card, and the agent waits
   until the card reports through one of them; one that uses none of them is
-  a view card.
+  a view card. Foldspace's docs call these **read-only** and **input**
+  cards; they mean the same thing.
 - **A view card shows something** - an account, a list, deals at risk -
   with `render(data, host, header)`: no `callback`, no `cancel`. As soon as
   `render` returns, the agent gets "Shown to the user. The user has not
@@ -818,6 +819,14 @@ Each of these cost a real build.
   choice, as fields**, with the state (chosen, declined, cancelled, failed)
   and nothing about what to do next (**Rules**, 1). A view card needs no
   state of its own: the SDK tells the agent it was shown.
+- **Never report a view card through `callback`.** Calling `callback(data)`
+  right after drawing (the old way to get a card's data to the agent) tells
+  the agent the user submitted that data, and it replies as if they had.
+  A view card takes `render(data, host, header)`, or calls
+  `readyState(value)` to send less than `execute` returned.
+- **The agent only knows what the card reports, not what it draws.** A
+  figure or date on the card that is not in that data is unknown to the
+  agent, so put every fact a follow-up question could need in it.
 - **A failed or signed-out call is never drawn as zeros.** A signed-out response
   often looks like a valid empty one: a 200 with zeros, nulls or an empty list.
   Before you draw numbers, check that the response belongs to a signed-in user -
@@ -834,11 +843,8 @@ Each of these cost a real build.
   code, from the API's own numbers - in `execute` for a view card, since its
   result is what the agent gets - show them on the card, and hand the agent
   the same figures. In the action's Studio `instructions`, tell the agent to
-  answer follow-up questions from the data it receives, to quote money and
-  counts exactly as given, never to add them up itself (a model that adds up
-  line items will eventually add them up wrong), and, right after a view
-  card, to say one short sentence at most - never repeat what the card
-  shows.
+  quote money and counts exactly as given and never to add them up itself (a
+  model that adds up line items will eventually add them up wrong).
 - **A card matches the panel, not the page.** The card sits in the agent's
   panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
   `primaryColor` for accents; a `darkTheme` when the panel is dark, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/recipes/README.md

@@ -43,9 +43,10 @@ SDK's: `execute(params)` and
 `render(data, host, header, callback, cancel, readyState)`
 (<https://docs.foldspace.ai/guides/in-chat-ui/>), `foldspace.identify(context)`
 (<https://docs.foldspace.ai/start/user-context/>), and the harness runtime.
-Where the in-chat UI page says to set `awaitUserInput`, do not - the SDK waits
-when `render` uses `callback` or `cancel` (see the card bullet below). That
-page does not list `readyState`; CLAUDE.md describes it, and no recipe uses it.
+Never set `awaitUserInput` - the SDK waits when `render` uses `callback`,
+`cancel` or `readyState` (see the card bullet below). What the agent receives
+for each is in CLAUDE.md (**Agentic UI components**); no recipe uses
+`readyState` yet.
 
 Error handling is **not** taken from those builds. They predate `reason`: one
 turns every failure into "unexpected error", another reports a missing session

package/recipes/account-overview/README.md

@@ -8,7 +8,7 @@ This card is the base layout. Copy it, then replace the `/__observe_me` routes w
 
 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 account, the totals and every row behind the tabs, or the failure (`success: false`, `error` and `reason`) - and it answers questions about the account from that. So `execute` returns the overview the card draws and nothing else. One tab is on screen at a time; an empty tab says so. A signed-out or failed call is drawn with `renderFailure`, never as zeros. A 200 is signed out unless the account has both an id and a name.
 
-In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`, described as "The account's id. Never taken from the user's words: get it from `<lookup action key>`." Replace `<lookup action key>` with the key of this agent's action that returns account ids; if the agent has none, build that action first - `find-by-name` has the shape. Its `instructions`: "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."
+In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`, described as "The account's id. Never taken from the user's words: get it from `<lookup action key>`." Replace `<lookup action key>` with the key of this agent's action that returns account ids; if the agent has none, build that action first - `find-by-name` has the shape. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

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

@@ -11,5 +11,5 @@
     }
   ],
   "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."
+  "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. Quote money and counts exactly as given, and never add them up yourself. No emoji."
 }

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

@@ -8,7 +8,7 @@ The app decides what "at risk" means, on the server. In that build it was: stall
 
 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. 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."
+In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

package/recipes/records-list/README.md

@@ -8,7 +8,7 @@ A view card: `render` takes no `callback` and the action sets no `awaitUserInput
 
 `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. 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."
+In Agent Studio: an action with key `list_accounts` and no parameters. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

package/src/lint/rules.mjs

@@ -586,7 +586,7 @@ export function ruleCardContract(sourceFile, relative, findings) {
               node: flag.name,
               file: relative,
               message:
-                "A view card (render uses neither callback nor cancel) sets awaitUserInput: true. The chat panel ignores it, but in headless mode the agent then waits for a callback that never comes.",
+                "A view card (render uses none of callback, cancel or readyState) sets awaitUserInput: true. The chat panel ignores it, but in headless mode the agent then waits for a callback that never comes.",
               fix: "Remove awaitUserInput. A view card is reported to the agent as shown, with what execute returned.",
             }),
           );
@@ -600,7 +600,7 @@ export function ruleCardContract(sourceFile, relative, findings) {
               node: flag.name,
               file: relative,
               message:
-                "A view card does not need awaitUserInput: render uses neither callback nor cancel, so the agent is told the card was shown, with what execute returned.",
+                "A view card does not need awaitUserInput: render uses none of callback, cancel or readyState, so the agent is told the card was shown, with what execute returned.",
               fix: "Remove awaitUserInput.",
             }),
           );