@foldspace_npm/harness 0.1.15 → 0.1.17

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
@@ -64,11 +71,15 @@ 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>."*
+**Say when the test window is yours, and when it is theirs - on the page and
+in chat.** You and the human share one Chrome window. Before you start looking
+at the app or testing in it, run `npx foldspace badge working` (a bar across
+the top of the window says Foldspace is building here, leave it alone) and say
+so in chat: *"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,
+`npx foldspace badge ready --text "Try asking: <the question this experience
+answers>"` and the same line in chat. `foldspace badge label` puts the small
+corner tag back; `off` removes it, for a screenshot they will share.
 
 Navigation, uploads, extraction and anything that writes are a later session.
 
@@ -92,15 +103,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.
@@ -180,11 +211,17 @@ with how you established each.
 | Navigation route | **yes** | `isActive: true` |
 
 Publishing a **new** object is inert; publishing an **edit to a live one** is
-the deploy above. Navigation has **no publish tool on the MCP** and
-`get_navigation_route` returns only `isActive` — publish routes in Agent Studio
-and say so. Route descriptions are a retrieval surface: write what the page is
-*for*, in the user's words, and pair every parameterised route with the lookup
-action that produces its parameter — or ship neither.
+the deploy above. **Navigation has two switches, and both must be on.** Each
+route has its own `isActive`, set when you create it (`create_navigation_route`
+/ `bulk_create_navigation_routes`, `isActive: true`). The agent has one
+agent-level switch, **off by default on a new subscription**: `publish_navigation`
+turns it on, `unpublish_navigation` off, and neither touches the routes' own
+`isActive`. `list_navigation_routes` shows both. There is no MCP tool to flip a
+single route's `isActive` after creation (it was disabled until Agent Studio
+can reverse it) - create it right, or `update_navigation_route`, which replaces
+the whole route. Route descriptions are a retrieval surface: write what the
+page is *for*, in the user's words, and pair every parameterised route with the
+lookup action that produces its parameter — or ship neither.
 
 **Ask before publishing.** It is required only so the copilot can call the
 action, and it is a live product change when the agent has real users.
@@ -198,9 +235,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,14 +248,32 @@ 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
 execute/render lines. Those record names, statuses, durations and parameter keys
 only — never results or error bodies.
 
+## Done, and what you say at the end
+
+A first session is done when the customer has seen one experience answer from
+their own data, in the test window, and been invited to try it. Not when the
+gates pass, and not when there is nothing left to improve.
+
+If they ask *"how do I put this in front of my users?"*, the honest answer is:
+
+> What you've seen runs in a test window on your machine. Putting it in front
+> of your users is a separate step, and the Foldspace team does it with you.
+> Reach them through the website - <https://foldspace.ai/demo> - or at
+> <support@foldspace.ai>. Everything built today carries over: the actions are
+> already in your Foldspace account, and the code is in this folder.
+
+Never run `foldspace deploy`, never install cloud tooling, never ask them for
+cloud credentials: `deploy` is Foldspace-internal and no customer can run it.
+
 ## Verification gates
 
 Do not report success without all six:
@@ -261,14 +315,17 @@ Do not report success without all six:
    MCP (`search_docs`, `fetch_page`) before asserting how the platform behaves;
    cite the page, or say plainly that the docs do not cover it and write down
    what you learned.
-4. **Do not send chat messages to test.** Every message is a real conversation
-   in the customer's list. `runTask` creates no conversation record — use it.
-5. **Test mode is off by default.** A new agent has no traffic to pollute, and
-   watching real conversations appear is the point of the first run. Arm it
-   only when the tenant already has real conversations — and then on **every**
-   instance via `armAllInstances`, because `foldspace.agent({apiName})` returns
-   the overlay handle, which is not the one serving an embedded chat. Nothing
-   can confirm it is on afterwards; never send probe messages to find out.
+4. **Test through the agent, then let them.** In a first session, talk to the
+   agent yourself to prove an experience - type the real question into its
+   panel in the test window and read the reply - and only then invite the
+   customer to try it. Those conversations appear in their Foldspace dashboard,
+   and that is wanted: seeing their own conversations recorded is part of what
+   they came to see. Never pass `--test-mode` in a first session.
+5. **Test mode is for an agent that already has real users.** Then `attach
+   --test-mode` keeps your conversations out of their data. It is not a safety
+   net: publishing still changes the live agent. Working on an agent in
+   production - test mode, pinned action versions, what may be published - is
+   a separate playbook, not this one.
 6. **The human is not necessarily a developer.** Never hand over a terminal
    line, a stack trace, or a choice between flags. Name experiences by outcome
    — *"show my plan and credits"*, not `get_account_status`. Their two jobs:

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
 
@@ -252,7 +252,7 @@ and **neither had all five**:
 | SDK load guard + retry | On an app with no `document.body` at document-start the append throws; the old guard tested for the stub, so nothing retried and the agent silently never loaded |
 | Worker release on auto-attach | Auto-attach pauses every worker until the attaching client releases it — the harness froze the app's own workers for the whole session |
 | `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded copilot leaves real conversations untagged |
-| `--no-test-mode` | Test mode was armed unconditionally, hiding exactly what initial setup needs to see |
+| `--test-mode` (off by default) | Test mode was armed unconditionally, hiding exactly what initial setup needs to see; now it is opt-in |
 | Honest badge | It asserted `TEST MODE` whether or not test mode was on |
 
 Two further changes came from packaging it: the bundle is **injected** rather

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,
@@ -134,11 +135,13 @@ try {
 }
 const bootstrap = attachMode === ATTACH_MODES.BOOTSTRAP;
 const replace = attachMode === ATTACH_MODES.REPLACE;
-// Test mode keeps conversations out of the customer's default list. Turn it off
-// only when you WANT the conversations and action calls to show up in the
-// Foldspace dashboard — a brand-new agent during initial setup, where there is
-// no production traffic to pollute.
-const noTestMode = process.argv.includes("--no-test-mode");
+// Test mode keeps conversations out of the customer's default list. It is OFF
+// by default: in a first session the customer's own conversations appearing in
+// their dashboard is the point - they see what Foldspace records - and an
+// orange TEST MODE label would imply a safety (nothing published) that does
+// not exist. --test-mode opts in, for an agent that already has real users.
+// --no-test-mode is still accepted so older instructions keep working.
+const noTestMode = !process.argv.includes("--test-mode");
 // The badge used to hardcode "TEST MODE" whether or not test mode was on — a
 // string that asserts you are safe while you are not. It now states what is
 // actually true. --no-badge drops it entirely, for recording a demo.
@@ -170,8 +173,8 @@ const agentKey = cfgTarget.overrideKey || `EU-${productId}-1-1`;
 const sdkUrl = cfgTarget.sdkUrl || cfg.sdkUrl;
 const actionTarget = { productId, agentApiName };
 const badgeText = noTestMode
-  ? `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 LIVE`
-  : `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 TEST MODE`;
+  ? `FOLDSPACE AGENT BUILDER \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 LIVE`
+  : `FOLDSPACE AGENT BUILDER \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 TEST MODE`;
 
 // Refuse to run against an uninitialised template. Without this, attach injects
 // the literal placeholder as an agent api name and the page fails with an opaque
@@ -217,19 +220,45 @@ const SDK_PATTERNS = [
   "*://*/*eucera.js*",
 ];
 
+// The badge has three states, set from outside with \`foldspace badge\`:
+//   label   - the small corner tag (default): who is attached, which mode
+//   working - a bar across the top: the agent is building in this window,
+//             please leave it alone
+//   ready   - a bar: it is the human's turn, with the question to try
+// The state lives in sessionStorage so it survives navigation inside the
+// test window; \`foldspace badge\` writes it and the script redraws.
 const badgeSrc = `(() => {
   if (window.top !== window.self) return;
-  const add = () => {
-    if (document.getElementById("foldspace-dev-badge") || !document.body) return;
-    const b = document.createElement("div");
-    b.id = "foldspace-dev-badge";
-    b.textContent = ${JSON.stringify(badgeText)};
-    b.style.cssText = "position:fixed;top:0;left:0;z-index:2147483647;background:#3247F2;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;padding:5px 10px;border-bottom-right-radius:4px;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35)";
-    document.body.appendChild(b);
+  const LABEL = ${JSON.stringify(badgeText)};
+  const KEY = "__foldspace_badge__";
+  const read = () => {
+    try { return JSON.parse(sessionStorage.getItem(KEY) || "null") || { state: "label" }; }
+    catch (e) { return { state: "label" }; }
   };
-  add();
-  document.addEventListener("DOMContentLoaded", add);
-  setInterval(add, 2000);
+  const draw = () => {
+    if (!document.body) return;
+    const s = read();
+    if (s.state === "off") { document.getElementById("foldspace-dev-badge")?.remove(); return; }
+    let b = document.getElementById("foldspace-dev-badge");
+    if (!b) { b = document.createElement("div"); b.id = "foldspace-dev-badge"; document.body.appendChild(b); }
+    const want = s.state + "|" + (s.text || "");
+    if (b.dataset.fsState === want) return;
+    b.dataset.fsState = want;
+    const base = "position:fixed;top:0;left:0;z-index:2147483647;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35);";
+    if (s.state === "working") {
+      b.style.cssText = base + "right:0;background:#3247F2;padding:9px 14px;font-size:12px;letter-spacing:.04em;text-align:center;";
+      b.textContent = s.text || "Foldspace is building your agent on this page. Please leave this window alone until Claude says it is ready.";
+    } else if (s.state === "ready") {
+      b.style.cssText = base + "right:0;background:#0F9D58;padding:9px 14px;font-size:12px;letter-spacing:.04em;text-align:center;";
+      b.textContent = s.text || "Ready - your turn. Open your agent and try it.";
+    } else {
+      b.style.cssText = base + "background:#3247F2;padding:5px 10px;border-bottom-right-radius:4px;";
+      b.textContent = LABEL;
+    }
+  };
+  draw();
+  document.addEventListener("DOMContentLoaded", draw);
+  setInterval(draw, 1000);
 })();`;
 
 // Flag every local session as test traffic so it is excluded from analytics and
@@ -699,6 +728,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",
@@ -948,11 +979,11 @@ const ver = await connect(owned.version);
 console.log(`Attached to ${ver.Browser} on :${port}`);
 console.log(`Mode:  ${attachMode}`);
 console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
-console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the dashboard" : "on"}`);
+console.log(`Test:  ${noTestMode ? "off — conversations appear in the dashboard (pass --test-mode to hide them)" : "on"}`);
 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/badge.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * foldspace badge <working|ready|label|off> [--text "<what to show>"]
