@foldspace_npm/harness 0.1.38 → 0.1.40

package/CLAUDE.md

@@ -362,8 +362,53 @@ to what they know. The action handler is yours: call it "the code behind it".
 | **Task agent** | *how* to do one reasoning job | Agent Studio | instructions + response schema |
 | **Navigation route** | where the agent can send the user | Agent Studio | a URL template + what the page is for |
 
-Knowledge search, navigation and sharing the current tab are platform
-built-ins — no code, and a first experience can lean on them.
+**Built into every agent - never build your own.** These need no action and no
+code. A copy of one competes with the built-in: the agent may pick yours, and
+yours lacks what the built-in does (consent, routes, settings). A first
+experience can lean on them. Lint warns (`no-native-lookalike`) when an action
+looks like one.
+
+| Built-in | What the agent gets | Turn it on | Never build |
+|---|---|---|---|
+| **Knowledge search** | Answers from the agent's knowledge | Add a knowledge source or an internal article | An action that searches docs, help or FAQ |
+| **Navigation** | Opens a page of the app | A navigation route (`create_navigation_route`) per page | A URL builder, or an action whose job is opening a page. Finding an item by name is an action; opening its page is a route |
+| **Share current tab** | A screenshot and/or the HTML of the page, once, when the agent needs it (the user agrees first) | Agent settings → Customize → Data Access & Handoff | An action that reads, summarises or screenshots the page: no "what's on this page", no handler that returns `document.body`, `innerHTML` or page text |
+| **Share screen** | The page with every message while sharing is on | The same setting; a developer can also set `screenSharingSettings: { active: true }` in `setConfiguration` | The same |
+| **Shared State** | The app's own state: an open form, filters, the selection | `shareState()` in the agent code | A "current view" or "what is selected" action |
+| **Voice** | Voice chat and dictation in the panel | Agent settings | Microphone, speech-to-text or text-to-speech code |
+| **Ask the user** | A question card with choices | Below | A generic "ask the user", "clarify" or "choose an option" action |
+| **Live-agent handoff, support ticket** | Hands the chat to a person, or opens a ticket | Agent settings → Customize → Data Access & Handoff | Your own handoff - unless the built-in doesn't cover their support tool: ask the human first |
+
+When the experience needs one of these and it's off, ask the human to turn it
+on; it changes the live agent. If an existing action already copies one (a
+URL builder, a page reader), say so to the human and propose moving to the
+built-in - don't delete it unasked.
+
+**Asking the user a question is a built-in too: `ask_user_question`.** It shows
+a card with 1-4 questions, 2-4 choices each plus "Other", and waits for the
+answers. **Never build an action or a card that does the same** - a generic
+"ask the user", "clarify" or "choose an option". It needs no action, handler
+or code. It may be off for this agent: when the agent needs it, ask the human
+to turn on **Ask questions with choices** (agent settings → **Customize → Data
+access**, then Save); it changes the live agent, and takes about a minute to
+reach it. Build your own input card only when the choices come from the app's
+data or the card does the work, as `pick-from-a-list` and `create-a-record` do.
+
+Change the built-in only when the human asks:
+
+- **A different look:** set `--fs-ask-*` variables (`--fs-ask-primary`,
+  `--fs-ask-surface`, `--fs-ask-border`, `--fs-ask-radius`...) in the agent's
+  `customCss`. Never a new card for a new look, and never style its class names.
+- **Their own card:** an action handler under the key `ask_user_question`,
+  with no Studio action. It runs instead of the built-in: `execute` gets
+  `params.questions`, and the card calls `callback({ status: "ANSWERED",
+  answers })` with one `{ header, selected, otherText?, skipped? }` per question,
+  or `cancel()` when everything is skipped - the same result, so the agent's
+  instructions still fit.
+- **Their own instructions too:** only then a Studio action named
+  `ask_user_question`. It replaces the built-in completely, text included.
+- **Removing one:** unpublish an `ask_user_question` action before deleting
+  it. A deleted published action still keeps the built-in off.
 
 1. `create_action` as a **draft**. `generate_action_handler` works from a draft
    schema; do not publish yet. Generating the handler from the schema is what
@@ -613,11 +658,14 @@ Do not report success without all six:
 5. The action behaves against the real workflow: `[actions]
    local-handler:execute` in the attach log after `foldspace ask` (or the
    human) exercises the visible agent. A card also needs
