@foldspace_npm/harness 0.1.8 → 0.1.10

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,