@foldspace_npm/harness 0.1.17 → 0.1.19

package/CLAUDE.md

@@ -77,8 +77,8 @@ 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
+`npx foldspace badge ready --text "<the question this experience answers>"` -
+the bar adds "Try asking:" and a Copy button itself - and say the same 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.
@@ -438,10 +438,14 @@ placeholder path and fields with what you observed. They match the harness
 version you have installed, and every one is built and run on each release.
 
 L0 → `who-is-the-user`. L2 → `find-by-name`, and `pick-from-a-list` when the
-user has to choose. App does not use a bearer token → `swap-the-login-method`.
+user has to choose. Show one account on a card → `account-overview`. Upload a
+CSV of contacts → `upload-contacts`. Save a note on a meeting →
+`update-meeting-notes`. Prepare for a meeting → `prepare-for-a-meeting`. The records that need
+attention, with reasons → `opportunities-at-risk`.
+App does not use a bearer token → `swap-the-login-method`.
 Each says how many production builds carry the pattern and what they learned.
-If nothing fits — there is no L1 card recipe yet — say so and build from
-`agent/actions/_example.ts`.
+If nothing fits — there is no L1 card recipe yet, and no navigation recipe —
+say so and build from `agent/actions/_example.ts`.
 
 ## What you already have
 

package/bin/attach.mjs

@@ -44,6 +44,7 @@ import {
 } from "../src/attach-preflight.mjs";
 import { serializeDiagnostic } from "../src/diagnostics.mjs";
 import { recordEvent } from "../src/session-events.mjs";
+import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import {
   ERROR_CODES,
   createLifecycleResult,
@@ -222,9 +223,12 @@ const SDK_PATTERNS = [
 
 // 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
+//   working - a pill at the foot of the window: the agent is building in this
+//             window, please leave it alone
+//   ready   - the same pill: it is the human's turn, with the question to try
+// The pill sits bottom-left, never across the top: a bar there covered the
+// app's own header and menu (seen on a CRM, 2026-09-22). The agent's panel
+// is on the right, so bottom-left is the corner nothing else uses.
 // The state lives in sessionStorage so it survives navigation inside the
 // test window; \`foldspace badge\` writes it and the script redraws.
 const badgeSrc = `(() => {
@@ -246,11 +250,35 @@ const badgeSrc = `(() => {
     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.";
+      // Attention, not decoration: a pulsing marker, the ask in bold, and an
+      // animated line underneath so it reads as "in progress" at a glance.
+      b.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#1F2A8A;padding:10px 14px 13px;font-size:13px;letter-spacing:.02em;text-align:left;line-height:1.3;";
+      b.innerHTML =
+        '<style>@keyframes fsPulse{0%,100%{opacity:1}50%{opacity:.25}}@keyframes fsSweep{0%{left:-30%}100%{left:100%}}' +
+        '#foldspace-dev-badge .fs-dot{display:inline-block;width:10px;height:10px;border-radius:50%;background:#FFB300;margin-right:10px;vertical-align:middle;animation:fsPulse 1s ease-in-out infinite}' +
+        '#foldspace-dev-badge .fs-line{position:absolute;left:0;right:0;bottom:0;height:3px;background:rgba(255,255,255,.15);overflow:hidden}' +
+        '#foldspace-dev-badge .fs-line::after{content:"";position:absolute;top:0;width:30%;height:100%;background:#FFB300;animation:fsSweep 1.4s linear infinite}</style>' +
+        '<span class="fs-dot"></span>Foldspace is building your agent on this page. <b style="color:#FFD54F">Please leave this window alone</b> until Claude says it is ready.' +
+        (s.text ? " " + s.text.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]) : "") +
+        '<span class="fs-line"></span>';
     } 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.";
+      // Calm, and useful: the question to try, with a Copy button so nobody
+      // retypes it into the panel. The bar accepts clicks only on that button.
+      const esc = (t) => String(t).replace(/[<>&"]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;" })[c]);
+      const question = s.text ? esc(s.text) : "";
+      b.style.cssText = base + "top:auto;bottom:16px;left:16px;right:auto;max-width:min(560px,calc(100vw - 32px));border-radius:8px;overflow:hidden;background:#0F9D58;padding:10px 14px;font-size:13px;letter-spacing:.02em;text-align:left;line-height:1.3;pointer-events:none;";
+      b.innerHTML =
+        '<style>#foldspace-dev-badge .fs-copy{pointer-events:auto;margin-left:12px;padding:4px 10px;border:1px solid rgba(255,255,255,.7);border-radius:4px;background:transparent;color:#fff;font:inherit;font-size:12px;cursor:pointer;letter-spacing:0}' +
+        '#foldspace-dev-badge .fs-copy:hover{background:rgba(255,255,255,.15)}</style>' +
+        '<b>Ready - your turn.</b> ' +
+        (question ? 'Try asking: <span class="fs-q">' + question + '</span><button class="fs-copy" type="button">Copy</button>' : "Open your agent and try it.");
+      const btn = b.querySelector(".fs-copy");
+      if (btn) btn.addEventListener("click", () => {
+        const q = b.querySelector(".fs-q")?.textContent || "";
+        const done = () => { btn.textContent = "Copied"; setTimeout(() => { btn.textContent = "Copy"; }, 1500); };
+        if (navigator.clipboard?.writeText) navigator.clipboard.writeText(q).then(done, done);
+        else { const ta = document.createElement("textarea"); ta.value = q; document.body.appendChild(ta); ta.select(); try { document.execCommand("copy"); } catch (e) {} ta.remove(); done(); }
+      });
     } else {
       b.style.cssText = base + "background:#3247F2;padding:5px 10px;border-bottom-right-radius:4px;";
       b.textContent = LABEL;
@@ -724,7 +752,7 @@ async function prepare(ws, sessionId, url) {
       ),
     });
     console.log(`  attached -> ${url}`);
