@foldspace_npm/harness 0.1.26 → 0.1.28

package/README.md

@@ -12,12 +12,12 @@ else about how a builder runs differs between them; this does not.
 
 | | **A — local** *(today)* | **B — remote** *(designed, unbuilt)* |
 |---|---|---|
-| Who runs the agent | Claude Code on the builder's desktop | Claude Agent SDK in GCP |
-| Whose browser | an isolated Chrome the harness launches | the user's **own** Chrome |
+| Where the build runs | Claude Code on the human's computer | Claude Agent SDK in GCP |
+| Whose browser | an isolated Chrome the harness launches | the human's **own** Chrome |
 | How code reaches the page | harness CDP preparation | builder extension loads the cloud artifact |
 | Prerequisites | Claude Code, a client repo, Node, an isolated Chrome profile | the extension installed |
-| Session and cookies | in a profile the harness creates | the user's own, untouched |
-| Code and history | a git repo on the builder's machine | a workspace in the hosted environment |
+| Session and cookies | in a profile the harness creates | the human's own, untouched |
+| Code and history | a git repo on the human's computer | a workspace in the hosted environment |
 
 "Export to repo" moves a build from B to A — **and it is only a copy, not a
 rewrite, while `agent/` is identical in both.** Keeping it identical is the
@@ -29,7 +29,7 @@ constraint this package exists to protect.
   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 deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
+- `foldspace deploy` (Foldspace-internal) - uploads `dist/index.js` to `agent/actions/<env>/<productId>/<agentApiName>`
 - fixtures and tests
 - **the verb interface** below
 
@@ -95,7 +95,7 @@ Non-interactive / CI form:
 
 ```bash
 npx --yes @foldspace_npm/harness init foldspace-agent \
-  --product-id FR8JUQZAQRZB \
+  --product-id <product-id> \
   --agent-key my-agent \
   --app-domain app.example.com \
   --name "My Agent"
@@ -105,7 +105,7 @@ When running directly from a harness checkout during development:
 
 ```bash
 node bin/cli.mjs init ../foldspace-agent \
-  --product-id FR8JUQZAQRZB \
+  --product-id <product-id> \
   --agent-key my-agent \
   --app-domain app.example.com
 ```
@@ -115,8 +115,9 @@ not the sidecar directory name. `--agent-api-name` remains a deprecated alias
 for `--agent-key`. `--domain` remains a deprecated alias for `--app-domain`.
 `--name` is optional and defaults to the target directory
 name (`foldspace-agent` unless you pass a directory). The product ID must be
-the bare ID, not the `EU-…-1-1` SDK loader key. The app domain may be a hostname
-or an HTTP(S) URL without a port or path.
+the bare ID, not the SDK key (the one that starts with `EU-`, in every
+region). The app domain may be a hostname or an HTTP(S) URL without a port or
+path.
 
 `--region us|eu` (default `us`) is the Foldspace region the account lives in.
 It is written to `foldspace.dev.json` as `region`, and picks the SDK the
@@ -131,9 +132,11 @@ initialize Git or overwrite files. On a TTY it can offer
 ```bash
 cd foldspace-agent
 npm install --ignore-scripts   # if you skipped the install prompt
+# before the first build, CLAUDE.md step 5: a code project's agent/ replaces the scaffold's
 npm run build
-npm run inject
-npm run attach
+npm run inject   # the human signs in in that window
+npx foldspace observe wait-login
+npx foldspace attach --daemon
 ```
 
 The generated npm scripts intentionally remain the normal project interface;
@@ -146,21 +149,21 @@ to that import with `foldspace upgrade --refresh-instructions`.
 ### Keep the harness current
 
 Tenant projects pin an exact `@foldspace_npm/harness` version. Publishing a
-newer package does not move them. Check, ask the user, then bump:
+newer package does not move them. Check, ask the human, then bump:
 
 ```bash
 npx --yes @foldspace_npm/harness@latest upgrade --check
-foldspace upgrade --yes   # only after the user agrees
+foldspace upgrade --yes   # only after the human agrees
 ```
 
 `--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
-`--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
-afterward; that is still not a deploy.
+`--yes` writes the new exact version and runs `npm install --ignore-scripts`.
+Rebuild afterward; that publishes nothing.
 
 `foldspace build` and `foldspace attach` run the same check before they start
 (`attach --status` and `--stop` do not). A project that is behind gets one line
 on stderr and carries on. A project on a **withdrawn** version (below) refuses
-to run and prints the reason. To build on it anyway, once the user has declined
+to run and prints the reason. To build on it anyway, once the human has declined
 the upgrade:
 
 ```bash
