@foldspace_npm/harness 0.1.30 → 0.1.32

package/CLAUDE.md

@@ -29,9 +29,9 @@ session ends at something they can **see on their own page** - not at
 
    | Result | Do |
    |---|---|
-   | The tool does not exist | The Foldspace MCP is not installed in this editor. Install it yourself, the one way that fits *this* region and editor. **EU** - any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** - Claude Code with git on the machine (`command -v git`): `claude plugin marketplace add https://github.com/foldspace-ai/plugins` (already added, or added from another source, is fine), then `claude plugin install foldspace-agent-builder@foldspace-plugins`; without git, or any other editor: the MCP block on <https://foldspace.ai/agents.md>. Either way it needs sign-in: start it before your turn ends, as **Connect Foldspace tools** on that page says. **The plugin** loads when your turn ends: call `list_agents` again on the human's next message. **A server added from the MCP block** (`claude mcp add`) never reaches a chat that is already running - not on the next message, not through `/mcp`: once it is signed in, the human opens a new chat in this folder and repeats their request. `claude mcp get` saying Connected proves only the setting; the check is `list_agents` in the chat you are in |
-   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where - Claude Code: `/mcp` → **foldspace-eu** (**EU**) or **foldspace** (**US**; listed as `plugin:foldspace-agent-builder:foldspace` when the plugin installed it) → finish in the browser - then check again. If `/mcp` does not list that server, it was added after this chat started: the human opens a new chat in this folder, as above |
-   | It returns agents | One agent: state its name, Agent Key and product in a line and carry on; the human objects if it is wrong. Several: ask which, as a choice |
+   | The tool does not exist | The Foldspace MCP is not installed in this editor. Install it yourself, the one way that fits *this* region and editor. **EU** - any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** - Claude Code with git on the machine (`command -v git`): `claude plugin marketplace add https://github.com/foldspace-ai/plugins` (already added, or added from another source, is fine), then `claude plugin install foldspace-agent-builder@foldspace-plugins`; without git, or any other editor: the MCP block on <https://foldspace.ai/agents.md>. Either way it needs sign-in: start it before your turn ends, as **Connect Foldspace tools** on that page says. **The plugin** loads when your turn ends: call `list_agents` again on the human's next message. **A server added from the MCP block** (`claude mcp add`) never reaches a chat that is already running - not on the next message, not through `/mcp`: once it is signed in, the human opens a new chat in this folder and repeats their request. `claude mcp get` saying Connected proves only the setting; the check is `list_agents` in the chat you are in. **Codex**: `codex mcp add foldspace --url https://api.foldspace.ai/mcp` (**EU**: `foldspace-eu` and `https://api.eu.foldspace.ai/mcp`) adds it and starts sign-in in one step; a server added during a thread never reaches that thread, so once it is signed in the work continues in a new thread in this folder: start it yourself if Codex gives you a tool for it - the human's request word for word, plus the one paragraph the playbook's Codex block gives - and say so in one line; otherwise the human starts it and repeats their request. **Cursor**: merge the server into `~/.cursor/mcp.json` yourself, keeping every other server; it reaches this chat on the human's next message, needing sign-in. **Any editor**: never read a saved sign-in or credentials file, and never reach the Foldspace MCP any other way (curl, a script, a client you write). If its tools are not in this chat, the fix is a new chat |
+   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where - Claude Code: `/mcp` → **foldspace-eu** (**EU**) or **foldspace** (**US**; listed as `plugin:foldspace-agent-builder:foldspace` when the plugin installed it) → finish in the browser - then check again. If `/mcp` does not list that server, it was added after this chat started: the human opens a new chat in this folder, as above. Codex: run `codex mcp login foldspace` (`foldspace-eu` for **EU**) - if the browser does not open, give the human the link it prints - then a new thread. Cursor: call the server's own sign-in tool, `mcp_auth`, yourself - the human finishes in the browser - then `list_agents` in this same chat |
+   | It returns agents | Work on the agent whose Agent Key this project has (`agentApiName` in `foldspace.dev.json`). Name it in one line - name, Agent Key and product - and carry on; the human objects if it is wrong. Skip that line when the setup playbook (agents.md) already named it in this chat. When no agent has that key, this account cannot see this project's agent: tell the human which Agent Key the project is for, and that they type `/mcp`, pick that server, and sign in as the account that has it; then check again. Never work on another agent from this folder - one the human wants instead gets a folder of its own (agents.md, from **Confirm the signed-in account**) |
 
 3. **Orient** — `get_agent_settings`, `list_actions`, `list_task_agents`,
    `list_navigation_routes`. Record current versions before changing anything;