-   `local-handler:render` from a real chat turn - not a hand-built `render()`
-   call. A view card leaves the chat free: in `ask`'s screenshot the panel's
-   message box does not read "Provide input, or cancel" beside a Cancel
-   button. If it does, `render` uses `callback` or `cancel` somewhere, or the
-   handler sets `awaitUserInput` - take them out. Then ask a follow-up
+   `local-handler:render` from a real chat turn (`renderComponent` logs as
+   `render` too) - not a hand-built call. A view card leaves the chat free: `ask`
+   returns a reply, and in its screenshot the panel shows no stop button and its
+   message box does not read "Provide input, or cancel" beside a Cancel button.
+   If `ask` returns `ok: false` with `hasCard: true`, or the panel shows either of
+   those, the agent is waiting for the card: it uses `callback` or `cancel`
+   somewhere, or the SDK can't read it and it never calls `readyState`
+   (**Agentic UI components**). Take them out, or destructure the keys. Then ask a follow-up
    question about the card (`foldspace ask` again): the reply quotes its
    numbers exactly as the card shows them. If it does not, make `execute`
    return them as the card shows them (rule 2). An input card holds the chat
@@ -772,17 +820,37 @@ wins**. <https://docs.foldspace.ai/customize/configuration/>
 
 ## Agentic UI components: what bites
 
