@foldspace_npm/harness 0.1.8 → 0.1.10

package/README.md

@@ -27,6 +27,7 @@ constraint this package exists to protect.
 
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
   nothing more. The actions built for Figma run unmodified in either track.
+- `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>`
 - fixtures and tests
@@ -150,6 +151,15 @@ v1 flags:
 
 Put action instructions in Agent Studio or MCP. `foldspace lint` cannot see that copy.
 
+### Runtime helpers
+
+Tenant actions import from `agent/utils.ts`, which configures and re-exports
+`@foldspace_npm/harness/runtime`. That code is bundled into `dist/index.js` and
+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`.
+
 ### Choose an attach mode
 
 - **Swap (default):** the page already uses the configured product and agent.

package/bin/attach.mjs

@@ -31,6 +31,7 @@ import {
   hostPatternsFromTarget,
   parseAgentId,
   registrationVerified,
+  resolveAttachLaunch,
 } from "../src/attach-helpers.mjs";
 import {
   buildReplacePrelude,
@@ -47,6 +48,12 @@ import {
   createLifecycleResult,
 } from "../src/protocol.mjs";
 import { createCdpRequestManager } from "../src/cdp-request-manager.mjs";
+import {
+  assertOwnedCdp,
+  chromeProfileDir,
+  ownershipErrorMessage,
+  verifyLaunchSentinel,
+} from "../src/cdp-ownership.mjs";
 import { buildActionObserverScript } from "../src/action-observer.mjs";
 import { buildBootstrapScript } from "../src/bootstrap-script.mjs";
 import {
@@ -61,8 +68,8 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
 const bundlePath = path.join(root, "dist", "index.js");
 
-// Prefer what inject actually launched, then an explicit override, then the
-// legacy default. Guessing here means attaching to the wrong browser.
+// Prefer an explicit override, then the port inject recorded. Do not guess
+// 9222 — that is how we attach to a different browser than the one we launched.
 function readDevState() {
   try {
     return JSON.parse(
@@ -82,18 +89,42 @@ const explicitPort =
   portArgIndex > -1 ? process.argv[portArgIndex + 1] : null;
 const explicitTarget =
   targetArgIndex > -1 ? process.argv[targetArgIndex + 1] : null;
-const savedLaunchMatches =
-  !explicitTarget || explicitTarget === devState.target;
-const useSavedLaunch =
-  !explicitPort &&
-  !process.env.CDP_PORT &&
-  savedLaunchMatches;
-const port = String(
-  explicitPort ||
-    process.env.CDP_PORT ||
-    (useSavedLaunch ? devState.debugPort : null) ||
-    "9222",
-);
+const { useSavedLaunch, port } = resolveAttachLaunch({
+  explicitPort,
+  envPort: process.env.CDP_PORT,
+  explicitTarget,
+  savedTarget: devState.target,
+  savedDebugPort: devState.debugPort,
+});
+if (!port) {
+  console.error(
+    `attach: no CDP port. Run "foldspace inject" first, or pass --port / CDP_PORT.\n` +
+      `        Refusing to guess 9222 — that port is often someone else's Chrome.`,
+  );
+  process.exit(1);
+}
+const profileDir = chromeProfileDir(root);
+const claimed = verifyLaunchSentinel({
+  profileDir,
+  token: devState.sentinel,
+});
+if (!claimed.ok) {
+  console.error(
+    `attach: ${ownershipErrorMessage(claimed.reason, { port, profileDir, root })}`,
+  );
+  process.exit(1);
+}
+const owned = await assertOwnedCdp({
+  profileDir,
+  port,
+  token: devState.sentinel,
+});
+if (!owned.ok) {
+  console.error(
+    `attach: ${ownershipErrorMessage(owned.reason, { port, profileDir, root })}`,
+  );
+  process.exit(1);
+}
 let attachMode;
 try {
   attachMode = attachModeFromArgs(process.argv.slice(2));
@@ -883,8 +914,8 @@ let ws;
 // temporal dead zone, throwing instead of reconnecting.
 const keepAlive = setInterval(() => {}, 1 << 30);
 
-async function connect() {
-  const ver = await (await fetch(`http://localhost:${port}/json/version`)).json();
+async function connect(version) {
+  const ver = version;
   const socket = new WebSocket(ver.webSocketDebuggerUrl);
   await new Promise((resolve, reject) => {
     socket.onopen = resolve;
@@ -912,7 +943,7 @@ async function connect() {
   return ver;
 }
 
-const ver = await connect();
+const ver = await connect(owned.version);
 
 console.log(`Attached to ${ver.Browser} on :${port}`);
 console.log(`Mode:  ${attachMode}`);

package/bin/inject.mjs

@@ -15,6 +15,11 @@ 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";
 
 // Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
 // hosted builder point the harness at a workspace it controls.
@@ -180,26 +185,7 @@ if (!chrome) {
 fs.mkdirSync(profileDir, { recursive: true });
 
 const debugPort = args.port || "9222";
-
-// Record it so attach does not have to be told again. inject and attach
-// disagreeing about the port is how you end up attached to a different
-// browser than the one you launched.
-fs.mkdirSync(workDir, { recursive: true });
-fs.writeFileSync(
-  path.join(workDir, "state.json"),
-  JSON.stringify(
-    {
-      debugPort,
-      target: targetName,
-      resolvedTarget: {
-        ...target,
-        sdkUrl: cfg.sdkUrl,
-      },
-    },
-    null,
-    2,
-  ),
-);
+const sentinel = writeLaunchSentinel(profileDir);
 
 // Name the profile so this window is identifiable among other Chrome windows.
 function nameProfile() {
@@ -244,6 +230,7 @@ const chromeArgs = [
   "--no-first-run",
   "--no-default-browser-check",
   "--test-type",
+  "--remote-allow-origins=*",
   startUrl,
 ];
 
@@ -253,6 +240,45 @@ console.log("Log in to the app once — the profile persists between runs.\n");
 const child = spawn(chrome, chromeArgs, { detached: true, stdio: "ignore" });
 child.unref();
 
+const owned = await waitForOwnedCdp({
+  profileDir,
+  port: debugPort,
+  token: sentinel,
+});
+if (!owned.ok) {
+  try {
+    if (child.pid) process.kill(child.pid, "SIGTERM");
+  } catch {
+    // The isolated window may still be open without a debug port.
+  }
+  console.error(`inject: ${ownershipErrorMessage(owned.reason, {
+    port: debugPort,
+    profileDir,
+    root,
+  })}`);
+  process.exit(1);
+}
+
+// Record only after the listener is provably this profile. Writing the port
+// first is how attach adopted someone else's Chrome on :9222.
+fs.mkdirSync(workDir, { recursive: true });
+fs.writeFileSync(
+  path.join(workDir, "state.json"),
+  JSON.stringify(
+    {
+      debugPort,
+      sentinel,
+      target: targetName,
+      resolvedTarget: {
+        ...target,
+        sdkUrl: cfg.sdkUrl,
+      },
+    },
+    null,
+    2,
+  ),
+);
+
 // --- theme -------------------------------------------------------------
 //
 // Chrome 151 ignores --load-extension, so load the optional cosmetic theme
@@ -260,34 +286,24 @@ child.unref();
 //
 // The CDP Extensions domain still works (that is what
 // --enable-unsafe-extension-debugging is for), so load the theme that way.
-// Only the theme: the SDK and actions arrive over CDP from attach.mjs, and the
-// dev extension is not required for them.
-async function loadTheme() {
-  const endpoint = `http://127.0.0.1:${debugPort}/json/version`;
-  for (let i = 0; i < 40; i++) {
-    try {
-      const version = await (await fetch(endpoint)).json();
-      const ws = new WebSocket(version.webSocketDebuggerUrl);
-      await new Promise((resolve, reject) => {
-        ws.addEventListener("open", resolve);
-        ws.addEventListener("error", reject);
-      });
-      const done = new Promise((resolve) => {
-        ws.addEventListener("message", (event) => {
-          const message = JSON.parse(event.data);
-          if (message.id === 1) resolve(message);
-        });
-      });
-      ws.send(JSON.stringify({ id: 1, method: "Extensions.loadUnpacked", params: { path: themeDir } }));
-      const result = await done;
-      ws.close();
-      if (result.error) console.log(`  theme not applied: ${result.error.message}`);
-      return;
-    } catch {
-      await new Promise((resolve) => setTimeout(resolve, 500));
-    }
-  }
-  console.log("  theme not applied: Chrome did not expose CDP in time");
+// Only the theme: the SDK and actions arrive over CDP from attach.mjs, and
+// the dev extension is not required for them.
+async function loadTheme(version) {
+  const ws = new WebSocket(version.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener("open", resolve);
+    ws.addEventListener("error", reject);
+  });
+  const done = new Promise((resolve) => {
+    ws.addEventListener("message", (event) => {
+      const message = JSON.parse(event.data);
+      if (message.id === 1) resolve(message);
+    });
+  });
+  ws.send(JSON.stringify({ id: 1, method: "Extensions.loadUnpacked", params: { path: themeDir } }));
+  const result = await done;
+  ws.close();
+  if (result.error) console.log(`  theme not applied: ${result.error.message}`);
 }
 
-await loadTheme();
+await loadTheme(owned.version);

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
     "foldspace": "bin/cli.mjs",
     "harness": "bin/cli.mjs"
   },
+  "exports": {
+    "./runtime": {
+      "types": "./src/runtime/index.ts",
+      "default": "./src/runtime/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "test": "node --test test/*.test.mjs"
   },

package/src/attach-helpers.mjs

@@ -15,6 +15,38 @@ export function attachModeFromArgs(argv) {
   return ATTACH_MODES.SWAP;
 }
 
+function present(value) {
+  if (value == null) return null;
+  const text = String(value);
+  return text ? text : null;
+}
+
+/**
+ * Resolve the Chrome debug port attach should connect to.
+ *
+ * An explicit --port or CDP_PORT always wins. Otherwise the port inject
+ * recorded is used only when the recorded target still matches. There is no
+ * fallback to 9222: that is Chrome's conventional debugging port, and guessing
+ * it attaches to whoever is listening — often not the profile we launched.
+ */
+export function resolveAttachLaunch({
+  explicitPort = null,
+  envPort = null,
+  explicitTarget = null,
+  savedTarget = null,
+  savedDebugPort = null,
+} = {}) {
+  const portOverride = present(explicitPort);
+  const envOverride = present(envPort);
+  const savedPort = present(savedDebugPort);
+  const useSavedLaunch =
+    !portOverride &&
+    !envOverride &&
+    (!explicitTarget || explicitTarget === savedTarget);
+  const port = portOverride || envOverride || (useSavedLaunch ? savedPort : null);
+  return { useSavedLaunch, port };
+}
+
 export function hostPatternsFromMatches(matches) {
   return matches.map((match) =>
     match.replace("*://", "").replace("/*", ""),

package/src/cdp-ownership.mjs

@@ -0,0 +1,241 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { createCdpRequestManager } from "./cdp-request-manager.mjs";
+
+export const SENTINEL_FILE = ".foldspace-sentinel";
+
+export function chromeProfileDir(root) {
+  return path.join(root, ".foldspace-dev", "chrome-profile");
+}
+
+export function sentinelPath(profileDir) {
+  return path.join(profileDir, SENTINEL_FILE);
+}
+
+function present(value) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  return text ? text : null;
+}
+
+function resolvedPath(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return path.resolve(filePath);
+  }
+}
+
+export function writeLaunchSentinel(profileDir) {
+  const token = crypto.randomBytes(16).toString("hex");
+  fs.mkdirSync(profileDir, { recursive: true });
+  fs.writeFileSync(sentinelPath(profileDir), `${token}\n`, "utf8");
+  return token;
+}
+
+export function readLaunchSentinel(profileDir) {
+  try {
+    return present(fs.readFileSync(sentinelPath(profileDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function verifyLaunchSentinel({ profileDir, token } = {}) {
+  const onDisk = readLaunchSentinel(profileDir);
+  const expected = present(token);
+  if (!expected || !onDisk || onDisk !== expected) {
+    return { ok: false, reason: "sentinel_mismatch" };
+  }
+  return { ok: true };
+}
+
+export function parseChromeVersionText(text) {
+  const body = String(text || "");
+  const profilePath = present(body.match(/Profile Path\s+(.+)/i)?.[1]);
+  const commandLine = present(
+    body.match(/Command Line\s+(.+?)(?=\n[A-Z][A-Za-z ]+\s|\n{2}|$)/s)?.[1],
+  );
+  const userDataMatch = commandLine?.match(
+    /--user-data-dir(?:=|\s+)(?:"([^"]+)"|(\S+))/,
+  );
+  return {
+    profilePath,
+    commandLine,
+    userDataDir: present(userDataMatch?.[1] || userDataMatch?.[2]),
+  };
+}
+
+export function reportedProfileMatches(profileDir, reported = {}) {
+  const expected = resolvedPath(profileDir);
+  if (reported.userDataDir) {
+    return resolvedPath(reported.userDataDir) === expected;
+  }
+  if (reported.profilePath) {
+    return resolvedPath(path.dirname(reported.profilePath)) === expected;
+  }
+  return false;
+}
+
+export function verifyCdpOwnership({ profileDir, token, reported } = {}) {
+  const sentinel = verifyLaunchSentinel({ profileDir, token });
+  if (!sentinel.ok) return sentinel;
+  if (!reportedProfileMatches(profileDir, reported)) {
+    return { ok: false, reason: "profile_mismatch" };
+  }
+  return { ok: true };
+}
+
+export function ownershipErrorMessage(
+  reason,
+  { port, profileDir, root } = {},
+) {
+  const profile =
+    root && profileDir
+      ? path.relative(root, profileDir) || profileDir
+      : profileDir || ".foldspace-dev/chrome-profile";
+  const hints = {
+    sentinel_mismatch:
+      "Launch sentinel is missing or does not match. Run foldspace inject again.",
+    profile_mismatch: `The browser on :${port} is using a different user-data-dir than ${profile}.`,
+    cdp_inspect_failed: `Could not read the profile path from Chrome on :${port}.`,
+    cdp_not_ready: `Chrome did not expose CDP on :${port}.`,
+  };
+  return (
+    `Chrome on :${port} is not the Foldspace profile.\n` +
+    `        ${hints[reason] || reason}\n` +
+    `        Close the other debugging Chrome, or pass --port <free-port>.`
+  );
+}
+
+export async function fetchCdpVersion(port) {
+  const response = await fetch(`http://127.0.0.1:${port}/json/version`);
+  if (!response.ok) {
+    throw new Error(`CDP /json/version returned ${response.status}`);
+  }
+  return response.json();
+}
+
+async function openCdpSocket(webSocketDebuggerUrl) {
+  const cdp = createCdpRequestManager({ timeoutMs: 8_000 });
+  const ws = new WebSocket(webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener("open", resolve);
+    ws.addEventListener("error", reject);
+  });
+  ws.addEventListener("message", (event) => {
+    cdp.handleMessage(JSON.parse(event.data));
+  });
+  return {
+    ws,
+    call: (method, params, sessionId) => cdp.call(ws, method, params, sessionId),
+    close() {
+      cdp.failAll();
+      ws.close();
+    },
+  };
+}
+
+export async function inspectCdpUserDataDir(webSocketDebuggerUrl) {
+  const session = await openCdpSocket(webSocketDebuggerUrl);
+  try {
+    const { targetId } = await session.call("Target.createTarget", {
+      url: "chrome://version/",
+    });
+    const attached = await session.call("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+    const sessionId = attached.sessionId;
+    await session.call("Runtime.enable", {}, sessionId);
+    await session.call("Page.enable", {}, sessionId);
+
+    let text = "";
+    for (let attempt = 0; attempt < 20; attempt++) {
+      const evaluation = await session.call(
+        "Runtime.evaluate",
+        {
+          expression: "document.body ? document.body.innerText : ''",
+          returnByValue: true,
+        },
+        sessionId,
+      );
+      text = evaluation?.result?.value || "";
+      if (/Profile Path|Command Line/i.test(text)) break;
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+
+    try {
+      await session.call("Target.closeTarget", { targetId });
+    } catch {
+      // Best-effort: ownership can still be decided from the text we got.
+    }
+
+    const reported = parseChromeVersionText(text);
+    if (!reported.userDataDir && !reported.profilePath) {
+      throw new Error("chrome://version did not expose a profile path");
+    }
+    return reported;
+  } finally {
+    session.close();
+  }
+}
+
+export async function assertOwnedCdp({
+  profileDir,
+  port,
+  token,
+  fetchVersion = fetchCdpVersion,
+  inspectUserDataDir = inspectCdpUserDataDir,
+} = {}) {
+  const sentinel = verifyLaunchSentinel({ profileDir, token });
+  if (!sentinel.ok) return sentinel;
+
+  let version;
+  try {
+    version = await fetchVersion(port);
+  } catch {
+    return { ok: false, reason: "cdp_not_ready", version: null };
+  }
+
+  let reported;
+  try {
+    reported = await inspectUserDataDir(version.webSocketDebuggerUrl);
+  } catch {
+    return { ok: false, reason: "cdp_inspect_failed", version };
+  }
+
+  const result = verifyCdpOwnership({ profileDir, token, reported });
+  return { ...result, version, reported };
+}
+
+export async function waitForOwnedCdp({
+  profileDir,
+  port,
+  token,
+  timeoutMs = 20_000,
+  fetchVersion = fetchCdpVersion,
+  inspectUserDataDir = inspectCdpUserDataDir,
+  now = Date.now,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  const started = now();
+  let last = { ok: false, reason: "cdp_not_ready", version: null };
+  while (now() - started < timeoutMs) {
+    last = await assertOwnedCdp({
+      profileDir,
+      port,
+      token,
+      fetchVersion,
+      inspectUserDataDir,
+    });
+    if (last.ok) return last;
+    if (last.reason !== "cdp_not_ready" && last.reason !== "cdp_inspect_failed") {
+      return last;
+    }
+    await sleep(250);
+  }
+  return last;
+}

package/src/cli-registry.mjs

@@ -194,7 +194,7 @@ export const CLI_COMMANDS = Object.freeze([
       value(
         "--port",
         "number",
-        "CDP port: CLI, CDP_PORT, saved launch state, then 9222",
+        "CDP port: CLI, CDP_PORT, or the port inject recorded",
       ),
       value("--agent", "api-name", "Override the configured agent API name"),
       flag(
@@ -217,6 +217,7 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     effects: [
       "May reload and instrument matching target pages",
+      "Refuses a Chrome that is not the profile inject launched",
       "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",

package/src/runtime/agent.ts

@@ -0,0 +1,66 @@
+import { getConfig } from "./config";
+
+let cached: any | null = null;
+
+/**
+ * Foldspace SDK handle for this agent's **overlay** instance.
+ *
+ * Takes no `mode` on purpose: `foldspace.agent({ apiName })` returns the overlay
+ * handle. On an app that embeds the copilot in-page that is not the instance
+ * serving the chat, so arming only it succeeds and leaves real conversations
+ * untagged. For a specific instance, enumerate `window.foldspace.agentIds()`
+ * (`"<mode>-<apiName>"`) and call `foldspace.agent({ apiName, mode })`.
+ *
+ * This is a thin wrapper around the SDK, not a second agent implementation.
+ * Cached after the first successful lookup.
+ *
+ * @returns The overlay agent, or `null` if the SDK is not on the page
+ */
+export function getAgent(): any | null {
+  if (cached) return cached;
+  cached =
+    (window as any).foldspace?.agent({ apiName: getConfig().agentApiName }) ??
+    null;
+  return cached;
+}
+
+/**
+ * Arm every Foldspace instance on the page for test mode and remote actions.
+ *
+ * Calls SDK `setTestMode` and `setConfiguration({ remoteActionsSettings })`.
+ * Local `foldspace attach` already injects test-mode arming without putting it
+ * in `dist/index.js`. Prefer that. Importing this helper from an action can
+ * ship those calls into the production CDN bundle.
+ *
+ * Do not call from `execute`. Partial `setConfiguration` has collapsed the
+ * widget to 0×0 in a real build.
+ *
+ * @param testMode - When true, mark conversations as test traffic
+ * @returns Instance ids that armed vs failed
+ */
+export function armAllInstances(testMode = true): {
+  armed: string[];
+  failed: string[];
+} {
+  const fs = (window as any).foldspace;
+  const armed: string[] = [];
+  const failed: string[] = [];
+  if (!fs || typeof fs.agentIds !== "function") return { armed, failed };
+
+  for (const id of fs.agentIds() as string[]) {
+    const cut = id.indexOf("-");
+    if (cut < 1) continue;
+    try {
+      const inst = fs.agent({
+        apiName: id.slice(cut + 1),
+        mode: id.slice(0, cut).toUpperCase(),
+      });
+      inst.setTestMode(testMode);
+      inst.setConfiguration({ remoteActionsSettings: { enabled: true } });
+      armed.push(id);
+    } catch {
+      failed.push(id);
+    }
+  }
+  return { armed, failed };
+}