@foldspace_npm/harness 0.1.13 → 0.1.15

package/CLAUDE.md

@@ -64,6 +64,12 @@ current CLI contract — risk, prerequisites, effects, next step.
    so and offer the next one. On an empty account the useful first action is
    one that creates data - say so instead.
 
+**Say when the test window is yours, and when it is theirs.** You and the
+human share one Chrome window. Before you start looking at the app or testing
+in it: *"I'm going to work in that Chrome window for a few minutes - please
+leave it alone until I tell you it's ready."* When it is their turn: *"It's
+ready. Try asking: <the question this experience answers>."*
+
 Navigation, uploads, extraction and anything that writes are a later session.
 
 ### Ask as a choice, and ask almost nothing
@@ -76,7 +82,7 @@ question. Everything else — attach mode, folder, name, level — you **state a
 move on**.
 
 Then agree the experience in the customer's words, before creating anything:
-*"Show my plan and credits needs one thing the agent can call and one card to
+*"Show my plan and credits needs one new action on your agent and one card to
 show it in. Sound right?"*
 
 ## Find the call yourself
@@ -111,8 +117,13 @@ an assumption by quoting that file later.
 
 ## Build: objects first, code second
 
-Four kinds of thing. Never make the customer learn these words — describe them
-by what they do.
+Four kinds of thing. With the customer, use **Foldspace's own words** for what
+they will see in Agent Studio - **action**, **task agent**, **navigation**,
+**publish** - and say what each does the first time you use it. Never invent a
+substitute: no "skill", "ability", "capability" or "tool", and no "switch on"
+for publish. "Skill" already means something else in Claude, and the customer
+has seen "Actions" at sign-up and in Agent Studio - a new word breaks the link
+to what they know. The action handler is yours: call it "the code behind it".
 
 | Thing | Answers | Lives in | You write |
 |---|---|---|---|
@@ -233,6 +244,15 @@ Do not report success without all six:
    paragraph telling the copilot what to say — those live in Agent Studio.
    Never return `ApiResult.detail` from `execute`; it is for the console.
    Validate parameters and return sanitised errors.
+   **What goes back to the agent states what happened - it never says what to
+   do next.** A status is state: it succeeded, it failed and why (`reason`),
+   or it found nothing. "Refine your query", "try again" and "ask the user for
+   the full name" are instructions, and an instruction inside a tool response
+   can make the model fire another tool call on its own. What the agent does
+   next is decided by the action's instructions in Agent Studio.
+   **A search that finds nothing is a valid result, not a failure**:
+   `success: true`, the query, zero matches - *"No <records> match
+   '<query>'."* - and it stops there.
 2. **`render` receives `execute`'s return value**, not the input params. A
    widget that lacks the ids the card needs passes in isolation and fails in the
    real chat. <https://docs.foldspace.ai/guides/in-chat-ui/>
@@ -269,6 +289,70 @@ Lint catches some of these in handler code; Agent Studio copy is on you.
 - **Never send the user out of the host app.** No "open in <product>" button,
   no pasted URLs — navigate with a route, same tab.
 