-An Agentic UI component is the card an action draws in the chat (`render`).
-Each of these cost a real build.
-
-- **A card is a view card or an input card.** `render(data, host, header,
-  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.
+An Agentic UI component is the card an action draws in the chat
+(`renderComponent`, or the older `render`). Each of these cost a real build.
+
+- **Write new cards with `renderComponent`.**
+  `renderComponent({ data, host, header, callback, cancel, readyState, theme })`
+  takes one object, so a card names only what it uses and no argument can land
+  in the wrong position. Destructure the keys in the parameter: the SDK and lint
+  read them to tell the two kinds of card apart. Nested keys are fine
+  (`{ data: { items }, host }`), and so is `const { data, host } = ctx`. The SDK
+  can't read the object passed on (`mount(ctx)`) or aliased, `...rest` at the top
+  of the pattern, `arguments`, or a bound function. The agent then waits until
+  that card calls `readyState`, `callback` or `cancel`, so a view card that calls
+  none of them never gets a reply until the user presses stop. Destructure the
+  keys; where you can't, the view card calls `readyState` once it is drawn. Lint
+  warns on these shapes, since it can't check them either.
+  `render(data, host, header, callback, cancel,
+  readyState, theme)` still works, and `renderComponent` wins if an action has
+  both. Leave a working `render` alone unless you are changing that card. The
+  recipes still use `render`: when you copy one, convert it, so
+  `render: (result, host, header) =>` becomes
+  `renderComponent: ({ data: result, host, header }) =>`, and an input card's
+  `render: (result, host, header, callback, cancel) =>` becomes
+  `renderComponent: ({ data: result, host, header, callback, cancel }) =>`.
+- **A card is a view card or an input card.** What it uses decides: a card
+  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. 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
+  with `renderComponent({ data, host, header })`: no `callback`, no `cancel`.
+  As soon as it returns, the agent gets "Shown to the user. The user has not
   acted on it." plus exactly what `execute` returned, and answers questions
   about the card from that. So `execute` returns the facts the card shows,
   as fields, and nothing else - or the failure the card draws with
@@ -801,23 +869,30 @@ Each of these cost a real build.
   draws a default "Cancel" control on a card; not yet checked in the live
   product.
 - **When the conversation should go on while the user decides,** an input
-  card calls `readyState(value)` (`render`'s 6th argument) once it is
-  drawn: the agent gets `value` as what is shown and carries on. ⚠️ The
+  card calls `readyState(value)` once it is drawn: the agent gets `value` as what is shown and carries on. ⚠️ The
   user's answer then arrives as a follow-up turn - seen in the SDK's
   headless mode (`mode: "HEADLESS"`, the customer's own chat UI), not yet
   checked in the chat panel. No recipe uses it yet.
-- **Never set `awaitUserInput`** on either kind: `render` decides whether
-  the agent waits. An input card does not need it. The chat panel ignores
+- **Never set `awaitUserInput`** on either kind: it is deprecated. What the
+  card uses decides whether the agent waits. An input card does not need it. The chat panel ignores
   it; in headless mode `awaitUserInput: true` on a view card leaves the
   agent waiting for a callback that never comes, until the user presses
   stop. Lint stops the build on `awaitUserInput: true` on a view card, and
-  warns on any other `awaitUserInput` and on a `render` that declares
-  `callback`, `cancel` or `readyState` but uses none of them (the SDK then
-  treats it as a view card).
+  warns on any other `awaitUserInput`, on a card that declares `callback`,
+  `cancel` or `readyState` but uses none of them (the SDK then treats it as a
+  view card), and on a `renderComponent` the SDK can't read.
 - **What reaches the agent is the tool response: the data and the user's
   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 `renderComponent({ 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 +909,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
@@ -851,6 +923,21 @@ Each of these cost a real build.
   white, so that falls back to greys and the file says so. Record where the
   values came from in the profile's Brand section. Never copy colours by eye:
   that is how a dark card ends up in a white panel.
+- **Every new card follows the panel's mode.** The SDK exposes the mode and
+  colours and paints nothing, so a card with fixed colours stays light in a dark
+  panel. Take surface, text and border from the `--fs-*` variables, with
+  `brand.ts` as the fallback: `background: var(--fs-paper, ${brand.surface})`,
+  `color: var(--fs-text, ${brand.text})`,
+  `border-color: var(--fs-border, ${brand.border})`. Put
+  `color-scheme: var(--fs-color-scheme)` on the card's own element for native
+  controls, and use `[data-fs-mode="dark"]` for what has no variable, such as a
+  shadow. What CSS can't reach, such as a canvas, reads `theme` (`theme.mode`,
+  `theme.primary`) and redraws on `theme.onChange(fn)`. A mode change repaints:
+  the card does not run again and nothing reaches the agent. The colours change
+  only if the agent has a `darkTheme`; without one only the mode changes, so the
+  variables stay light. Look at the card in both modes
+  (`agent.setThemeMode("DARK")`) before you call it done. Fields:
+  <https://docs.foldspace.ai/guides/in-chat-ui/#support-dark-mode>
 
 ## Layout
 

package/README.md

@@ -256,13 +256,13 @@ v1 flags:
 
 - **error** `no-static-agent-prompt` - `execute`, a card's `callback` or its `readyState` handing the agent instructions (`directive`, “tell the user”, …)
 - **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
-- **error** `card-contract` - `awaitUserInput: true` on a view card (its `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
+- **error** `card-contract` - `awaitUserInput: true` on a view card (its `renderComponent` or `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
 - **error** `no-test-mode-in-bundle` - `armAllInstances` used anywhere in `agent/` (called, or handed on to be called later), or `setTestMode(...)` with anything but a literal `false`. A code project's own copy of the runtime in `agent/runtime/` is not refused for the `setTestMode` inside its `armAllInstances`
 - **error** `no-fixed-customer-address` - on a product with a subdomain per customer (`PER_CUSTOMER_SUBDOMAIN` in `agent/constants.ts`), one customer's address in `API_BASE` or anywhere in `agent/`; while that is undecided, an address whose first part looks like a customer's name (`acme.` - not `app.`, `eu1.`, `reports.`)
 - **error** `token-stays-home` - the user's sign-in token (`getAuthToken`, a session-named storage key, `document.cookie`, followed through variables and helper functions) returned from `execute` or a card, handed to Foldspace, logged, stored again, or sent to a host that is not the product's backend
 - **error** `no-secrets` - API keys, JWTs, bearer tokens, cookie values, secret-named strings, `.har` captures, storage dumps and `.env` files anywhere in the project (not `node_modules/`, `dist/`, `.foldspace-dev/`, `agent/runtime/`)
 - **warning** `known-hosts-only` - `fetch`, `sendBeacon`, `WebSocket`, `EventSource`, `XMLHttpRequest`, `publicFetch` or `import()` to an address written out whose host is neither Foldspace's (`*.foldspace.ai`), the product's (`foldspace.dev.json` hosts, `API_BASE`, the app's own domain) nor written in `agent/constants.ts`
-- **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), or a `render` that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card)
+- **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), a card that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card), or a `renderComponent` the SDK can't read (the object passed on or aliased, `...rest`, `arguments`): the agent waits until it calls `readyState`, `callback` or `cancel`, so a view card that calls none of them never gets a reply
 - **warning** `no-emoji` — emoji in handler or `agent/views` string literals
 - **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`
 

package/package.json

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

package/recipes/README.md

@@ -40,12 +40,16 @@ those builds learned the hard way. **What is taken is the shape** — the order
 calls, what is returned to the agent, where the traps are. **What is not taken**
 is any customer's name, endpoint, identifier, styling or code. Contracts are the
 SDK's: `execute(params)` and
-`render(data, host, header, callback, cancel, readyState)`
-(<https://docs.foldspace.ai/guides/in-chat-ui/>), `foldspace.identify(context)`
+`renderComponent({ data, host, header, callback, cancel, readyState, theme })`
+for a new card, or the older
+`render(data, host, header, callback, cancel, readyState, theme)` these recipes
+use (<https://docs.foldspace.ai/guides/in-chat-ui/>; convert when you copy, see
+CLAUDE.md), `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 a card 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/action-observer.mjs

