@foldspace_npm/harness 0.1.15 → 0.1.17

package/package.json

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

package/recipes/INDEX.md

@@ -7,6 +7,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`who-is-the-user`](who-is-the-user/) | **L0** | Foldspace knows who is signed in — id, email, name, role, subscription — so conversations and analytics are not anonymous | Runs once at start-up. No action, no card | 4 production builds |
 | [`find-by-name`](find-by-name/) | **L2** | The agent turns a name the user said into the id the next action needs; a count when no name is given; every tie when the name is ambiguous; near-misses when nothing matches | A data action. **No card** | 3 production builds |
 | [`pick-from-a-list`](pick-from-a-list/) | **L2** | A clickable list, shown **only** when the user has to choose — with "none of these" and cancel | An action with a card that waits for the user | 1 production build |
+| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page whose starters change with the screen the user is on — configured from code, the way customers do it | Page set-up, runs once at start-up | 2 |
 | [`swap-the-login-method`](swap-the-login-method/) | any | `apiFetch` for an app that authenticates with a custom header, or with cookies, instead of a bearer token | A replacement `agent/utils.ts` | 2 production builds (3 builds, 3 different schemes) |
 
 **Not here yet — no production build proves it:** the user's own plan or

package/recipes/bottom-bar/README.md

@@ -0,0 +1,43 @@
+# Bottom bar with page starters — L0
+
+The bottom bar is the agent's resting entry point: a bar at the foot of the
+page that shows a few starters and opens the agent when one is clicked. Its
+starters change with the screen the user is on, so an agent with two actions
+still looks useful everywhere.
+
+It is configured **from code** — Agent Studio has no UI for it today, and this
+is how customers set it. **Proven by 2 production builds** (one in the
+product's own source, one from the agent project behind a feature flag).
+
+## Adapt it
+
+| In `agent/bottomBar.ts` | Change |
+|---|---|
+| `PAGE_STARTERS` | This product's screens (path prefixes) and, for each, two or three questions **its actions can answer**. A starter for something the agent cannot do is worse than none |
+| `DEFAULT_STARTERS` | What to show on any other page |
+| `BOTTOM_BAR_SETTINGS` | Leave as the docs' defaults unless the product asks |
+
+Then call it from the bundle's entry point:
+
+```ts
+// agent/actions/index.ts — last line
+import { installBottomBar } from "../bottomBar";
+installBottomBar();
+```
+
+## What those builds learned
+
+- **`setConversationStarters` replaces the whole set for the page** — both
+  groups. `null` restores Agent Studio's. So always pass the full list you
+  want shown.
+- **In embedded mode the bar needs `openEmbeddedCallback`**, or nothing opens
+  when a starter is clicked. This recipe is for the overlay agent; see the
+  docs for embedded.
+- **Route changes in a single-page app don't reload**, so the starters must be
+  re-applied on navigation — this recipe wraps `pushState` / `replaceState`
+  and listens to `popstate`.
+- **Dark mode**: the SDK's default colours are being fixed (PLG-5891). Until
+  then a product in dark mode may need `theme` / `darkModeSettings` set.
+
+Docs: [Bottom Bar](https://docs.foldspace.ai/customize/bottom-bar/) ·
+[Conversation starters](https://docs.foldspace.ai/customize/conversation-starters/)

package/recipes/bottom-bar/agent/bottomBar.ts

@@ -0,0 +1,94 @@
+// The bottom bar: the agent's resting entry point at the foot of the page,
+// cycling starters that fit the screen the user is on. Configured from code -
+// Agent Studio has no UI for it today, and this is how customers set it.
+// https://docs.foldspace.ai/customize/bottom-bar/
+// https://docs.foldspace.ai/customize/conversation-starters/
+//
+// Product-neutral: the paths and starters below are placeholders. Replace them
+// with this product's own screens and with questions its actions can answer.
+
+import { getAgent } from "./utils";
+
+/** Starters per screen. Paths are matched as prefixes, first match wins. */
+export const PAGE_STARTERS: Array<{ match: RegExp; starters: string[] }> = [
+  { match: /^\/dashboard/, starters: ["<A question about what this screen shows>", "<Another one>"] },
+  { match: /^\/<records>/, starters: ["Find <a record> by name", "Show me <a record>'s details"] },
+];
+
+/** Shown on any page not listed above. */
+export const DEFAULT_STARTERS: string[] = ["What can you do?", "Show my account"];
+
+// The docs' own settings, unchanged. Change nothing here unless the product
+// asks for it: every field is documented on the Bottom Bar page.
+export const BOTTOM_BAR_SETTINGS = {
+  enabled: true,
+  maxVisibleStarters: 3,
+  reopenFrequency: "EVERY_LOAD",
+  starterClickBehavior: "OPEN_AGENT",
+  idleTimeoutMs: 5000,
+  initialBehaviorMode: "FULL",
+} as const;
+
+export function startersForPath(pathname: string): string[] {
+  const hit = PAGE_STARTERS.find((entry) => entry.match.test(pathname));
+  return hit ? hit.starters : DEFAULT_STARTERS;
+}
+
+// On window, not in module scope: a bundle evaluated twice on one page must
+// not install two route listeners.
+const INSTALLED_FLAG = "__foldspace_bottom_bar__";
+
+/**
+ * Turn the bar on and keep its starters matched to the page. Call once from
+ * the bundle's entry point; safe to call again.
+ *
+ * `setConversationStarters` REPLACES the whole set for this page view (both
+ * groups); passing `null` restores what Agent Studio has. Starters go in the
+ * KNOWLEDGE group so the bar shows them as plain questions.
+ */
+export function installBottomBar(): void {
+  const foldspace = (window as any).foldspace;
+  if (typeof foldspace !== "function") return;
+  if ((window as any)[INSTALLED_FLAG]) return;
+  (window as any)[INSTALLED_FLAG] = true;
+
+  foldspace("when", "ready", () => {
+    const agent = getAgent();
+    if (!agent) return;
+    let current: string[] = [];
+
+    const apply = () => {
+      const next = startersForPath(window.location.pathname);
+      if (next === current) return;
+      current = next;
+      agent.setConversationStarters?.(
+        { KNOWLEDGE: next.map((title) => ({ title })), ACTION: [] },
+        "KNOWLEDGE",
+      );
+    };
+
+    // One whole settings group per call, as the docs do.
+    agent.setConfiguration?.({ bottomBarSettings: BOTTOM_BAR_SETTINGS });
+    apply();
+
+    // Single-page apps change the URL without a load: re-apply on navigation
+    // and bring the bar back so the new starters are seen.
+    const onRouteChange = () => {
+      apply();
+      agent.openBottomBar?.({ mode: "FULL" });
+    };
+    window.addEventListener("popstate", onRouteChange);
+    const history = window.history as any;
+    for (const method of ["pushState", "replaceState"] as const) {
+      const original = history[method];
+      if (typeof original !== "function" || original.__foldspaceWrapped) continue;
+      const wrapped = function (this: any, ...args: unknown[]) {
+        const result = original.apply(this, args);
+        onRouteChange();
+        return result;
+      };
+      (wrapped as any).__foldspaceWrapped = true;
+      history[method] = wrapped;
+    }
+  });
+}

package/recipes/bottom-bar/fixtures/configuration.sent.json

@@ -0,0 +1,17 @@
+{
+  "note": "This recipe makes no network calls. What it sends to the SDK on /dashboard:",
+  "setConfiguration": {
+    "bottomBarSettings": {
+      "enabled": true,
+      "maxVisibleStarters": 3,
+      "reopenFrequency": "EVERY_LOAD",
+      "starterClickBehavior": "OPEN_AGENT",
+      "idleTimeoutMs": 5000,
+      "initialBehaviorMode": "FULL"
+    }
+  },
+  "setConversationStarters": {
+    "starters": { "KNOWLEDGE": [{ "title": "<A question about what this screen shows>" }, { "title": "<Another one>" }], "ACTION": [] },
+    "defaultStarterType": "KNOWLEDGE"
+  }
+}

package/recipes/bottom-bar/recipe.json

@@ -0,0 +1,9 @@
+{
+  "title": "Bottom bar with page starters",
+  "level": "L0",
+  "family": "entry-point",
+  "kind": "page-setup",
+  "entry": "agent/bottomBar.ts",
+  "outcome": "The agent's resting entry point is a bar at the bottom of the page whose starters change with the page the user is on",
+  "provenBy": 2
+}

package/src/badge-core.mjs

@@ -0,0 +1,22 @@
+// Pure logic behind `foldspace badge`, unit-tested.
+
+export const BADGE_STATES = ["working", "ready", "label", "off"];
+
+/** What gets written into the page for a badge state, or throws on bad input. */
+export function badgePayload(state, text) {
+  const wanted = String(state || "").trim().toLowerCase();
+  if (!BADGE_STATES.includes(wanted)) {
+    throw new Error(`usage: foldspace badge <${BADGE_STATES.join("|")}> [--text "<what to show>"]`);
+  }
+  const payload = { state: wanted };
+  if (text !== undefined) {
+    if (wanted !== "working" && wanted !== "ready") {
+      throw new Error(`--text only applies to working or ready (got ${wanted}).`);
+    }
+    const clean = String(text).replace(/\s+/g, " ").trim();
+    if (!clean) throw new Error("--text is empty.");
+    if (clean.length > 160) throw new Error("--text is longer than 160 characters; keep it to one line.");
+    payload.text = clean;
+  }
+  return payload;
+}

package/src/cdp-client.mjs

@@ -0,0 +1,233 @@
+// A small CDP page client for the read-only verbs (`observe`, `ask`, `run`).
+//
+// It is a second client on the inject Chrome and is safe to use while
+// `foldspace attach` is running: attach's claim on the debug port is about
+// request interception (`Fetch.enable`) and navigation, and nothing here
+// enables Fetch. `Runtime.evaluate`, `Network.enable` and
+// `Page.captureScreenshot` from a second client do not disturb it.
+//
+// Uses the global WebSocket, as bin/attach.mjs does.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { assertOwnedCdp, chromeProfileDir, ownershipErrorMessage } from "./cdp-ownership.mjs";
+import { resolveProjectDir } from "./upgrade.mjs";
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Where inject recorded the Chrome it launched. Never guess a port. */
+export function readLaunchState(projectDir = resolveProjectDir()) {
+  const statePath = path.join(projectDir, ".foldspace-dev", "state.json");
+  if (!fs.existsSync(statePath)) {
+    throw new Error(
+      "No .foldspace-dev/state.json here. Run `npm run inject` first, from the project folder.",
+    );
+  }
+  const state = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  const port = process.env.CDP_PORT || state.debugPort;
+  if (!port) throw new Error("state.json has no debugPort. Run `npm run inject` again.");
+  const hosts = state.resolvedTarget?.hosts || [];
+  return {
+    projectDir,
+    port: String(port),
+    hosts,
+    target: state.resolvedTarget || {},
+    sentinel: state.sentinel,
+    profileDir: chromeProfileDir(projectDir),
+  };
+}
+
+async function listTargets(port) {
+  let response;
+  try {
+    response = await fetch(`http://127.0.0.1:${port}/json/list`);
+  } catch {
+    throw new Error(
+      `The inject Chrome is not answering on :${port}. It was closed; run \`npm run inject\` again.`,
+    );
+  }
+  return response.json();
+}
+
+function hostMatches(url, hosts) {
+  try {
+    const host = new URL(url).hostname;
+    return hosts.some((pattern) => {
+      const bare = String(pattern).replace(/^\*\./, "");
+      return host === bare || host.endsWith(`.${bare}`);
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The human's tab: the page on the product's host. When the project names its
+ * hosts and no tab is on one of them, that is an error, never "the first tab":
+ * these commands reload, click and read with a session attached, and the first
+ * tab may be anything the human opened.
+ */
+export function choosePage(pages, hosts = []) {
+  const real = pages.filter(
+    (target) => target.type === "page" && !String(target.url).startsWith("devtools://"),
+  );
+  if (!real.length) throw new Error("The test window has no open page.");
+  const match = real.find((page) => hostMatches(page.url, hosts));
+  if (match) return match;
+  if (hosts.length) {
+    throw new Error(
+      `The test window has no tab on ${hosts.join(", ")}. Open the product there (or finish signing in), then try again.`,
+    );
+  }
+  return real[0];
+}
+
+export async function pickPage(port, hosts = []) {
+  return choosePage(await listTargets(port), hosts);
+}
+
+// One check per process: it opens a browser-level session.
+let ownershipVerified = false;
+
+/**
+ * Prove the Chrome on this port is the one `inject` launched for THIS project -
+ * same check as `attach`. A stale port, or CDP_PORT pointing elsewhere, would
+ * otherwise have these commands reload and click in someone else's browser.
+ */
+export async function assertTestWindow(state, verify = assertOwnedCdp) {
+  if (ownershipVerified) return;
+  const owned = await verify({ profileDir: state.profileDir, port: state.port, token: state.sentinel });
+  if (!owned.ok) {
+    throw new Error(
+      ownershipErrorMessage(owned.reason, {
+        port: state.port,
+        profileDir: state.profileDir,
+        root: state.projectDir,
+      }),
+    );
+  }
+  ownershipVerified = true;
+}
+
+export class CdpPage {
+  #socket;
+  #nextId = 0;
+  #pending = new Map();
+  #listeners = new Map();
+
+  constructor(socket, info) {
+    this.#socket = socket;
+    this.info = info;
+    socket.addEventListener("message", (event) => this.#dispatch(JSON.parse(event.data)));
+  }
+
+  static async open({ projectDir } = {}) {
+    const state = readLaunchState(projectDir);
+    await assertTestWindow(state);
+    const page = await pickPage(state.port, state.hosts);
+    const socket = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((resolve, reject) => {
+      socket.addEventListener("open", resolve, { once: true });
+      socket.addEventListener("error", () => reject(new Error("Could not open the CDP socket.")), {
+        once: true,
+      });
+    });
+    const client = new CdpPage(socket, { ...state, url: page.url, title: page.title });
+    await client.send("Runtime.enable");
+    await client.send("Page.enable");
+    return client;
+  }
+
+  #dispatch(message) {
+    if (message.id && this.#pending.has(message.id)) {
+      const { resolve, reject } = this.#pending.get(message.id);
+      this.#pending.delete(message.id);
+      if (message.error) reject(new Error(message.error.message));
+      else resolve(message.result);
+      return;
+    }
+    for (const listener of this.#listeners.get(message.method) || []) listener(message.params);
+  }
+
+  send(method, params = {}, { timeoutMs = 30000 } = {}) {
+    const id = ++this.#nextId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.#pending.delete(id)) {
+          reject(new Error(`CDP ${method} did not answer within ${timeoutMs}ms.`));
+        }
+      }, timeoutMs);
+      this.#pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      this.#socket.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  on(method, listener) {
+    if (!this.#listeners.has(method)) this.#listeners.set(method, []);
+    this.#listeners.get(method).push(listener);
+  }
+
+  /** Evaluate the body of an async function in the page; returns its JSON value. */
+  async evaluate(body, { timeoutMs = 30000 } = {}) {
+    const result = await this.send(
+      "Runtime.evaluate",
+      { expression: `(async () => { ${body} })()`, awaitPromise: true, returnByValue: true },
+      { timeoutMs },
+    );
+    if (result.exceptionDetails) {
+      throw new Error(
+        result.exceptionDetails.exception?.description ||
+          result.exceptionDetails.text ||
+          "evaluate failed",
+      );
+    }
+    return result.result?.value;
+  }
+
+  /** PNG screenshot of the viewport, or of `clip` ({x,y,width,height}). */
+  async screenshot(filePath, clip) {
+    const params = { format: "png" };
+    if (clip) params.clip = { ...clip, scale: 1 };
+    const shot = await this.send("Page.captureScreenshot", params);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, Buffer.from(shot.data, "base64"));
+    return filePath;
+  }
+
+  close() {
+    try {
+      this.#socket.close();
+    } catch {
+      // already closed
+    }
+  }
+}
+
+/** Parse `--flag value` / `--flag` out of argv; returns { flags, rest }. */
+export function parseArgs(argv, valueFlags = []) {
+  const flags = {};
+  const rest = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg.startsWith("--")) {
+      const name = arg.slice(2);
+      if (valueFlags.includes(name)) flags[name] = argv[++index];
+      else flags[name] = true;
+    } else rest.push(arg);
+  }
+  return { flags, rest };
+}
+
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/src/cli-help.mjs

@@ -49,7 +49,8 @@ export function renderGeneralHelp(registry) {
     "  foldspace upgrade --check        Compare the installed pin to npm latest",
     "",
     "attach loads local actions and observes the normal agent experience.",
-    "deploy is a separate remote publication step.",
+    "observe, ask and run look at and test that experience without the customer's help.",
+    ...(registry.publishWorkflow.length ? ["deploy is a separate remote publication step."] : []),
   );
   return sections.join("\n");
 }

package/src/cli-registry.mjs

@@ -241,9 +241,10 @@ export const CLI_COMMANDS = Object.freeze([
       ),
       value("--agent", "api-name", "Override the configured agent API name"),
       flag(
-        "--no-test-mode",
-        "Do not mark conversations as test traffic; use deliberately",
+        "--test-mode",
+        "Mark this session's conversations as test traffic, so they stay out of the dashboard; for an agent that already has real users",
       ),
+      flag("--no-test-mode", "Accepted for older instructions; test mode is already off by default"),
       flag("--no-badge", "Hide the visible Foldspace development badge"),
       flag(
         "--daemon",
@@ -261,7 +262,7 @@ export const CLI_COMMANDS = Object.freeze([
     effects: [
       "May reload and instrument matching target pages",
       "Refuses a Chrome that is not the profile inject launched",
-      "Test mode is enabled unless --no-test-mode is passed",
+      "Test mode is off unless --test-mode is passed: conversations appear in the dashboard",
       "Never directly invokes an action handler",
       "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
@@ -276,8 +277,81 @@ export const CLI_COMMANDS = Object.freeze([
       "Detach with Ctrl-C, or foldspace attach --stop for a daemon",
     ],
   }),
+  Object.freeze({
+    name: "observe",
+    entry: "observe.mjs",
+    group: "verify",
+    summary: "Look at the signed-in test window, read-only: screens, requests, auth, styles",
+    usage:
+      "foldspace observe <pages|menu|screen|read|auth|styles|screenshot|wait-login> [options]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({
+        name: "verb",
+        required: true,
+        description:
+          "pages | menu | screen | read <path> | auth | styles | screenshot | wait-login",
+      }),
+      Object.freeze({
+        name: "path",
+        required: false,
+        description: "read: the GET path or same-site URL to replay",
+      }),
+    ],
+    options: [
+      value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
+      value("--goto", "path", "screen: a same-origin path"),
+      value("--match", "words", "screen: rank the requests seen by these words"),
+      value("--wait", "ms", "screen/auth: how long to keep listening"),
+      value("--out", "file", "screenshot: where to save the PNG"),
+      value("--timeout", "seconds", "wait-login: give up after this long", { default: "600" }),
+    ],
+    prerequisites: ["foldspace inject has opened the test window"],
+    effects: [
+      "GET only. Never submits a form; clicks navigation elements only",
+      "Prints names, shapes and counts - never values, tokens or cookies",
+      "Works while foldspace attach is running",
+    ],
+    next: ["Record what you established in docs/app-profile.md", "Write the handler"],
+  }),
+  Object.freeze({
+    name: "badge",
+    entry: "badge.mjs",
+    group: "verify",
+    summary: "Set the banner across the top of the test window: working, ready, label or off",
+    usage: 'foldspace badge <working|ready|label|off> [--text "<what to show>"]',
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({
+        name: "state",
+        required: true,
+        description:
+          "working: the agent is building here, leave the window alone | ready: the human's turn | label: the small corner tag | off: remove it",
+      }),
+    ],
+    options: [
+      value("--text", "text", "working/ready: the line to show, e.g. the question to try (one line, up to 160 characters)"),
+    ],
+    prerequisites: ["foldspace attach is running (it draws the badge)"],
+    effects: [
+      "Writes one key to the test window's sessionStorage; touches nothing else on the page",
+      "The banner survives navigation inside the test window",
+    ],
+    next: ["Tell the human in chat what the banner says"],
+  }),
   Object.freeze({
     name: "deploy",
+    // Foldspace-internal: it uploads to Foldspace's own storage, which no
+    // customer can write to. It stays runnable (the deploy pipeline calls it)
+    // but is left out of help unless FOLDSPACE_INTERNAL=1, because a coding
+    // agent that finds it in the contract offers it to the customer.
+    internal: true,
     entry: "deploy.mjs",
     group: "publish",
     summary: "Publish dist/index.js to remote Foldspace action storage",
@@ -351,7 +425,9 @@ export function commandByName(name) {
   return CLI_COMMANDS.find((command) => command.name === name) || null;
 }
 
-export function createCliRegistry({ packageName, packageVersion }) {
+export function createCliRegistry({ packageName, packageVersion, env = process.env }) {
+  const showInternal = env.FOLDSPACE_INTERNAL === "1";
+  const visible = CLI_COMMANDS.filter((command) => showInternal || !command.internal);
   const diagnostics = diagnosticCatalogue()
     .filter((diagnostic) => PUBLIC_DIAGNOSTICS.has(diagnostic.name))
     .map((diagnostic) => ({
@@ -368,7 +444,8 @@ export function createCliRegistry({ packageName, packageVersion }) {
     },
     protocolVersion: HARNESS_PROTOCOL_VERSION,
     workflow: ["init", "build", "inject", "attach"],
-    publishWorkflow: ["deploy"],
+    verifyWorkflow: ["observe"],
+    publishWorkflow: showInternal ? ["deploy"] : [],
     capabilities: CAPABILITY_CATALOGUE.map(([id, description]) => ({
       id,
       description,
@@ -378,7 +455,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       id,
       description,
     })),
-    commands: CLI_COMMANDS.map(({ entry: _entry, ...command }) => command),
+    commands: visible.map(({ entry: _entry, internal: _internal, ...command }) => command),
     diagnostics,
     notes: [
       "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
@@ -387,6 +464,8 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
       "If update.outdated is true, ask the user before foldspace upgrade --yes.",
+      "observe, ask and run are read-only second clients on the test window and work while attach runs.",
+      "There is no customer-run publication step: putting actions in front of end users is done with Foldspace's team.",
     ],
   };
 }