@foldspace_npm/harness 0.1.7 → 0.1.9

package/templates/agent-starter/CLAUDE.md

@@ -29,11 +29,15 @@ from actions that read or mutate a selected resource.
 3. Capture at least one real HTTP 200 for the data the action needs. Use
    chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
    **before** `attach` owns the debug port. If there is no 200,
-   pivot; do not create Foldspace resources.
+   pivot; do not create Foldspace resources. Write what you establish into
+   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
+   by quoting that file.
 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.
-6. Register the handler in `agent/actions/index.ts` and build.
+   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
    see how the agent works.
@@ -45,17 +49,30 @@ 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.
 - Do not substitute a public developer API when the browser session is missing;
   ask the user to sign in.
-- Validate parameters and return sanitized errors.
+- 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. 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.
+   - `render` receives **`execute`'s return value**, not the action's input params.
+     Returning anything that lacks the ids the card needs is why widgets pass in
+     isolation and fail in the real chat.
+   - `runAction` refuses render actions (`cannot be executed silently`). Driving
+     `render()` yourself never runs `execute()`, so it does not test that contract.
    - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
 
 ## Task agents
@@ -70,6 +87,7 @@ known response shape. Those stay in `execute`.
 Task agents are created in Agent Studio, not in this repo. Ask before
 creating or publishing one. Call a published task agent from the
 handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
+`data` carries extracted facts only — not `prompt` / `instructions` strings.
 Prefer JSON output when the handler must consume the result.
 
 See https://docs.foldspace.ai/user-guides/task-agents/ and
@@ -114,42 +132,85 @@ execute/render lines; do not invoke the handler directly. Those lines record
 names, statuses, durations, and parameter keys only — not results or error
 bodies.
 
+## Product defaults
+
+These are not Joist-specific. Lint can catch some of them in handler code;
+Agent Studio copy is on you.
+
+- **No emoji** in copilot replies, cards, or handler strings. Put that in the
+  agent's Behavior instructions (MCP cannot write that field, so each new
+  action's Studio `instructions` must carry the line too).
+- **Never send the user out of the host app.** No "open in <product>"
+  button and no pasted URLs — navigate with a navigation route, same tab.
+- **Check row counts before choosing the experience.** On an empty account the
+  useful first action is one that creates data.
+
 ## Verification gates
 
 Do not report success without all six:
 
-1. TypeScript compiles with `npx tsc --noEmit -p tsconfig.json`.
-2. The expected handler appears in `dist/index.js`.
-3. The browser reports `inspect_registration:registration_ok`. For a named
+1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
+   Do not run `npx tsc` — that can install the wrong package.
+2. `foldspace lint` reports no errors (`foldspace build` runs this first).
+3. The expected handler appears in `dist/index.js`.
+4. The browser reports `inspect_registration:registration_ok`. For a named
    action, the captured registry includes that handler.
-4. The action behaves correctly against the real target workflow. Confirm
+5. The action behaves correctly against the real target workflow. Confirm
    `[actions] local-handler:execute` in the attach log after the user exercises
-   the visible agent.
-5. Existing neighbouring action fixtures still pass when fixtures exist.
+   the visible agent. For a widget, that log must include `local-handler:render`
+   from a real chat turn — not a hand-built `render()` call.
 6. Browser evidence came from the live target, not from hand-authored examples.
+   Neighbour fixtures still pass when they exist.
 
 ## Layout
 
 - `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/` — optional coding-agent learnings; create on demand
+- `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
 
-Use `docs/` to record durable, repository-specific lessons so later sessions do
-not repeat the same mistakes.
+`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
+not afterwards. Other notes in `docs/` are fine for session-specific lessons.
 
-- Before similar work, read any relevant notes already in `docs/`.
-- After non-obvious discoveries, add a short note covering verified gotchas,
-  failed approaches, design rationale, or useful verification commands.
-- Keep notes concise and evidence-based. Create `docs/` when the first note is
-  useful; do not leave an empty directory.
+- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
+- After non-obvious discoveries, add them to the profile (or a short extra
+  note) covering verified gotchas, failed approaches, and how they were
+  established.
+- Keep notes concise and evidence-based.
 - Do not store secrets, cookies, HAR files, browser storage, or other transient
   session data in `docs/`.
 

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/docs/app-profile.md

