@foldspace_npm/harness 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {

package/templates/agent-starter/CLAUDE.md

@@ -53,6 +53,27 @@ Actions execute in the user's signed-in browser session.
 - 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.
+- 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.
+   - 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).
+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
 
@@ -109,7 +130,8 @@ Do not report success without all six:
 
 ## Layout
 
-- `agent/actions/` — one handler per action, registered in `index.ts`
+- `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

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

@@ -15,4 +15,19 @@ export const example_action = {
       return { ok: false, error: detail };
     }
   },
+
+  // 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);
+  // },
 };