@@ -200,13 +203,14 @@ To undo a withdrawal, deprecate with an empty message:
 npm deprecate @foldspace_npm/harness@0.1.14 ""
 ```
 
-**It is not instant.** Each project caches the registry's answer for 12 hours
-in `.foldspace-dev/harness-update.json`. A project that checked recently keeps
-its "fine" answer until that expires, so a withdrawal reaches every project
-within 12 hours. It only reaches projects on a harness version that has this
-check.
+**It is not instant for `build` and `attach`.** They use the registry's answer
+cached for 12 hours in `.foldspace-dev/harness-update.json`. `foldspace help
+--json` (which the manual reads first) and `foldspace upgrade` ask the registry
+each time and refresh that cache, so a withdrawal reaches a project at its next
+session start, and within 12 hours otherwise. It only reaches projects on a
+harness version that has this check.
 
-### Lint handlers before they ship
+### Lint agent code before it ships
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings
 print and still produce `dist/index.js`.
@@ -218,12 +222,16 @@ foldspace lint --json
 
 v1 flags:
 
-- **error** `no-static-agent-prompt` — `execute` / chatterblock `callback` returning copilot instructions (`directive`, “tell the user”, …)
+- **error** `no-static-agent-prompt` - `execute`, a card's `callback` or its `readyState` handing the agent instructions (`directive`, “tell the user”, …)
 - **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
+- **error** `card-contract` - `awaitUserInput: true` on a view card (its `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
+- **error** `no-test-mode-in-bundle` - `armAllInstances(...)`, or `setTestMode(...)` with anything but a literal `false`, anywhere in `agent/`
+- **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), or a `render` that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card)
 - **warning** `no-emoji` — emoji in handler or `agent/views` string literals
 - **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`
 
-Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
+Put action instructions in Agent Studio or with the Foldspace tools. `foldspace
+lint` cannot see that copy.
 
 ### Runtime helpers
 
@@ -232,7 +240,10 @@ Tenant actions import from `agent/utils.ts`, which configures and re-exports
 runs in the customer's page — it is not a CLI command.
 
 `API_BASE` and `AUTH_SOURCE` stamp empty. Fill them from a captured XHR, not a
-guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
+guess. For auth that is not Bearer, follow
+`recipes/swap-the-login-method/README.md`: for a custom header, copy its
+`agent/utils.ts` over `agent/utils.ts`; for cookies with no token, its
+`variants/utils.cookies.ts`.
 
 ### Choose an attach mode
 
@@ -242,21 +253,25 @@ guess. Custom auth headers stay a tenant override of one function in `utils.ts`.
   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
+Coding agents 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
+the default for someone watching the terminal. `attach --status` and
 `attach --stop` inspect and tear down a daemon. Look at the customer's app with
-`foldspace observe`: it reads the same window, read-only, while attach runs.
+`foldspace observe`: it reads the test window, read-only, while attach runs.
 
 ### Verify actions through the agent
 
 `foldspace attach` does not invoke action handlers directly. It loads the local
 artifact, verifies that the captured local registry matches the configured SDK
-agent — including an empty registry — and then observes action callbacks while
+agent - including an empty registry - and then observes action calls while
 you exercise the normal agent experience. Named actions are not required to
 attach.
 
-Action output identifies SDK callbacks and local `execute`/`render` phases:
+`npx foldspace ask "<question>" --retry 2` types the question into the agent's
+panel and reports the reply, the card text and a screenshot, and - while attach
+runs - whether execute and render ran.
+
+Action output shows the SDK's action calls and local `execute`/`render` phases:
 
 ```text
 [actions] sdk:action show_account_360 executed
@@ -269,6 +284,36 @@ parameter values, results, and error messages are not. On detach, repeated page
 failures and bounded action observations are summarized. The observer and
 diagnostics are injected by the harness, so `dist/index.js` is not rewritten.
 
+### Check the published code
+
+After the `deploy` tool in the Foldspace tools - not `foldspace deploy`, which
+is for Foldspace staff only - publishes the code project to dev (or, with the
+human's yes, to production), check it in the same test window. This needs a
+site that loads this agent by itself: after `attach --bootstrap` or
+`--replace` there is nothing to check yet.
+
+```bash
+npx foldspace attach --stop          # while attach runs the page serves your local build
+npx foldspace published dev          # this page's agent now loads the published dev code
+npx foldspace ask "<the question>" --retry 2
+npx foldspace attach --daemon        # back to your local build before you build anything else
+```
+
+`published` refuses while attach runs. It also refuses unless the page's own
+Foldspace agent is this project's agent - the same product and Agent Key as
+`foldspace.dev.json`, checked the way attach checks it. It changes only this
+page's agent, through the SDK's `setConfiguration({ enableDebugLogs: true,
+remoteActionsSettings: { enabled: true, environment: "DEV" | "PROD" } })`; a
+reload puts the page back on what the agent loads normally. When code loads,
+the SDK keeps any handler the agent already has over a new one of the same
+name, so once the published code has loaded, its handlers are set over the
+page's for every action it defines; the page keeps its own handlers for the
+rest. An agent pinned to one version of its code, or loading code from its
+own address, is refused: the window would not show what was published last.
+Without attach, `ask` still reports the reply, the card text and a
+screenshot; `handler.execute` and `handler.render` read "not tracked here
+(published code)".
+
 ### Add the harness to an existing project
 
 ```bash
@@ -281,8 +326,7 @@ npm i -D @foldspace_npm/harness
     "build":  "foldspace build",
     "inject": "foldspace inject",
     "attach": "foldspace attach",
-    "attach:daemon": "foldspace attach --daemon",
-    "deploy": "foldspace deploy"
+    "attach:daemon": "foldspace attach --daemon"
 } }
 ```
 
@@ -290,9 +334,13 @@ Every command resolves the **consuming** repo — `process.cwd()`, or
 `FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it
 controls. Config comes from the consumer's `foldspace.dev.json`.
 
-`foldspace deploy` is an explicit remote publication step that reads product
-and agent identity from the selected target in `foldspace.dev.json`. It requires
-local cloud credentials and is separate from local verification.
+`foldspace deploy` is Foldspace-internal: it writes to Foldspace's own storage,
+which no customer can write to. A coding agent never runs or offers it. With a
+code project, a build session publishes the agent's code with the Foldspace
+tools instead: `repo_write` saves it, and the `deploy` tool publishes it - to
+dev after saying so, to production only on the human's yes - as the manual's
+"Done, and what you say at the end" says. Without a code project, the
+Foldspace team does it with the human.
 
 ---
 
@@ -306,7 +354,7 @@ and **neither had all five**:
 |---|---|
 | SDK load guard + retry | On an app with no `document.body` at document-start the append throws; the old guard tested for the stub, so nothing retried and the agent silently never loaded |
 | Worker release on auto-attach | Auto-attach pauses every worker until the attaching client releases it — the harness froze the app's own workers for the whole session |
-| `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded copilot leaves real conversations untagged |
+| `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded agent leaves real conversations untagged |
 | `--test-mode` (off by default) | Test mode was armed unconditionally, hiding exactly what initial setup needs to see; now it is opt-in |
 | Honest badge | It asserted `TEST MODE` whether or not test mode was on |
 

package/bin/ask.mjs

@@ -1,17 +1,23 @@
 #!/usr/bin/env node
-// foldspace ask — put a question to the visible assistant through its panel,
+// foldspace ask - put a question to the visible agent through its panel,
 // exactly as a person would, and report what came back: the reply, any card,
 // what the handlers did, and a picture.
 //
-// It exists so the coding agent stops asking a non-technical customer to
-// "reload, try these two sentences and tell me what you saw".
+// It exists so the coding agent stops asking the human to "reload, try these
+// two sentences and tell me what you saw".
 //
-//   node bin/ask.mjs "<question>" [--retry <n>] [--every <s>] [--timeout <s>] [--out <dir>]
+//   npx foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>]
 //
 // Nothing here reaches into the SDK, patches fetch or injects into the panel:
 // it opens the panel, types into the composer, presses Enter and reads the
 // screen. --retry re-asks when no action fired, which covers the platform
 // taking up to a minute to pick up a newly published action; lagMs is that cost.
+//
+// What the handlers did comes from the attach daemon's log. Without a daemon
+// (after `foldspace published`, the page runs published code) execute and
+// render read "not tracked here (published code)", so only a card shows that
+// an action fired: --retry re-asks whenever no card came back, even when an
+// action that draws no card ran.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -23,8 +29,9 @@ import {
   shouldRetry,
   squash,
   summarizeHandlerLog,
+  untrackedHandler,
 } from "../src/ask-core.mjs";
-import { ATTACH_DAEMON_LOG_FILE } from "../src/attach-daemon.mjs";
+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";
@@ -44,6 +51,7 @@ const outDir = flags.out
   ? path.resolve(projectDir, String(flags.out))
   : path.join(projectDir, ".foldspace-dev", "ask");
 const logFile = path.join(projectDir, ".foldspace-dev", ATTACH_DAEMON_LOG_FILE);
+const tracked = Boolean(liveDaemon(projectDir));
 
 let page = null;
 
@@ -223,7 +231,7 @@ async function askOnce() {
     reply: reply.slice(0, 2000),
     cards: seen.cards.map((card) => card.slice(0, 2000)),
     hasCard: seen.cards.length > 0 || seen.newCardFrames > 0,
-    handler: summarizeHandlerLog(logSince(logOffset)),
+    handler: tracked ? summarizeHandlerLog(logSince(logOffset)) : untrackedHandler(),
   };
 }
 
@@ -264,7 +272,7 @@ async function main() {
       {
         ok: false,
         reason:
-          'No question. Usage: foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>] [--out <dir>]',
+          'No question. Usage: foldspace ask "<question>" [--retry <n>] [--every <s>] [--timeout <s>]',
       },
       1,
     );
@@ -290,8 +298,10 @@ async function main() {
         ok: false,
         question,
         reason: state.frame
-          ? "The assistant panel is on the page but never showed a composer."
-          : "No assistant panel on this page. Run `foldspace attach --daemon` (add --bootstrap when the page has no Foldspace SDK), then ask again.",
+          ? "The agent panel is on the page but never showed a composer. Run `npx foldspace observe screenshot` and look at the page."
+          : tracked
+            ? "No agent panel on this page while attach runs. Read the lines under the last [lifecycle] line in .foldspace-dev/attach-daemon.log, then ask again."
+            : "No agent panel on this page. Run `npx foldspace attach --daemon`, follow what it says about the page, then ask again.",
         url,
       },
       1,