+ *
+ * Sets the banner the attach badge draws across the top of the test window.
+ * The agent and the human share that one Chrome window, so the banner says
+ * whose turn it is:
+ *   working - "Foldspace is building your agent on this page. Please leave
+ *             this window alone until Claude says it is ready."
+ *   ready   - "Ready - your turn. Open your agent and try it." (pass --text
+ *             with the question to try)
+ *   label   - back to the small corner tag
+ *   off     - remove it
+ * The state is kept in the page's sessionStorage, so it survives navigation;
+ * attach's badge script redraws within a second. Nothing else on the page is
+ * touched.
+ */
+import { CdpPage, parseArgs, printJson } from "../src/cdp-client.mjs";
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import { badgePayload } from "../src/badge-core.mjs";
+
+const projectDir = resolveProjectDir();
+const { flags, rest } = parseArgs(process.argv.slice(2), ["text"]);
+
+let payload;
+try {
+  const unknown = Object.keys(flags).filter((name) => name !== "text");
+  if (unknown.length) throw new Error(`unknown option '--${unknown[0]}'`);
+  if (rest.length > 1) throw new Error(`unexpected argument '${rest[1]}'`);
+  payload = badgePayload(rest[0], flags.text);
+} catch (error) {
+  console.error(`badge: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
+let page;
+try {
+  page = await CdpPage.open({ projectDir });
+  const shown = await page.evaluate(
+    `sessionStorage.setItem("__foldspace_badge__", ${JSON.stringify(JSON.stringify(payload))});
+     const b = document.getElementById("foldspace-dev-badge");
+     return { url: location.href.split(/[?#]/)[0], hadBadge: Boolean(b) };`,
+  );
+  printJson({ ok: true, state: payload.state, ...(payload.text ? { text: payload.text } : {}), ...shown });
+} catch (error) {
+  printJson({ ok: false, error: error instanceof Error ? error.message : String(error) });
+  process.exit(1);
+} finally {
+  page?.close();
+}

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";
@@ -143,7 +144,7 @@ fs.writeFileSync(
   path.join(themeDir, "manifest.json"),
   JSON.stringify({
     manifest_version: 3,
-    name: "Foldspace Dev Theme",
+    name: "Foldspace Agent Builder Theme",
     version: "1.0",
     description: "Paints the dev browser Foldspace blue.",
     theme: {
@@ -196,7 +197,7 @@ function nameProfile() {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(data));
   };
-  const label = `Foldspace Dev \u2014 ${target.name}`;
+  const label = `Foldspace Agent Builder \u2014 ${target.name}`;
   writeMerged(path.join(profileDir, "Local State"), (d) => {
     d.profile = d.profile || {};
     d.profile.info_cache = d.profile.info_cache || {};
@@ -279,6 +280,8 @@ fs.writeFileSync(
   ),
 );
 
+recordEvent(root, "chrome_opened", { url: startUrl });
+
 // --- theme -------------------------------------------------------------
 //
 // Chrome 151 ignores --load-extension, so load the optional cosmetic theme