@foldspace_npm/harness 0.1.5 → 0.1.7

package/README.md

@@ -138,6 +138,11 @@ The generated npm scripts intentionally remain the normal project interface;
   has an SDK without the configured agent.
 
 Use `foldspace help attach` for mode requirements, effects, and safety options.
+Coding agents should run `foldspace attach --daemon` so the invoking tool
+returns after `[lifecycle] inspect_registration:…`. Foreground attach remains
+the default for humans watching the terminal. `attach --status` and
+`attach --stop` inspect and tear down a daemon. Observe customer-app network
+traffic after `inject` and before attach; attach owns the debug port.
 
 ### Verify actions through the agent
 
@@ -172,6 +177,7 @@ npm i -D @foldspace_npm/harness
     "build":  "foldspace build",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
+    "attach:daemon": "foldspace attach --daemon",
     "deploy": "foldspace deploy"
 } }
 ```

package/bin/attach.mjs

@@ -1012,7 +1012,7 @@ async function cleanup() {
   return result;
 }
 
-process.on("SIGINT", () => {
+function requestDetach() {
   if (shuttingDown) return;
   shuttingDown = true;
   void cleanup().finally(() => {
@@ -1020,7 +1020,10 @@ process.on("SIGINT", () => {
     console.log(`\nDetached. Served the local bundle ${served} time(s).`);
     process.exit(0);
   });
-});
+}
+
+process.on("SIGINT", requestDetach);
+process.on("SIGTERM", requestDetach);
 
 // A closed socket does not mean the browser closed. Chrome drops the CDP
 // connection on target churn and transient errors too, and exiting on those

package/bin/cli.mjs

@@ -5,6 +5,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import {
+  classifyAttachControl,
+  runAttachControl,
+} from "../src/attach-daemon.mjs";
 import {
   CLI_COMMANDS,
   createCliRegistry,
@@ -151,10 +155,32 @@ if (!command || command === "--help" || command === "-h") {
   } else {
     try {
       const definition = commandByName(command);
-      runScript(
-        definition.entry,
-        normalizeCommandArgs(definition, args),
-      );
+      const normalized = normalizeCommandArgs(definition, args);
+      if (command === "attach") {
+        const control = classifyAttachControl(normalized);
+        if (control) {
+          Promise.resolve()
+            .then(() =>
+              runAttachControl(control, normalized, {
+                attachScript: path.join(here, definition.entry),
+                spawnFn: spawn,
+              }),
+            )
+            .then((report) => {
+              console.log(JSON.stringify(report, null, 2));
+              if (control === "daemon" && report.ok === false) {
+                process.exitCode = 1;
+              }
+            })
+            .catch((error) => {
+              fail(error instanceof Error ? error.message : String(error));
+            });
+        } else {
+          runScript(definition.entry, normalized);
+        }
+      } else {
+        runScript(definition.entry, normalized);
+      }
     } catch (error) {
       fail(error instanceof Error ? error.message : String(error));
     }

package/package.json

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

package/src/attach-daemon.mjs

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const ATTACH_DAEMON_ENV = "FOLDSPACE_ATTACH_DAEMON";
+export const ATTACH_DAEMON_STATE_FILE = "attach-daemon.json";
+export const ATTACH_DAEMON_LOG_FILE = "attach-daemon.log";
+
+const CONTROL_FLAGS = ["--daemon", "--status", "--stop"];
+const LIFECYCLE_PATTERN =
+  /\[lifecycle\] inspect_registration:(registration_ok|registration_mismatch)/g;
+
+export function projectRoot(env = process.env, cwd = process.cwd()) {
+  return env.FOLDSPACE_PROJECT_DIR || cwd;
+}
+
+export function daemonPaths(root) {
+  const dir = path.join(root, ".foldspace-dev");
+  return {
+    dir,
+    stateFile: path.join(dir, ATTACH_DAEMON_STATE_FILE),
+    logFile: path.join(dir, ATTACH_DAEMON_LOG_FILE),
+  };
+}
+
+export function isProcessAlive(pid, killFn = process.kill) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    killFn(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function classifyAttachControl(args) {
+  const selected = CONTROL_FLAGS.filter((flag) => args.includes(flag));
+  if (selected.length > 1) {
+    throw new Error("--daemon, --status, and --stop cannot be used together");
+  }
+  if (selected[0] === "--daemon") return "daemon";
+  if (selected[0] === "--status") return "status";
+  if (selected[0] === "--stop") return "stop";
+  return null;
+}
+
+export function childAttachArgs(args) {
+  return args.filter((token) => !CONTROL_FLAGS.includes(token));
+}
+
+export function parseRegistrationLifecycle(logText) {
+  let last = null;
+  const matches = String(logText ?? "").matchAll(LIFECYCLE_PATTERN);
+  for (const match of matches) {
+    last = {
+      state: match[1],
+      ok: match[1] === "registration_ok",
+    };
+  }
+  return last;
+}
+
+export function readDaemonState(root) {
+  const { stateFile } = daemonPaths(root);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeDaemonState(root, state) {
+  const { dir, stateFile } = daemonPaths(root);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function clearDaemonState(root) {
+  const { stateFile } = daemonPaths(root);
+  try {
+    fs.unlinkSync(stateFile);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function waitForRegistration({
+  logFile,
+  pid,
+  attempts = 60,
+  intervalMs = 250,
+  readFile = fs.readFileSync,
+  isAlive = isProcessAlive,
+  delay = sleep,
+} = {}) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let text = "";
+    try {
+      text = readFile(logFile, "utf8");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+    const registration = parseRegistrationLifecycle(text);
+    if (registration) return registration;
+    if (!isAlive(pid)) {
+      throw new Error(
+        `Attach daemon exited before inspect_registration. Check ${logFile}`,
+      );
+    }
+    await delay(intervalMs);
+  }
+  throw new Error(
+    `Attach daemon did not report inspect_registration. Check ${logFile}`,
+  );
+}
+
+export function liveDaemon(root, isAlive = isProcessAlive) {
+  const state = readDaemonState(root);
+  if (!state?.pid || !isAlive(state.pid)) return null;
+  return state;
+}
+
+function daemonReport(state, extra = {}) {
+  let logText = "";
+  if (state?.logPath) {
+    try {
+      logText = fs.readFileSync(state.logPath, "utf8");
+    } catch {
+      logText = "";
+    }
+  }
+  const registration = parseRegistrationLifecycle(logText);
+  return {
+    daemon: true,
+    pid: state?.pid ?? null,
+    logPath: state?.logPath ?? null,
+    ...(registration
+      ? { ok: registration.ok, registration: registration.state }
+      : {}),
+    ...extra,
+  };
+}
+
+export async function stopAttachDaemon({
+  root,
+  killFn = process.kill,
+  isAlive = isProcessAlive,
+  delay = sleep,
+  attempts = 20,
+  intervalMs = 100,
+} = {}) {
+  const state = readDaemonState(root);
+  if (!state?.pid || !isAlive(state.pid)) {
+    clearDaemonState(root);
+    return { daemon: true, stopped: true, pid: state?.pid ?? null, reused: false };
+  }
+
+  try {
+    killFn(state.pid, "SIGTERM");
+  } catch (error) {
+    if (error?.code !== "ESRCH") throw error;
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (!isAlive(state.pid)) break;
+    await delay(intervalMs);
+  }
+  if (isAlive(state.pid)) {
+    try {
+      killFn(state.pid, "SIGKILL");
+    } catch (error) {
+      if (error?.code !== "ESRCH") throw error;
+    }
+  }
+
+  clearDaemonState(root);
+  return { daemon: true, stopped: true, pid: state.pid };
+}
+
+export async function startAttachDaemon({
+  root,
+  attachScript,
+  args,
+  spawnFn,
+  env = process.env,
+  wait = waitForRegistration,
+  isAlive = isProcessAlive,
+  killFn = process.kill,
+} = {}) {
+  const existing = liveDaemon(root, isAlive);
+  if (existing) {
+    return daemonReport(existing, { reused: true, alive: true });
+  }
+
+  const stale = readDaemonState(root);
+  if (stale) clearDaemonState(root);
+
+  const paths = daemonPaths(root);
+  fs.mkdirSync(paths.dir, { recursive: true });
+  fs.writeFileSync(paths.logFile, "");
+  const logFd = fs.openSync(paths.logFile, "a");
+  let child;
+  try {
+    child = spawnFn(process.execPath, [attachScript, ...childAttachArgs(args)], {
+      detached: true,
+      env: { ...env, [ATTACH_DAEMON_ENV]: "1" },
+      stdio: ["ignore", logFd, logFd],
+    });
+  } finally {
+    fs.closeSync(logFd);
+  }
+  if (typeof child.unref === "function") child.unref();
+
+  const state = {
+    pid: child.pid,
+    startedAt: new Date().toISOString(),
+    logPath: paths.logFile,
+  };
+  writeDaemonState(root, state);
+
+  try {
+    const registration = await wait({
+      logFile: paths.logFile,
+      pid: child.pid,
+      isAlive,
+    });
+    return daemonReport(state, {
+      reused: false,
+      ready: true,
+      ok: registration.ok,
+      registration: registration.state,
+    });
+  } catch (error) {
+    if (isAlive(child.pid)) {
+      try {
+        killFn(child.pid, "SIGTERM");
+      } catch {
+        // Best-effort: the wait error is what the caller should see.
+      }
+    }
+    clearDaemonState(root);
+    throw error;
+  }
+}
+
+export async function runAttachControl(control, args, options = {}) {
+  const root = options.root ?? projectRoot(options.env);
+  const isAlive = options.isAlive ?? isProcessAlive;
+  if (control === "status") {
+    const state = readDaemonState(root);
+    if (!state) {
+      return { daemon: false, alive: false, pid: null, logPath: null };
+    }
+    return daemonReport(state, {
+      reused: true,
+      alive: Boolean(state.pid && isAlive(state.pid)),
+    });
+  }
+  if (control === "stop") {
+    return stopAttachDaemon({ root, isAlive, killFn: options.killFn });
+  }
+  return startAttachDaemon({ root, args, isAlive, ...options });
+}

package/src/cli-registry.mjs

@@ -118,7 +118,7 @@ export const CLI_COMMANDS = Object.freeze([
       "Otherwise creates an isolated profile and writes .foldspace-dev/state.json",
       "Does not load the SDK or action artifact",
     ],
-    next: ["Sign in to the target application", "Run foldspace attach"],
+    next: ["Sign in to the target application", "Observe the real workflow, or run foldspace attach"],
   }),
   Object.freeze({
     name: "attach",
@@ -127,7 +127,7 @@ export const CLI_COMMANDS = Object.freeze([
     summary:
       "Load local actions over CDP and observe the normal agent experience",
     usage:
-      "foldspace attach [--bootstrap | --replace] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
+      "foldspace attach [--bootstrap | --replace] [--daemon | --status | --stop] [--target <name>] [--port <number>] [--agent <api-name>] [--no-test-mode] [--no-badge]",
     risk: "browser-session",
     environment: "local-chrome",
     environmentVariables: [
@@ -178,6 +178,12 @@ export const CLI_COMMANDS = Object.freeze([
         "Do not mark conversations as test traffic; use deliberately",
       ),
       flag("--no-badge", "Hide the visible Foldspace development badge"),
+      flag(
+        "--daemon",
+        "Start attach in the background and return after inspect_registration",
+      ),
+      flag("--status", "Print whether the attach daemon is running"),
+      flag("--stop", "Stop the attach daemon and restore prepared pages"),
     ],
     prerequisites: [
       "foldspace.dev.json",
@@ -191,13 +197,15 @@ export const CLI_COMMANDS = Object.freeze([
       "Never directly invokes an action handler",
       "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
+      "--daemon returns after inspect_registration and keeps CDP in a child process",
     ],
     next: [
+      "Coding agents should use foldspace attach --daemon so the invoking tool returns",
       "Exercise the visible agent normally",
-      "Confirm [lifecycle] inspect_registration:registration_ok",
+      "Confirm [lifecycle] inspect_registration:registration_ok in the terminal or daemon log",
       "On mismatch, read foldspace help attach --json diagnostics and the lifecycle details",
-      "Confirm execute/render observations when verifying a named action",
-      "Detach with Ctrl-C",
+      "After a named action, read [actions] execute/render lines from the attach log",
+      "Detach with Ctrl-C, or foldspace attach --stop for a daemon",
     ],
   }),
   Object.freeze({
@@ -308,6 +316,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "Action verification is passive and agent-driven.",
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
+      "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
     ],
   };
 }

package/templates/agent-starter/CLAUDE.md

@@ -15,22 +15,31 @@ changes there.
 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.
+   choose what to build. Treat those ideas as candidates, not an inventory.
 
 ## 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 experience and how its actions compose.
-2. Create the action metadata as a draft.
-3. Ask before publishing when the agent has real users; publishing is a live
-   product change.
-4. Observe the real target workflow and capture its browser requests.
-5. Generate the typed handler skeleton from the published action schema.
-6. Implement the handler using the observed request and response shapes.
-7. Register the handler in `agent/actions/index.ts`.
-8. Complete the verification gates below.
+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.
+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.
+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
 
@@ -38,26 +47,50 @@ Actions execute in the user's signed-in browser session.
 
 - Use the same internal APIs as the product page, with
   `credentials: "include"`.
-- Never guess endpoints or schemas. Capture at least one real request and
-  response before implementing a parser.
+- 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.
+- 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
 
 ```bash
 npm run dev
 npm run inject