-    await call(ws, "Page.reload", { ignoreCache: true }, sessionId);
+    await withoutStealingFocus(() => call(ws, "Page.reload", { ignoreCache: true }, sessionId));
 
     {
       const verification = await verifyPreparedPage(ws, sessionId);
@@ -1039,7 +1067,7 @@ async function cleanupPreparedSession(
   // identity aliases alike.
   if (reload) {
     try {
-      await call(socket, "Page.reload", { ignoreCache: true }, sessionId);
+      await withoutStealingFocus(() => call(socket, "Page.reload", { ignoreCache: true }, sessionId));
     } catch (error) {
       failures.push(`restore reload: ${error instanceof Error ? error.message : String(error)}`);
     }

package/bin/observe.mjs

@@ -22,6 +22,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
+import { withoutStealingFocus } from "../src/keep-focus.mjs";
 import {
   NAV_ITEM_SELECTOR,
   NAV_SCOPE_SELECTOR,
@@ -330,7 +331,7 @@ async function runScreen(page, flags) {
   let reached;
 
   if (destination) {
-    await page.send("Page.navigate", { url: destination.url });
+    await withoutStealingFocus(() => page.send("Page.navigate", { url: destination.url }));
     reached = { how: "goto", path: destination.path };
     if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
   }
@@ -360,7 +361,7 @@ async function runScreen(page, flags) {
   }
   if (!reached) {
     // Nothing to reach: reload so this screen's own requests are seen.
-    await page.send("Page.reload");
+    await withoutStealingFocus(() => page.send("Page.reload"));
     reached = { how: "reload" };
   }
   await network.settle(waitMs);
@@ -456,7 +457,7 @@ async function runAuth(page, flags) {
   const waitMs = numberFlag(flags.wait, 5000, "wait");
   await page.send("Network.enable");
   const network = recordNetwork(page);
-  await page.send("Page.reload");
+  await withoutStealingFocus(() => page.send("Page.reload"));
   await network.settle(waitMs);
 
   const url = await page.evaluate("return location.href;");

package/package.json

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

package/recipes/INDEX.md

@@ -9,8 +9,12 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`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) |
+| [`account-overview`](account-overview/) | **L2** | One account on a card: identity, pipeline total, contacts, cases, meetings. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
+| [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An action with a card that waits for the user | 1 production build |
+| [`update-meeting-notes`](update-meeting-notes/) | **L4** | A note is saved on a meeting and the new note id comes back | A write. **No card** | 1 production build |
+| [`prepare-for-a-meeting`](prepare-for-a-meeting/) | **L2** | Meeting facts are gathered in code, then a task agent writes the summary | A data action plus a task agent. **No card** | 1 production build |
+| [`opportunities-at-risk`](opportunities-at-risk/) | **L2** | Every open opportunity the app flags as at risk, on one card: count, total, and why each one is at risk. The model does not see the card | A view-only card. **No** `awaitUserInput` | 1 production build |
 
 **Not here yet — no production build proves it:** the user's own plan or
 settings drawn as a card (L1). In production that data is sent to `identify`
-(`who-is-the-user`), not rendered. Navigation (L3), writes (L4), uploads and
-task agents are also still to come.
+(`who-is-the-user`), not rendered. Navigation (L3) is also still to come.

package/recipes/account-overview/README.md

@@ -0,0 +1,26 @@
+# Account overview — L2
+
+**The user says** "show me this account". **The user sees** the account card: identity, phone, revenue, a metrics bar, and tabs for opportunities, meetings, cases, and contacts.
+
+**Proven by 1 production build.**
+
+This card is the base layout. Copy it, then replace the `/__observe_me` routes with the app's own paths and re-sample `brand.ts` if the product is not this dark theme.
+
+The card is view-only. `awaitUserInput` stays off. For a component that only shows something, the model is told that the information was displayed — nothing `execute` returned and nothing the card drew. One tab is on screen at a time; an empty tab says so. A signed-out or failed call is drawn with `renderFailure`, never as zeros. A 200 full of nulls is signed out when the account has no id and no name.
+
+In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`.
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/accounts.ts` | Mock path and envelope. Find a real API that returns a similar shape |
+| `agent/accounts.ts` | Which fields a summary carries. The pipeline total is summed here |
+| `agent/views/overview.ts` | The card. Routes under `/__observe_me` are placeholders for the app's own paths. Re-sample `brand.ts` when the host product is not this dark theme |
+
+## What that build learned the hard way
+
+- **The card is the experience.** A rich object returned from `execute` does not reach the model when the action only draws.
+- **Add the money in code.** Line items summed by the model eventually come out wrong. The card shows the total the code computed.
+- **The links only work where the app listens.** "Open Account", the rows and "View All" post a message the build's single-page app routed on; other apps do not. ⚠️ Wire that message in the host app, or replace the links with a navigation route.
+- **A signed-out response often looks empty.** Zeros and nulls on a 200 are not an account with no pipeline. Check for an id and a name before drawing numbers.

package/recipes/account-overview/agent/accounts.ts

@@ -0,0 +1,159 @@
+// Totals are computed here, from the API's own numbers. The model does not add them.
+
+import type { OverviewPayload } from "./api/accounts";
+
+export type AccountSummary = {
+  id: string;
+  name: string;
+  industry: string | null;
+  website: string | null;
+  phone: string | null;
+  revenue: number | null;
+  employeeCount: number | null;
+};
+
+export type OpportunitySummary = {
+  id: string;
+  name: string;
+  value: number;
+  stage: string | null;
+  closeDate: string | null;
+};
+
+export type ContactSummary = {
+  id: string;
+  name: string;
+  email: string | null;
+  phone: string | null;
+  title: string | null;
+};
+
+export type CaseSummary = {
+  id: string;
+  title: string;
+  priority: string | null;
+  status: string | null;
+  createdAt: string | null;
+};
+
+export type MeetingSummary = {
+  id: string;
+  title: string;
+  startTime: string | null;
+  attendees: number;
+};
+
+export type AccountMetrics = {
+  openOpportunities: number;
+  pipelineValue: number;
+  contacts: number;
+  openCases: number;
+};
+
+export type AccountOverview = {
+  account: AccountSummary;
+  metrics: AccountMetrics;
+  opportunities: OpportunitySummary[];
+  contacts: ContactSummary[];
+  openCases: CaseSummary[];
+  recentMeetings: MeetingSummary[];
+};
+
+/** A 200 full of nulls is not an account. Zeros are only real once an id and a name are present. */
+export function belongsToSignedInUser(payload: OverviewPayload): boolean {
+  const id = payload.account?.id;
+  const name = payload.account?.name;
+  return typeof id === "string" && id.trim() !== "" && typeof name === "string" && name.trim() !== "";
+}
+
+export function formatMoney(value: number): string {
+  const rounded = Math.round(value);
+  const sign = rounded < 0 ? "-" : "";
+  const digits = String(Math.abs(rounded));
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}$${grouped}`;
+}
+
+/** The metrics bar shortens the pipeline: $18K, $2.4M. Row amounts stay full. */
+export function formatPipeline(value: number): string {
+  const amount = Math.abs(value);
+  const sign = value < 0 ? "-" : "";
+  if (amount >= 1_000_000) return `${sign}$${(amount / 1_000_000).toFixed(1)}M`;
+  if (amount >= 1000) return `${sign}$${(amount / 1000).toFixed(0)}K`;
+  return `${sign}$${amount.toFixed(0)}`;
+}
+
+export function formatWhen(iso: string | null, withTime = false): string | null {
+  if (!iso) return null;
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  const day = date.toLocaleDateString();
+  if (!withTime) return day;
+  const time = date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  return `${day} at ${time}`;
+}
+
+export function titleCase(value: string): string {
+  return value
+    .split(/[_\s]+/)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+const text = (value: string | null | undefined, fallback: string) => value?.trim() || fallback;
+
+export function toOverview(payload: OverviewPayload): AccountOverview {
+  const account = payload.account ?? {};
+  const opportunities = (payload.opportunities ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    name: text(row.name, "Untitled"),
+    value: typeof row.value === "number" && Number.isFinite(row.value) ? row.value : 0,
+    stage: row.stage?.trim() || null,
+    closeDate: row.closeDate?.trim() || null,
+  }));
+  const contacts = (payload.contacts ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    name: text(row.name, "Untitled"),
+    email: row.email?.trim() || null,
+    phone: row.phone?.trim() || null,
+    title: row.title?.trim() || null,
+  }));
+  const openCases = (payload.openCases ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    title: text(row.title, "Untitled"),
+    priority: row.priority?.trim() || null,
+    status: row.status?.trim() || null,
+    createdAt: row.createdAt?.trim() || null,
+  }));
+  const recentMeetings = (payload.recentMeetings ?? []).map((row) => ({
+    id: row.id?.trim() || "",
+    title: text(row.title, "Untitled"),
+    startTime: row.startTime?.trim() || null,
+    attendees: Array.isArray(row.attendees) ? row.attendees.length : 0,
+  }));
+  const revenue = account.revenue;
+  const employees = account.employeeCount;
+
+  return {
+    account: {
+      id: String(account.id),
+      name: String(account.name).trim(),
+      industry: account.industry?.trim() || null,
+      website: account.website?.trim() || null,
+      phone: account.phone?.trim() || null,
+      revenue: typeof revenue === "number" && Number.isFinite(revenue) ? revenue : null,
+      employeeCount: typeof employees === "number" && Number.isFinite(employees) ? employees : null,
+    },
+    metrics: {
+      openOpportunities: opportunities.length,
+      pipelineValue: opportunities.reduce((sum, row) => sum + row.value, 0),
+      contacts: contacts.length,
+      openCases: openCases.length,
+    },
+    opportunities,
+    contacts,
+    openCases,
+    recentMeetings,
+  };
+}

