@foldspace_npm/harness 0.1.14 → 0.1.15

package/CLAUDE.md

@@ -244,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/>
@@ -280,11 +289,59 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.14",
+  "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 },
       };
     }