+## How the agent looks and opens is configuration
+
+Three layers: built-in defaults, then Agent Studio, then code - **and code
+wins**. <https://docs.foldspace.ai/customize/configuration/>
+
+- **Agent-wide conversation starters you can set yourself**, through the
+  Foldspace tools, and they carry over to the customer's real site. Once the
+  first action works, offer one starter that asks its question, so they can
+  click instead of type. `set_conversation_starters` **replaces the whole set
+  and clears whatever you leave out**: call `list_conversation_starters` first
+  and send back the full list with your one addition. It changes their
+  Foldspace account, so it needs their yes.
+- **Page-specific starters and the bottom bar are only possible from code
+  today** - `setConversationStarters` (`null` restores Agent Studio's), and
+  `setConfiguration({ bottomBarSettings })` then `openBottomBar()`. Send one
+  whole settings group per call, as the docs do.
+- **That code belongs where the product mounts the agent - in the customer's
+  own source.** In this project you do not have their source: you see their
+  product only through the test window. So this is their engineers' change, not
+  yours. Shipping it from this project's start-up code instead is a fallback for
+  a customer who cannot make the change, decided with Foldspace - not something
+  to reach for, and never in a first session.
+- **An action's `execute` never calls `setConfiguration`**: a partial call from
+  one once collapsed the agent's panel to nothing.
+
+If they ask for page-specific starters or the bottom bar, say what it takes in
+one sentence and note it in `docs/app-profile.md` as a next step.
+
+## 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 component that asks sets `awaitUserInput: true` - and then calling
+  `callback` is mandatory, on every path.** The agent is paused until it is
+  called: submitting, choosing "none of these" and closing the component all
+  end in `callback` (or `cancel()` when they abort), or the conversation hangs.
+  A component that only shows never sets the flag - it would hold the
+  conversation until the user clicked an acknowledgement nobody needed.
+- **What a component sends back is the tool response: the data and the user's
+  choice, as fields**, with the state - chosen, declined, failed - and nothing
+  about what to do next (**Rules**, 1).
+- **A view-only component's data does not reach the model.** For an action
+  that only shows something, the model is told just that *the information was
+  displayed to the end-user* - nothing `execute` returned, nothing the component
+  drew. So the component carries every fact, including the bad ones.
+- **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 -
+  an id or a name that has to be there. If it does not, that is `signed_out`:
+  return it as a failure (`success: false`, `reason`) and draw that state with
+  `renderFailure`. A balance of 0 shown to someone who is signed out is a wrong
+  answer reported as a success.
+- **Every path through `render` draws something.** An action that returns
+  without drawing leaves the slot spinning forever: nothing throws, the console
+  stays clean, and the action is recorded as succeeded. Only looking at it shows
+  the problem. Draw the empty or the failed state (`renderEmpty`,
+  `renderFailure`) - never nothing.
+- **Totals and money are never computed by the model.** Compute them in the
+  action's code or in the component, from the API's own numbers, and show them
+  in the component. The action's instructions tell the model not to restate or
+  recompute them: a model that adds up line items will eventually add them up
+  wrong.
+
 ## Layout
 
 - `agent/actions/` — one handler per action (`execute`, optional `render`),
@@ -337,6 +421,14 @@ export { apiFetch } from "./api";
 
 ## Safety
 
+- **A refusal is an answer.** When a command or tool call is declined - by the
+  human or by the session's own safety checks - stop. Say in one plain sentence
+  what you wanted it for, or take a narrower read-only route. Never retry it,
+  and never try a different command hoping it gets through.
+- **Never create an account or a key** - not in Foldspace, not in the
+  customer's product, not anywhere. If one is missing, say which and where it
+  goes. **Never widen your own access**: if something is refused for a site or
+  a permission, say so and ask; do not try others.
 - Do not commit secrets, cookies, HAR files, browser storage, or
   `.foldspace-dev/`. Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.

package/package.json

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

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

@@ -18,7 +18,7 @@ parameter `name` — *the name, or part of the name, the user said*.
 | no name ("how many projects do I have?") | the account's **count**, plus a small sample — never the whole account |
 | one clear match | that project, its match strength, and up to three alternatives |
 | several equally good matches | **all of them**, marked `ambiguous` — never a silent pick |
-| nothing matches | `success: false`, plus near-misses for a typo |
+| nothing matches | `success: true` with zero `matches` - an empty search is a valid result, not a failure - plus near-misses for a typo, as data. Never "refine your query" |
 | the account is empty | a count of zero — not an error |
 | signed out, no access, throttled, unreachable | `success: false` with the `reason` |
 

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

@@ -48,15 +48,17 @@ export const find_project_id = {
 
     if (summaries.length === 0) {
       // Server search is a substring of the name, so a typo finds nothing.
-      // Near-misses give the agent something true to work with — but they are
+      // An empty search is a VALID result, not a failure: say that nothing
+      // matched and stop. Never "refine your query" or "try again" - an
+      // instruction in a tool response can make the model call a tool again on
+      // its own. Near-misses are facts, so they go back as data - but they are
       // near-misses, not a resolution.
       const wide = await listProjects({ pageSize: SHORTLIST });
       const near = wide.ok ? nearMatches(wide.data.projects.map(toSummary), query, 5) : [];
       return {
-        success: false,
-        error: `No project matching "${query}".`,
-        reason: "not_found" as const,
-        data: { query, total: res.data.total, nearMatches: near },
+        success: true,
+        message: `No projects match "${query}".`,
+        data: { query, total: res.data.total, matches: [], nearMatches: near },
       };
     }