package/recipes/account-overview/agent/actions/show_account_overview.ts

@@ -0,0 +1,61 @@
+// View-only card. Do not set awaitUserInput: the model is told only that the
+// information was displayed, so the card itself carries every fact. A failed
+// or signed-out call is drawn with renderFailure, never as a row of zeros.
+
+import { belongsToSignedInUser, toOverview, type AccountOverview } from "../accounts";
+import { getAccountOverview } from "../api/accounts";
+import { renderFailure, type FailureReason } from "../utils";
+import { mountAccountOverview } from "../views/overview";
+
+type ShowResult = {
+  success: boolean;
+  message?: string;
+  error?: string;
+  reason?: FailureReason;
+  data?: AccountOverview | { accountId: string };
+};
+
+function isOverview(data: NonNullable<ShowResult["data"]>): data is AccountOverview {
+  return "account" in data;
+}
+
+export const show_account_overview = {
+  execute: async (params: { accountId?: string }): Promise<ShowResult> => {
+    const accountId = typeof params?.accountId === "string" ? params.accountId.trim() : "";
+    if (!accountId) {
+      return { success: false, error: "accountId was not provided.", reason: "config" };
+    }
+
+    const res = await getAccountOverview(accountId);
+    if (!res.ok) {
+      console.warn("[show_account_overview]", res.status, res.reason, res.detail);
+      return { success: false, error: res.error, reason: res.reason, data: { accountId } };
+    }
+
+    if (!belongsToSignedInUser(res.data)) {
+      return { success: false, error: "Not signed in.", reason: "signed_out", data: { accountId } };
+    }
+
+    // `message` never reaches the model for a view-only action; it is for the console.
+    return { success: true, message: "Displayed.", data: toOverview(res.data) };
+  },
+
+  render: (result: ShowResult | undefined, host: HTMLElement, header: HTMLElement) => {
+    if (!result?.success || !result.data || !isOverview(result.data)) {
+      const accountId = result?.data && "accountId" in result.data ? result.data.accountId : "";
+      renderFailure(
+        host,
+        {
+          ok: false,
+          status: 0,
+          error: result?.error ?? "The account could not be loaded.",
+          reason: result?.reason ?? "server",
+        },
+        { notFound: accountId ? `No account ${accountId}.` : "No account." },
+      );
+      return;
+    }
+
+    mountAccountOverview(host, header, result.data);
+  },
+};

