@foldspace_npm/harness 0.1.11 → 0.1.12

package/recipes/pick-from-a-list/agent/views/picker.ts

@@ -0,0 +1,119 @@
+// A clickable list. textContent only — never innerHTML with API data.
+
+import type { ProjectSummary } from "../projects";
+import { brand } from "./brand";
+
+export type PickerChoice =
+  | { kind: "project"; project: ProjectSummary }
+  | { kind: "other" }
+  | { kind: "cancel" };
+
+export type PickerOptions = {
+  title: string;
+  subtitle: string;
+  projects: ProjectSummary[];
+  onSubmit: (choice: PickerChoice, offered: ProjectSummary[]) => void;
+};
+
+const CSS = `
+.fs-pick{font-family:${brand.font};font-size:${brand.size.base};color:${brand.text};
+  background:${brand.surface};border:1px solid ${brand.border};border-radius:${brand.radius};overflow:hidden;box-sizing:border-box}
+.fs-pick *{box-sizing:border-box;margin:0}
+.fs-pick-head{background:${brand.tint};padding:12px 16px}
+.fs-pick-title{font-weight:600}
+.fs-pick-sub{font-size:${brand.size.small};color:${brand.muted};margin-top:2px}
+.fs-pick-row{display:block;width:100%;text-align:left;padding:10px 16px;border:0;border-top:1px solid ${brand.border};
+  background:${brand.surface};font:inherit;color:inherit;cursor:pointer}
+.fs-pick-row.is-selected{background:${brand.tint};box-shadow:inset 3px 0 0 ${brand.primary}}
+.fs-pick-meta{display:block;font-size:${brand.size.small};color:${brand.muted}}
+.fs-pick-foot{display:flex;justify-content:flex-end;gap:8px;padding:10px 16px;border-top:1px solid ${brand.border}}
+.fs-pick-btn{font:inherit;padding:6px 14px;border-radius:${brand.radius};border:1px solid ${brand.border};background:${brand.surface};cursor:pointer}
+.fs-pick-submit{background:${brand.primary};border-color:${brand.primary};color:${brand.surface}}
+.fs-pick-submit:disabled{opacity:.5;cursor:default}
+`;
+
+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;
+}
+
+export function mountProjectPicker(host: HTMLElement, header: HTMLElement, options: PickerOptions): void {
+  // `host` lives inside the component's frame; styles belong in `header`.
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  const card = el("div", "fs-pick");
+  const head = el("div", "fs-pick-head");
+  const title = el("div", "fs-pick-title", options.title);
+  const subtitle = el("div", "fs-pick-sub", options.subtitle);
+  head.append(title, subtitle);
+  card.append(head);
+
+  const submit = button("fs-pick-btn fs-pick-submit", "Submit");
+  submit.disabled = true;
+  const cancel = button("fs-pick-btn", "Cancel");
+
+  let choice: PickerChoice | null = null;
+  const rows: HTMLButtonElement[] = [];
+
+  const select = (row: HTMLButtonElement, next: PickerChoice) => {
+    choice = next;
+    for (const other of rows) other.className = "fs-pick-row";
+    row.className = "fs-pick-row is-selected";
+    submit.disabled = false;
+  };
+
+  for (const project of options.projects) {
+    const row = button("fs-pick-row", project.name);
+    if (project.status) row.append(el("span", "fs-pick-meta", project.status));
+    row.addEventListener("click", () => select(row, { kind: "project", project }));
+    rows.push(row);
+    card.append(row);
+  }
+
+  const none = button("fs-pick-row", "None of these");
+  none.append(el("span", "fs-pick-meta", "Tell the assistant what you meant"));
+  none.addEventListener("click", () => select(none, { kind: "other" }));
+  rows.push(none);
+  card.append(none);
+
+  // Once answered, the card says so and stops responding — a card that still
+  // looks live after the agent has moved on gets clicked again.
+  const finish = (done: PickerChoice) => {
+    for (const row of rows) row.disabled = true;
+    submit.disabled = true;
+    cancel.disabled = true;
+    if (done.kind === "project") {
+      title.textContent = "Project selected";
+      subtitle.textContent = done.project.name;
+    } else if (done.kind === "other") {
+      title.textContent = "Sent to the assistant";
+      subtitle.textContent = "None of these projects.";
+    } else {
+      title.textContent = "Cancelled";
+      subtitle.textContent = "No project chosen.";
+    }
+    options.onSubmit(done, options.projects);
+  };
+
+  submit.addEventListener("click", () => {
+    if (choice) finish(choice);
+  });
+  cancel.addEventListener("click", () => finish({ kind: "cancel" }));
+
+  const foot = el("div", "fs-pick-foot");
+  foot.append(cancel, submit);
+  card.append(foot);
+
+  host.textContent = "";
+  host.append(card);
+}

