@foldspace_npm/harness 0.1.14 → 0.1.16

package/CLAUDE.md

@@ -44,16 +44,23 @@ current CLI contract — risk, prerequisites, effects, next step.
 | **L2 · look up entities** | a search from the user's own words, showing rows |
 
 1. **Get the agent live first (L0) - with no actions.** Straight after
-   orienting: `npm run build`, `npm run inject`, the human signs in to their
-   app, then `npx foldspace attach --daemon`. An empty registry is valid. L0
-   is `registration_ok` with the agent visible on their page - tell them to
-   look at it and say hello to it. **Do not explore the app first**: no
+   orienting: `npm run build`, `npm run inject`, and one ask - *"A Chrome
+   window opened at <Product>'s login. Please log in there - I'll notice when
+   you're in."* Then `npx foldspace observe wait-login`: it returns the moment
+   they are in, so nobody has to type "I've logged in". Then
+   `npx foldspace attach --daemon`. An empty registry is valid. L0 is
+   `registration_ok` with the agent visible on their page: take
+   `npx foldspace observe screenshot`, send them the image, and tell them to
+   look at it and say hello to it. **From here on the agent stays on their
+   page** - you never detach to look at the app.
+   **Do not explore the app first**: no
    reading its bundle, no watching its traffic, no browsing its screens.
    Nothing about L0 needs any of it, and minutes of silent investigation
    before the human has seen anything is the wrong first impression.
 2. **Then offer experiences - from what you already have.** With the agent on
    their screen, offer three or four read-only experiences as a choice,