@@ -0,0 +1,109 @@
+# {{DISPLAY_NAME}} — app profile
+
+Durable facts about `{{APP_DOMAIN}}` and its API, established by observing the
+running app on **<date>** from a logged-in session.
+
+**Everything here should be observed.** Each entry says how. Where something is
+only believed, say so in the same breath — do not promote an assumption by
+quoting this file. Re-run the probe before trusting an entry that matters.
+
+Do not store secrets, cookies, HAR files, tokens, or session data here. Record
+*where* the token lives and *what a redacted value looks like*, never the value.
+
+How to re-run any probe below:
+
+```bash
+npm run inject
+# Sign in. Capture from chrome-devtools MCP, or a page-context fetch,
+# before foldspace attach owns the debug port.
+```
+
+Start URL: `{{START_URL}}`
+
+---
+
+## Auth
+
+- Where the token lives (cookie name, `localStorage` key, custom header), and
+  how you know — wrapping XHR/`fetch` on the live page beats guessing.
+- Its lifetime, measured. (One app's expired in ~52 minutes and killed three
+  probing sessions.)
+- What an expired or refused response looks like, verbatim. A CORS-less refusal
+  often surfaces as `TypeError: Failed to fetch` with no status — that is not
+  "host down".
+- Anything inherited but never exercised — mark it **assumed**.
+
+## API base
+
+- The exact base, including any explicit port. Note if omitting `:443` fails
+  CORS, and whether the API is a **different host** from the app (a relative
+  path then returns the HTML shell).
+
+## Account contents
+
+Row counts from the signed-in account **before** choosing the experience. On an
+empty account the only useful first action is one that creates data.
+
+| Resource | Count | How established |
+|---|---|---|
+| | | |
+
+## Endpoints called and observed
+
+For each: the path, the **envelope**, the row keys you actually read, and how
+you established them.
+
+> Watch for endpoints on the same host that wrap the same resource
+> differently (`{data}` vs `{contacts}` vs `{items}`). Reaching for the wrong
+> key yields `undefined`, not an empty array — it throws downstream rather
+> than returning nothing.
+
+| Path | Method | Envelope | Verified |
+|---|---|---|---|
+| | | | |
+
+## Verified behaviour
+
+A table of probe → result. Paging, search, sort, filters. One row per call you
+actually made.
+
+**What the search matches.** Test prefix, mid-word, case, digits, across spaces,
+and one transposed letter. Most app search is a plain case-insensitive substring
+with no tolerance.
+
+> A probe using values no record has proves nothing. If a filter returns zero,
+> confirm a matching record exists before concluding anything.
+
+| Probe | Result |
+|---|---|
+| | |
+
+## Vocabulary observed
+
+Real enum values seen on live records — not the generic ones you would expect.
+Mark which you verified and which came from reading the app bundle.
+
+## Identifiers
+
+| Identifier | Produced by | Example |
+|---|---|---|
+| | | |
+
+## Brand (sampled, not guessed)
+
+Colour, typeface, greys, base size and radii from the running app's computed
+styles — not from a screenshot. Re-sample per tenant; do not carry values
+across.
+
+## Endpoints seen in the bundle but NOT called
+
+Listed so the next person knows they exist **and knows they are unverified**.
+
+## Failures observed
+
+| Call | Result | What it means |
+|---|---|---|
+| | | |
+
+Record inconclusive results as inconclusive. A 401 on a dead session says
+nothing about whether the endpoint works.

package/templates/agent-starter/package.json

@@ -7,6 +7,8 @@
   "scripts": {
     "dev": "foldspace build --watch",
     "build": "foldspace build",
+    "lint": "foldspace lint",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
     "attach:daemon": "foldspace attach --daemon"

package/templates/agent-starter/tsconfig.json

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