@@ -39,17 +39,26 @@ session ends at something they can **see on their own page** - not at
    seeded at sign-up are often a specification someone already wrote.
 4. **Read `docs/app-profile.md`.** It is what is already known about this app,
    with how each fact was established.
-5. **Does the agent already have code saved in Foldspace?** If your Foldspace
-   tools include `repo_read`, call it with command `status` now - before the
-   first build, because the first build is what the test window shows them.
+5. **Does the agent already have code saved in Foldspace?** If the setup
+   playbook (agents.md) ran in this chat, it already asked: use its answer in
+   the list below, and do not tell the human again what setup told them. If
+   setup also set this folder up and found a code project, the project's
+   `agent/` is already here - do not replace it again. Otherwise, if your
+   Foldspace tools include `repo_read`, call it with command `status` now -
+   before the first build, because the first build is what the test window
+   shows them.
    - **A code project.** Call `repo_read` with command `instructions` and
      follow what it returns. The project's `agent/` is the copy Foldspace
      builds and publishes, and it may hold work someone else saved. Before you
      build, replace this folder's `agent/` with it (`repo_read` commands `tree`
-     and `file`): delete what is there rather than copying over the top, or
-     their page shows the template instead of their agent. An action file here
-     that the project lacks is work a session never saved: keep it aside and
-     put it back after.
+     and `file`, with the `ref` the instructions name - the default can be
+     older than what someone saved): delete what is there rather than copying
+     over the top, or their page shows the template instead of their agent.
+     This folder's `agent/` may hold work a session never saved, so copy it to
+     `.foldspace-dev/agent-kept/` first. Put back the action files the project
+     lacks; where a file differs, the project's wins. If any differed, tell
+     the human in one line which actions had changes on this computer that
+     were never saved.
    - **`NO_REPO`.** Nothing is saved yet. Follow the next step `status` gives:
      it creates the code project in about a minute and changes nothing anyone
      sees - say you are setting up their project, no need to ask. Get the agent
@@ -73,6 +82,12 @@ session ends at something they can **see on their own page** - not at
    - **No `repo_read` tool.** This folder is the only copy, so there is no code
      project.
 
+   With a code project, a published action (step 3, `isPublished: true`)
+   whose handler `agent/actions/index.ts` does not register has its code
+   somewhere else - on someone's computer, or in their product's own code.
+   When you ask to publish for their users, name it and say it may stop
+   working once this project is published, because its code is not in it.
+
 Before an unfamiliar harness operation, `npx foldspace help --json` is the
 current CLI contract — risk, prerequisites, effects, next step.
 
@@ -153,6 +168,10 @@ steps in **Done, and what you say at the end**:
    Behavior instructions (Agent Studio → **Style & Behavior** → **Behavior &
    Responses**). No Foldspace tool writes those, so it is theirs to add: on a
    yes, give them the line to paste and where it goes.
+6. **A short video of it to share** - the `share-a-video` skill, in
+   `.claude/skills/share-a-video/SKILL.md` (any other editor: read
+   `node_modules/@foldspace_npm/harness/templates/agent-starter/skills/share-a-video/SKILL.md`).
+   Ask it as its own question next to the choice - a choice holds four options.
 
 Not before the first experience: nothing about it needs any of these, and it
 is silent work before the human has seen anything.
