@foldspace_npm/harness 0.1.8 → 0.1.9

package/README.md

@@ -27,6 +27,7 @@ constraint this package exists to protect.
 
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. The actions built for Figma run unmodified in either track.
+- `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
 - `foldspace build` — esbuild → `dist/index.js`
 - `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
@@ -150,6 +151,15 @@ v1 flags:
 
 Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
 
+### Runtime helpers
+
+Tenant actions import from `agent/utils.ts`, which configures and re-exports
+`@foldspace_npm/harness/runtime`. That code is bundled into `dist/index.js` and
+runs in the customer's page — it is not a CLI command.
+
+`API_BASE` and `AUTH_SOURCE` stamp empty. Fill them from a captured XHR, not a
+guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
+
 ### Choose an attach mode
 
 - **Swap (default):** the page already uses the configured product and agent.

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
     "foldspace": "bin/cli.mjs",
     "harness": "bin/cli.mjs"
   },
+  "exports": {
+    "./runtime": {
+      "types": "./src/runtime/index.ts",
+      "default": "./src/runtime/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "test": "node --test test/*.test.mjs"
   },

package/src/runtime/agent.ts

@@ -0,0 +1,66 @@
+import { getConfig } from "./config";
+
+let cached: any | null = null;
+
+/**
+ * Foldspace SDK handle for this agent's **overlay** instance.
+ *
+ * Takes no `mode` on purpose: `foldspace.agent({ apiName })` returns the overlay
+ * handle. On an app that embeds the copilot in-page that is not the instance
+ * serving the chat, so arming only it succeeds and leaves real conversations
+ * untagged. For a specific instance, enumerate `window.foldspace.agentIds()`
+ * (`"<mode>-<apiName>"`) and call `foldspace.agent({ apiName, mode })`.
+ *
+ * This is a thin wrapper around the SDK, not a second agent implementation.
+ * Cached after the first successful lookup.
+ *
+ * @returns The overlay agent, or `null` if the SDK is not on the page
+ */
+export function getAgent(): any | null {
+  if (cached) return cached;
+  cached =
+    (window as any).foldspace?.agent({ apiName: getConfig().agentApiName }) ??
+    null;
+  return cached;
+}
+
+/**
+ * Arm every Foldspace instance on the page for test mode and remote actions.
+ *
+ * Calls SDK `setTestMode` and `setConfiguration({ remoteActionsSettings })`.
+ * Local `foldspace attach` already injects test-mode arming without putting it
+ * in `dist/index.js`. Prefer that. Importing this helper from an action can
+ * ship those calls into the production CDN bundle.
+ *
+ * Do not call from `execute`. Partial `setConfiguration` has collapsed the
+ * widget to 0×0 in a real build.
+ *
+ * @param testMode - When true, mark conversations as test traffic
+ * @returns Instance ids that armed vs failed
+ */
+export function armAllInstances(testMode = true): {
+  armed: string[];
+  failed: string[];
+} {
+  const fs = (window as any).foldspace;
+  const armed: string[] = [];
+  const failed: string[] = [];
+  if (!fs || typeof fs.agentIds !== "function") return { armed, failed };
+
+  for (const id of fs.agentIds() as string[]) {
+    const cut = id.indexOf("-");
+    if (cut < 1) continue;
+    try {
+      const inst = fs.agent({
+        apiName: id.slice(cut + 1),
+        mode: id.slice(0, cut).toUpperCase(),
+      });
+      inst.setTestMode(testMode);
+      inst.setConfiguration({ remoteActionsSettings: { enabled: true } });
+      armed.push(id);
+    } catch {
+      failed.push(id);
+    }
+  }
+  return { armed, failed };
+}

package/src/runtime/config.ts

@@ -0,0 +1,78 @@
+/**
+ * Tenant-specific facts for the page runtime. Set once from `agent/utils.ts`.
+ *
+ * This module cannot import the client's `constants.ts`, so the client pushes
+ * values in with {@link configure}. Nothing here is a Foldspace cloud setting.
+ */
+
+/**
+ * Where the customer app keeps its own session token — not a Foldspace token.
+ *
+ * Custom headers (not Bearer) are out of scope: override `apiFetch` in
+ * `agent/utils.ts` instead of adding a third `kind`.
+ */
+export interface AuthSource {
+  /** Where the live page stores the token. */
+  kind: "localStorage" | "cookie";
+  /** The localStorage key or cookie name observed on the page. */
+  name: string;
+}
+
+/**
+ * Values {@link configure} stores for the rest of the runtime.
+ *
+ * Stamp `apiBase` and `authSource` empty until you capture a real XHR. A
+ * guessed host or Bearer vs cookie looks like success and publishes to the
+ * wrong place.
+ */
+export interface RuntimeConfig {
+  /** Foldspace agent apiName, e.g. `joist-agent`. */
+  agentApiName: string;
+  /**
+   * Prefix for `apiFetch` / `apiFetchBinary`. Include an explicit port if the
+   * app uses one — omitting `:443` can fail CORS.
+   */
+  apiBase?: string;
+  /**
+   * Prefix for `publicFetch` when the caller does not pass an origin.
+   * Marketing / unauthenticated hosts only.
+   */
+  publicOrigin?: string;
+  /** Session location for `getAuthToken`. Omit until observed. */
+  authSource?: AuthSource;
+  /** `fetch` timeout in ms. Defaults to 15_000 in `configure`. */
+  timeoutMs?: number;
+}
+
+let config: RuntimeConfig | null = null;
+
+/**
+ * Store tenant config for this page bundle. Call once from `agent/utils.ts`
+ * at module load — not from an action `execute`.
+ *
+ * Replaces the previous object; it does not merge. A second call clobbers the
+ * first. `timeoutMs` defaults to 15_000 if omitted.
+ *
+ * @param next - Tenant ids and observed API/auth facts
+ */
+export function configure(next: RuntimeConfig): void {
+  config = { timeoutMs: 15_000, ...next };
+}
+
+/**
+ * Read the config {@link configure} stored.
+ *
+ * Throws if `configure` never ran (imported the runtime without going through
+ * `agent/utils.ts`). Empty `apiBase` / `authSource` after configure is valid;
+ * `apiFetch` returns `{ ok: false }` for those instead of throwing.
+ *
+ * @returns The singleton config for this bundle
+ */
+export function getConfig(): RuntimeConfig {
+  if (!config) {
+    throw new Error(
+      "harness runtime is not configured — call configure() from agent/utils.ts",
+    );
+  }
+  return config;
+}

package/src/runtime/http.ts

@@ -0,0 +1,373 @@
+// HTTP against the customer's own API, from inside their signed-in page.
+//
+// Lifted from the Transparency Catalog build. Errors are RETURNED, never
+// thrown, and never carry the token or a raw API error body back to the agent.
+//
+// Two of three early builds used Authorization: Bearer from localStorage, not
+// cookies. Reach for credentials: "include" only when you have observed the
+// app doing that. Custom headers (Joist-style) belong in a tenant override of
+// apiFetch, not here.
+
+import { getConfig } from "./config";
+
+/**
+ * Mask a secret for logs. Never log a raw token.
+ *
+ * @param value - Token or other secret; null/empty becomes `"<empty>"`
+ * @returns `"<redacted:N chars>"` or `"<empty>"`
+ */
+export function redact(value: string | null | undefined): string {
+  if (!value) return "<empty>";
+  return `<redacted:${value.length} chars>`;
+}
+
+function readLocalStorageValue(key: string): string | null {
+  const raw = window.localStorage.getItem(key);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "string") return parsed;
+    if (parsed && typeof parsed === "object") {
+      return parsed.access_token ?? parsed.token ?? parsed.value ?? null;
+    }
+  } catch {
+    return raw;
+  }
+  return raw;
+}
+
+function readCookie(name: string): string | null {
+  const prefix = `${name}=`;
+  for (const part of document.cookie.split(";")) {
+    const c = part.trim();
+    if (c.startsWith(prefix)) {
+      return decodeURIComponent(c.slice(prefix.length)) || null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read the customer app's session token from `authSource`.
+ *
+ * Returns null when unsigned-in, `AUTH_SOURCE` is unset, or the key is empty.
+ * This is the host app token, not a Foldspace credential.
+ *
+ * @returns The token string, or `null`
+ */
+export function getAuthToken(): string | null {
+  const source = getConfig().authSource;
+  if (!source?.name) return null;
+  if (source.kind === "cookie") return readCookie(source.name);
+  return readLocalStorageValue(source.name);
+}
+
+/**
+ * Decode a JWT payload without verifying the signature.
+ *
+ * Identity hints only (email, sub). Never use this for authorization.
+ *
+ * @param token - Compact JWT from {@link getAuthToken}
+ * @returns Parsed payload, or `null` if the token is not a JWT
+ */
+export function parseJwt<T = Record<string, unknown>>(token: string): T | null {
+  try {
+    const [, payload] = token.split(".");
+    if (!payload) return null;
+    const json = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Successful JSON/binary response from {@link apiFetch}, {@link apiFetchBinary},
+ * or {@link publicFetch}.
+ */
+export interface ApiSuccess<T> {
+  ok: true;
+  /** HTTP status (typically 200). */
+  status: number;
+  /** Parsed JSON (`apiFetch` / `publicFetch`) or bytes (`apiFetchBinary`). */
+  data: T;
+}
+
+/**
+ * Failed request. Errors are **returned**, never thrown.
+ *
+ * Show `error` to a person. Log `detail` to the console only — never put
+ * `detail` in an action return value; Foldspace may quote that to the user.
+ *
+ * `unreachable` is true when the browser never got a response (DNS, CORS,
+ * offline, connection refused). Timeouts set `unreachable: false` and
+ * `error: "Request timed out."`. Empty `API_BASE` / `AUTH_SOURCE` also
+ * return `{ ok: false }` with status 0 — they do not throw.
+ */
+export interface ApiFailure {
+  ok: false;
+  /** HTTP status, or `0` when there was no response / config was missing. */
+  status: number;
+  /** Safe, user-facing sentence. Pass this to `renderError`. */
+  error: string;
+  /** Truncated API body for the console. Never show this in the widget. */
+  detail?: string;
+  /**
+   * True when the network itself failed (not HTTP 4xx/5xx, not abort).
+   * Use this to distinguish "server said no" from "could not reach host".
+   */
+  unreachable?: boolean;
+}
+
+/** Discriminated result of a customer-API call. Branch on `ok`. */
+export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
+
+function missingConfigResult(): ApiResult<never> | null {
+  const config = getConfig();
+  if (!config.apiBase) {
+    return {
+      ok: false,
+      status: 0,
+      error: "API_BASE is not set — capture the app's XHR first.",
+    };
+  }
+  if (!config.authSource) {
+    return {
+      ok: false,
+      status: 0,
+      error: "AUTH_SOURCE is not set — capture the app's session first.",
+    };
+  }
+  return null;
+}
+
+function failureDetail(parsed: unknown): string | undefined {
+  if (parsed && typeof parsed === "object") {
+    const m = (parsed as { message?: unknown }).message;
+    if (typeof m === "string") return m.slice(0, 300);
+  } else if (typeof parsed === "string" && parsed.trim()) {
+    return parsed.trim().slice(0, 300);
+  }
+  return undefined;
+}
+
+/**
+ * Authenticated JSON request against `apiBase` with `Authorization: Bearer`.
+ *
+ * Matches the common pattern (two of three early builds). If the live page
+ * uses cookies, custom headers, or no Bearer, **stop re-exporting this** from
+ * `agent/utils.ts` and write a local `apiFetch` instead.
+ *
+ * Empty `API_BASE` / `AUTH_SOURCE` return `{ ok: false }` so a guessed host
+ * cannot look like success. Errors never throw and never include the token.
+ *
+ * @param path - Path under `apiBase`, including a leading `/`
+ * @param init - Extra `fetch` options; your headers merge over Bearer/JSON
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs?: number,
+): Promise<ApiResult<T>> {
+  const missing = missingConfigResult();
+  if (missing) return missing;
+
+  const token = getAuthToken();
+  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+
+  try {
+    const res = await fetch(`${getConfig().apiBase}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        ...(init.headers ?? {}),
+      },
+    });
+
+    const text = await res.text();
+    let parsed: unknown = text;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* non-JSON; keep the raw text for the status check */
+    }
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        error:
+          res.status === 401
+            ? "Your session expired. Sign in again."
+            : "That request could not be completed.",
+        detail: failureDetail(parsed),
+      };
+    }
+
+    return { ok: true, status: res.status, data: parsed as T };
+  } catch (error) {
+    const aborted = error instanceof Error && error.name === "AbortError";
+    return {
+      ok: false,
+      status: 0,
+      unreachable: !aborted,
+      error: aborted ? "Request timed out." : "Could not reach the server.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run an async worker over a list with a cap on in-flight work.
+ *
+ * Use this for N+1 fetches after a list call (export, hydrate rows). A large
+ * list without a cap can open dozens of sockets at once.
+ *
+ * @param items - Inputs to process
+ * @param limit - Max concurrent `worker` calls
+ * @param worker - Async mapper; results stay in input order
+ */
+export async function mapWithConcurrency<T, R>(
+  items: T[],
+  limit: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let cursor = 0;
+  const runners = Array.from(
+    { length: Math.min(limit, items.length) || 0 },
+    async () => {
+      while (cursor < items.length) {
+        const i = cursor++;
+        results[i] = await worker(items[i], i);
+      }
+    },
+  );
+  await Promise.all(runners);
+  return results;
+}
+
+/**
+ * Same auth and `apiBase` as {@link apiFetch}, but returns raw bytes.
+ *
+ * Use for file downloads / exports, not JSON endpoints.
+ *
+ * @param path - Path under `apiBase`, including a leading `/`
+ * @param init - Extra `fetch` options
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function apiFetchBinary(
+  path: string,
+  init: RequestInit = {},
+  timeoutMs?: number,
+): Promise<ApiResult<Uint8Array>> {
+  const missing = missingConfigResult();
+  if (missing) return missing;
+
+  const token = getAuthToken();
+  if (!token) return { ok: false, status: 401, error: "Not signed in." };
+
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+
+  try {
+    const res = await fetch(`${getConfig().apiBase}${path}`, {
+      ...init,
+      signal: controller.signal,
+      headers: { Authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
+    });
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        error:
+          res.status === 401
+            ? "Your session expired. Sign in again."
+            : "That file could not be returned.",
+      };
+    }
+    return {
+      ok: true,
+      status: res.status,
+      data: new Uint8Array(await res.arrayBuffer()),
+    };
+  } catch (error) {
+    const aborted = error instanceof Error && error.name === "AbortError";
+    return {
+      ok: false,
+      status: 0,
+      unreachable: !aborted,
+      error: aborted ? "Download timed out." : "Could not reach the server.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Unauthenticated JSON GET. No Bearer token.
+ *
+ * Origin is the second argument, or `RuntimeConfig.publicOrigin`. Path first
+ * (Transparency Catalog calling convention). Use for marketing / public APIs,
+ * not the signed-in product API.
+ *
+ * @param path - Path under the public origin
+ * @param origin - Override `publicOrigin` for this call
+ * @param timeoutMs - Override the configured timeout (default 15s)
+ */
+export async function publicFetch<T = unknown>(
+  path: string,
+  origin?: string,
+  timeoutMs?: number,
+): Promise<ApiResult<T>> {
+  const base = origin ?? getConfig().publicOrigin;
+  if (!base) {
+    return {
+      ok: false,
+      status: 0,
+      error: "No public origin is configured for this app.",
+    };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(),
+    timeoutMs ?? getConfig().timeoutMs ?? 15_000,
+  );
+  try {
+    const res = await fetch(`${base}${path}`, {
+      credentials: "include",
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        error: "That request could not be completed.",
+      };
+    }
+    return { ok: true, status: res.status, data: (await res.json()) as T };
+  } catch (error) {
+    const aborted = error instanceof Error && error.name === "AbortError";
+    return {
+      ok: false,
+      status: 0,
+      unreachable: !aborted,
+      error: aborted ? "The request timed out." : "Could not reach that host.",
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Page-runtime helpers compiled into the customer's bundle via esbuild.
+ *
+ * Source is TypeScript on purpose: what you read here is what ships. Import
+ * these from `agent/utils.ts` in the client repo, not from this package path
+ * inside an action file.
+ *
+ * @packageDocumentation
+ */
+
+export { configure, getConfig } from "./config";
+export type { RuntimeConfig, AuthSource } from "./config";
+
+export { getAgent, armAllInstances } from "./agent";
+
+export {
+  redact,
+  getAuthToken,
+  parseJwt,
+  apiFetch,
+  apiFetchBinary,
+  publicFetch,
+  mapWithConcurrency,
+} from "./http";
+export type { ApiResult, ApiSuccess, ApiFailure } from "./http";
+
+export { rankBy } from "./match";
+export type { FuzzyMatch, RankByOptions } from "./match";
+
+export {
+  renderLoading,
+  renderEmpty,
+  renderError,
+  renderFatal,
+} from "./render";
+export type { ViewHost } from "./render";

package/src/runtime/match.ts

@@ -0,0 +1,87 @@
+/**
+ * Rank an in-memory list against what a user typed.
+ *
+ * Substring hits first (they meant that name), then the Foldspace SDK's
+ * `searchInList` (Fuse) for typos. Do not use this for domain ranking
+ * (invoices, coverage, MasterFormat).
+ */
+
+import { getAgent } from "./agent";
+
+/** One SDK fuzzy hit. `score` is lower-is-better Fuse scoring. */
+export interface FuzzyMatch<T> {
+  item: T;
+  score?: number;
+}
+
+/**
+ * Options for {@link rankBy}.
+ */
+export interface RankByOptions<T> {
+  /** Fields to match, in priority order. */
+  searchKeys: (keyof T & string)[];
+  /** Stable identity so substring and fuzzy hits can be merged. */
+  idOf: (item: T) => string | number;
+  /** Max rows to return. Default 10. */
+  limit?: number;
+  /**
+   * Drop SDK hits with score at or above this. Default 0.45. Lower is a
+   * closer Fuse match.
+   */
+  plausible?: number;
+}
+
+/** Lower is better in the SDK's scoring. Above this, a hit is noise. */
+const PLAUSIBLE = 0.45;
+
+/**
+ * Rank records against a user's phrase.
+ *
+ * If `searchInList` is missing, the substring pass still answers — a missing
+ * SDK method degrades the result rather than breaking the action.
+ *
+ * @param items - Records already loaded (e.g. from {@link apiFetch})
+ * @param query - What the user typed
+ * @param opts - Fields, identity, optional limit
+ * @returns Up to `limit` items, substring matches first
+ */
+export function rankBy<T>(
+  items: T[],
+  query: string,
+  opts: RankByOptions<T>,
+): T[] {
+  const limit = opts.limit ?? 10;
+  const q = query.trim();
+  if (!q) return items.slice(0, limit);
+
+  const needle = q.toLowerCase();
+  const substring = items.filter((item) =>
+    opts.searchKeys.some((k) =>
+      String(item[k] ?? "")
+        .toLowerCase()
+        .includes(needle),
+    ),
+  );
+
+  let fuzzy: T[] = [];
+  try {
+    const hits: FuzzyMatch<T>[] =
+      getAgent()?.searchInList?.(items, q, { searchKeys: opts.searchKeys }) ??
+      [];
+    fuzzy = hits
+      .filter((h) => (h.score ?? 1) < (opts.plausible ?? PLAUSIBLE))
+      .map((h) => h.item);
+  } catch (err) {
+    console.warn("[foldspace] fuzzy search unavailable:", err);
+  }
+
+  const seen = new Set(substring.map(opts.idOf));
+  const merged = [...substring];
+  for (const item of fuzzy) {
+    const id = opts.idOf(item);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    merged.push(item);
+  }
+  return merged.slice(0, limit);
+}

package/src/runtime/render.ts

@@ -0,0 +1,97 @@
+/**
+ * Unstyled chatterblock states. Tenant brand belongs in `agent/views/`.
+ *
+ * An action's `render` output cannot be typechecked. Look at a frame. Never
+ * use `innerHTML` with API data.
+ */
+
+/**
+ * The `host` argument Foldspace passes to `render`, or `{ container }` from
+ * older tenant helpers. Either works.
+ */
+export type ViewHost = HTMLElement | { container: HTMLElement };
+
+function containerOf(host: ViewHost): HTMLElement {
+  return host instanceof HTMLElement ? host : host.container;
+}
+
+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 replace(host: ViewHost, node: HTMLElement): void {
+  const container = containerOf(host);
+  container.textContent = "";
+  container.appendChild(node);
+}
+
+/**
+ * In-progress chatterblock. Unstyled scaffolding — replace with branded UI
+ * when the card is the experience.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Short status text. Default `"Working..."`.
+ */
+export function renderLoading(host: ViewHost, message = "Working..."): void {
+  replace(host, el("div", "fs-state fs-loading", message));
+}
+
+/**
+ * Nothing matched, but nothing went wrong. Say what was searched for — an empty
+ * panel that does not name the query reads as a failure.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Include the query, e.g. `No estimates matching "Webb"`
+ */
+export function renderEmpty(host: ViewHost, message: string): void {
+  replace(host, el("div", "fs-state fs-empty", message));
+}
+
+/**
+ * Recoverable error: the user can retry or narrow. Pass `ApiResult.error`,
+ * never `detail` — `detail` is the API's own words and is for the console.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Safe, user-facing sentence
+ * @param onRetry - Optional click handler for a "Try again" button
+ */
+export function renderError(
+  host: ViewHost,
+  message: string,
+  onRetry?: () => void,
+): void {
+  const wrap = el("div", "fs-state fs-error");
+  wrap.appendChild(el("p", "fs-error-message", message));
+  if (onRetry) {
+    const btn = el("button", "fs-retry", "Try again") as HTMLButtonElement;
+    btn.addEventListener("click", onRetry);
+    wrap.appendChild(btn);
+  }
+  replace(host, wrap);
+}
+
+/**
+ * Unrecoverable: retrying cannot help (signed out, host refused). Optional
+ * same-tab link — do not open a second tab out of the host app.
+ *
+ * @param host - Foldspace `render` host
+ * @param message - Safe, user-facing sentence
+ * @param action - Optional `{ label, href }` rendered as a same-tab `<a>`
+ */
+export function renderFatal(
+  host: ViewHost,
+  message: string,
+  action?: { label: string; href: string },
+): void {
+  const wrap = el("div", "fs-state fs-fatal");
+  wrap.appendChild(el("p", "fs-error-message", message));
+  if (action) {
+    const a = el("a", "fs-fatal-action", action.label) as HTMLAnchorElement;
+    a.href = action.href;
+    wrap.appendChild(a);
+  }
+  replace(host, wrap);
+}

package/templates/agent-starter/CLAUDE.md

@@ -35,6 +35,8 @@ from actions that read or mutate a selected resource.
 4. Create action metadata as a draft. `generate_action_handler` works from the
    draft schema; do not publish yet.
 5. Implement the handler using the observed request and response shapes.
+   Import helpers from `agent/utils.ts` — inspect that file before writing
+   another `fetch` or rank helper.
 6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
 7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
    the page requires it). An empty local registry is valid if you only want to
@@ -47,8 +49,13 @@ from actions that read or mutate a selected resource.
 
 Actions execute in the user's signed-in browser session.
 
-- Use the same internal APIs as the product page, with
-  `credentials: "include"`.
+- Import HTTP, ranking, and widget helpers from `../utils`, not a new
+  `agent/api.ts` copy of `fetch`.
+- Do not guess `API_BASE` or `AUTH_SOURCE`. Capture at least one real 200
+  (and the auth header the page actually sends) before filling them in.
+  `credentials: "include"` is correct only when you have observed the app
+  using cookies that way. Many apps use `Authorization: Bearer` from
+  `localStorage` instead; some use a custom header.
 - Never guess endpoints or schemas. Capture at least one real 200 before
   implementing a parser. Do not implement a path that was not observed.
 - Verify that the user is signed in before observing a workflow.
@@ -56,7 +63,8 @@ Actions execute in the user's signed-in browser session.
   ask the user to sign in.
 - Validate parameters and return sanitized errors. Return **data only** — never
   `directive`, `instructions`, or a paragraph telling the copilot what to say.
-  Action and agent instructions live in Agent Studio / MCP.
+  Action and agent instructions live in Agent Studio / MCP. Never return
+  `ApiResult.detail` from `execute` — it is for the console.
 - Actions that return data the user will inspect should include a `render`
   function for in-chat UI (a chatterblock). If it makes more sense to output the data
   in a UI component instead of text then consider using render to show a component.
@@ -159,13 +167,40 @@ Do not report success without all six:
 - `agent/actions/` — one handler per action (`execute`, optional `render`),
   registered in `index.ts`
 - `agent/api/` — one HTTP helper per endpoint
-- `agent/constants.ts` — agent, product, and domain identifiers
-- `agent/utils.ts` — Foldspace agent lookup
+- `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
+  `AUTH_SOURCE` and `LOAD_MODE`
+- `agent/utils.ts` — configure the harness runtime and re-export it. **This is
+  the only import surface for actions.**
 - `foldspace.dev.json` — local harness target configuration
 - `docs/app-profile.md` — what is known about this app, and how it was established
 
 Do not introduce another bundler or bundle format.
 
+## What you already have
+
+Import from `../utils`. Inspect that file before implementing another
+general-purpose helper. MCP `generate_action_handler` may still emit a
+skeleton that does not import it — fix the import when you implement.
+
+| Helper | Use when | Do not use when |
+|---|---|---|
+| `apiFetch` / `apiFetchBinary` | The app's own JSON/file API, after a real 200 | Public marketing hosts (`publicFetch`); custom auth headers |
+| `publicFetch` | Unauthenticated / marketing origin | Signed-in product APIs |
+| `getAuthToken` / `parseJwt` | `AUTH_SOURCE` is `localStorage` or `cookie` | Custom header schemes — override `apiFetch` in `utils.ts` |
+| `rankBy` | User typed a name; API search is exact or ignored | Domain ranking (invoices, coverage, MasterFormat) |
+| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock empty/error paths | Branded cards — those stay in `agent/views/` |
+| `getAgent` | Talking to Foldspace | You need a specific instance — then `agentIds()` |
+| `armAllInstances` | Attach/bootstrap setup | Inside `execute` (can ship into `dist`; attach already arms test mode) |
+| `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
+
+If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
+that one function and keep the rest:
+
+```ts
+export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
+export { apiFetch } from "./api";
+```
+
 ## Agent learnings
 
 `docs/app-profile.md` is the durable record of this app. Fill it as you probe,

package/templates/agent-starter/agent/actions/_example.ts

@@ -1,33 +1,28 @@
 // Copy this file to <action_key>.ts and register it in index.ts.
 // Do not register _example — it is not a real Agent Studio action.
+//
+// Import helpers from ../utils, not from @foldspace_npm/harness/runtime.
+// The path below is a placeholder until you capture a real HTTP 200.
+
+import { apiFetch, rankBy } from "../utils";
+
+type Item = { id: string; name: string };
 
 export const example_action = {
-  execute: async (params: { message?: string }) => {
-    const message = typeof params?.message === "string" ? params.message.trim() : "";
-    if (!message) {
-      return { ok: false, error: "message is required" };
-    }
+  execute: async (params: { query?: string }) => {
+    const query = typeof params?.query === "string" ? params.query.trim() : "";
 
-    try {
-      return { ok: true, echo: message };
-    } catch (error) {
-      const detail = error instanceof Error ? error.message : "unknown error";
-      return { ok: false, error: detail };
+    const result = await apiFetch<{ items?: Item[] }>("/__observe_me");
+    if (!result.ok) {
+      return { ok: false, error: result.error };
     }
-  },
 
-  // Optional chatterblock: uncomment to render in-chat UI instead of
-  // returning text-only data. See https://docs.foldspace.ai/guides/in-chat-ui/ for more information. Set
-  // awaitUserInput: true for forms and confirmations.
-  //
-  // render: (data, host, header, callback, cancel) => {
-  //   host.replaceChildren();
-  //   if (data?.ok === false) {
-  //     host.textContent = data.error;
-  //     return;
-  //   }
-  //   const card = document.createElement("div");
-  //   card.textContent = data.echo;
-  //   host.append(card);
-  // },
+    const items = result.data.items ?? [];
+    const matches = rankBy(items, query, {
+      searchKeys: ["name"],
+      idOf: (item) => item.id,
+    });
+
+    return { ok: true, matches };
+  },
 };

package/templates/agent-starter/agent/actions/index.ts

@@ -3,8 +3,16 @@
 // Registration here is the switch: the SDK transmits these to the server, and
 // the server excludes any active action it does not receive. Comment an entry
 // out and the copilot can no longer see it — no unpublishing required.
+//
+// LOAD_MODE "injected" publishes the registry for attach to swap. "embedded"
+// skips that assignment because the host page already loads Foldspace.
+
+import { LOAD_MODE } from "../constants";
 
 const actions = {};
-(window as any).__FOLDSPACE_REMOTE_ACTIONS__ = actions;
+
+if (LOAD_MODE === "injected") {
+  (window as any).__FOLDSPACE_REMOTE_ACTIONS__ = actions;
+}
 
 export default actions;

package/templates/agent-starter/agent/constants.ts

@@ -1,3 +1,28 @@
 export const AGENT_API_NAME = {{AGENT_API_NAME_JSON}};
 export const PRODUCT_ID = {{PRODUCT_ID_JSON}};
 export const APP_DOMAIN = {{APP_DOMAIN_JSON}};
+
+/**
+ * Empty until you capture the app's own XHR. A guessed host looks like it
+ * worked. Include an explicit port if the app uses one.
+ */
+export const API_BASE = "";
+
+/**
+ * Set after observing where the session token lives, for example
+ * `{ kind: "localStorage", name: "access_token" }` or
+ * `{ kind: "cookie", name: "session" }`.
+ *
+ * Custom headers that are not Bearer belong in a local `apiFetch` override —
+ * see CLAUDE.md. Do not guess this value.
+ */
+export const AUTH_SOURCE:
+  | { kind: "localStorage" | "cookie"; name: string }
+  | undefined = undefined;
+
+/**
+ * "injected" assigns `window.__FOLDSPACE_REMOTE_ACTIONS__` so attach can swap
+ * the bundle. "embedded" does not — the page already publishes handlers
+ * through its own SDK snippet.
+ */
+export const LOAD_MODE: "injected" | "embedded" = "injected";

package/templates/agent-starter/agent/utils.ts

@@ -1,15 +1,62 @@
-import { AGENT_API_NAME } from "./constants";
+/**
+ * The seam between this repo and the harness page runtime.
+ *
+ * Actions import helpers from `../utils` (or `./utils`), never from
+ * `@foldspace_npm/harness/runtime` directly. Swapping an implementation —
+ * custom auth headers, a different `apiFetch`, branded loading UI — is a
+ * change to this file and nothing else. `configure` runs once at module load
+ * so `apiFetch` / `getAgent` can read tenant facts without importing
+ * `constants.ts` from the published package.
+ *
+ * ## What `export *` gives you
+ *
+ * HTTP (customer API, from the signed-in page):
+ * - `apiFetch` — JSON + `Authorization: Bearer`. Stop re-exporting this if
+ *   the live app uses cookies, custom headers, or no Bearer (see below).
+ * - `apiFetchBinary` — same auth, raw bytes (file download).
+ * - `publicFetch` — no token; marketing / public origin only.
+ * - `getAuthToken` / `parseJwt` / `redact` — session read and safe logging.
+ * - `mapWithConcurrency` — cap parallel fetches over a list.
+ *
+ * Foldspace SDK (thin wrappers; the SDK is the source of truth):
+ * - `getAgent` — overlay handle for `searchInList` and similar.
+ * - `rankBy` — substring first, then SDK fuzzy match. Not for domain ranking.
+ * - `armAllInstances` — **attach/bootstrap only**, never from `execute`.
+ *   Local `foldspace attach` already arms test mode. Importing this from an
+ *   action can put those SDK calls in the production `dist` bundle.
+ *
+ * Widget chrome (unstyled; replace in `agent/views/` when brand matters):
+ * - `renderLoading` / `renderEmpty` / `renderError` / `renderFatal`
+ *
+ * Config (already called above; you rarely need these in an action):
+ * - `configure` / `getConfig`
+ *
+ * Leave `API_BASE` and `AUTH_SOURCE` empty in `constants.ts` until you capture
+ * a real XHR. Empty config makes `apiFetch` return `{ ok: false }` instead of
+ * guessing a host. Errors are returned, never thrown; show `result.error` in
+ * the widget and log `result.detail` only.
+ *
+ * ## Override example (custom auth — do not guess Bearer)
+ *
+ * ```ts
+ * import { configure, apiFetch as defaultApiFetch, ... } from "@foldspace_npm/harness/runtime";
+ * // After configure(...):
+ * export async function apiFetch<T>(path: string, init: RequestInit = {}) {
+ *   // observe the live request first, then copy its headers here
+ *   return defaultApiFetch<T>(path, { ...init, headers: { ... } });
+ * }
+ * export { getAgent, rankBy, renderEmpty, renderError, renderFatal, renderLoading };
+ * // Do not `export *` if that would re-export the default apiFetch.
+ * ```
+ */
 
-let agent: any | null = null;
+import { configure } from "@foldspace_npm/harness/runtime";
+import { AGENT_API_NAME, API_BASE, AUTH_SOURCE } from "./constants";
 
-export function getAgent(): any | null {
-  if (agent) {
-    return agent;
-  }
+configure({
+  agentApiName: AGENT_API_NAME,
+  apiBase: API_BASE,
+  authSource: AUTH_SOURCE,
+});
 
-  agent = (window as any).foldspace?.agent({
-    apiName: AGENT_API_NAME,
-  });
-
-  return agent;
-}
+export * from "@foldspace_npm/harness/runtime";

package/templates/agent-starter/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
     "module": "ESNext",
     "moduleResolution": "bundler",
     "esModuleInterop": true,