@foldspace_npm/harness 0.1.3 → 0.1.5

package/README.md

@@ -95,7 +95,7 @@ Non-interactive / CI form:
 ```bash
 npx --yes @foldspace_npm/harness init my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com \
   --name "My Agent"
 ```
@@ -105,12 +105,14 @@ When running directly from a harness checkout during development:
 ```bash
 node bin/cli.mjs init ../my-agent \
   --product-id FR8JUQZAQRZB \
-  --agent-api-name my-agent \
+  --agent-key my-agent \
   --domain app.example.com
 ```
 
-`--name` is optional and defaults to the target directory name. The product ID
-must be the bare ID, not an `EU-…` SDK key. The domain may be a hostname or an
+The Agent Key is the value shown in Agent Studio, such as `my-agent`.
+`--agent-api-name` remains a deprecated alias for `--agent-key`. `--name` is
+optional and defaults to the target directory name. The product ID must be the
+bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname or an
 HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
@@ -140,9 +142,10 @@ Use `foldspace help attach` for mode requirements, effects, and safety options.
 ### Verify actions through the agent
 
 `foldspace attach` does not invoke action handlers directly. It loads the local
-artifact, verifies that its action names exactly match the configured SDK agent,
-and then observes action callbacks while you exercise the normal agent
-experience.
+artifact, verifies that the captured local registry matches the configured SDK
+agent — including an empty registry — and then observes action callbacks while
+you exercise the normal agent experience. Named actions are not required to
+attach.
 
 Action output identifies SDK callbacks and local `execute`/`render` phases:
 

package/bin/attach.mjs

@@ -30,6 +30,7 @@ import {
   hostMatches,
   hostPatternsFromTarget,
   parseAgentId,
+  registrationVerified,
 } from "../src/attach-helpers.mjs";
 import {
   buildReplacePrelude,
@@ -294,8 +295,10 @@ const sessionCollector = createSessionCollector();
 // sessionId -> preparation state used for deterministic detach cleanup.
 const prepared = new Map();
 const preparing = new Set();
-// Rejections are scoped to the observed URL so a later navigation can retry.
-const rejected = new Map();
+// Rejections are scoped to the CDP session. SPA URL changes must not retry
+// prepare() on the same tab. Off-host navigation still clears rejected in
+// targetInfoChanged so a later return to the app can retry.
+const rejected = new Set();
 // targetId -> sessionId, so a target that navigates INTO a matching host can be
 // prepared later. Without this, opening Chrome on a new tab and then browsing
 // to the app never arms the swap.
@@ -451,13 +454,7 @@ async function verifyPreparedPage(ws, sessionId) {
           },
         );
         latest.registration = registration;