package/recipes/pick-from-a-list/fixtures/projects.all.json

@@ -0,0 +1,29 @@
+{
+  "items": [
+    {
+      "id": "p_101",
+      "name": "Maple Street",
+      "status": "Active",
+      "updatedAt": "2026-08-30T14:05:00Z"
+    },
+    {
+      "id": "p_102",
+      "name": "Harbor Street Office",
+      "status": "Draft",
+      "updatedAt": "2026-07-12T09:00:00Z"
+    },
+    {
+      "id": "p_103",
+      "name": "Maple Street Annex",
+      "status": "Closed",
+      "updatedAt": "2026-03-02T17:40:00Z"
+    },
+    {
+      "id": "p_104",
+      "name": "Harbor View",
+      "status": "Active",
+      "updatedAt": "2026-02-11T10:00:00Z"
+    }
+  ],
+  "total": 4
+}

package/recipes/pick-from-a-list/fixtures/projects.empty-account.json

@@ -0,0 +1,4 @@
+{
+  "items": [],
+  "total": 0
+}

package/recipes/pick-from-a-list/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Pick from a list",
+  "level": "L2",
+  "family": "ask-the-user",
+  "kind": "action",
+  "action": "choose_project",
+  "entry": "agent/actions/choose_project.ts",
+  "outcome": "A clickable list, shown only when the user has to choose",
+  "provenBy": 1
+}

package/recipes/swap-the-login-method/README.md

@@ -0,0 +1,40 @@
+# Swap the login method
+
+The harness's `apiFetch` sends `Authorization: Bearer <token>`. That fits some
+apps. **Three production builds, three different schemes:**
+
+| What the app's own requests carried | Builds | Use |
+|---|---|---|
+| `Authorization: Bearer`, token in a cookie or `localStorage`, plus a fixed API-key header | 1 | the default `apiFetch`, with the extra header passed in `init.headers` |
+| A **custom header** holding a session id read from `localStorage` | 1 | `agent/utils.ts` here |
+| **Cookies** — `credentials: "include"` — and no token at all | 1 | `variants/utils.cookies.ts` |
+
+**Observe which one the app uses before choosing.** Read it off a request the
+page already made. Never guess, and never reach for a public developer API
+because the browser session was missing.
+
+## Adapt it
+
+Copy the variant you need over your project's `agent/utils.ts`. Actions keep
+importing from `../utils`, so nothing else changes — that is what the seam is
+for.
+
+| In the file | Change |
+|---|---|
+| `SESSION_STORAGE_KEY`, `SESSION_HEADER` | The key and header name you **observed** |
+| The cookies variant's extra headers | Only what you observed the app sending. One build needed `x-requested-with`; most do not |
+| `API_BASE` in `constants.ts` | For a same-origin app, the app's own origin. Empty stays a failure on purpose, so a guessed host cannot look like success |
+
+## What those builds learned the hard way
+
+- **Keep the failure reasons.** Replace the transport, not what a 401 or a 404
+  means: `httpFailure` and `networkFailure` are exported for exactly this, so a
+  custom `apiFetch` still returns `signed_out`, `not_found`, `rate_limited`.
+  Hand-rolled versions turned every failure into "unexpected error", or a
+  missing session into an empty list.
+- **Tokens are stored three ways** — raw, JSON-encoded (wrapped in quotes), or
+  inside an object. Strip the quotes; one app switched between the first two.
+- **With cookies there is no token to check first**, so "signed out" is only
+  known from the 401. Let it through as `signed_out` instead of pre-empting it.
+- **Do not `export *`** alongside your own `apiFetch` — name what you re-export,
+  so the default cannot come back by accident.

package/recipes/swap-the-login-method/agent/utils.ts

@@ -0,0 +1,73 @@
+// agent/utils.ts for an app that authenticates with a CUSTOM HEADER holding a
+// session id from localStorage — not `Authorization: Bearer`.
+//
+// Only the transport is replaced. What a 401, a 404 or a 429 means still comes
+// from the harness, so actions and renderFailure behave exactly the same.
+
+import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { AGENT_API_NAME, API_BASE } from "./constants";
+
+configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
+
+/** The localStorage key and the header name you OBSERVED on a real request. */
+const SESSION_STORAGE_KEY = "__observe_me_session";
+const SESSION_HEADER = "__observe-me-session";
+
+function readSession(): string | null {
+  const raw = window.localStorage.getItem(SESSION_STORAGE_KEY);
+  // Apps store it raw or JSON-encoded; strip the quotes either way.
+  return raw ? raw.replace(/^"|"$/g, "") || null : null;
+}
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<T>> {
+  if (!API_BASE) {
+    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+  }
+  const session = readSession();
+  if (!session) return { ok: false, status: 401, reason: "signed_out", error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: { "Content-Type": "application/json", [SESSION_HEADER]: session, ...(init.headers ?? {}) },
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text */
+    }
+    if (!res.ok) return httpFailure(res, "That request could not be completed.");
+    return { ok: true, status: res.status, data: parsed as T };
+  } catch (error) {
+    return networkFailure(error, "Request timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else still comes from the harness. Named, NOT `export *` — that
+// would put the default apiFetch back next to this one.
+export {
+  getAgent,
+  armAllInstances,
+  rankBy,
+  redact,
+  parseJwt,
+  publicFetch,
+  mapWithConcurrency,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+  renderFailure,
+} from "@foldspace_npm/harness/runtime";
+export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";

package/recipes/swap-the-login-method/fixtures/anything.ok.json

@@ -0,0 +1,8 @@
+{
+  "items": [
+    {
+      "id": "1",
+      "name": "Alpha"
+    }
+  ]
+}

package/recipes/swap-the-login-method/recipe.json

@@ -0,0 +1,12 @@
+{
+  "title": "Swap the login method",
+  "level": "any",
+  "family": "auth",
+  "kind": "override",
+  "entry": "agent/utils.ts",
+  "variants": [
+    "variants/utils.cookies.ts"
+  ],
+  "outcome": "apiFetch for an app that does not authenticate with a bearer token",
+  "provenBy": 2
+}

package/recipes/swap-the-login-method/variants/utils.cookies.ts

@@ -0,0 +1,64 @@
+// agent/utils.ts for an app that authenticates with COOKIES — no token to read.
+// Copy this over agent/utils.ts.
+//
+// There is nothing to check before the request, so "signed out" is only known
+// from the 401. It comes back as `signed_out` like any other.
+
+import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { AGENT_API_NAME, API_BASE } from "./constants";
+
+configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs = 15_000,
+): Promise<ApiResult<T>> {
+  if (!API_BASE) {
+    return { ok: false, status: 0, reason: "config", error: "API_BASE is not set — capture the app's XHR first." };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${API_BASE}${path}`, {
+      ...init,
+      credentials: "include",
+      signal: controller.signal,
+      // Add only what you OBSERVED the app sending. One build needed
+      // `x-requested-with: XMLHttpRequest`; most do not.
+      headers: { accept: "application/json", "Content-Type": "application/json", ...(init.headers ?? {}) },
+    });
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text */
+    }
+    if (!res.ok) return httpFailure(res, "That request could not be completed.");
+    return { ok: true, status: res.status, data: parsed as T };
+  } catch (error) {
+    return networkFailure(error, "Request timed out.", "Could not reach the server.");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Everything else still comes from the harness. Named, NOT `export *` — that
+// would put the default apiFetch back next to this one.
+export {
+  getAgent,
+  armAllInstances,
+  rankBy,
+  redact,
+  parseJwt,
+  publicFetch,
+  mapWithConcurrency,
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+  renderFailure,
+} from "@foldspace_npm/harness/runtime";
+export type { ApiResult, ApiFailure, FailureReason, ViewHost } from "@foldspace_npm/harness/runtime";

package/recipes/who-is-the-user/README.md

@@ -0,0 +1,56 @@
+# Who is the user — L0
+
+L0 is not "the agent appears". It is the agent appearing **and** Foldspace
+knowing who it is talking to. Without `identify`, every conversation, every
+analytics row and every segment is anonymous.
+
+**Proven by 4 production builds**, which found the identity in three different
+places — so look before you assume:
+
+| Where the signed-in user was found | Builds |
+|---|---|
+| Claims inside the app's own session token (user id, email, organisation id) | 2 |
+| A user object the app keeps in `localStorage` | 1 |
+| A call to the app's own account endpoint, cached for the page | 1 |
+
+## Adapt it
+
+| In `agent/identify.ts` | Change |
+|---|---|
+| `SessionClaims` | The claim names you **observed** in the token. Two builds, two spellings |
+| `/__observe_me/profile` and `Profile` | The endpoint that describes **the signed-in user** — see the trap below |
+| `subscription.id` | Whatever groups colleagues: organisation, account, workspace |
+
+Then call `identifyUser()` from the bundle's entry point:
+
+```ts
+// agent/actions/index.ts — last line
+import { identifyUser } from "../identify";
+identifyUser();
+```
+
+Custom attributes (a plan name, a sign-up date) only land if they were created
+first in **Settings → Attribute Settings**; send them under their API Name.
+
+## What those builds learned the hard way
+
+- **Claim the "already done" flag before the first `await`.** Checking and then
+  awaiting lets every concurrent load past the check — three bundle loads
+  produced three `identify` calls.
+- **Keep the flag on `window`, not in module scope.** A bundle evaluated twice
+  gets two module scopes and identifies twice.
+- **An account endpoint may describe the account, not the person.** One returned
+  the billing contact's name and email for whoever was signed in — which labels
+  every colleague as the same person. Read the person from the session; read
+  only the account id from the account.
+- **No id means stay anonymous.** A wrong id silently merges or splits real
+  people in the analytics. Never invent one.
+- **A failed identify must not break the agent.** Every failure is silent to the
+  user, and releases the flag so a later load can try again.
+- **Hide the agent until identify resolves, with a timeout** — and on a page
+  with no signed-in user (the login page), do not show it at all.
+- **This is unsigned.** Anyone can call `foldspace.identify` from a console.
+  Signing has to come from the customer's backend
+  (<https://docs.foldspace.ai/security/overview/>); until then treat the
+  analytics as indicative. And if the customer's own page ever calls
+  `identify`, delete this file — theirs runs earlier and knows more.

package/recipes/who-is-the-user/agent/identify.ts

@@ -0,0 +1,89 @@
+// Tell Foldspace who the signed-in user is — once, when the SDK is ready.
+// Context shape: https://docs.foldspace.ai/start/user-context/
+//
+// UNSIGNED: anyone can call foldspace.identify from a console. Signing has to
+// come from the customer's backend. See this recipe's README.
+
+import { apiFetch, getAuthToken, parseJwt, redact } from "./utils";
+
+/** Claims you OBSERVED in the app's session token. Replace these names. */
+type SessionClaims = {
+  sub?: string | number;
+  email?: string;
+};
+
+/**
+ * The endpoint that describes THE SIGNED-IN USER. Check it against a second
+ * account member before trusting it: one app's account endpoint returned the
+ * billing contact for everyone.
+ */
+type Profile = {
+  firstName?: string | null;
+  lastName?: string | null;
+  role?: string | null;
+  organizationId?: string | number | null;
+};
+
+// On window, not in module scope: a bundle evaluated twice on one page gets two
+// module scopes, and would identify twice.
+const IDENTIFIED_FLAG = "__foldspace_identified__";
+
+const claimed = (): boolean => (window as any)[IDENTIFIED_FLAG] === true;
+const claim = (): void => void ((window as any)[IDENTIFIED_FLAG] = true);
+const release = (): void => void ((window as any)[IDENTIFIED_FLAG] = false);
+
+function sessionIdentity(): { id: string; email: string | null } | null {
+  const token = getAuthToken();
+  const claims = token ? parseJwt<SessionClaims>(token) : null;
+  const raw = claims?.sub;
+  const id = typeof raw === "number" ? String(raw) : typeof raw === "string" ? raw.trim() : "";
+  if (!id) return null;
+  const email = typeof claims?.email === "string" && claims.email.includes("@") ? claims.email.trim() : null;
+  return { id, email };
+}
+
+/** Every failure is silent to the user: an unidentified session is a degraded record, never a broken agent. */
+export function identifyUser(): void {
+  const foldspace = (window as any).foldspace;
+  if (typeof foldspace !== "function" || typeof foldspace.identify !== "function") return;
+  if (claimed()) return;
+
+  foldspace("when", "ready", async () => {
+    if (claimed()) return;
+    // Claimed BEFORE the first await, or every concurrent load gets past the check.
+    claim();
+
+    try {
+      // No id means anonymous. Never invent one: a wrong id merges or splits
+      // real people in the analytics.
+      const who = sessionIdentity();
+      if (!who) {
+        release();
+        return;
+      }
+
+      const user: Record<string, unknown> = { id: who.id };
+      if (who.email) user.email = who.email;
+      const context: Record<string, unknown> = { user };
+
+      const profile = await apiFetch<Profile>("/__observe_me/profile");
+      if (profile.ok) {
+        const name = [profile.data?.firstName, profile.data?.lastName].filter(Boolean).join(" ");
+        if (name) user.name = name;
+        if (profile.data?.role) user.role = profile.data.role;
+        // One subscription, many users: whatever groups colleagues together.
+        const org = profile.data?.organizationId;
+        if (org !== null && org !== undefined && String(org) !== "") {
+          context.subscription = { id: String(org) };
+        }
+      }
+
+      foldspace.identify(context);
+      // Never log the identity itself — only that it fired.
+      console.debug("[foldspace] identified", redact(who.id), user.name ? "with name" : "id only");
+    } catch (error) {
+      release();
+      console.warn("[foldspace] identify skipped:", error);
+    }
+  });
+}

package/recipes/who-is-the-user/fixtures/profile.ok.json

@@ -0,0 +1,6 @@
+{
+  "firstName": "Dana",
+  "lastName": "Reyes",
+  "role": "admin",
+  "organizationId": 4410
+}

package/recipes/who-is-the-user/recipe.json

@@ -0,0 +1,9 @@
+{
+  "title": "Who is the user",
+  "level": "L0",
+  "family": "user-context",
+  "kind": "startup",
+  "entry": "agent/identify.ts",
+  "outcome": "Foldspace knows who is signed in, once, when the SDK is ready",
+  "provenBy": 4
+}

package/src/runtime/config.ts

@@ -26,7 +26,7 @@ export interface AuthSource {
  * wrong place.
  */
 export interface RuntimeConfig {
-  /** Foldspace agent apiName, e.g. `joist-agent`. */
+  /** Foldspace agent apiName, e.g. `acme-agent`. */
   agentApiName: string;
   /**
    * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the