@foldspace_npm/harness 0.1.17 → 0.1.19

package/recipes/upload-contacts/agent/contacts.ts

@@ -0,0 +1,133 @@
+import type { ContactDraft, ImportPayload } from "./api/contacts";
+
+export type ParsedContact = ContactDraft & {
+  valid: boolean;
+  reason: string | null;
+};
+
+export type ContactRow = {
+  name: string;
+  email: string;
+  reason: string | null;
+};
+
+export type ImportOutcome = {
+  created: number;
+  skipped: number;
+  rows: ContactRow[];
+};
+
+type Column = "firstName" | "lastName" | "email" | "phone" | "title" | "accountName";
+
+function splitCsvLine(line: string): string[] {
+  const values: string[] = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (char === '"') {
+      inQuotes = !inQuotes;
+    } else if (char === "," && !inQuotes) {
+      values.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  values.push(current.trim());
+  return values;
+}
+
+function columnOf(header: string): Column | null {
+  const normalized = header.replace(/['"]/g, "").trim().toLowerCase();
+  if (normalized.includes("first") && normalized.includes("name")) return "firstName";
+  if (normalized === "firstname" || normalized === "first_name") return "firstName";
+  if (normalized.includes("last") && normalized.includes("name")) return "lastName";
+  if (normalized === "lastname" || normalized === "last_name") return "lastName";
+  if (normalized.includes("email")) return "email";
+  if (normalized.includes("phone") || normalized.includes("mobile")) return "phone";
+  if (normalized.includes("title")) return "title";
+  if (normalized.includes("account") || normalized.includes("company")) return "accountName";
+  return null;
+}
+
+export function parseContactsCsv(csv: string): ParsedContact[] {
+  const lines = csv.trim().split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (lines.length < 2) return [];
+
+  const columns = splitCsvLine(lines[0]).map(columnOf);
+  const contacts: ParsedContact[] = [];
+
+  for (const line of lines.slice(1)) {
+    const values = splitCsvLine(line);
+    const read = (column: Column) => {
+      const index = columns.indexOf(column);
+      return index >= 0 ? (values[index] ?? "").trim() : "";
+    };
+    const contact: ParsedContact = {
+      firstName: read("firstName"),
+      lastName: read("lastName"),
+      email: read("email"),
+      phone: read("phone") || null,
+      title: read("title") || null,
+      accountName: read("accountName") || null,
+      valid: true,
+      reason: null,
+    };
+    if (!contact.firstName || !contact.lastName) {
+      contact.valid = false;
+      contact.reason = "Missing name";
+    } else if (!contact.email) {
+      contact.valid = false;
+      contact.reason = "Missing email";
+    } else if (!contact.email.includes("@")) {
+      contact.valid = false;
+      contact.reason = "Invalid email";
+    }
+    contacts.push(contact);
+  }
+
+  return contacts;
+}
+
+export function contactName(contact: { firstName?: string; lastName?: string; name?: string | null }): string {
+  if (contact.name?.trim()) return contact.name.trim();
+  return `${contact.firstName ?? ""} ${contact.lastName ?? ""}`.trim();
+}
+
+export function outcomeFrom(parsed: ParsedContact[], server: ImportPayload): ImportOutcome {
+  const heldBack = parsed.filter((row) => !row.valid);
+  const serverSkipped = server.skippedContacts ?? [];
+  const rows: ContactRow[] = [
+    ...(server.createdContacts ?? []).map((row) => ({
+      name: row.name?.trim() || "Untitled",
+      email: row.email?.trim() || "",
+      reason: null,
+    })),
+    ...heldBack.map((row) => ({
+      name: contactName(row) || "Untitled",
+      email: row.email,
+      reason: row.reason,
+    })),
+    ...serverSkipped.map((row) => ({
+      name: row.name?.trim() || "Untitled",
+      email: row.email?.trim() || "",
+      reason: row.reason?.trim() || null,
+    })),
+  ];
+  const created = typeof server.created === "number" ? server.created : (server.createdContacts ?? []).length;
+  const skipped =
+    heldBack.length + (typeof server.skipped === "number" ? server.skipped : serverSkipped.length);
+  return { created, skipped, rows };
+}
+
+export function toDraft(contact: ParsedContact): ContactDraft {
+  return {
+    firstName: contact.firstName,
+    lastName: contact.lastName,
+    email: contact.email,
+    phone: contact.phone,
+    title: contact.title,
+    accountName: contact.accountName,
+  };
+}

package/recipes/upload-contacts/agent/views/brand.ts

@@ -0,0 +1,21 @@
+// 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",
+  border: "#344256",
+  text: "#E0E0E0",
+  textStrong: "#FFFFFF",
+  muted: "#94A3B8",
+  faint: "#64748B",
+  accent: "#60A5FA",
+  accentDeep: "#3B82F6",
+  ok: "#34D399",
+  warn: "#FBBF24",
+  bad: "#F87171",
+  tableHead: "#1E293B",
+  disabled: "#475569",
+  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  radius: "8px",
+} as const;

package/recipes/upload-contacts/agent/views/uploader.ts

@@ -0,0 +1,394 @@
+// The import card from the production build. textContent only — never innerHTML
+// with file data. Styles go in `header`. The write runs only after Import.
+// Done is what finishes the card.
+
+import { importContacts } from "../api/contacts";
+import { contactName, outcomeFrom, parseContactsCsv, toDraft, type ImportOutcome, type ParsedContact } from "../contacts";
+import { renderFailure, type ApiFailure } from "../utils";
+import { brand } from "./brand";
+
+const CSS = `
+.fs-up{background:${brand.surface};border-radius:${brand.radius};padding:16px;font-family:${brand.font};
+  color:${brand.text};border:1px solid ${brand.border};width:100%;box-sizing:border-box}
+.fs-up *{box-sizing:border-box;margin:0}
+.fs-up-head{margin-bottom:16px}
+.fs-up-title{font-size:16px;font-weight:600;color:${brand.textStrong};margin-bottom:6px;display:flex;align-items:center;gap:6px}
+.fs-up-sub{font-size:12px;color:${brand.muted};line-height:1.4}
+.fs-up-icon{width:20px;height:20px;color:${brand.accent};flex-shrink:0}
+.fs-up-icon.is-ok{color:${brand.ok}}
+.fs-up-zone{border:2px dashed ${brand.border};border-radius:6px;padding:24px 16px;text-align:center;cursor:pointer;
+  background:rgba(96,165,250,.05)}
+.fs-up-zone:hover,.fs-up-zone.is-drag{border-color:${brand.accent};background:rgba(96,165,250,.1)}
+.fs-up-zone svg{width:40px;height:40px;margin:0 auto 12px;color:${brand.accent};display:block}
+.fs-up-zone-text{font-size:13px;color:${brand.text};margin-bottom:6px}
+.fs-up-hint{font-size:11px;color:${brand.faint}}
+.fs-up-file{display:none}
+.fs-up-sum{display:flex;gap:12px;margin-bottom:12px;padding:12px;background:rgba(30,41,59,.5);border-radius:6px;
+  flex-wrap:wrap;justify-content:center}
+.fs-up-stat{display:flex;flex-direction:column;gap:2px;flex:1;min-width:80px;align-items:center;text-align:center}
+.fs-up-num{font-size:24px;font-weight:600;color:${brand.textStrong}}
+.fs-up-num.is-ok{color:${brand.ok}}
+.fs-up-num.is-warn{color:${brand.warn}}
+.fs-up-label{font-size:11px;color:${brand.muted};text-transform:uppercase;letter-spacing:.5px}
+.fs-up-scroll{max-height:250px;overflow:auto;border:1px solid ${brand.border};border-radius:6px;margin-bottom:12px}
+.fs-up-table{width:100%;border-collapse:collapse;font-size:12px}
+.fs-up-table th{background:${brand.tableHead};padding:8px 10px;text-align:left;font-weight:600;color:${brand.muted};
+  text-transform:uppercase;font-size:10px;letter-spacing:.5px;border-bottom:1px solid ${brand.border}}
+.fs-up-table td{padding:8px 10px;border-bottom:1px solid ${brand.border};color:#E2E8F0}
+.fs-up-ready,.fs-up-invalid{display:inline-flex;align-items:center;padding:4px 8px;border-radius:12px;font-size:11px;font-weight:500}
+.fs-up-ready{background:rgba(52,211,153,.15);color:${brand.ok}}
+.fs-up-invalid{background:rgba(248,113,113,.15);color:${brand.bad}}
+.fs-up-actions{display:flex;gap:8px;justify-content:flex-end;margin-top:12px;flex-wrap:wrap}
+.fs-up-btn{padding:8px 16px;border-radius:6px;font-size:13px;font-weight:500;cursor:pointer;white-space:nowrap;font-family:inherit}
+.fs-up-primary{background:${brand.accent};color:${brand.textStrong};border:none}
+.fs-up-primary:hover{background:${brand.accentDeep}}
+.fs-up-primary:disabled{background:${brand.disabled};cursor:not-allowed}
+.fs-up-secondary{background:transparent;border:1px solid ${brand.border};color:${brand.text}}
+.fs-up-spin{display:inline-block;width:16px;height:16px;border:2px solid ${brand.border};border-top-color:${brand.accent};
+  border-radius:50%;animation:fs-up-spin .8s linear infinite}
+.fs-up-spin.is-lg{width:32px;height:32px;border-width:2px}
+@keyframes fs-up-spin{to{transform:rotate(360deg)}}
+.fs-up-wait{text-align:center;padding:40px}
+.fs-up-wait-text{margin-top:16px;color:${brand.muted};font-size:14px}
+.fs-up-section{margin-top:12px}
+.fs-up-section-title{font-size:13px;font-weight:600;color:${brand.text};margin-bottom:8px}
+.fs-up-list{max-height:200px;overflow:auto;font-size:12px;line-height:1.5;padding:8px;background:rgba(30,41,59,.3);border-radius:6px}
+.fs-up-item{padding:6px 0;border-bottom:1px solid rgba(52,66,86,.5);display:flex;flex-direction:column;gap:4px}
+.fs-up-name{color:#E2E8F0;font-weight:500}
+.fs-up-email{color:${brand.faint};font-size:11px}
+.fs-up-reason{color:${brand.warn};font-size:10px;font-style:italic}
+.fs-up-tag{background:rgba(96,165,250,.15);color:${brand.accent};padding:3px 8px;border-radius:10px;font-size:10px;font-weight:500}
+.fs-up-rule{height:1px;background:${brand.border};margin:12px 0}
+.fs-up-error{padding:10px;background:rgba(248,113,113,.1);border:1px solid rgba(248,113,113,.3);border-radius:6px;
+  color:${brand.bad};font-size:12px;line-height:1.4}
+`;
+
+const UPLOAD_PATH = "M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12";
+const FILE_PATH = "M9 13h6m-3-3v6m5 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z";
+const REVIEW_PATH = "M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4";
+const DONE_PATH = "M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z";
+const UPLOAD_COPY = "Upload a CSV file with your contacts. The file should include columns for firstName, lastName, and email (required). Optional columns: phone, title, accountName.";
+
+export type UploadHandlers = {
+  onCancel: () => void;
+  onEmpty: () => void;
+  onDone: (outcome: ImportOutcome) => void;
+  onFailed: (failure: ApiFailure) => void;
+};
+
+type CsvFile = { text: () => Promise<string> };
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function button(className: string, text: string): HTMLButtonElement {
+  const node = el("button", className, text) as HTMLButtonElement;
+  node.type = "button";
+  return node;
+}
+
+function icon(className: string, pathD: string, strokeWidth = "2"): SVGElement | null {
+  if (typeof document.createElementNS !== "function") return null;
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("class", className);
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  path.setAttribute("stroke-linecap", "round");
+  path.setAttribute("stroke-linejoin", "round");
+  path.setAttribute("stroke-width", strokeWidth);
+  path.setAttribute("d", pathD);
+  svg.appendChild(path);
+  return svg;
+}
+
+function toggleClass(node: HTMLElement, name: string, on: boolean): void {
+  const names = node.className.split(/\s+/).filter(Boolean);
+  const has = names.includes(name);
+  if (on && !has) node.className = [...names, name].join(" ");
+  if (!on && has) node.className = names.filter((item) => item !== name).join(" ");
+}
+
+// The production build's single-page app listened for this message and routed
+// on it. No other app does — on any other product this click does nothing.
+// Open a record with a navigation route instead (CLAUDE.md, "Product defaults").
+function go(path: string): void {
+  const top = window.top;
+  if (top && typeof top.postMessage === "function") {
+    top.postMessage({ type: "NAVIGATE", path }, "*");
+  }
+}
+
+function dash(value: string | null | undefined): string {
+  const text = value?.trim();
+  return text ? text : "-";
+}
+
+export function mountContactUpload(host: HTMLElement, header: HTMLElement, handlers: UploadHandlers): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  let settled = false;
+  let busy = false;
+  let parsed: ParsedContact[] = [];
+
+  const report = (draw: () => void, send: () => void) => {
+    if (settled) return;
+    settled = true;
+    draw();
+    send();
+  };
+
+  const mount = (card: HTMLElement) => {
+    host.textContent = "";
+    host.append(card);
+  };
+
+  const heading = (title: string, subtitle: string, mark: SVGElement | null): HTMLElement => {
+    const head = el("div", "fs-up-head");
+    const row = el("div", "fs-up-title");
+    if (mark) row.append(mark);
+    row.append(el("span", "", title));
+    head.append(row, el("div", "fs-up-sub", subtitle));
+    return head;
+  };
+
+  const actions = (...nodes: HTMLElement[]): HTMLElement => {
+    const row = el("div", "fs-up-actions");
+    row.append(...nodes);
+    return row;
+  };
+
+  const stat = (label: string, value: string, tone?: "ok" | "warn"): HTMLElement => {
+    const node = el("div", "fs-up-stat");
+    node.append(el("div", "fs-up-label", label), el("div", tone ? `fs-up-num is-${tone}` : "fs-up-num", value));
+    return node;
+  };
+
+  const showUpload = () => {
+    const card = el("div", "fs-up");
+    card.append(heading("Import Contacts from CSV", UPLOAD_COPY, icon("fs-up-icon", UPLOAD_PATH)));
+
+    const zone = el("div", "fs-up-zone");
+    const mark = icon("", FILE_PATH, "1.5");
+    if (mark) zone.append(mark);
+    zone.append(el("div", "fs-up-zone-text", "Click to select a CSV file or drag and drop"));
+    zone.append(el("div", "fs-up-hint", "Supports: .csv files"));
+
+    const input = document.createElement("input");
+    input.type = "file";
+    input.className = "fs-up-file";
+    input.accept = ".csv";
+    zone.append(input);
+
+    const readFile = async (file: CsvFile | undefined) => {
+      if (settled || busy || !file) return;
+      const csv = await file.text();
+      parsed = parseContactsCsv(csv);
+      if (parsed.length === 0) {
+        report(
+          () => {
+            const empty = el("div", "fs-up");
+            empty.append(heading("Import Contacts from CSV", UPLOAD_COPY, icon("fs-up-icon", UPLOAD_PATH)));
+            empty.append(el("div", "fs-up-error", "The file had no contacts."));
+            mount(empty);
+          },
+          () => handlers.onEmpty(),
+        );
+        return;
+      }
+      showPreview();
+    };
+
+    zone.addEventListener("click", () => input.click());
+    input.addEventListener("click", (event) => {
+      if (typeof event.stopPropagation === "function") event.stopPropagation();
+    });
+    input.addEventListener("change", () => {
+      const file = input.files?.[0] as CsvFile | undefined;
+      void readFile(file);
+    });
+    zone.addEventListener("dragover", (event) => {
+      if (typeof event.preventDefault === "function") event.preventDefault();
+      toggleClass(zone, "is-drag", true);
+    });
+    zone.addEventListener("dragleave", () => toggleClass(zone, "is-drag", false));
+    zone.addEventListener("drop", (event) => {
+      if (typeof event.preventDefault === "function") event.preventDefault();
+      toggleClass(zone, "is-drag", false);
+      const transfer = "dataTransfer" in event ? event.dataTransfer : null;
+      const file = transfer?.files?.[0] as CsvFile | undefined;
+      void readFile(file);
+    });
+
+    const cancel = button("fs-up-btn fs-up-secondary", "Cancel");
+    cancel.addEventListener("click", () => {
+      report(() => mount(el("div", "fs-up")), () => handlers.onCancel());
+    });
+
+    card.append(zone, actions(cancel));
+    mount(card);
+  };
+
+  const showPreview = () => {
+    const ready = parsed.filter((row) => row.valid);
+    const skipped = parsed.length - ready.length;
+    const accounts = new Set(parsed.map((row) => row.accountName?.trim()).filter((name): name is string => Boolean(name)));
+
+    const card = el("div", "fs-up");
+    card.append(
+      heading(
+        "Review Contacts",
+        "Review the contacts below before importing. Invalid contacts will be skipped.",
+        icon("fs-up-icon", REVIEW_PATH),
+      ),
+    );
+
+    const summary = el("div", "fs-up-sum");
+    summary.append(stat("Total Contacts", String(parsed.length)));
+    summary.append(stat("Ready to Import", String(ready.length), "ok"));
+    if (skipped > 0) summary.append(stat("Will Be Skipped", String(skipped), "warn"));
+    summary.append(stat("Accounts", String(accounts.size)));
+    card.append(summary);
+
+    const table = el("table", "fs-up-table");
+    const head = document.createElement("thead");
+    const headRow = document.createElement("tr");
+    for (const label of ["Name", "Email", "Title", "Account", "Status"]) {
+      headRow.append(el("th", "", label));
+    }
+    head.append(headRow);
+    const body = document.createElement("tbody");
+    for (const row of parsed) {
+      const line = document.createElement("tr");
+      line.append(
+        el("td", "", contactName(row) || "-"),
+        el("td", "", dash(row.email)),
+        el("td", "", dash(row.title)),
+        el("td", "", dash(row.accountName)),
+      );
+      const status = document.createElement("td");
+      const badge = el("span", row.valid ? "fs-up-ready" : "fs-up-invalid", row.valid ? "Ready" : "Invalid");
+      if (!row.valid && row.reason) badge.title = row.reason;
+      status.append(badge);
+      line.append(status);
+      body.append(line);
+    }
+    table.append(head, body);
+    const scroll = el("div", "fs-up-scroll");
+    scroll.append(table);
+    card.append(scroll);
+
+    const back = button("fs-up-btn fs-up-secondary", "Back");
+    back.addEventListener("click", () => {
+      if (settled || busy) return;
+      parsed = [];
+      showUpload();
+    });
+    const confirm = button("fs-up-btn fs-up-primary", `Import ${ready.length} Contacts`);
+    confirm.disabled = ready.length === 0;
+    confirm.addEventListener("click", async () => {
+      if (settled || busy || ready.length === 0) return;
+      busy = true;
+      showImporting(ready.length);
+      const res = await importContacts(ready.map(toDraft));
+      if (!res.ok) {
+        report(
+          () => renderFailure(host, res, { notFound: "No import endpoint answered." }),
+          () => handlers.onFailed(res),
+        );
+        return;
+      }
+      showResults(outcomeFrom(parsed, res.data));
+    });
+    card.append(actions(back, confirm));
+    mount(card);
+  };
+
+  const showImporting = (count: number) => {
+    const card = el("div", "fs-up");
+    const row = el("div", "fs-up-title");
+    row.append(el("span", "fs-up-spin"), el("span", "", "Importing Contacts..."));
+    const head = el("div", "fs-up-head");
+    head.append(row, el("div", "fs-up-sub", "Please wait while we import your contacts. This may take a moment for large files."));
+    const wait = el("div", "fs-up-wait");
+    wait.append(el("div", "fs-up-spin is-lg"), el("div", "fs-up-wait-text", `Processing ${count} contacts...`));
+    card.append(head, wait);
+    mount(card);
+  };
+
+  const showResults = (outcome: ImportOutcome) => {
+    const created = outcome.rows.filter((row) => !row.reason);
+    const skipped = outcome.rows.filter((row) => row.reason);
+    const card = el("div", "fs-up");
+
+    if (outcome.created > 0) {
+      const noun = outcome.created === 1 ? "contact" : "contacts";
+      card.append(
+        heading(
+          "Import Complete",
+          `Successfully imported ${outcome.created} ${noun}.`,
+          icon("fs-up-icon is-ok", DONE_PATH),
+        ),
+      );
+    }
+
+    const summary = el("div", "fs-up-sum");
+    summary.append(stat("Imported", String(outcome.created), "ok"));
+    summary.append(stat("Skipped", String(outcome.skipped), "warn"));
+    card.append(summary);
+
+    if (created.length > 0) {
+      const section = el("div", "fs-up-section");
+      section.append(el("div", "fs-up-section-title", `Imported Contacts (${created.length})`));
+      const list = el("div", "fs-up-list");
+      for (const row of created) {
+        const item = el("div", "fs-up-item");
+        const who = el("div", "");
+        who.append(el("span", "fs-up-name", row.name), el("span", "fs-up-email", ` - ${dash(row.email)}`));
+        item.append(who);
+        const account = parsed.find((source) => source.email === row.email)?.accountName;
+        if (account) item.append(el("span", "fs-up-tag", account));
+        list.append(item);
+      }
+      section.append(list);
+      card.append(section);
+    }
+
+    if (skipped.length > 0) {
+      card.append(el("div", "fs-up-rule"));
+      const section = el("div", "fs-up-section");
+      section.append(el("div", "fs-up-section-title", `Skipped Contacts (${skipped.length})`));
+      const list = el("div", "fs-up-list");
+      for (const row of skipped) {
+        const item = el("div", "fs-up-item");
+        const who = el("div", "");
+        who.append(el("span", "fs-up-name", row.name), el("span", "fs-up-email", ` - ${dash(row.email)}`));
+        item.append(who, el("span", "fs-up-reason", row.reason ?? ""));
+        list.append(item);
+      }
+      section.append(list);
+      card.append(section);
+    }
+
+    const finish = () => report(() => {}, () => handlers.onDone(outcome));
+    const view = button("fs-up-btn fs-up-secondary", "View Contacts");
+    view.addEventListener("click", () => {
+      // callback first: a navigation that unloads the page must not lose it.
+      finish();
+      go("/__observe_me/contacts");
+    });
+    const done = button("fs-up-btn fs-up-primary", "Done");
+    done.addEventListener("click", finish);
+    card.append(actions(view, done));
+    mount(card);
+  };
+
+  showUpload();
+}

package/recipes/upload-contacts/fixtures/import.ok.json

@@ -0,0 +1,9 @@
+{
+  "created": 2,
+  "skipped": 0,
+  "createdContacts": [
+    { "name": "Dana Reyes", "email": "dana@example.com" },
+    { "name": "Sam Lee", "email": "sam@example.com" }
+  ],
+  "skippedContacts": []
+}

package/recipes/upload-contacts/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Upload contacts",
+  "level": "L4",
+  "family": "upload",
+  "kind": "action",
+  "action": "upload_contacts",
+  "entry": "agent/actions/upload_contacts.ts",
+  "outcome": "A CSV is previewed, then written only after the user confirms",
+  "provenBy": 1
+}