@@ -162,7 +181,7 @@ Uploads and extraction are a later session.
 ### Ask as a choice, and ask almost nothing
 
 Every question to the human is an **enumerated choice with the recommended
-option first** (in Claude Code, `AskUserQuestion`). A first session asks only
+option first** (in Claude Code, `AskUserQuestion`; elsewhere, the editor's own question tool), asked once - not repeated in your message. A first session asks only
 this: which agent (only if several), the app's hostname, which experience
 first - and a yes wherever this manual asks for one, such as agreeing the
 experience (below), upgrading, publishing an action, task agent or
@@ -794,6 +813,18 @@ import is right.
   `Bash(npx foldspace observe:*)` - and meanwhile hand that step to them: for
   a chat turn, that is them typing the question into the panel. `init`,
   `upgrade` and `deploy` ask on purpose: never give an allow rule for them.
+- **A sandbox error is not a refusal.** Some editors (Codex) run your commands
+  in a sandbox: no network, and no writes outside this folder, unless the
+  human approves that one command. There `npm`, `npx foldspace`, `inject` and
+  anything that reaches the test window fail with errors that look like
+  something else - a host that cannot be resolved, `EPERM` in npm's cache,
+  `listen EPERM`, Chrome quitting, or *the test window is closed*. Ask to run
+  that same command outside the sandbox through the editor's own approval,
+  with one plain line on why; that approval is not a retry. Never move npm's
+  cache, change file ownership, or have the human run the command instead.
+  An approval can expire when the human sends a new message, so after one,
+  the same errors mean ask again - not that the window closed. If the human
+  declines, that is a refusal: the rule above applies.
 - **Never create an account or a key** - not in Foldspace, not in the
   customer's product, not anywhere. If one is missing, say which and where it
   goes. **Never widen your own access**: if something is refused for a site or

package/README.md

@@ -125,8 +125,16 @@ project loads (`sdkUrl`): each region has its own build, pointing at that
 region's servers. A project with no `region` is US. The values per region live
 in `src/region.mjs`.
 
-For safety, `init` requires a target path that does not exist. It does not
-initialize Git or overwrite files. On a TTY it can offer
+For safety, `init` sets up a new folder, or fills one that holds nothing but
+what the system or an editor put there (`.DS_Store`, `.localized`, `Icon\r`,
+`._*`, `Thumbs.db`, `desktop.ini`, `.mcp.json`, and the folders `.git/`,
+`.vscode/`, `.cursor/`, `.idea/`, and `.claude/` without `settings.json`). It
+leaves those as they are and refuses anything else, including an existing
+Foldspace project. It never fills the home directory or its Desktop, Documents
+or Downloads, the disk's root, or the folder Claude Code Desktop makes for a
+session started with no folder (under `scratch-workspaces`), or Codex's folder
+for chats with no project (`~/Documents/Codex`) and each chat's folder in it,
+even when they are empty. It never overwrites a file and does not initialize Git. On a TTY it can offer
 `npm install --ignore-scripts` after scaffolding. After creation:
 
 ```bash
@@ -314,6 +322,21 @@ Without attach, `ask` still reports the reply, the card text and a
 screenshot; `handler.execute` and `handler.render` read "not tracked here
 (published code)".
 
+### Make a short video to share
+
+`npx foldspace record` shows the agent's key use cases, from
+`video/scenes.json`: an opening card meets the product's agent, then each
+question is asked in the test window, typed in a new conversation, with a
+caption once it is answered - the Foldspace features it shows as pills, the
+question, and one large line on what the user gets, its payoff highlighted.
+About 40 s, in Foldspace's colours with the official logo:
+`video/<product>-<date>.mp4` and a poster. It records with Chrome's own screencast and encodes in a hidden Google
+Chrome - no ffmpeg, no screen-recording permission, nothing uploaded. The
+video shows real data from the signed-in account; sharing it is the human's
+call, and `video/.gitignore` keeps it out of git. The `share-a-video` skill,
+written into each project's `.claude/skills/`, is the how-to. It runs for a
+few minutes; stopped half-way, it puts the window back as it was.
+
 ### Add the harness to an existing project
 
 ```bash

package/bin/ask.mjs

@@ -25,7 +25,6 @@ import path from "node:path";
 import {
   createSettleTracker,
   numberFlag,
-  replyAfter,
   shouldRetry,
   squash,
   summarizeHandlerLog,
@@ -35,9 +34,15 @@ import { ATTACH_DAEMON_LOG_FILE, liveDaemon } from "../src/attach-daemon.mjs";
 import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
 import { withWorkingBadge } from "../src/badge-auto.mjs";
+import {
+  PANEL_DOC,
+  openComposer,
+  readPanel,
+  sendQuestion,
+  waitForReply,
+} from "../src/panel-driver.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
 
-const PANEL_ID = "eucera-agent-iframe";
 const COMPOSER_WAIT_S = 30;
 const POLL_MS = 1500;
 
@@ -81,147 +86,20 @@ function logSince(offset) {
   }
 }
 
-// Shared by every page snippet: the panel document, or null while it loads.
-const PANEL_DOC = `
-  const frame = document.getElementById(${JSON.stringify(PANEL_ID)});
-  let doc = null;
-  try { doc = frame && frame.contentDocument; } catch {}
-`;
-
-async function panelState() {
-  return page.evaluate(`${PANEL_DOC}
-    if (!doc) return { frame: !!frame, composer: false };
-    const box = doc.querySelector("textarea");
-    const rect = frame.getBoundingClientRect();
-    return { frame: true, composer: !!box, visible: rect.width > 50 && rect.height > 50 };`);
-}
-
-// open() is the SDK's public "show the panel" call, the same thing the
-// launcher button does. The handle comes from the bootstrap when attach made
-// one, else from the page's own SDK.
-async function openPanel(agentApiName) {
-  return page.evaluate(`
-    const wanted = ${JSON.stringify(agentApiName || "")};
-    const namespace = typeof window.__FOLD_SPACE__ === "string" && window.__FOLD_SPACE__
-      ? window.__FOLD_SPACE__ : "foldspace";
-    const sdk = window[namespace];
-    let agent = window.__FOLDSPACE_AGENT__ || null;
-    if (!agent && typeof sdk?.agentIds === "function") {
-      const ids = sdk.agentIds().filter((id) => typeof id === "string" && id.indexOf("-") > 0);
-      const id = ids.find((item) => item.slice(item.indexOf("-") + 1) === wanted) || ids[0];
-      if (id) {
-        const cut = id.indexOf("-");
-        agent = sdk.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() });
-      }
-    }
-    if (typeof agent?.open !== "function") return { sdk: !!sdk, opened: false };
-    try { agent.open(); return { sdk: true, opened: true }; }
-    catch (error) { return { sdk: true, opened: false, error: String(error?.message || error) }; }`);
-}
-
-async function readPanel(cardsBefore) {
-  return page.evaluate(`${PANEL_DOC}
-    if (!doc || !doc.body) return { panel: "", cards: [], cardFrames: 0, newCardFrames: 0 };
-    const squash = (text) => (text || "").replace(/\\s+/g, " ").trim();
-    const frames = Array.from(doc.querySelectorAll("iframe"));
-    const cards = [];
-    let painted = 0;
-    // Cards from earlier turns are still in the panel; only the new ones count.
-    for (const card of frames.slice(${Number(cardsBefore) || 0})) {
-      const rect = card.getBoundingClientRect();
-      if (rect.width > 20 && rect.height > 20) painted += 1;
-      try {
-        const body = card.contentDocument && card.contentDocument.body;
-        if (body) cards.push(squash(body.innerText || body.textContent));
-      } catch {}
-    }
-    return {
-      panel: squash(doc.body.innerText || doc.body.textContent),
-      cards: cards.filter(Boolean),
-      cardFrames: frames.length,
-      newCardFrames: painted,
-    };`);
-}
-
-// Real key events through the browser's input pipeline, like a person at the
-// keyboard. Frameworks that ignore synthetic DOM events still hear these.
-async function typeLikeAPerson(text) {
-  const focused = await page.evaluate(`${PANEL_DOC}
-    const box = doc && doc.querySelector("textarea");
-    if (!box) return false;
-    window.focus(); frame.contentWindow.focus(); box.focus();
-    return doc.activeElement === box;`);
-  if (!focused) return false;
-  await page.send("Input.insertText", { text });
-  const typed = await page.evaluate(`${PANEL_DOC}
-    const box = doc && doc.querySelector("textarea");
-    return box ? box.value : null;`);
-  if (squash(typed) !== text) return false;
-  const enter = {
-    key: "Enter",
-    code: "Enter",
-    windowsVirtualKeyCode: 13,
-    nativeVirtualKeyCode: 13,
-  };
-  await page.send("Input.dispatchKeyEvent", { type: "rawKeyDown", ...enter });
-  await page.send("Input.dispatchKeyEvent", { type: "char", ...enter, text: "\r" });
-  await page.send("Input.dispatchKeyEvent", { type: "keyUp", ...enter });
-  return true;
-}
-
-// A background or unfocused tab can swallow CDP input. Same gesture, delivered
-// as DOM events on the composer; still only typing, still nothing injected.
-async function typeWithDomEvents(text) {
-  return page.evaluate(`${PANEL_DOC}
-    const box = doc && doc.querySelector("textarea");
-    if (!box) return false;
-    const view = frame.contentWindow;
-    const setValue = Object.getOwnPropertyDescriptor(view.HTMLTextAreaElement.prototype, "value").set;
-    box.focus();
-    setValue.call(box, ${JSON.stringify(text)});
-    box.dispatchEvent(new view.Event("input", { bubbles: true }));
-    for (const type of ["keydown", "keypress", "keyup"]) {
-      box.dispatchEvent(new view.KeyboardEvent(type, {
-        key: "Enter", code: "Enter", keyCode: 13, which: 13, bubbles: true, cancelable: true,
-      }));
-    }
-    return true;`);
-}
-
-async function composerValue() {
-  return page
-    .evaluate(`${PANEL_DOC}
-      const box = doc && doc.querySelector("textarea");
-      return box ? box.value : "";`)
-    .catch(() => "");
-}
-
 async function askOnce() {
-  const before = await readPanel(0);
+  const before = await readPanel(page, 0);
   const cardsBefore = before.cardFrames;
   const logOffset = logSize();
 
-  let typedBy = "keyboard";
-  let sent = await typeLikeAPerson(question).catch(() => false);
-  await sleep(700);
-  // Still sitting in the composer means Enter never landed.
-  if (!sent || squash(await composerValue()) === question) {
-    typedBy = "dom-events";
-    sent = await typeWithDomEvents(question).catch(() => false);
-  }
+  const { sent, typedBy } = await sendQuestion(page, question);
   if (!sent) return { sent: false };
 
-  const tracker = createSettleTracker();
-  const deadline = Date.now() + timeoutS * 1000;
-  let seen = { panel: "", cards: [], newCardFrames: 0 };
-  let reply = "";
-  let settled = false;
-  while (Date.now() < deadline && !settled) {
-    await sleep(POLL_MS);
-    seen = await readPanel(cardsBefore).catch(() => seen);
-    reply = replyAfter(seen.panel, question);
-    settled = tracker.observe({ reply, cards: seen.cards }).settled;
-  }
+  const { settled, reply, seen } = await waitForReply(page, question, {
+    cardsBefore,
+    timeoutS,
+    pollMs: POLL_MS,
+    tracker: createSettleTracker(),
+  });
   // The render line trails the card by a beat; let attach flush it.
   await sleep(400);
   return {
@@ -284,14 +162,7 @@ async function main() {
 
   // The composer does not exist until the panel has opened, and one open() is
   // not always enough, so it is retried inside the poll.
-  let state = await panelState();
-  let opened = { sdk: false, opened: false };
-  for (let tick = 0; tick < COMPOSER_WAIT_S && !(state.composer && state.visible); tick++) {
-    opened = await openPanel(page.info.target?.agentApiName).catch(() => opened);
-    await sleep(1000);
-    state = await panelState().catch(() => state);
-    if (tick === 5 && !state.frame && !opened.sdk) break;
-  }
+  const { state } = await openComposer(page, page.info.target?.agentApiName, { waitS: COMPOSER_WAIT_S });
   if (!state.composer) {
     finish(
       {

package/bin/attach.mjs

@@ -303,6 +303,8 @@ const badgeSrc = `(() => {
 // one. See the playbook's test-mode rule.
 const testModeScript = (enable) => `(() => {
   if (window.top !== window.self) return;
+  // What this attach set, for \`foldspace record\` to read (it refuses test mode).
+  window.__FOLDSPACE_TEST_MODE__ = ${enable};
   const AGENT = ${JSON.stringify(agentApiName)};
   const WANT = ${enable};
   const WORD = ${JSON.stringify(enable ? "ON" : "OFF")};

package/bin/cli.mjs

@@ -8,6 +8,7 @@ import { runInit } from "../src/init.mjs";
 import { isWriteFlag } from "../src/observe-core.mjs";
 import {
   checkForUpdate,
+  ensureProjectSkills,
   gateForCommand,
   nagIfOutdated,
   resolveProjectDir,
@@ -41,12 +42,28 @@ function fail(message) {
   process.exitCode = 1;
 }
 
+// A stop sent to this wrapper alone (a timeout, `kill <pid>`) goes on to the
+// command: otherwise the wrapper dies and the command runs on as an orphan,
+// still driving the test window. Ctrl-C reaches both; each command takes a
+// second stop as the same one.
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
 function runScript(scriptName, args) {
   const child = spawn(process.execPath, [path.join(here, scriptName), ...args], {
     stdio: "inherit",
     env: process.env,
   });
+  const forward = (signal) => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    try {
+      child.kill(signal);
+    } catch {
+      // already gone
+    }
+  };
+  for (const signal of FORWARDED_SIGNALS) process.on(signal, forward);
   child.on("exit", (code, signal) => {
+    for (const name of FORWARDED_SIGNALS) process.removeListener(name, forward);
     if (signal) {
       process.kill(process.pid, signal);
       return;
@@ -152,6 +169,11 @@ function normalizeCommandArgs(command, args) {
 
 const [command, ...args] = process.argv.slice(2);
 
+// The harness's skills, when the project lacks them: the first upgrade to a
+// version that ships one runs the older harness, which cannot write it. Only
+// missing files, and only in a Foldspace project; silent.
+if (command !== "init") ensureProjectSkills(resolveProjectDir());
+
 if (!command || command === "--help" || command === "-h") {
   printHelp(null, args.includes("--json"));
 } else if (command === "--version" || command === "-v") {

package/bin/inject.mjs

@@ -14,13 +14,13 @@
 import { recordEvent } from "../src/session-events.mjs";
 import fs from "fs";
 import path from "path";
-import os from "os";
 import { spawn } from "child_process";
 import {
   ownershipErrorMessage,
   waitForOwnedCdp,
   writeLaunchSentinel,
 } from "../src/cdp-ownership.mjs";
+import { findChrome } from "../src/chrome-binary.mjs";
 
 // Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
 // hosted builder point the harness at a workspace it controls.
@@ -165,19 +165,7 @@ fs.writeFileSync(
   }, null, 2),
 );
 
-function findChrome() {
-  const candidates =
-    os.platform() === "darwin"
-      ? [
-          "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-          "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
-          "/Applications/Chromium.app/Contents/MacOS/Chromium",
-        ]
-      : ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium"];
-  return candidates.find((p) => fs.existsSync(p));
-}
-
-const chrome = process.env.CHROME_PATH || findChrome();
+const chrome = findChrome();
 if (!chrome) {
   console.error("\nChrome not found. Set CHROME_PATH=/path/to/chrome and retry.");
   process.exit(1);