-   recommended first. Sources: the conversation starters seeded at sign-up,
+   recommended first. Sources: the product's own menu (`npx foldspace observe
+   menu` takes a second and moves nothing), the conversation starters seeded at sign-up,
    `discover_actions`, and `docs/app-profile.md`. `discover_actions` gives
    candidates, not an inventory. Do not investigate the app to build this
    list. Order them cheapest first: the user's own data with no parameter
@@ -92,15 +99,35 @@ and asking are not the only options — **observing is, and it comes first**:
 
 1. **Already known** — `docs/app-profile.md`. A verified endpoint needs no
    browsing.
-2. **You drive - once they have chosen an experience.** The agent is already
-   attached from L0, and `attach` owns the debug port: `npx foldspace attach
-   --stop` first. Then *you* go to the one screen that experience needs: read
-   the app's bundle for API paths and watch the requests it makes
-   (chrome-devtools MCP against the inject Chrome, or a page-context
-   `fetch`). Attach again when you have the call. Read the auth method off a request
-   the page already sent — bearer from `localStorage`, cookie, custom header.
-   Delegate the watching to a read-only subagent so the traffic does not flood
-   your context.
+2. **You look - once they have chosen an experience - with `foldspace
+   observe`.** It reads the test window they signed in to, it is read-only by
+   construction, and it works **while the agent stays attached**: do not
+   `attach --stop` to look. Write no browser-driving script of your own, and do
+   not reach for a separate DevTools server - one launched on its own opens a
+   different, signed-out Chrome and can never see the window they logged in to.
+
+   ```bash
+   npx foldspace observe menu                      # the product's own screens, by label and path
+   npx foldspace observe screen --click "<a label from menu>" --match "<three to five words for the data>"
+   npx foldspace observe read "<the GET path screen returned>"   # GET only: status, field names and types, row count
+   npx foldspace observe auth                      # only if a read came back 401 or 403
+   npx foldspace observe styles                    # their font and colours, for the card
+   ```
+
+   `screen` reaches a screen the way a person does and returns at most eight
+   requests, ranked by your words - field names, value types and row counts,
+   **never values**. `read` confirms the one you picked. `auth` reports *where*
+   each header value comes from, never the value: do not go hunting through
+   storage, cookies or bundles yourself. One experience needs one screen; two
+   `screen` calls is normal, five means the experience is wrong for this
+   product - offer the next one.
+
+   **`observe` refuses what is not provably looking**, and a refusal is an
+   answer (**Safety**): it follows links, tabs and menu openers only - a plain
+   button can do anything, so use `--goto <path>` from `menu` instead; it will
+   not open a path that does something (`/logout`, `/…/delete`); and `read`
+   only goes to the app's own origin, a host configured for this project, or
+   an origin `screen` saw the page call.
 3. **Ask the human to perform the workflow** — only for what you cannot reach:
    an MFA step, a paywall, a screen that needs a record the account does not
    have, or anything that would write.
@@ -198,9 +225,8 @@ npx foldspace attach --daemon
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port; it
-loads nothing. In a first session `attach` comes straight after sign-in (L0);
-to observe afterwards, `attach --stop`, use chrome-devtools MCP against the
-same Chrome, then attach again. `attach` prepares the page and loads the local
+loads nothing. In a first session `attach` comes straight after sign-in (L0),
+and `foldspace observe` reads the same window while it runs. `attach` prepares the page and loads the local
 `dist/index.js` over CDP. Coding agents use `--daemon` so the tool returns after
 `[lifecycle] inspect_registration:…`. An empty local registry is valid; `npm run
 build` is still required so `dist/index.js` exists.
@@ -212,8 +238,9 @@ SDK without the configured agent.
 
 `inspect_registration:registration_ok` is the signal. On `registration_mismatch`
 read `npx foldspace help attach --json` and map `missingActionNames`,
-`unexpectedActionNames`, `diagnosticError`. While attach runs it owns the debug
-port — `attach --stop` before using chrome-devtools MCP again.
+`unexpectedActionNames`, `diagnosticError`. A running attach keeps the actions
+it loaded: after a rebuild, `attach --stop` and attach again to load the new
+ones. That is the only reason to stop it.
 
 Prove a named action through the visible agent: after the human talks to the
 copilot, read the daemon log for `[actions]` SDK callback and local
@@ -244,6 +271,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 +316,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/README.md

@@ -190,8 +190,8 @@ Use `foldspace help attach` for mode requirements, effects, and safety options.
 Coding agents should run `foldspace attach --daemon` so the invoking tool
 returns after `[lifecycle] inspect_registration:…`. Foreground attach remains
 the default for humans watching the terminal. `attach --status` and
-`attach --stop` inspect and tear down a daemon. Observe customer-app network
-traffic after `inject` and before attach; attach owns the debug port.
+`attach --stop` inspect and tear down a daemon. Look at the customer's app with
+`foldspace observe`: it reads the same window, read-only, while attach runs.
 
 ### Verify actions through the agent
 

package/bin/attach.mjs

@@ -43,6 +43,7 @@ import {
   shouldFulfillActionRequest,
 } from "../src/attach-preflight.mjs";
 import { serializeDiagnostic } from "../src/diagnostics.mjs";
+import { recordEvent } from "../src/session-events.mjs";
 import {
   ERROR_CODES,
   createLifecycleResult,
@@ -699,6 +700,8 @@ async function prepare(ws, sessionId, url) {
 
     {
       const verification = await verifyPreparedPage(ws, sessionId);
+      // For scoring a session: the moment the customer could first see their agent.
+      if (verification.ok) recordEvent(root, "agent_visible", { mode: attachMode });
       logLifecycle(
         createLifecycleResult({
           operation: "inspect_registration",
@@ -952,7 +955,7 @@ console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the das
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
 console.log(`Serving: ${path.relative(root, bundlePath)}`);
 console.log(
-  `CDP: this process owns the debug port. Detach before using chrome-devtools MCP against the same Chrome.\n`,
+  `CDP: attached. \`foldspace observe\` reads this same window while attach runs; stop attach only to load rebuilt actions.\n`,
 );
 
 function printSessionSummary() {

package/bin/inject.mjs

@@ -11,6 +11,7 @@
  *   npm run inject -- --url https://app.other.com --product ABC123 --agent other-agent
  *   npm run inject -- --print                       # resolve target only, don't launch
  */
+import { recordEvent } from "../src/session-events.mjs";
 import fs from "fs";
 import path from "path";
 import os from "os";
@@ -279,6 +280,8 @@ fs.writeFileSync(
   ),
 );
 
+recordEvent(root, "chrome_opened", { url: startUrl });
+
 // --- theme -------------------------------------------------------------
 //
 // Chrome 151 ignores --load-extension, so load the optional cosmetic theme