package/src/attach-preflight.mjs

@@ -39,6 +39,15 @@ export function guardAttachMode({
     if (characterization.status === "no-sdk") {
       return { ok: true, mode };
     }
+    // The bootstrap script is added on every new document, so after the tab
+    // navigates within the app the SDK on the page is OUR bootstrap, carrying
+    // the configured agent. That is the expected state, not a foreign SDK:
+    // refusing it made the agent vanish on every in-app navigation
+    // (Buildium, 2026-09-22). Only a page whose SDK belongs to someone else
+    // is a real mismatch.
+    if (characterization.status === "same-agent") {
+      return { ok: true, mode, reattached: true };
+    }
     return {
       ok: false,
       mode,

package/src/keep-focus.mjs

@@ -0,0 +1,49 @@
+// The test Chrome must never steal the keyboard. Chrome raises its window when
+// a page navigates or reloads over CDP, and a customer typing somewhere else
+// then types into their live product (seen 2026-09-22). Nothing in CDP stops
+// that; on macOS the fix is to hand focus straight back to whatever app the
+// human was using. Elsewhere this is a no-op.
+
+import { execFile } from "node:child_process";
+
+const FRONT_APP_SCRIPT =
+  'tell application "System Events" to get bundle identifier of first application process whose frontmost is true';
+
+function osascript(script) {
+  return new Promise((resolve) => {
+    // 4s, not less: the first call wakes System Events, which alone can take
+    // over a second, and a timeout here silently leaves focus on Chrome.
+    execFile("osascript", ["-e", script], { timeout: 4000 }, (error, stdout) => {
+      resolve(error ? null : String(stdout).trim());
+    });
+  });
+}
+
+/** Bundle id of the app in front right now, or null (not macOS, or unknown). */
+export async function frontApp() {
+  if (process.platform !== "darwin") return null;
+  return osascript(FRONT_APP_SCRIPT);
+}
+
+/**
+ * Run `action` (which will make Chrome raise its window), then give focus back
+ * to the app that had it. If Chrome itself was in front, nothing to restore.
+ */
+export async function withoutStealingFocus(action, { front = frontApp, restore = restoreFront } = {}) {
+  const before = await front();
+  try {
+    return await action();
+  } finally {
+    if (before && !/google\.chrome|chromium/i.test(before)) await restore(before);
+  }
+}
+
+export async function restoreFront(bundleId) {
+  if (process.platform !== "darwin" || !bundleId) return;
+  // Twice, a beat apart: Chrome's activation lands after the navigation
+  // settles, so one immediate restore can be overtaken.
+  const script = `tell application id "${bundleId.replace(/"/g, "")}" to activate`;
+  await osascript(script);
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  await osascript(script);
+}