@foldspace_npm/harness 0.1.31 → 0.1.33

package/src/cli-registry.mjs

@@ -32,7 +32,7 @@ export const CLI_COMMANDS = Object.freeze([
       {
         name: "directory",
         required: "non-interactive",
-        description: "New project directory",
+        description: "Project directory: a new one, or one that holds nothing but files the system or an editor put there",
       },
     ],
     options: [
@@ -59,10 +59,10 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     prerequisites: [
       "Node 20 or newer",
-      "A target directory that does not already exist",
+      "A target directory that does not exist yet, or holds nothing but .DS_Store, .localized, Icon\\r, ._*, Thumbs.db, desktop.ini, .mcp.json, .git/, .vscode/, .cursor/, .idea/ or .claude/ without settings.json, and is not the home directory, its Desktop, Documents or Downloads, the disk's root, a Claude Code Desktop no-folder session, or a Codex chat's folder (~/Documents/Codex and the folders directly in it)",
       "Non-interactive use requires directory, product ID, Agent Key, and app domain",
     ],
-    effects: ["Creates a new local project; never initializes Git"],
+    effects: ["Creates a local project in a new folder, or in place in one that holds nothing but files the system or an editor put there; never overwrites a file and never initializes Git"],
     next: [
       "npm install --ignore-scripts",
       "Before the first build, CLAUDE.md step 5 (\"Every session starts the same way\"): with a code project, its agent/ replaces the scaffold's",
@@ -107,6 +107,8 @@ export const CLI_COMMANDS = Object.freeze([
       "With --yes, writes the latest version into package.json (exact) and runs npm install --ignore-scripts",
       "Does not rebuild dist/index.js or publish anything",
       "--refresh-instructions copies CLAUDE.md to CLAUDE.md.bak then writes the stub",
+      "With --yes or --refresh-instructions, writes the harness's skills (share-a-video) into .claude/skills/ from the installed version, keeping a copy that differs as <file>.bak; other skills there are left alone",
+      "Any foldspace command writes a harness skill the project is missing, so the first upgrade from a harness older than the skill still gets it",
     ],
     next: [
       "If outdated, ask the human, then run npx foldspace upgrade --yes",
@@ -440,6 +442,96 @@ export const CLI_COMMANDS = Object.freeze([
       "To go back to the local build: npx foldspace attach --daemon",
     ],
   }),
+  Object.freeze({
+    name: "record",
+    entry: "record.mjs",
+    group: "share",
+    summary: "Record a short video of the agent's key use cases, answered in the test window, for the human to share",
+    usage:
+      "foldspace record [--scenes <file>] [--preset landscape|square] [--no-end-card] [--from <record-dir>]",
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT", "CHROME_PATH"],
+    capabilities: ["browser.cdp", "page.evaluate", "browser.launch"],
+    positionals: [],
+    options: [
+      value("--scenes", "file", "The scenes and their captions: { product, scenes: [{ question, capabilities, line }] }", {
+        default: "video/scenes.json",
+      }),
+      value("--preset", "landscape|square", "1920x1080 or 1080x1080; either way the whole product stays in the frame", {
+        default: "landscape",
+        choices: ["landscape", "square"],
+      }),
+      flag("--no-end-card", "Leave out the closing card"),
+      value(
+        "--from",
+        "record-dir",
+        "Make the video again from an earlier recording, with the capabilities and lines in the scenes file now; records nothing",
+      ),
+    ],
+    prerequisites: [
+      "The test window from `npm run inject`, signed in, with the agent on the page: `npx foldspace attach --daemon` running, or after `npx foldspace published`",
+      "attach without --test-mode",
+      "Each question already proven with `npx foldspace ask`",
+      "Google Chrome, which makes the video (some Chromium builds cannot encode H.264)",
+    ],
+    effects: [
+      "Asks each question in a new conversation, typed key by key: real conversations, in their Foldspace dashboard",
+      "The video shows real data from the signed-in account; nothing is masked. Whether to share it is the human's call",
+      "Hides the pill and the corner tag while it records, and puts them back after - also when it is stopped (Ctrl-C, a timeout)",
+      "Runs for a few minutes: give it a 10-minute timeout",
+      "Records with Chrome's own screen capture (no screen-recording permission) into .foldspace-dev/record/, keeping the 3 latest finished recordings",
+      "Makes the video in a separate hidden Chrome; writes video/<product>-<date>.mp4 and a .jpg poster, and video/.gitignore so neither is saved with the code",
+      "Uploads nothing and posts nothing",
+    ],
+    next: [
+      "Read the poster and each scene's lastFrame: every answer complete, none an error. The human watches the video",
+      "Hand over the MP4 and the poster: say plainly it shows real data from their account, and that sharing it is their call",
+      "To change a scene's capabilities or line: edit the scenes file, then `npx foldspace record --from <recordDir>`",
+    ],
+  }),
+  Object.freeze({
+    name: "share",
+    entry: "share.mjs",
+    group: "share",
+    summary: "Size and check a video for a Foldspace share link, then upload it with the targets create_video_share returned",
+    usage: "foldspace share <inspect|upload> [<video.mp4>] [--poster <file.jpg>] [--targets '<json>']",
+    risk: "remote-upload",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["video.upload"],
+    positionals: [
+      Object.freeze({
+        name: "action",
+        required: true,
+        description:
+          "inspect: size and check the MP4 and its poster here, uploading nothing | upload: send both to Foldspace's video storage with the targets create_video_share returned",
+      }),
+      Object.freeze({
+        name: "video",
+        required: false,
+        description: "The MP4; default the newest video/*.mp4 that `record` made",
+      }),
+    ],
+    options: [
+      value("--poster", "file.jpg", "The JPEG poster", { default: "the MP4's name with .jpg" }),
+      value("--targets", "json", "upload only: the targets JSON exactly as the upload command from create_video_share has it"),
+    ],
+    prerequisites: [
+      "An H.264 MP4 with its moov box first (what `record` makes) and a JPEG poster",
+      "upload: the human said yes to a public link, and the Foldspace MCP tool create_video_share returned the upload command (its targets last 30 minutes)",
+    ],
+    effects: [
+      "inspect reads the two files and nothing else",
+      "upload sends the MP4 and the poster to Foldspace's video storage, and only there; it reads no Foldspace sign-in",
+      "Never prints the upload targets: each is a one-time credential for one file",
+      "Anyone with the link publish_video_share returns can watch the video, which shows real data from the account",
+    ],
+    next: [
+      "After inspect, with the human's yes: create_video_share with a title, video_bytes and poster_bytes, then run its upload command",
+      "After upload: publish_video_share with the share_id; give the human the link",
+    ],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no
@@ -492,12 +584,14 @@ export const CAPABILITY_CATALOGUE = Object.freeze([
   ["page.evaluate", "Inspect bounded SDK and registration state"],
   ["page.mutate", "Prepare and restore a matching development page"],
   ["artifact.publish", "Write the built artifact to remote storage"],
+  ["video.upload", "Upload a video and its poster for a Foldspace share link, with targets the Foldspace MCP issued"],
 ]);
 
 export const RISK_CATALOGUE = Object.freeze([
   ["local-write", "Writes only inside the consuming project"],
   ["browser-session", "Launches or temporarily mutates a local browser session"],
   ["remote-publish", "Writes the action artifact to remote storage"],
+  ["remote-upload", "Uploads files the human chose to share to Foldspace's video storage"],
 ]);
 
 export const ENVIRONMENT_CATALOGUE = Object.freeze([

package/src/init.mjs

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
@@ -299,13 +300,11 @@ function createTemplateValues(config, harnessVersion) {
     throw new Error("Display name must be a non-empty single line and cannot contain '{{'.");
   }
 
-  const packageName = toPackageName(displayName);
-  if (!packageName) {
-    throw new Error("Display name must contain at least one letter or number.");
-  }
-
   const productId = validateProductId(config.productId);
   const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
+  // A name in another alphabet, such as a folder the human named, has no
+  // letters a package name can use; the Agent Key always has.
+  const packageName = toPackageName(displayName) || toPackageName(agentApiName);
   const region = parseRegion(config.region || DEFAULT_REGION);
   const target = normalizeTarget(config.domain);
   const hosts =
@@ -362,14 +361,17 @@ function copyTemplate(templateRoot, targetRoot, values) {
       const sourcePath = path.join(templateRoot, relativePath);
       // npm excludes .gitignore files from package tarballs, so the bundled
       // template uses a publish-safe name and restores it during generation.
-      // The permission allowlist lives in .claude/, kept flat here for the
-      // same reason.
+      // The permission allowlist and the skills live in .claude/, kept flat
+      // here for the same reason - and so a session working on the harness
+      // itself does not pick the skills up as its own.
       const outputPath =
         relativePath === "gitignore"
           ? ".gitignore"
           : relativePath === "claude-settings.json"
             ? path.join(".claude", "settings.json")
-            : relativePath;
+            : relativePath === "skills" || relativePath.startsWith(`skills${path.sep}`)
+              ? path.join(".claude", relativePath)
+              : relativePath;
       const targetPath = path.join(targetRoot, outputPath);
       assertInside(targetRoot, targetPath);
 
@@ -401,10 +403,147 @@ function validateGeneratedProject(projectDir) {
   }
 }
 
+// What a folder the human made for their agent may already hold: files the
+// system, an editor or Claude Code put there. The template writes none of them
+// except .claude/settings.json, and init leaves each one as it is.
+const ignorableFiles = new Set([".ds_store", ".localized", "icon\r", "thumbs.db", "desktop.ini", ".mcp.json"]);
+const ignorableDirectories = new Set([".claude", ".git", ".vscode", ".cursor", ".idea"]);
+
+function isIgnorableEntry(entry) {
+  const name = entry.name.toLowerCase();
+  if (entry.isDirectory()) {
+    return ignorableDirectories.has(name);
+  }
+  // A .git file, not a folder, belongs to another repository's worktree or
+  // submodule, so it is not ignorable.
+  return entry.isFile() && (ignorableFiles.has(name) || name.startsWith("._"));
+}
+
+// What stops init from filling an existing folder; an empty list means nothing.
+function existingTargetBlockers(targetDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(`Refusing to set up a project in ${targetDir}: it cannot be read (${error.code || error.message}).`);
+  }
+  const blockers = entries
+    .filter((entry) => !isIgnorableEntry(entry))
+    .map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
+    .sort((a, b) => a.localeCompare(b));
+  // The one template file that lands inside an ignorable folder. lstat, so a
+  // link there counts even when what it points to is missing.
+  if (fs.lstatSync(path.join(targetDir, ".claude", "settings.json"), { throwIfNoEntry: false })) {
+    blockers.push(path.join(".claude", "settings.json"));
+  }
+  return blockers;
+}
+
+function realPath(target) {
+  try {
+    return fs.realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+// Folders init never fills, even empty: the home folder and its own Desktop,
+// Documents and Downloads, the disk's root, the folders Claude Code
+// Desktop makes for a session started with no folder, which the human cannot
+// find again, and Codex's folder for chats with no project
+// (~/Documents/Codex) and each chat's own folder in it.
+function personalFolderReason(targetDir) {
+  const target = realPath(targetDir);
+  const home = realPath(os.homedir());
+  if (path.dirname(target) === target) {
+    return "it is the disk's root";
+  }
+  if (target === home) {
+    return "it is the home folder";
+  }
+  if (path.dirname(target) === home && ["desktop", "documents", "downloads"].includes(path.basename(target).toLowerCase())) {
+    return `it is the home folder's ${path.basename(target)}`;
+  }
+  if (target.split(path.sep).includes("scratch-workspaces")) {
+    return "it is a temporary session folder";
+  }
+  const codexChats = path.join(home, "documents", "codex");
+  const lower = target.toLowerCase();
+  if (lower === codexChats.toLowerCase() || path.dirname(lower) === codexChats.toLowerCase()) {
+    return "it is Codex's folder for chats with no project; make the agent's folder next to the chat's, in ~/Documents/Codex";
+  }
+  return null;
+}
+
+function assertFillableTarget(targetDir) {
+  if (!fs.statSync(targetDir).isDirectory()) {
+    throw new Error(`Refusing to overwrite existing path: ${targetDir}`);
+  }
+  if (fs.existsSync(path.join(targetDir, "foldspace.dev.json"))) {
+    throw new Error(`${targetDir} is already a Foldspace project. Open it instead of running init.`);
+  }
+  const reason = personalFolderReason(targetDir);
+  if (reason) {
+    throw new Error(`Refusing to set up a project in ${targetDir}: ${reason}. Pass a new folder instead.`);
+  }
+  const blockers = existingTargetBlockers(targetDir);
+  if (blockers.length > 0) {
+    const shown = blockers.slice(0, 5).join(", ") + (blockers.length > 5 ? `, and ${blockers.length - 5} more` : "");
+    throw new Error(
+      `Refusing to set up a project in ${targetDir}: it already holds ${shown}. ` +
+        "init sets up a new folder, or one that holds nothing but files the system or an editor put there.",
+    );
+  }
+}
+
+// Fill an existing folder without replacing it, so a session working in it
+// stays in the same folder. A file that is already there is never
+// overwritten, and on any error everything this call created is removed.
+// foldspace.dev.json goes in last: init and the playbook take it to mean a
+// finished project, so a fill that is cut short never looks like one.
+function copyIntoExisting(sourceRoot, targetRoot) {
+  const created = [];
+  const lastAtRoot = (entries, relativeDir) =>
+    relativeDir === ""
+      ? [...entries.filter((entry) => entry.name !== "foldspace.dev.json"), ...entries.filter((entry) => entry.name === "foldspace.dev.json")]
+      : entries;
+  const walk = (relativeDir) => {
+    for (const entry of lastAtRoot(fs.readdirSync(path.join(sourceRoot, relativeDir), { withFileTypes: true }), relativeDir)) {
+      const relativePath = path.join(relativeDir, entry.name);
+      const sourcePath = path.join(sourceRoot, relativePath);
+      const targetPath = path.join(targetRoot, relativePath);
+      if (entry.isDirectory()) {
+        try {
+          fs.mkdirSync(targetPath);
+          created.push(targetPath);
+        } catch (error) {
+          // .claude/ is the one template folder the human's folder may hold.
+          if (error?.code !== "EEXIST" || relativePath !== ".claude") {
+            throw error;
+          }
+        }
+        walk(relativePath);
+        continue;
+      }
+      fs.copyFileSync(sourcePath, targetPath, fs.constants.COPYFILE_EXCL);
+      created.push(targetPath);
+    }
+  };
+  try {
+    walk("");
+  } catch (error) {
+    for (const createdPath of created.reverse()) {
+      fs.rmSync(createdPath, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+
 export function scaffoldProject(config, options = {}) {
   const targetDir = config.targetDir;
-  if (fs.existsSync(targetDir)) {
-    throw new Error(`Refusing to overwrite existing path: ${targetDir}`);
+  const inPlace = fs.existsSync(targetDir);
+  if (inPlace) {
+    assertFillableTarget(targetDir);
   }
 
   const templateRoot = options.templateRoot || defaultTemplateRoot;
@@ -414,17 +553,29 @@ export function scaffoldProject(config, options = {}) {
 
   const harnessVersion = options.harnessVersion || readHarnessVersion(options.packageRoot || packageRoot);
   const values = createTemplateValues(config, harnessVersion);
+  // A new folder is rendered next to where it goes, so it can be renamed into
+  // place in one step. Filling a folder copies file by file, so it renders in
+  // the system's temporary folder and leaves nothing beside the human's folder.
   const parentDir = path.dirname(targetDir);
   fs.mkdirSync(parentDir, { recursive: true });
-  const temporaryDir = fs.mkdtempSync(path.join(parentDir, `.${path.basename(targetDir)}.foldspace-init-`));
+  const temporaryDir = fs.mkdtempSync(
+    path.join(inPlace ? os.tmpdir() : parentDir, `.${path.basename(targetDir)}.foldspace-init-`),
+  );
 
   try {
     copyTemplate(templateRoot, temporaryDir, values);
     validateGeneratedProject(temporaryDir);
-    if (fs.existsSync(targetDir)) {
-      throw new Error(`Target path appeared while initializing: ${targetDir}`);
+    if (inPlace) {
+      // Checked again: something may have landed there while rendering.
+      assertFillableTarget(targetDir);
+      copyIntoExisting(temporaryDir, targetDir);
+      fs.rmSync(temporaryDir, { recursive: true, force: true });
+    } else {
+      if (fs.existsSync(targetDir)) {
+        throw new Error(`Target path appeared while initializing: ${targetDir}`);
+      }
+      fs.renameSync(temporaryDir, targetDir);
     }
-    fs.renameSync(temporaryDir, targetDir);
   } catch (error) {
     fs.rmSync(temporaryDir, { recursive: true, force: true });
     throw error;
@@ -434,6 +585,7 @@ export function scaffoldProject(config, options = {}) {
     targetDir,
     packageName: values.PACKAGE_NAME,
     harnessVersion,
+    inPlace,
   };
 }
 
@@ -496,11 +648,13 @@ export async function runInit(argv, options = {}) {
   const log = options.log || console.log;
   const installed = await maybeInstallDependencies(result.targetDir, options);
 
-  log(`Created Foldspace project at ${result.targetDir}`);
+  log(`${result.inPlace ? "Set up Foldspace project in" : "Created Foldspace project at"} ${result.targetDir}`);
   log(`Using @foldspace_npm/harness ${result.harnessVersion}`);
   log("");
   log("Next steps:");
-  log(`  cd ${result.targetDir}`);
+  if (path.resolve(process.cwd()) !== result.targetDir) {
+    log(`  cd ${result.targetDir}`);
+  }
   if (!installed) {
     log("  npm install --ignore-scripts");
   }

package/src/panel-driver.mjs

@@ -0,0 +1,283 @@
+// Driving the agent's panel the way a person does: open it, type into the
+// composer, press Enter, read the screen. Shared by `foldspace ask` and
+// `foldspace record`.
+//
+// Nothing here reaches into the SDK's internals, patches fetch or injects into
+// the panel. The panel is the SDK's iframe#eucera-agent-iframe; its document is
+// readable from the page, so the reply is read from what is on screen.
+
+import { createSettleTracker, replyAfter, squash } from "./ask-core.mjs";
+import { sleep } from "./cdp-client.mjs";
+
+export const PANEL_ID = "eucera-agent-iframe";
+
+// Shared by every page snippet: the panel document, or null while it loads.
+export const PANEL_DOC = `
+  const frame = document.getElementById(${JSON.stringify(PANEL_ID)});
+  let doc = null;
+  try { doc = frame && frame.contentDocument; } catch {}
+`;
+
+// The agent handle: the one attach's bootstrap made, else the page's own SDK
+// handle for this project's agent. Defines `sdk` and `agent` for the snippet
+// that follows.
+const AGENT_HANDLE = (agentApiName) => `
+  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() });
+    }
+  }
+`;
+
+export async function panelState(page) {
+  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.
+export async function openPanel(page, agentApiName) {
+  return page.evaluate(`${AGENT_HANDLE(agentApiName)}
+    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) }; }`);
+}
+
+/**
+ * Open the panel until its composer shows. The composer does not exist until
+ * the panel has opened, and one open() is not always enough, so it is retried
+ * inside the poll. Gives up early when there is no panel and no SDK at all.
+ */
+export async function openComposer(page, agentApiName, { waitS = 30 } = {}) {
+  let state = await panelState(page);
+  let opened = { sdk: false, opened: false };
+  for (let tick = 0; tick < waitS && !(state.composer && state.visible); tick++) {
+    opened = await openPanel(page, agentApiName).catch(() => opened);
+    await sleep(1000);
+    state = await panelState(page).catch(() => state);
+    if (tick === 5 && !state.frame && !opened.sdk) break;
+  }
+  return { state, opened };
+}
+
+export async function readPanel(page, 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,
+    };`);
+}
+
+/** Where the panel sits in the page, in CSS pixels, with the viewport size; null without one. */
+export async function panelRect(page) {
+  return page.evaluate(`${PANEL_DOC}
+    if (!frame) return null;
+    const rect = frame.getBoundingClientRect();
+    return {
+      x: rect.left, y: rect.top, width: rect.width, height: rect.height,
+      viewportWidth: window.innerWidth, viewportHeight: window.innerHeight,
+    };`);
+}
+
+async function focusComposer(page) {
+  return 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;`);
+}
+
+export async function composerValue(page) {
+  return page
+    .evaluate(`${PANEL_DOC}
+      const box = doc && doc.querySelector("textarea");
+      return box ? box.value : "";`)
+    .catch(() => "");
+}
+
+/** Enter as real key events through the browser's input pipeline. */
+export async function pressEnter(page) {
+  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 });
+}
+
+// Real key events through the browser's input pipeline, like a person at the
+// keyboard. Frameworks that ignore synthetic DOM events still hear these.
+export async function typeLikeAPerson(page, text) {
+  const focused = await focusComposer(page);
+  if (!focused) return false;
+  await page.send("Input.insertText", { text });
+  const typed = await composerValue(page);
+  if (squash(typed) !== text) return false;
+  await pressEnter(page);
+  return true;
+}
+
+// The same gesture delivered as DOM events on the composer; still only typing,
+// still nothing injected. `submit` false fills the box and presses nothing.
+async function setComposerWithDomEvents(page, text, { submit = true } = {}) {
+  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 }));
+    if (${submit ? "true" : "false"}) {
+      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;`);
+}
+
+// A background or unfocused tab can swallow CDP input. Same gesture, delivered
+// as DOM events on the composer.
+export async function typeWithDomEvents(page, text) {
+  return setComposerWithDomEvents(page, text, { submit: true });
+}
+
+/**
+ * Type the question and send it, the way `ask` always has: the keyboard
+ * first; if the question is still sitting in the composer afterwards, Enter
+ * never landed, so the same thing again as DOM events.
+ */
+export async function sendQuestion(page, question) {
+  let typedBy = "keyboard";
+  let sent = await typeLikeAPerson(page, question).catch(() => false);
+  await sleep(700);
+  // Still sitting in the composer means Enter never landed.
+  if (!sent || squash(await composerValue(page)) === question) {
+    typedBy = "dom-events";
+    sent = await typeWithDomEvents(page, question).catch(() => false);
+  }
+  return { sent, typedBy };
+}
+
+/**
+ * Type the question one character at a time, so a recording shows it being
+ * typed, then press Enter. Each character goes through the keyboard pipeline;
+ * if the window swallows CDP input, each one is set as a DOM input event
+ * instead - it still appears key by key. `delayMs` is the pause between keys.
+ * Returns { sent, typedBy, enteredAt }: enteredAt is when the Enter that sent
+ * it was pressed (ms), for a recording's timeline.
+ */
+export async function typeKeyByKey(page, question, { delayMs = 45 } = {}) {
+  const characters = [...question];
+  let typedBy = "keyboard";
+  if (!(await focusComposer(page).catch(() => false))) return { sent: false, typedBy };
+  let typed = "";
+  for (const character of characters) {
+    typed += character;
+    if (typedBy === "keyboard") {
+      await page.send("Input.insertText", { text: character }).catch(() => {});
+      // Checked on the first key only: the composer either hears CDP or not.
+      if (typed.length === 1 && (await composerValue(page)) !== typed) typedBy = "dom-events";
+    }
+    if (typedBy === "dom-events") {
+      await setComposerWithDomEvents(page, typed, { submit: false }).catch(() => false);
+    }
+    await sleep(delayMs);
+  }
+  if (squash(await composerValue(page)) !== squash(question)) return { sent: false, typedBy, enteredAt: null };
+  await sleep(250);
+  let enteredAt = Date.now();
+  await pressEnter(page).catch(() => {});
+  await sleep(500);
+  if (squash(await composerValue(page)) === squash(question)) {
+    // Enter never landed: the same key as DOM events.
+    enteredAt = Date.now();
+    await typeWithDomEvents(page, question).catch(() => false);
+    await sleep(400);
+    typedBy = "dom-events";
+  }
+  return { sent: squash(await composerValue(page)) !== squash(question), typedBy, enteredAt };
+}
+
+/**
+ * A fresh conversation, the way a person starts one: the New Chat button in
+ * the panel's header (its class is in both header layouts of the panel).
+ * Returns false when this panel shows no such button.
+ */
+export async function clickNewChat(page) {
+  return page.evaluate(`${PANEL_DOC}
+    const button = doc && doc.querySelector(".eucera-copilot-header-new-chat-icon");
+    if (!button) return false;
+    button.click();
+    return true;`);
+}
+
+/**
+ * The SDK's own way to put a question to the agent in a new conversation:
+ * agent.message(text, { newChat: true, autoSend: true }). The question is
+ * sent at once - nothing is typed - so it is only the fallback for a panel
+ * with no New Chat button.
+ */
+export async function messageInNewChat(page, agentApiName, question) {
+  return page.evaluate(`${AGENT_HANDLE(agentApiName)}
+    if (typeof agent?.message !== "function") return false;
+    agent.message(${JSON.stringify(question)}, { newChat: true, autoSend: true });
+    return true;`);
+}
+
+/**
+ * Poll the panel until the reply to `question` settles or `timeoutS` passes.
+ * `onPoll` sees each observation (with its time), for a caller that wants to
+ * know when the reply first appeared and when it last changed.
+ */
+export async function waitForReply(
+  page,
+  question,
+  { cardsBefore = 0, timeoutS = 90, pollMs = 1500, tracker = createSettleTracker(), onPoll } = {},
+) {
+  const deadline = Date.now() + timeoutS * 1000;
+  let seen = { panel: "", cards: [], newCardFrames: 0 };
+  let reply = "";
+  let settled = false;
+  while (Date.now() < deadline && !settled) {
+    await sleep(pollMs);
+    seen = await readPanel(page, cardsBefore).catch(() => seen);
+    reply = replyAfter(seen.panel, question);
+    settled = tracker.observe({ reply, cards: seen.cards }).settled;
+    if (onPoll) onPoll({ at: Date.now(), reply, seen, settled });
+  }
+  return { settled, reply, seen };
+}