package/recipes/account-overview/agent/api/accounts.ts

@@ -0,0 +1,59 @@
+// Mock API. These paths are not a real product. Find an API that returns a
+// similar shape — one account, its opportunities, contacts, open cases, and
+// recent meetings — and replace the path and the envelope with what you
+// observed. `__observe_me` cannot succeed until you do.
+
+import { apiFetch, type ApiResult } from "../utils";
+
+export type AccountRecord = {
+  id?: string | null;
+  name?: string | null;
+  industry?: string | null;
+  website?: string | null;
+  phone?: string | null;
+  revenue?: number | null;
+  employeeCount?: number | null;
+};
+
+export type OpportunityRecord = {
+  id?: string | null;
+  name?: string | null;
+  value?: number | null;
+  stage?: string | null;
+  closeDate?: string | null;
+};
+
+export type ContactRecord = {
+  id?: string | null;
+  name?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  title?: string | null;
+};
+
+export type CaseRecord = {
+  id?: string | null;
+  title?: string | null;
+  priority?: string | null;
+  status?: string | null;
+  createdAt?: string | null;
+};
+
+export type MeetingRecord = {
+  id?: string | null;
+  title?: string | null;
+  startTime?: string | null;
+  attendees?: unknown[] | null;
+};
+
+export type OverviewPayload = {
+  account?: AccountRecord | null;
+  opportunities?: OpportunityRecord[] | null;
+  contacts?: ContactRecord[] | null;
+  openCases?: CaseRecord[] | null;
+  recentMeetings?: MeetingRecord[] | null;
+};
+
+export async function getAccountOverview(accountId: string): Promise<ApiResult<OverviewPayload>> {
+  return apiFetch<OverviewPayload>(`/__observe_me/accounts/${encodeURIComponent(accountId)}/overview`);
+}

package/recipes/account-overview/agent/views/brand.ts

@@ -0,0 +1,22 @@
+// Palette sampled from the production build this recipe came from (a dark CRM).
+// Re-sample these from the host page when that product's brand differs.
+// Record where each value came from in docs/app-profile.md.
+
+export const brand = {
+  surface: "#0E1729",
+  headerStart: "#1a2332",
+  border: "#344256",
+  text: "#E0E0E0",
+  textStrong: "#FFFFFF",
+  muted: "#94A3B8",
+  faint: "#6B7280",
+  accent: "#60A5FA",
+  accentDeep: "#3B82F6",
+  money: "#34D399",
+  deals: "#60A5FA",
+  contacts: "#A78BFA",
+  cases: "#FBBF24",
+  row: "rgba(255, 255, 255, 0.03)",
+  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  radius: "8px",
+} as const;