@foldspace_npm/harness 0.1.29 → 0.1.31

package/CLAUDE.md

@@ -29,8 +29,8 @@ 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 |
+   | 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 | 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 |
 
 3. **Orient** — `get_agent_settings`, `list_actions`, `list_task_agents`,
@@ -162,7 +162,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
@@ -696,6 +696,8 @@ Each of these cost a real build.
   `AUTH_SOURCE` and `LOAD_MODE`
 - `agent/utils.ts` — configures the harness runtime and re-exports it. **The
   only import surface for actions.**
+- `agent/runtime/` — a code project only: this harness's runtime, which every
+  build keeps current. Never edit it.
 - `agent/views/` — branded cards
 - `docs/app-profile.md` — what is known about this app, and how it was established
 - `foldspace.dev.json` — local harness target configuration
@@ -766,10 +768,17 @@ README's **Adapt it** table lists to what you observed.
 package: Foldspace builds the published bundle with no `node_modules`, so a
 package import passes every gate in this manual and then fails on publish.
 Import the helpers the way the project's own `agent/utils.ts` does - from
-`./runtime` - in a recipe file you copy too. A project with an `agent/utils/`
-folder has its own helpers instead: change the sign-in there, and never add an
-`agent/utils.ts` beside it, which would win the import. Without a code project,
-the package import is right.
+`./runtime` - in a recipe file you copy too. `agent/runtime/` is this harness's
+runtime, copied in for that reason. A build that changes files there names
+them: save exactly those files in a save of their own as soon as the agent is
+on their page. Say you are bringing their project up to date - no need to ask,
+it changes nothing for their users. If their account cannot save, carry on.
+Never edit a file there: the next build puts the harness's copy back. To change
+how a helper behaves, define it in `agent/utils.ts` and export it from there in
+place of the runtime's. A project with an `agent/utils/` folder has its own
+helpers instead: change the sign-in there, and never add an `agent/utils.ts`
+beside it, which would win the import. Without a code project, the package
+import is right.
 
 ## Safety
 
@@ -785,6 +794,18 @@ the package 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

@@ -28,7 +28,7 @@ constraint this package exists to protect.
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. Actions built in one track run unmodified in the other.
 - `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
-- `foldspace build` — esbuild → `dist/index.js`
+- `foldspace build` — esbuild → `dist/index.js`. In a code project, it first makes `agent/runtime/` match this harness's runtime (never rolling back a copy of a newer runtime; the version is in `src/runtime/VERSION`) and names every file it wrote
 - `foldspace deploy` (Foldspace-internal) - uploads `dist/index.js` to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below

package/bin/build.ts

@@ -3,6 +3,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { bundleTurnsOnTestMode, lintProject, printLint } from "../src/lint/index.mjs";
+import { compareVersions } from "../src/upgrade.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
@@ -11,6 +12,100 @@ const agentActionsEntry = path.join(projectDir, "agent", "actions", "index.ts");
 
 const watchMode = process.argv.includes("--watch");
 
+// A code project carries its own copy of this harness's runtime in
+// agent/runtime/, because Foldspace builds it with no node_modules. Each build
+// keeps that copy the same as the runtime here, so the harness's fixes reach
+// the project, and names what it wrote so the session saves it.
+// src/runtime/VERSION is the runtime's own version - it changes only when the
+// runtime does - and the copy carries it in agent/runtime/VERSION: a copy of a
+// newer runtime is left alone, so an older harness never rolls it back.
+// Other files there, and links, are left alone too.
+let runtimeSaveLine = "";
+
+function plainFile(file: string): "missing" | "file" | "other" {
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  if (!stat) return "missing";
+  return stat.isFile() ? "file" : "other";
+}
+
+function sameText(left: string, right: string): boolean {
+  return left.replace(/\r\n/g, "\n") === right.replace(/\r\n/g, "\n");
+}
+
+function refreshRuntimeCopy(): void {
+  const copyDir = path.join(projectDir, "agent", "runtime");
+  const copyStat = fs.lstatSync(copyDir, { throwIfNoEntry: false });
+  if (!copyStat) return;
+  if (copyStat.isSymbolicLink()) {
+    console.log("agent/runtime/ is a link, so this build leaves it as is.\n");
+    return;
+  }
+  if (!copyStat.isDirectory()) return;
+
+  const sourceDir = path.join(__dirname, "..", "src", "runtime");
+  const runtimeVersion = fs.readFileSync(path.join(sourceDir, "VERSION"), "utf8").trim();
+  const versionFile = path.join(copyDir, "VERSION");
+  const versionKind = plainFile(versionFile);
+  if (versionKind === "other") {
+    console.log("agent/runtime/VERSION is not a plain file, so this build leaves agent/runtime/ as is.\n");
+    return;
+  }
+  const copyVersion = versionKind === "file" ? fs.readFileSync(versionFile, "utf8").trim() : "";
+  if (copyVersion && compareVersions(copyVersion, runtimeVersion) > 0) {
+    console.log(
+      `agent/runtime/ is runtime ${copyVersion}, newer than this harness's (${runtimeVersion}), so this build uses it as it is. ` +
+        "Unless the human already said no to upgrading this session, ask them, then run npx foldspace upgrade --yes and build again.\n",
+    );
+    return;
+  }
+
+  const toWrite: Array<[string, string]> = [];
+  for (const name of fs.readdirSync(sourceDir).filter((file) => file.endsWith(".ts")).sort()) {
+    const source = fs.readFileSync(path.join(sourceDir, name), "utf8");
+    const target = path.join(copyDir, name);
+    const kind = plainFile(target);
+    if (kind === "other") continue;
+    if (kind === "file" && sameText(fs.readFileSync(target, "utf8"), source)) continue;
+    toWrite.push([name, source]);
+  }
+  const stamp = copyVersion !== runtimeVersion;
+  if (toWrite.length === 0 && !stamp) return;
+
+  const targets = [...toWrite.map(([name]) => path.join(copyDir, name)), ...(stamp ? [versionFile] : [])];
+  const blocked = targets.filter((file) => {
+    try {
+      fs.accessSync(fs.existsSync(file) ? file : copyDir, fs.constants.W_OK);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+  const named = (files: string[]) => files.map((file) => `agent/runtime/${path.basename(file)}`).join(", ");
+  if (blocked.length > 0) {
+    console.error(`Could not update agent/runtime/: ${named(blocked)} cannot be written. Fix that and build again.`);
+    process.exit(1);
+  }
+  try {
+    for (const [name, source] of toWrite) fs.writeFileSync(path.join(copyDir, name), source);
+    if (stamp) fs.writeFileSync(versionFile, `${runtimeVersion}\n`);
+  } catch (error) {
+    console.error(`Could not update agent/runtime/: ${(error as Error).message}. Fix that and build again.`);
+    process.exit(1);
+  }
+
+  // The same runtime version that no longer matches was changed after it was copied.
+  if (!stamp) {
+    console.log(
+      `${named(toWrite.map(([name]) => name))} did not match this harness's copy of the same runtime; this build put the harness's copy back. ` +
+        "Never edit agent/runtime/ - to change how a helper behaves, define it in agent/utils.ts and export it from there in place of the runtime's.",
+    );
+  }
+  runtimeSaveLine =
+    `Updated to this harness's runtime (${runtimeVersion}): ${named(targets)}. ` +
+    "Save exactly these files to the code project in a save of their own, as soon as the agent is on their page - saving changes nothing for their users.";
+  console.log(`${runtimeSaveLine}\n`);
+}
+
 function gateLint(): void {
   const result = lintProject(projectDir);
   printLint(result);
@@ -75,6 +170,8 @@ async function build() {
     process.exit(1);
   }
 
+  refreshRuntimeCopy();
+
   if (!watchMode) {
     gateLint();
   }
@@ -105,6 +202,8 @@ async function build() {
       if (!bundleIsSafe()) process.exit(1);
       console.log("Built: dist/index.js");
       console.log("\nBuild complete!");
+      // Said again at the end, where a session reading only the last lines sees it.
+      if (runtimeSaveLine) console.log(`\n${runtimeSaveLine}`);
     }
   } catch (error) {
     console.error("Build failed:", error);

package/package.json

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

package/src/cli-registry.mjs

@@ -129,11 +129,13 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: ["agent/actions/index.ts"],
     effects: [
       "Checks the harness version first: behind prints one line, a withdrawn version refuses to run (FOLDSPACE_SKIP_UPDATE_CHECK=1 skips the check)",
+      "In a code project (agent/runtime/ present), first makes each agent/runtime/*.ts match this harness's runtime and records the runtime's version in agent/runtime/VERSION, naming every file it wrote; a copy of a newer runtime, other files there and links are left alone",
       "Runs foldspace lint first; errors skip bundling",
       "Writes dist/index.js when lint has no errors",
     ],
     next: [
       "First build: `npm run inject` (the human signs in in that window), `npx foldspace observe wait-login`, then `npx foldspace attach --daemon`",
+      "If the build names files in agent/runtime/ to save: save exactly those to the code project, in a save of their own, once the agent is on their page",
       "Rebuild while attach runs: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with (`--bootstrap`, `--replace`, `--test-mode`) - a running attach keeps the actions it loaded",
     ],
   }),

package/src/runtime/VERSION

@@ -0,0 +1 @@
+0.1.30

package/templates/agent-starter/AGENTS.md

@@ -0,0 +1,24 @@
+# Foldspace actions for {{APP_DOMAIN}}
+
+This folder builds a Foldspace agent for {{APP_DOMAIN}}. Its manual is
+`node_modules/@foldspace_npm/harness/CLAUDE.md` - written for every coding
+agent, whatever the file name says.
+
+**Read that manual in full before anything else**, and follow it from **Every
+session starts the same way**. It is long: read it in parts of about 250 lines
+until you reach its last line, because a tool that cuts long output short has
+not shown you all of it. If the file is missing, run
+`npm install --ignore-scripts` first. Run every command from this folder, even
+when your chat started somewhere else. What follows is only what is true of
+**this** product.
+
+## This product
+
+| | |
+|---|---|
+| Agent Key | `{{AGENT_API_NAME}}` |
+| Product ID | `{{PRODUCT_ID}}` |
+| App | `{{APP_DOMAIN}}` |
+
+What is known about this app, and how each fact was established, is in
+`docs/app-profile.md`.