-npm run attach
+npx foldspace attach --daemon
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port.
-It does not generate or load an application extension. `attach` prepares the
-page and loads the local `dist/index.js` bundle through CDP. An empty local
-registry is valid: attach before implementing handlers to see how the agent
-works. `npm run build` is still required so `dist/index.js` exists.
+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
@@ -71,8 +104,15 @@ local registry is empty. On `registration_mismatch`, read
 lifecycle details (`missingActionNames`, `unexpectedActionNames`,
 `diagnosticError`).
 
-Prove a named action through the visible agent and require both an SDK action
-callback and local execute/render evidence; do not invoke the handler directly.
+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.
 
 ## Verification gates
 
@@ -82,13 +122,16 @@ Do not report success without all six:
 2. The expected handler appears in `dist/index.js`.
 3. 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.
+4. 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.
 6. Browser evidence came from the live target, not from hand-authored examples.
 
 ## 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/README.md

@@ -50,12 +50,17 @@ npm run build    # create dist/index.js
 npm run dev      # rebuild dist/index.js on changes
 npm run inject   # launch the dedicated Chrome profile
 npm run attach   # load local actions and observe the agent over CDP
+npm run attach:daemon  # same, but return after inspect_registration
 ```
 
 Run `inject` before `attach`. Sign in to the product in the Chrome window that
-`inject` opens. `inject` does not generate an application extension; `attach`
-loads `dist/index.js` directly through CDP. An empty local registry is valid,
-so you can attach before implementing handlers.
+`inject` opens. Observe the real product workflow in that window **before**
+attach if you need customer API evidence; `attach` owns the debug port.
+`inject` does not generate an application extension; `attach` loads
+`dist/index.js` directly through CDP. An empty local registry is valid,
+so you can attach before implementing handlers. Coding agents should use
+`attach --daemon` (or `npm run attach:daemon`) so the command returns after
+registration instead of occupying the terminal.
 
 Choose the attach mode from the state of the target page:
 
@@ -69,10 +74,13 @@ agents can read the versioned contract with `npx foldspace help --json`.
 
 ## Add an action
 
-1. Define and publish the action in Agent Studio or through Product MCP.
-2. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
-3. Implement the handler from observed browser API evidence.
-4. Import and register the handler in `agent/actions/index.ts`.
-5. Type-check, rebuild, attach, and verify it in the target product.
+1. Observe the real product workflow in the inject Chrome and capture a real
+   200 for the API the action will call.
+2. Create the action as a draft in Agent Studio or through Product MCP.
+3. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
+4. Implement the handler from that observed request and response.
+5. Import and register the handler in `agent/actions/index.ts`.
+6. Type-check, rebuild, `attach --daemon`, and verify it through the visible
+   agent. Publish only when the copilot must call the action.
 
-Action keys and parameter names must exactly match the published action schema.
+Action keys and parameter names must exactly match the action schema.

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);
+  // },
 };

package/templates/agent-starter/package.json

@@ -8,7 +8,8 @@
     "dev": "foldspace build --watch",
     "build": "foldspace build",
     "inject": "foldspace inject",
-    "attach": "foldspace attach"
+    "attach": "foldspace attach",
+    "attach:daemon": "foldspace attach --daemon"
   },
   "devDependencies": {
     "@foldspace_npm/harness": "{{HARNESS_VERSION}}",