@@ -65,17 +65,22 @@ export function buildActionObserverScript({
     catch { return Date.now(); }
   };
 
-  const wrapFunction = (actionName, phase, fn) =>
+  const errorName = (error) =>
+    typeof error?.name === "string" ? error.name.slice(0, 100) : "Error";
+
+  // Only execute is wrapped. The SDK reads a card's source to tell a view card
+  // from an input card, and a wrapper would hide it: the agent would then wait
+  // on every view card. recordRender logs cards from the SDK's own events.
+  const wrapExecute = (actionName, fn) =>
     function observedActionPhase(...args) {
       const startedAt = now();
+      const phase = "execute";
       record({
         source: "local-handler",
         actionName,
         phase,
         status: "started",
-        ...(phase === "execute"
-          ? { parameterKeys: parameterKeys(args[0]) }
-          : {}),
+        parameterKeys: parameterKeys(args[0]),
       });
 
       const succeeded = (value) => {
@@ -95,10 +100,7 @@ export function buildActionObserverScript({
           phase,
           status: "failed",
           durationMs: Math.max(0, Math.round(now() - startedAt)),
-          errorName:
-            typeof error?.name === "string"
-              ? error.name.slice(0, 100)
-              : "Error",
+          errorName: errorName(error),
         });
         throw error;
       };
@@ -132,18 +134,16 @@ export function buildActionObserverScript({
         continue;
       }
       const actionDescriptors = Object.getOwnPropertyDescriptors(definition);
-      for (const phase of ["execute", "render"]) {
-        const phaseDescriptor = actionDescriptors[phase];
-        if (
-          phaseDescriptor &&
-          "value" in phaseDescriptor &&
-          typeof phaseDescriptor.value === "function"
-        ) {
-          actionDescriptors[phase] = {
-            ...phaseDescriptor,
-            value: wrapFunction(name, phase, phaseDescriptor.value),
-          };
-        }
+      const executeDescriptor = actionDescriptors.execute;
+      if (
+        executeDescriptor &&
+        "value" in executeDescriptor &&
+        typeof executeDescriptor.value === "function"
+      ) {
+        actionDescriptors.execute = {
+          ...executeDescriptor,
+          value: wrapExecute(name, executeDescriptor.value),
+        };
       }
       if (!descriptor || !("value" in descriptor)) continue;
       const observedDefinition = Object.create(
@@ -207,6 +207,37 @@ export function buildActionObserverScript({
   };
   ensureActionCapture();
 
+  // The SDK emits "rendered" just before it calls the card, and "failed" if that
+  // call throws, in the same task. Still pending on the next task means it drew.
+  const pendingRenders = new Map();
+  const recordRender = (event) => {
+    const actionName = event?.actionKey;
+    if (!state.expectedActionNames.includes(actionName)) return;
+    const phase = "render";
+    const source = "local-handler";
+    const durationMs = () =>
+      Math.max(0, Math.round(now() - pendingRenders.get(actionName)));
+    if (event.status === "rendered") {
+      pendingRenders.set(actionName, now());
+      record({ source, actionName, phase, status: "started" });
+      setTimeout(() => {
+        if (!pendingRenders.has(actionName)) return;
+        record({ source, actionName, phase, status: "succeeded", durationMs: durationMs() });
+        pendingRenders.delete(actionName);
+      }, 0);
+    } else if (event.status === "failed" && pendingRenders.has(actionName)) {
+      record({
+        source,
+        actionName,
+        phase,
+        status: "failed",
+        durationMs: durationMs(),
+        errorName: errorName(event.payload),
+      });
+      pendingRenders.delete(actionName);
+    }
+  };
+
   const observedAgents = new WeakSet();
   const subscribe = () => {
     ensureActionCapture();
@@ -237,6 +268,7 @@ export function buildActionObserverScript({
               ? event.status.slice(0, 100)
               : "unknown",
         });
+        recordRender(event);
       };
       agent.on?.("action.callback", recordSdkAction);
       agent.on?.("remoteActions.loaded", ensureActionCapture);

package/src/lint/ast.mjs

@@ -71,7 +71,7 @@ function initializerOf(node) {
 }
 
 /**
- * Call `visit(fn, name)` for execute / render / callback function-likes.
+ * Call `visit(fn, name)` for execute / render / renderComponent / callback function-likes.
  */
 export function forEachNamedFunction(sourceFile, names, visit) {
   const wanted = names instanceof Set ? names : new Set(names);
@@ -102,6 +102,101 @@ export function callbackParamName(fn) {
   return "callback";
 }
 
+const REPORT_KEYS = ["callback", "cancel", "readyState"];
+
+/** Every default inside a nested pattern. */
+function collectBindingDefaults(pattern, defaults) {
+  for (const element of pattern.elements) {
+    if (!ts.isBindingElement(element)) continue;
+    if (element.initializer) defaults.push(element.initializer);
+    if (!ts.isIdentifier(element.name)) collectBindingDefaults(element.name, defaults);
+  }
+}
+
+function readComponentPattern(pattern, read) {
+  for (const element of pattern.elements) {
+    const keyName = element.propertyName;
+    if (element.dotDotDotToken || (keyName && !ts.isIdentifier(keyName))) {
+      read.unknown = true;
+      continue;
+    }
+    const key = (keyName || element.name).getText();
+    const reports = REPORT_KEYS.includes(key);
+    if (element.initializer) read.defaults.push(element.initializer);
+    if (ts.isIdentifier(element.name)) {
+      if (reports) read.locals.set(element.name.text, key);
+    } else if (reports) {
+      read.unknown = true;
+    } else {
+      collectBindingDefaults(element.name, read.defaults);
+    }
+  }
+}
+
+/**
+ * How a `renderComponent` reads its one object, the way the SDK reads it.
+ * `locals` maps the name each report function goes by to its key:
+ * `{ callback: done }` gives done -> callback, from the parameter or from
+ * `const { callback } = ctx`. `context` is the parameter's name when it is not
+ * destructured. `defaults` are the pattern's defaults, which run like the body.
+ * `unknown` is what the SDK cannot read either: a `...rest` at the top of the
+ * pattern, a report key taken apart, or a key that is not a plain name. Nested
+ * patterns under any other key are read.
+ */
+export function readComponentParam(fn) {
+  const params = (fn.parameters || []).filter((param) => !(ts.isIdentifier(param.name) && param.name.text === "this"));
+  const first = params[0];
+  const read = { locals: new Map(), context: null, defaults: [], unknown: false };
+  if (!first) return read;
+  if (first.dotDotDotToken) return { ...read, unknown: true };
+  if (first.initializer) read.defaults.push(first.initializer);
+  if (ts.isIdentifier(first.name)) {
+    read.context = first.name.text;
+    const walk = (node) => {
+      if (
+        ts.isVariableDeclaration(node) &&
+        ts.isObjectBindingPattern(node.name) &&
+        node.initializer &&
+        ts.isIdentifier(node.initializer) &&
+        node.initializer.text === read.context
+      ) {
+        readComponentPattern(node.name, read);
+      }
+      ts.forEachChild(node, walk);
+    };
+    if (fn.body) walk(fn.body);
+    return read;
+  }
+  if (!ts.isObjectBindingPattern(first.name)) return { ...read, unknown: true };
+  readComponentPattern(first.name, read);
+  return read;
+}
+
+/**
+ * Call `visit(call, key)` for each call a `renderComponent` makes to a report
+ * function: `callback(x)` from the pattern, or `ctx.callback(x)`.
+ */
+export function forEachComponentReport(fn, visit) {
+  const { locals, context } = readComponentParam(fn);
+  function walk(node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isIdentifier(callee) && locals.has(callee.text)) visit(node, locals.get(callee.text));
+      if (
+        context &&
+        ts.isPropertyAccessExpression(callee) &&
+        ts.isIdentifier(callee.expression) &&
+        callee.expression.text === context &&
+        REPORT_KEYS.includes(callee.name.text)
+      ) {
+        visit(node, callee.name.text);
+      }
+    }
+    ts.forEachChild(node, walk);
+  }
+  if (fn.body) walk(fn.body);
+}
+
 export function collectConstBindings(scopeNode) {
   const map = new Map();
 

package/src/lint/rules.mjs

@@ -5,6 +5,7 @@ import {
   collectModuleBindings,
   finding,
   forEachCallNamed,
+  forEachComponentReport,
   forEachNamedFunction,
   forEachReturn,
   forEachStringLiteral,
@@ -18,6 +19,7 @@ import {
   resolveNode,
   shouldSkipActionFile,
   stringText,
+  readComponentParam,
 } from "./ast.mjs";
 import { ts } from "./ts.mjs";
 
@@ -113,9 +115,17 @@ function inspectReturnedObject(obj, bindings, sourceFile, relative, findings, or
 }
 
 export function ruleNoStaticAgentPrompt(sourceFile, relative, findings) {
-  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn, name) => {
+  forEachNamedFunction(sourceFile, ["execute", "render", "renderComponent", "callback"], (fn, name) => {
     const bindings = mergeBindings(fn, sourceFile);
 
+    if (name === "renderComponent") {
+      forEachComponentReport(fn, (call, key) => {
+        const arg = call.arguments[0];
+        if (!arg || key === "cancel") return;
+        inspectReturnedObject(resolveNode(arg, bindings), bindings, sourceFile, relative, findings, key);
+      });
+    }
+
     if (name === "execute" || name === "callback") {
       forEachReturn(fn, (expression) => {
         inspectReturnedObject(
@@ -235,7 +245,7 @@ export function ruleNoEmoji(sourceFile, relative, findings, { wholeFile = false
     return;
   }
 
-  forEachNamedFunction(sourceFile, ["execute", "render", "callback"], (fn) => {
+  forEachNamedFunction(sourceFile, ["execute", "render", "renderComponent", "callback"], (fn) => {
     const bindings = mergeBindings(fn, sourceFile);
     forEachStringLiteral(
       fn,
@@ -479,7 +489,7 @@ export function ruleRegistryIntegrity({ indexFile, indexSource, actionFiles, pro
 // `this` parameter is erased, so it takes no position.
 const CARD_PARAMS = ["callback", "cancel", "readyState"];
 
-function mentions(fn, test) {
+function mentions(fn, test, { also = [], bindings = true } = {}) {
   let found = false;
   function walk(node) {
     if (found) return;
@@ -495,6 +505,7 @@ function mentions(fn, test) {
           ts.isSetAccessorDeclaration(parent)) &&
         parent.name === node;
       const isKey = parent && ts.isBindingElement(parent) && parent.propertyName === node;
+      const isBinding = !bindings && parent && ts.isBindingElement(parent) && parent.name === node;
       let inType = false;
       for (let up = parent; up && up !== fn; up = up.parent) {
         if (ts.isTypeNode(up) && !ts.isExpressionWithTypeArguments(up)) {
@@ -502,14 +513,14 @@ function mentions(fn, test) {
           break;
         }
       }
-      if (!isName && !isKey && !inType) {
+      if (!isName && !isKey && !isBinding && !inType) {
         found = true;
         return;
       }
     }
     ts.forEachChild(node, walk);
   }
-  if (fn.body) walk(fn.body);
+  for (const root of [fn.body, ...also]) if (root) walk(root);
   return found;
 }
 
@@ -525,6 +536,44 @@ function readRender(fn) {
   return { waits, declaredUnused: !waits && names.length > 0 ? names : [] };
 }
 
+// A renderComponent takes one object, and only the keys it uses tell the two
+// kinds of card apart. What the SDK can't read (`...rest`, `arguments`, the
+// object passed on or aliased) is settled by `waitsForUser`, which defaults to
+// waiting: with no flag, a view card written that way never releases the agent.
+function readComponent(fn, members) {
+  const { locals, context, defaults, unknown: unreadable } = readComponentParam(fn);
+  let unknown = unreadable || mentions(fn, (name) => name === "arguments", { also: defaults });
+  let waits = false;
+  if (context) {
+    const walk = (node) => {
+      if (ts.isIdentifier(node) && node.text === context) {
+        const parent = node.parent;
+        const destructured =
+          ts.isVariableDeclaration(parent) && parent.initializer === node && ts.isObjectBindingPattern(parent.name);
+        if (ts.isPropertyAccessExpression(parent) && parent.expression === node) {
+          if (CARD_PARAMS.includes(parent.name.text)) waits = true;
+        } else if (!destructured && !(ts.isPropertyAccessExpression(parent) && parent.name === node)) {
+          unknown = true;
+        }
+      }
+      ts.forEachChild(node, walk);
+    };
+    if (fn.body) walk(fn.body);
+  }
+  const names = [...locals.keys()];
+  if (names.some((name) => mentions(fn, (text) => text === name, { also: defaults, bindings: false }))) waits = true;
+  if (waits) return { waits: true, declaredUnused: [] };
+  if (unknown) {
+    const flag = members.find((member) => propertyName(member) === "waitsForUser");
+    return {
+      waits: !(flag && ts.isPropertyAssignment(flag) && flag.initializer.kind === ts.SyntaxKind.FalseKeyword),
+      declaredUnused: [],
+      unsettled: !flag,
+    };
+  }
+  return { waits: false, declaredUnused: names.map((name) => locals.get(name)) };
+}
+
 // The function `render` names: inline, a method, or - for `render` and
 // `render: renderCard` - a `function` or `const` of that name in the same file.
 function declaredFunction(sourceFile, name) {
@@ -567,14 +616,19 @@ export function ruleCardContract(sourceFile, relative, findings) {
   function walk(node) {
     if (ts.isObjectLiteralExpression(node)) {
       const members = node.properties;
-      const render = members.find(
-        (member) =>
-          propertyName(member) === "render" &&
-          (ts.isPropertyAssignment(member) || ts.isMethodDeclaration(member) || ts.isShorthandPropertyAssignment(member)),
-      );
+      const named = (name) =>
+        members.find(
+          (member) =>
+            propertyName(member) === name &&
+            (ts.isPropertyAssignment(member) || ts.isMethodDeclaration(member) || ts.isShorthandPropertyAssignment(member)),
+        );
+      // If an action has both, the SDK draws renderComponent.
+      const component = named("renderComponent");
+      const render = component || named("render");
+      const drawn = component ? "renderComponent" : "render";
       const fn = render ? renderFunction(sourceFile, render) : null;
       if (fn) {
-        const { waits, declaredUnused } = readRender(fn);
+        const { waits, declaredUnused, unsettled } = component ? readComponent(fn, members) : readRender(fn);
         const flag = members.find((member) => propertyName(member) === "awaitUserInput");
         const flagTrue = flag && ts.isPropertyAssignment(flag) && flag.initializer.kind === ts.SyntaxKind.TrueKeyword;
         if (flagTrue && !waits) {
@@ -586,7 +640,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 (${drawn} 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 +654,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: ${drawn} uses none of callback, cancel or readyState, so the agent is told the card was shown, with what execute returned.`,
               fix: "Remove awaitUserInput.",
             }),
           );
@@ -614,11 +668,25 @@ export function ruleCardContract(sourceFile, relative, findings) {
               node: flag.name,
               file: relative,
               message:
-                "An input card does not need awaitUserInput: render uses callback, cancel or readyState, and that is what makes the agent wait.",
+                `An input card does not need awaitUserInput: ${drawn} uses callback, cancel or readyState, and that is what makes the agent wait.`,
               fix: 'Remove awaitUserInput. Then check that every path calls callback or cancel - choosing, "none of these", closing the card, failing. When the conversation should go on while the user decides, call readyState(value) once the card is drawn.',
             }),
           );
         }
+        if (unsettled && !flag) {
+          findings.push(
+            finding({
+              rule: "card-contract",
+              severity: "warning",
+              sourceFile,
+              node: render.name,
+              file: relative,
+              message:
+                "The SDK can't read this renderComponent (the object passed on or aliased, ...rest, arguments), so the agent waits until it calls readyState, callback or cancel. A view card that calls none of them never gets a reply, until the user presses stop.",
+              fix: "Destructure the keys in the parameter: renderComponent({ data, host, header, readyState }). A view card calls readyState once it is drawn; an input card calls callback or cancel.",
+            }),
+          );
+        }
         if (declaredUnused.length > 0) {
           const list =
             declaredUnused.length === 1
@@ -632,8 +700,8 @@ export function ruleCardContract(sourceFile, relative, findings) {
               sourceFile,
               node: render.name,
               file: relative,
-              message: `render declares ${list} but ${unused} - the SDK treats the card as a view card: the agent is told it was shown, with what execute returned.`,
-              fix: `For a view card, remove ${list} from render. For an input card, call callback or cancel on every path, or readyState(value) once the card is drawn.`,
+              message: `${drawn} declares ${list} but ${unused} - the SDK treats the card as a view card: the agent is told it was shown, with what execute returned.`,
+              fix: `For a view card, remove ${list} from ${drawn}. For an input card, call callback or cancel on every path, or readyState(value) once the card is drawn.`,
             }),
           );
         }
@@ -857,6 +925,115 @@ export function bundleTurnsOnTestMode(js) {
   return /setTestMode/.test(js.replace(/\??\.setTestMode(\?\.)?\(\s*(!1|false)\s*\)/g, ""));
 }
 
+/*
+  no-native-lookalike: an action that copies something every agent already
+  has (CLAUDE.md, "Built into every agent"). A warning, not an error: a name
+  is only a hint, and an action can have a reason the built-in doesn't cover.
+  Two signals: the action's key (agent/actions/<key>.ts or <key>/index.ts), and
+  code that reads the whole page or the microphone.
+*/
+const NATIVE_LOOKALIKE_NAMES = [
+  {
+    native: "navigation",
+    pattern: /(^|_)(navigat[a-z]*|go_to|goto|open_(page|screen|view|url)|redirect[a-z]*)(_|$)|(^|_)urls?$|(^|_)build_[a-z_]*url/,
+    use: "a navigation route for each page (create_navigation_route); the agent opens it with the built-in navigate",
+  },
+  {
+    native: "share current tab / share screen",
+    pattern: /(^|_)(current|active|visible)_(page|screen|view|tab)(_|$)|(^|_)(page|screen|view|tab)_(content|context|html|text|snapshot|state)(_|$)|(^|_)(read_page|screenshot|capture_(page|screen))(_|$)/,
+    use: "Share current tab (agent settings → Customize → Data Access & Handoff), or shareState() for the app's own state",
+  },
+  {
+    native: "knowledge search",
+    pattern: /(^|_)search_(docs|documentation|knowledge|help|articles|faq)(_|$)/,
+    use: "a knowledge source or an internal article",
+  },
+  {
+    native: "voice",
+    pattern: /(^|_)(speech|voice|dictat[a-z]*|transcri[a-z]*|text_to_speech|tts|stt)(_|$)/,
+    use: "voice chat and dictation in agent settings",
+  },
+  {
+    native: "ask_user_question",
+    pattern: /^(ask_user(_input)?|ask_question|ask_the_user|clarify[a-z_]*|choose_option[s]?)$/,
+    use: "the built-in ask_user_question (to restyle or replace it, see CLAUDE.md)",
+  },
+];
+
+const PAGE_TEXT_PROPS = new Set(["innerText", "innerHTML", "outerHTML", "textContent"]);
+const VOICE_NAMES = new Set(["getUserMedia", "SpeechRecognition", "webkitSpeechRecognition", "speechSynthesis", "SpeechSynthesisUtterance"]);
+
+export function actionKeyOf(filePath) {
+  const parts = filePath.split(/[\\/]/);
+  const i = parts.lastIndexOf("actions");
+  if (i < 0) return null;
+  const rest = parts.slice(i + 1);
+  let key = null;
+  if (rest.length === 1) key = rest[0].replace(/\.(ts|tsx|js|mjs)$/, "");
+  else if (rest.length === 2 && /^index\.(ts|tsx|js|mjs)$/.test(rest[1])) key = rest[0];
+  if (!key || key === "index") return null;
+  return key.replace(/-/g, "_").toLowerCase();
+}
+
+export function ruleNoNativeLookalike(sourceFile, relative, findings, filePath) {
+  const key = actionKeyOf(filePath || relative);
+  if (key && key !== "ask_user_question") {
+    for (const item of NATIVE_LOOKALIKE_NAMES) {
+      if (!item.pattern.test(key)) continue;
+      findings.push(
+        finding({
+          rule: "no-native-lookalike",
+          severity: "warning",
+          sourceFile,
+          node: sourceFile,
+          file: relative,
+          message: `"${key}" looks like the built-in ${item.native}, which every agent already has.`,
+          fix: `Use ${item.use}. If this action does something the built-in can't, keep it and tell the human why.`,
+        }),
+      );
+      break;
+    }
+  }
+
+  const reported = new Set();
+  const report = (node, native, use) => {
+    if (reported.has(native)) return;
+    reported.add(native);
+    findings.push(
+      finding({
+        rule: "no-native-lookalike",
+        severity: "warning",
+        sourceFile,
+        node,
+        file: relative,
+        message: native === "voice"
+          ? "Microphone or speech code: voice chat and dictation are built into every agent."
+          : "Reads the whole page's text or HTML: sharing the current tab is built into every agent.",
+        fix: `Use ${use}.`,
+      }),
+    );
+  };
+
+  function walk(node) {
+    if (ts.isPropertyAccessExpression(node)) {
+      const name = node.name.text;
+      if (PAGE_TEXT_PROPS.has(name)) {
+        const target = node.expression.getText(sourceFile).replace(/\s+/g, "");
+        if (/^(window\.)?document\.(body|documentElement)$/.test(target)) {
+          report(node, "page", NATIVE_LOOKALIKE_NAMES[1].use);
+        }
+      }
+      if (VOICE_NAMES.has(name)) report(node, "voice", NATIVE_LOOKALIKE_NAMES[3].use);
+    } else if (ts.isIdentifier(node) && VOICE_NAMES.has(node.text) && !ts.isPropertyAccessExpression(node.parent)) {
+      report(node, "voice", NATIVE_LOOKALIKE_NAMES[3].use);
+    } else if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "html2canvas") {
+      report(node, "page", NATIVE_LOOKALIKE_NAMES[1].use);
+    }
+    ts.forEachChild(node, walk);
+  }
+  walk(sourceFile);
+}
+
 export function lintActionFile(filePath, relative, findings) {
   if (shouldSkipActionFile(filePath)) return;
   const sourceFile = parseFile(filePath);
@@ -864,6 +1041,7 @@ export function lintActionFile(filePath, relative, findings) {
   ruleNoRunTaskPrompt(sourceFile, relative, findings);
   ruleNoEmoji(sourceFile, relative, findings);
   ruleCardContract(sourceFile, relative, findings);
+  ruleNoNativeLookalike(sourceFile, relative, findings, filePath);
 }
 
 export function lintViewsFile(filePath, relative, findings) {

package/src/lint/safety.mjs

@@ -13,7 +13,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { finding, forEachNamedFunction, forEachReturn, isFunctionLike, parseFile, resolveModulePath, stringText } from "./ast.mjs";
+import { finding, forEachComponentReport, forEachNamedFunction, forEachReturn, isFunctionLike, parseFile, resolveModulePath, stringText } from "./ast.mjs";
 import { ts } from "./ts.mjs";
 import { hostMatchesAny, siteOf } from "../observe-core.mjs";
 import { addressNamesLabel, customerLabel, suggestedApiBase } from "../customer-subdomain.mjs";
@@ -518,7 +518,7 @@ export function ruleTokenStaysHome(sourceFile, relative, findings, facts, scopes
     findings.push(finding({ rule: "token-stays-home", severity: "error", sourceFile, node, file: relative, message, fix }));
 
   // Returned to the agent: what execute and a card's callback return, and what
-  // render hands to callback or readyState.
+  // render or renderComponent hands to callback or readyState.
   forEachNamedFunction(sourceFile, ["execute", "callback"], (fn, name) => {
     forEachReturn(fn, (expression) => {
       if (flow.carries(expression)) {
@@ -539,6 +539,14 @@ export function ruleTokenStaysHome(sourceFile, relative, findings, facts, scopes
     };
     if (fn.body) walk(fn.body);
   });
+  forEachNamedFunction(sourceFile, ["renderComponent"], (fn) => {
+    forEachComponentReport(fn, (call, key) => {
+      if (key === "cancel") return;
+      if (call.arguments.some((arg) => flow.carries(arg))) {
+        report(call, `The card hands the user's sign-in token to ${key}, which reaches the agent and the model.`, TOKEN_FIXES.agent);
+      }
+    });
+  });
 
   const walk = (node) => {
     if (ts.isCallExpression(node)) {