-        if (
-          observation?.captureCount > 0 &&
-          expectedActionNames.length > 0 &&
-          registration?.agentFound &&
-          registration.missingActionNames?.length === 0 &&
-          registration.unexpectedActionNames?.length === 0
-        ) {
+        if (registrationVerified(observation, registration)) {
           return {
             ok: true,
             state,
@@ -493,9 +490,6 @@ async function verifyPreparedPage(ws, sessionId) {
 }
 
 async function prepare(ws, sessionId, url) {
-  if (rejected.has(sessionId) && rejected.get(sessionId) !== url) {
-    rejected.delete(sessionId);
-  }
   if (
     prepared.has(sessionId) ||
     preparing.has(sessionId) ||
@@ -527,7 +521,7 @@ async function prepare(ws, sessionId, url) {
       pageProductIds,
     });
     if (!guard.ok) {
-      rejected.set(sessionId, url);
+      rejected.add(sessionId);
       logLifecycle(
         createLifecycleResult({
           operation: "prepare_page",
@@ -697,6 +691,11 @@ async function prepare(ws, sessionId, url) {
               verification.registration?.actionNames || [],
             expectedActionNames:
               verification.observation?.expectedActionNames || [],
+            expectedActionCount: Array.isArray(
+              verification.observation?.expectedActionNames,
+            )
+              ? verification.observation.expectedActionNames.length
+              : 0,
             missingActionNames:
               verification.registration?.missingActionNames || [],
             unexpectedActionNames:
@@ -715,7 +714,7 @@ async function prepare(ws, sessionId, url) {
           await cleanupPreparedSession(ws, sessionId, state);
           prepared.delete(sessionId);
         }
-        rejected.set(sessionId, url);
+        rejected.add(sessionId);
       }
     }
   } finally {
@@ -920,7 +919,10 @@ console.log(`Mode:  ${attachMode}`);
 console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
 console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the dashboard" : "on"}`);
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
-console.log(`Serving: ${path.relative(root, bundlePath)}\n`);
+console.log(`Serving: ${path.relative(root, bundlePath)}`);
+console.log(
+  `CDP: this process owns the debug port. Detach before using chrome-devtools MCP against the same Chrome.\n`,
+);
 
 function printSessionSummary() {
   if (summaryPrinted) return;

package/bin/cli.mjs

@@ -62,9 +62,13 @@ function printHelp(topic, json) {
 }
 
 function normalizeCommandArgs(command, args) {
-  const options = new Map(
-    command.options.map((option) => [option.name, option]),
-  );
+  const options = new Map();
+  for (const option of command.options) {
+    options.set(option.name, { option, canonicalName: option.name });
+    for (const alias of option.deprecatedAliases || []) {
+      options.set(alias, { option, canonicalName: option.name });
+    }
+  }
   const seen = new Set();
   const normalized = [];
   let positionals = 0;
@@ -81,14 +85,17 @@ function normalizeCommandArgs(command, args) {
 
     const separator = token.indexOf("=");
     const name = separator > -1 ? token.slice(0, separator) : token;
-    const option = options.get(name);
-    if (!option) throw new Error(`unknown option '${name}'`);
-    if (seen.has(name)) throw new Error(`option '${name}' was provided twice`);
-    seen.add(name);
+    const match = options.get(name);
+    if (!match) throw new Error(`unknown option '${name}'`);
+    const { option, canonicalName } = match;
+    if (seen.has(canonicalName)) {
+      throw new Error(`option '${canonicalName}' was provided twice`);
+    }
+    seen.add(canonicalName);
 
     if (option.kind === "flag") {
       if (separator > -1) throw new Error(`option '${name}' takes no value`);
-      normalized.push(name);
+      normalized.push(canonicalName);
       continue;
     }
 
@@ -97,7 +104,7 @@ function normalizeCommandArgs(command, args) {
     if (!optionValue || optionValue.startsWith("--")) {
       throw new Error(`option '${name}' requires a value`);
     }
-    normalized.push(name, optionValue);
+    normalized.push(canonicalName, optionValue);
   }
   return normalized;
 }

package/package.json

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

package/src/attach-helpers.mjs

@@ -140,6 +140,21 @@ export function actionRequestMatchesTarget(request, target) {
   );
 }
 
+export function registrationVerified(observation, registration) {
+  return Boolean(
+    observation?.installed === true &&
+      observation?.ownerMatches === true &&
+      observation?.actionNameLimitExceeded !== true &&
+      observation?.captureCount > 0 &&
+      Array.isArray(observation.expectedActionNames) &&
+      registration?.agentFound === true &&
+      Array.isArray(registration.missingActionNames) &&
+      registration.missingActionNames.length === 0 &&
+      Array.isArray(registration.unexpectedActionNames) &&
+      registration.unexpectedActionNames.length === 0,
+  );
+}
+
 export function summarizeConsoleMessages(messages, limit = 50) {
   const summaries = new Map();
   for (const message of messages) {

package/src/cli-help.mjs

@@ -74,6 +74,10 @@ export function renderCommandHelp(registry, name) {
       `${option.name}${option.value ? ` <${option.value}>` : ""}`,
       `${option.description}${
         option.default ? ` (default: ${option.default})` : ""
+      }${
+        option.deprecatedAliases?.length
+          ? ` (deprecated alias: ${option.deprecatedAliases.join(", ")})`
+          : ""
       }`,
     ]);
     sections.push("", "Options:", rows(optionRows));

package/src/cli-registry.mjs

@@ -21,7 +21,7 @@ export const CLI_COMMANDS = Object.freeze([
     group: "start",
     summary: "Create a configured Foldspace actions project",
     usage:
-      "foldspace init [<directory>] [--product-id <id>] [--agent-api-name <name>] [--domain <host>] [--name <display-name>]",
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--domain <host>] [--name <display-name>]",
     risk: "local-write",
     environment: "node",
     environmentVariables: [],
@@ -37,8 +37,9 @@ export const CLI_COMMANDS = Object.freeze([
       value("--product-id", "id", "Bare Foldspace product ID", {
         required: "non-interactive",
       }),
-      value("--agent-api-name", "name", "Agent API name", {
+      value("--agent-key", "key", "Agent Key shown in Agent Studio", {
         required: "non-interactive",
+        deprecatedAliases: ["--agent-api-name"],
       }),
       value("--domain", "host", "Target hostname or HTTP(S) URL", {
         required: "non-interactive",
@@ -50,7 +51,7 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: [
       "Node 20 or newer",
       "A target directory that does not already exist",
-      "Non-interactive use requires directory, product ID, agent name, and domain",
+      "Non-interactive use requires directory, product ID, Agent Key, and domain",
     ],
     effects: ["Creates a new local project; never initializes Git"],
     next: [
@@ -188,12 +189,14 @@ export const CLI_COMMANDS = Object.freeze([
       "May reload and instrument matching target pages",
       "Test mode is enabled unless --no-test-mode is passed",
       "Never directly invokes an action handler",
+      "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
     ],
     next: [
       "Exercise the visible agent normally",
       "Confirm [lifecycle] inspect_registration:registration_ok",
-      "Confirm execute/render observations",
+      "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",
     ],
   }),
@@ -304,6 +307,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "Capability metadata describes current behavior; it is not hosted-environment enforcement.",
       "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.",
     ],
   };
 }

package/src/init.mjs

@@ -8,7 +8,13 @@ import { commandByName } from "./cli-registry.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
-const allowedFlags = new Set(["name", "product-id", "agent-api-name", "domain"]);
+const allowedFlags = new Set([
+  "name",
+  "product-id",
+  "agent-key",
+  "agent-api-name",
+  "domain",
+]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
 const defaultDirectory = "my-agent";
 
@@ -75,12 +81,17 @@ export function parseInitArgs(argv) {
   if (positional.length > 1) {
     throw new Error(`Usage: ${initUsage}`);
   }
+  if (flags["agent-key"] && flags["agent-api-name"]) {
+    throw new Error(
+      "Use --agent-key only; --agent-api-name is its deprecated alias.",
+    );
+  }
 
   return {
     directory: positional[0] || null,
     displayName: flags.name || null,
     productId: flags["product-id"] || null,
-    agentApiName: flags["agent-api-name"] || null,
+    agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
     domain: flags.domain || null,
   };
 }
@@ -89,7 +100,7 @@ function missingInitFields(parsed) {
   const missing = [];
   if (!parsed.directory) missing.push("directory");
   if (!parsed.productId) missing.push("product-id");
-  if (!parsed.agentApiName) missing.push("agent-api-name");
+  if (!parsed.agentApiName) missing.push("agent-key");
   if (!parsed.domain) missing.push("domain");
   return missing;
 }
@@ -208,8 +219,8 @@ async function promptForMissingFields(parsed, options = {}) {
 
   if (!next.agentApiName) {
     next.agentApiName = await askUntilValid(
-      "Agent API name",
-      (value) => validateIdentifier(value, "Agent API name"),
+      "Agent Key",
+      (value) => validateIdentifier(value, "Agent Key"),
       options,
     );
   }
@@ -243,7 +254,7 @@ function finalizeInitConfig(parsed) {
 
   for (const [key, label] of [
     ["productId", "product-id"],
-    ["agentApiName", "agent-api-name"],
+    ["agentApiName", "agent-key"],
     ["domain", "domain"],
   ]) {
     if (!parsed[key]) {
@@ -282,7 +293,7 @@ function createTemplateValues(config, harnessVersion) {
   }
 
   const productId = validateProductId(config.productId);
-  const agentApiName = validateIdentifier(config.agentApiName, "Agent API name");
+  const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
   const target = normalizeTarget(config.domain);
   const hosts =
     target.domain === "localhost" || /^\d+(?:\.\d+){3}$/.test(target.domain)

package/templates/agent-starter/CLAUDE.md

@@ -55,7 +55,9 @@ npm run attach
 
 `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.
+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.
 
 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
@@ -63,9 +65,14 @@ agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
 present without the configured agent.
 
 The attach log must report `inspect_registration:registration_ok` before
-treating the page as registered. Prove the experience through the visible agent
-and require both an SDK action callback and local execute/render evidence; do
-not invoke the handler directly.
+treating the page as registered. Zero captured actions is success when the
+local registry is empty. On `registration_mismatch`, read
+`npx foldspace help attach --json` diagnostics and map those names onto the
+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.
 
 ## Verification gates
 
@@ -73,7 +80,8 @@ Do not report success without all six:
 
 1. TypeScript compiles with `npx tsc --noEmit -p tsconfig.json`.
 2. The expected handler appears in `dist/index.js`.
-3. The browser reports the expected number of attached actions.
+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.
 5. Existing neighbouring action fixtures still pass when fixtures exist.
 6. Browser evidence came from the live target, not from hand-authored examples.

package/templates/agent-starter/README.md

@@ -54,7 +54,8 @@ npm run attach   # load local actions and observe the agent over CDP
 
 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.
+loads `dist/index.js` directly through CDP. An empty local registry is valid,
+so you can attach before implementing handlers.
 
 Choose the attach mode from the state of the target page: