@foldspace_npm/harness 0.1.10 → 0.1.12

package/templates/agent-starter/CLAUDE.md

@@ -1,225 +1,16 @@
-# Foldspace browser actions
+# Foldspace actions for {{APP_DOMAIN}}
 
-## Scope
+@node_modules/@foldspace_npm/harness/CLAUDE.md
 
-This project contains Foldspace action handlers. The customer website, SDK
-snippet, `identify()` call, and layout are out of scope unless the user asks for
-changes there.
+If that import did not resolve, read `node_modules/@foldspace_npm/harness/CLAUDE.md`
+before building. What follows is only what is true of **this** product.
 
-## Before building
+## This product
 
-1. Run `npx foldspace help --json` before an unfamiliar harness operation.
-   Treat its risk, prerequisites, effects, and next-step fields as the current
-   CLI contract.
-2. Connect Product MCP and verify that `list_agents` works.
-3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
-   `list_task_agents`.
-4. Use `discover_actions` to identify candidate experiences, then let the user
-   choose what to build. Treat those ideas as candidates, not an inventory.
+| | |
+|---|---|
+| Agent | `{{AGENT_API_NAME}}` |
+| Product | `{{PRODUCT_ID}}` |
+| App | `{{APP_DOMAIN}}` |
 
-## Build workflow
-
-An experience can require several reusable actions. Separate lookup actions
-from actions that read or mutate a selected resource.
-
-1. Agree on the candidate experience and how its actions would compose. This is
-   not a publish and not a commitment.
-2. Run `npm run inject`. Ask the user to sign in and perform the real target
-   workflow in that Chrome window.
-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. 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.
-   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.
-8. Ask before publishing. Publishing is required only so the copilot can call
-   the action, and it is a live product change when the agent has real users.
-9. Complete the verification gates below.
-
-## API rules
-
-Actions execute in the user's signed-in browser session.
-
-- 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. 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
-
-Use a Task Agent when the handler needs a one-time LLM subtask that
-deterministic code cannot do well: extraction, summarization,
-classification, normalization, enrichment, or generation.
-
-Do not use a Task Agent for API calls, CRUD, routing, or parsing a
-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
-https://docs.foldspace.ai/reference/task-agent-api/
-
-## Local harness loop
-
-```bash
-npm run dev
-npm run inject
-npx foldspace attach --daemon
-```
-
-`inject` launches an isolated Chrome profile and records its debug port.
-It does not generate or load an application extension. Observe the customer's
-workflow after inject and **before** attach, while chrome-devtools MCP can use
-the same Chrome. `attach` prepares the page and loads the local `dist/index.js`
-bundle through CDP. Coding agents must use `--daemon` so the invoking tool
-returns after `[lifecycle] inspect_registration:…`; foreground `npm run attach`
-is for humans watching the terminal. An empty local registry is valid. `npm run
-build` is still required so `dist/index.js` exists.
-
-Use the default swap only when the page already has the configured product and
-agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
-`--replace` when it embeds a different product or agent, or when an SDK is
-present without the configured agent.
-
-The attach log must report `inspect_registration:registration_ok` before
-treating the page as registered. Zero captured actions is success when the
-local registry is empty. On `registration_mismatch`, read
-`npx foldspace help attach --json` diagnostics and map those names onto the
-lifecycle details (`missingActionNames`, `unexpectedActionNames`,
-`diagnosticError`).
-
-While attach is running it owns the debug port. Detach (`attach --stop`, or
-Ctrl-C in the foreground) before using chrome-devtools MCP against the same
-Chrome.
-
-Prove a named action through the visible agent. After the user talks to the
-copilot, read the daemon log for `[actions]` SDK callback and local
-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 `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.
-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. 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, 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,
-not afterwards. Other notes in `docs/` are fine for session-specific lessons.
-
-- 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/`.
-
-## Safety
-
-- Do not commit secrets, cookies, HAR files, browser storage, or
-  `.foldspace-dev/`.
-- Local handler changes are not cloud publication.
-- Creating or publishing Foldspace resources requires explicit approval.
-- Action keys and parameter names must match the published schema.
-- Search Foldspace documentation before asserting unfamiliar platform
-  behaviour.
+Observed API, auth, and account facts for this app live in `docs/app-profile.md`.

package/templates/agent-starter/README.md

@@ -28,7 +28,7 @@ agent/
   utils.ts     Foldspace agent lookup
 docs/          optional notes for coding-agent learnings (create when needed)
 foldspace.dev.json
-CLAUDE.md
+CLAUDE.md          imports platform instructions from the installed harness
 ```
 
 ## Agent learnings

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

@@ -1,6 +1,9 @@
 // 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.
 //
+// This is an empty skeleton. For a finished experience — handler, card with
+// every state, fixtures — read node_modules/@foldspace_npm/harness/recipes/INDEX.md.
+//
 // Import helpers from ../utils, not from @foldspace_npm/harness/runtime.
 // The path below is a placeholder until you capture a real HTTP 200.
 
@@ -14,7 +17,9 @@ export const example_action = {
 
     const result = await apiFetch<{ items?: Item[] }>("/__observe_me");
     if (!result.ok) {
-      return { ok: false, error: result.error };
+      // Pass `reason` through so `render` can call renderFailure — an expired
+      // session, a 404 and a throttled call are three different widget states.
+      return { ok: false, error: result.error, reason: result.reason };
     }
 
     const items = result.data.items ?? [];
@@ -23,6 +28,8 @@ export const example_action = {
       idOf: (item) => item.id,
     });
 
-    return { ok: true, matches };
+    // Zero matches is an answer, not an error. Return the query so the empty
+    // state can name what was searched for.
+    return { ok: true, query, matches };
   },
 };

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

@@ -27,6 +27,8 @@
  *
  * Widget chrome (unstyled; replace in `agent/views/` when brand matters):
  * - `renderLoading` / `renderEmpty` / `renderError` / `renderFatal`
+ * - `renderFailure` — picks one of those from `ApiFailure.reason`, so an expired
+ *   session, a 404 and a throttled call each draw the right state.
  *
  * Config (already called above; you rarely need these in an action):
  * - `configure` / `getConfig`