@foldspace_npm/harness 0.1.33 → 0.1.34

package/recipes/bottom-bar/agent/bottomBar.ts

@@ -1,52 +1,64 @@
 // The bottom bar: the agent's resting entry point at the foot of the page,
-// cycling starters that fit the screen the user is on. Configured from code -
-// Agent Studio has no UI for it today, and this is how customers set it.
+// showing starters that fit the screen the user is on.
 // https://docs.foldspace.ai/customize/bottom-bar/
 // https://docs.foldspace.ai/customize/conversation-starters/
 //
+// Foldspace turns the bar on from its own settings, so this code never sends
+// `bottomBarSettings`: it only picks each page's starters.
+//
 // Product-neutral: the paths and starters below are placeholders. Replace them
-// with this product's own screens and with questions its actions can answer.
+// with this product's main-menu screens (`npx foldspace observe menu`) and,
+// for each, starters the agent can answer today.
 
 import { getAgent } from "./utils";
 
-/** Starters per screen. Paths are matched as prefixes, first match wins. */
-export const PAGE_STARTERS: Array<{ match: RegExp; starters: string[] }> = [
-  { match: /^\/dashboard/, starters: ["<A question about what this screen shows>", "<Another one>"] },
-  { match: /^\/<records>/, starters: ["Find <a record> by name", "Show me <a record>'s details"] },
-];
+/**
+ * The most starters one page shows, both groups together. The same call sets
+ * the agent panel's opening screen, and a long list there buries the one
+ * that matters. `npx foldspace lint` refuses more.
+ */
+export const MAX_STARTERS_PER_PAGE = 3;
 
-/** Shown on any page not listed above. */
-export const DEFAULT_STARTERS: string[] = ["What can you do?", "<A question one of its actions can answer>"];
+/**
+ * Starters per screen. Paths are matched as prefixes, first match wins.
+ * - `ACTION`: clicking it runs one of the agent's actions (the bar shows the
+ *   action icon), e.g. "Show my open invoices".
+ * - `KNOWLEDGE`: a question answered from what the agent knows (its knowledge
+ *   base), e.g. "How do I add a teammate?".
+ * A page that is not listed shows Agent Studio's starters.
+ */
+export const PAGE_STARTERS: Array<{ match: RegExp; KNOWLEDGE: string[]; ACTION: string[] }> = [
+  { match: /^\/dashboard/, KNOWLEDGE: [], ACTION: ["<Something an action shows about this screen>"] },
+  { match: /^\/<records>/, KNOWLEDGE: ["<A how-to question about this screen>"], ACTION: ["Find <a record> by name"] },
+];
 
-// The docs' settings, except two: `enabled: true` (the docs default it to
-// `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the
-// docs default 5). Change any of them only if the human asks: every field is
-// documented on the Bottom Bar page.
-export const BOTTOM_BAR_SETTINGS = {
-  enabled: true,
-  maxVisibleStarters: 3,
-  reopenFrequency: "EVERY_LOAD",
-  starterClickBehavior: "OPEN_AGENT",
-  idleTimeoutMs: 5000,
-  initialBehaviorMode: "FULL",
-} as const;
+export type PageStarters = (typeof PAGE_STARTERS)[number];
 
-export function startersForPath(pathname: string): string[] {
-  const hit = PAGE_STARTERS.find((entry) => entry.match.test(pathname));
-  return hit ? hit.starters : DEFAULT_STARTERS;
+/** This page's starters, or null for a page that keeps Agent Studio's. */
+export function startersForPath(pathname: string): PageStarters | null {
+  return PAGE_STARTERS.find((entry) => entry.match.test(pathname)) ?? null;
 }
 
 // On window, not in module scope: a bundle evaluated twice on one page must
 // not install two route listeners.
 const INSTALLED_FLAG = "__foldspace_bottom_bar__";
 
+const warned = new Set<string>();
+function warnOnce(method: string): void {
+  if (warned.has(method)) return;
+  warned.add(method);
+  console.warn(
+    `[foldspace] This page's Foldspace SDK has no ${method}(), so the bottom bar keeps Agent Studio's starters. Load a newer SDK to get page starters.`,
+  );
+}
+
 /**
- * Set up the bar and keep its starters matched to the page. Call once from
- * the bundle's entry point; safe to call again.
+ * Keep the bar's starters matched to the page. Call once from the bundle's
+ * entry point; safe to call again.
  *
  * `setConversationStarters` REPLACES the whole set for this page view (both
- * groups); passing `null` restores what Agent Studio has. Starters go in the
- * KNOWLEDGE group so the bar shows them as plain questions.
+ * groups) and also sets the panel's opening screen; `null` restores what
+ * Agent Studio has.
  */
 export function installBottomBar(): void {
   const foldspace = (window as any).foldspace;
@@ -57,7 +69,12 @@ export function installBottomBar(): void {
   foldspace("when", "ready", () => {
     const agent = getAgent();
     if (!agent) return;
-    let current: string[] = [];
+    if (typeof agent.setConversationStarters !== "function") {
+      warnOnce("setConversationStarters");
+      return;
+    }
+    // Agent Studio's starters are what the page starts with.
+    let current: PageStarters | null = null;
 
     // On a navigation, the bar is brought back to full only when its starters
     // changed, so the new ones are seen. Same starters: nothing is sent, and a
@@ -66,19 +83,40 @@ export function installBottomBar(): void {
       const next = startersForPath(window.location.pathname);
       if (next === current) return;
       current = next;
-      agent.setConversationStarters?.(
-        { KNOWLEDGE: next.map((title) => ({ title })), ACTION: [] },
-        "KNOWLEDGE",
-      );
-      if (reopen) agent.openBottomBar?.({ mode: "FULL" });
+      if (next) {
+        agent.setConversationStarters(
+          {
+            KNOWLEDGE: next.KNOWLEDGE.map((title) => ({ title })),
+            ACTION: next.ACTION.map((title) => ({ title })),
+          },
+          // The group shown first. Not documented: which group the bar itself
+          // shows when a page has both - check it on the page.
+          next.ACTION.length ? "ACTION" : "KNOWLEDGE",
+        );
+      } else {
+        agent.setConversationStarters(null);
+      }
+      if (!reopen) return;
+      if (typeof agent.openBottomBar === "function") agent.openBottomBar({ mode: "FULL" });
+      else warnOnce("openBottomBar");
     };
 
-    // One whole settings group per call, as the docs do.
-    agent.setConfiguration?.({ bottomBarSettings: BOTTOM_BAR_SETTINGS });
     apply(false);
 
-    // Single-page apps change the URL without a load: re-apply on navigation.
+    // Single-page apps change the address without a page load: re-apply on
+    // each navigation. The browser's own page-change event where it has one:
+    // `currententrychange` fires once the address has changed - router links,
+    // pushState, replaceState, back and forward. (`navigate` fires before the
+    // address changes, so the page it would read is the old one.)
     const onRouteChange = () => apply(true);
+    const navigation = (window as any).navigation;
+    if (navigation && typeof navigation.addEventListener === "function") {
+      navigation.addEventListener("currententrychange", onRouteChange);
+      return;
+    }
+    // Browsers without the Navigation API (some Safari and Firefox versions;
+    // not tried live): listen for back/forward and wrap pushState /
+    // replaceState.
     window.addEventListener("popstate", onRouteChange);
     const history = window.history as any;
     for (const method of ["pushState", "replaceState"] as const) {

package/recipes/bottom-bar/fixtures/configuration.sent.json

@@ -1,17 +1,18 @@
 {
-  "note": "This recipe makes no network calls. What it sends to the SDK on /dashboard:",
-  "setConfiguration": {
-    "bottomBarSettings": {
-      "enabled": true,
-      "maxVisibleStarters": 3,
-      "reopenFrequency": "EVERY_LOAD",
-      "starterClickBehavior": "OPEN_AGENT",
-      "idleTimeoutMs": 5000,
-      "initialBehaviorMode": "FULL"
+  "note": "This recipe makes no network calls and sends no bottomBarSettings (Foldspace turns the bar on). What it sends to the SDK on each page:",
+  "/dashboard": {
+    "setConversationStarters": {
+      "starters": { "KNOWLEDGE": [], "ACTION": [{ "title": "<Something an action shows about this screen>" }] },
+      "defaultStarterType": "ACTION"
     }
   },
-  "setConversationStarters": {
-    "starters": { "KNOWLEDGE": [{ "title": "<A question about what this screen shows>" }, { "title": "<Another one>" }], "ACTION": [] },
-    "defaultStarterType": "KNOWLEDGE"
+  "/<records>/42": {
+    "setConversationStarters": {
+      "starters": { "KNOWLEDGE": [{ "title": "<A how-to question about this screen>" }], "ACTION": [{ "title": "Find <a record> by name" }] },
+      "defaultStarterType": "ACTION"
+    }
+  },
+  "a page with no starters of its own, after one that had them": {
+    "setConversationStarters": { "starters": null }
   }
 }

package/recipes/swap-the-login-method/README.md

@@ -31,7 +31,7 @@ says). If you observed neither, leave the user anonymous.
 |---|---|
 | `SESSION_STORAGE_KEY`, `SESSION_HEADER` | The key and header name you **observed** |
 | `EXTRA_HEADERS` in the cookies variant | What you **observed** the app sending besides the cookies; most apps send none |
-| `API_BASE` in `constants.ts` | For a same-origin app, the app's own origin. Empty stays a failure on purpose, so a guessed host cannot look like success |
+| `API_BASE` in `constants.ts` | For a same-origin app, `"/api"` (the path), so each user's page calls its own host - on a product with a subdomain per customer, never the address you observed (the manual's **Each customer on their own subdomain**). Empty stays a failure on purpose, so a guessed host cannot look like success. Both files build their URLs with `apiBaseUrl()`, never `API_BASE` directly |
 
 ## What those builds learned the hard way
 

package/recipes/swap-the-login-method/agent/utils.ts

@@ -4,7 +4,7 @@
 // Only the transport is replaced. What a 401, a 404 or a 429 means still comes
 // from the harness, so actions and renderFailure behave exactly the same.
 
-import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { apiBaseUrl, configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
 import { AGENT_API_NAME, API_BASE } from "./constants";
 
 configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
@@ -27,13 +27,13 @@ export async function apiFetch<T = unknown>(
   // Empty API_BASE is a failure on purpose: a guessed host cannot look like
   // success. `error` is drawn on the card and read by the agent - it says what
   // is true; the builder's hint goes in `detail`, which only the console sees.
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
   const session = readSession();
@@ -42,7 +42,7 @@ export async function apiFetch<T = unknown>(
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: { "Content-Type": "application/json", [SESSION_HEADER]: session, ...(init.headers ?? {}) },
@@ -69,13 +69,13 @@ export async function apiFetchBinary(
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<Uint8Array>> {
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
   const session = readSession();
@@ -84,7 +84,7 @@ export async function apiFetchBinary(
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       signal: controller.signal,
       headers: { [SESSION_HEADER]: session, ...(init.headers ?? {}) },
@@ -103,6 +103,7 @@ export async function apiFetchBinary(
 // the harness's returns a config failure here, because this file sets no
 // `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
+  apiBaseUrl,
   getAgent,
   armAllInstances,
   rankBy,

package/recipes/swap-the-login-method/variants/utils.cookies.ts

@@ -4,7 +4,7 @@
 // There is nothing to check before the request, so "signed out" is only known
 // from the 401. It comes back as `signed_out` like any other.
 
-import { configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
+import { apiBaseUrl, configure, httpFailure, networkFailure, type ApiResult } from "@foldspace_npm/harness/runtime";
 import { AGENT_API_NAME, API_BASE } from "./constants";
 
 configure({ agentApiName: AGENT_API_NAME, apiBase: API_BASE });
@@ -24,20 +24,20 @@ export async function apiFetch<T = unknown>(
   // Empty API_BASE is a failure on purpose: a guessed host cannot look like
   // success. `error` is drawn on the card and read by the agent - it says what
   // is true; the builder's hint goes in `detail`, which only the console sees.
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       credentials: "include",
       signal: controller.signal,
@@ -65,20 +65,20 @@ export async function apiFetchBinary(
   init: RequestInit = {},
   timeoutMs = 15_000,
 ): Promise<ApiResult<Uint8Array>> {
-  if (!API_BASE) {
+  if (!apiBaseUrl()) {
     return {
       ok: false,
       status: 0,
       reason: "config",
       error: "This is not set up yet.",
-      detail: "API_BASE is not set - capture the app's XHR first.",
+      detail: "API_BASE is not set, or names a {subdomain} this page does not have.",
     };
   }
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const res = await fetch(`${API_BASE}${path}`, {
+    const res = await fetch(`${apiBaseUrl()}${path}`, {
       ...init,
       credentials: "include",
       signal: controller.signal,
@@ -98,6 +98,7 @@ export async function apiFetchBinary(
 // the harness's returns a config failure here, because this file sets no
 // `authSource`. For the same reason getAuthToken returns null (see the README).
 export {
+  apiBaseUrl,
   getAgent,
   armAllInstances,
   rankBy,

package/src/chrome-binary.mjs

@@ -26,3 +26,36 @@ export function chromeCandidates(platform = os.platform(), env = process.env) {
 export function findChrome({ env = process.env, platform = os.platform(), exists = fs.existsSync } = {}) {
   return env.CHROME_PATH || chromeCandidates(platform, env).find((candidate) => exists(candidate)) || null;
 }
+
+// Chrome slows a page whose window is hidden, covered or minimized - timers
+// throttled, the renderer moved to the background - and the build in it stalls.
+// These keep the test window working while the builder looks at another app
+// or another macOS user's session (⚠️ not tried live with a user switch).
+// The hidden Chrome that makes the video uses them too.
+export const KEEP_RUNNING_ARGS = Object.freeze([
+  "--disable-background-timer-throttling",
+  "--disable-renderer-backgrounding",
+  "--disable-backgrounding-occluded-windows",
+]);
+
+/** How `inject` starts the test window. */
+export function testWindowArgs({ profileDir, debugPort, themeDir, startUrl }) {
+  return [
+    `--user-data-dir=${profileDir}`,
+    `--remote-debugging-port=${debugPort}`,
+    // The theme only paints the isolated window Foldspace blue. SDK and action
+    // code are loaded later by attach over CDP.
+    `--load-extension=${themeDir}`,
+    `--disable-extensions-except=${themeDir}`,
+    // Chrome 136+ dropped --load-extension. Keep the legacy switch for older
+    // builds, and enable the CDP Extensions domain so we can load it at runtime.
+    "--disable-features=DisableLoadExtensionCommandLineSwitch",
+    "--enable-unsafe-extension-debugging",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--test-type",
+    "--remote-allow-origins=*",
+    ...KEEP_RUNNING_ARGS,
+    startUrl,
+  ];
+}

package/src/cli-registry.mjs

@@ -76,7 +76,7 @@ export const CLI_COMMANDS = Object.freeze([
     name: "upgrade",
     entry: null,
     group: "start",
-    summary: "Check for a newer harness and, after asking, update the version this project uses",
+    summary: "Check for a newer harness and update the version this project uses",
     usage:
       "foldspace upgrade [--check | --yes] [--refresh-instructions]",
     risk: "local-write",
@@ -91,7 +91,7 @@ export const CLI_COMMANDS = Object.freeze([
       flag("--check", "Compare versions and print JSON; never install"),
       flag(
         "--yes",
-        "Install the latest version after the human has agreed",
+        "Install the latest version: within the same line (update.autoUpgrade) without asking; across a line, after the human has agreed",
       ),
       flag(
         "--refresh-instructions",
@@ -111,11 +111,56 @@ export const CLI_COMMANDS = Object.freeze([
       "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",
+      "If update.autoUpgrade (a newer version in the same line, such as 0.1.x): run npx foldspace upgrade --yes without asking, and tell the human in one plain line",
+      "If outdated across a line (0.1 to 0.2): ask the human, then run npx foldspace upgrade --yes",
       "Run npm run build after an upgrade",
       "If attach is running: `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with, to load the rebuild",
     ],
   }),
+  Object.freeze({
+    name: "sync",
+    entry: "sync.mjs",
+    group: "start",
+    summary: "Keep agent/ up to date with the agent's saved code: what to pull, then merge it in",
+    usage:
+      "foldspace sync <check|apply|saved> [--develop <sha>] [--line <sha>] [--head <sha>] [--paths <a,b>]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR"],
+    capabilities: ["project.sync"],
+    positionals: [
+      Object.freeze({
+        name: "verb",
+        required: true,
+        description:
+          "check: compare the heads you just read with what this folder last pulled, and say what to pull | apply: merge what you pulled into agent/ | saved: remember a save this folder made",
+      }),
+    ],
+    options: [
+      value("--develop", "sha", "check: develop_head from repo_read status"),
+      value("--line", "sha", "check: the head of foldspace/<Agent Key>, the line of work saves go to (the sha repo_read tree prints for that ref); leave it out while that line does not exist"),
+      value("--head", "sha", "saved: the commit_sha the save returned"),
+      value("--paths", "a,b", "saved: the committed_paths the save returned, comma-separated"),
+    ],
+    prerequisites: [
+      "foldspace.dev.json",
+      "A code project (repo_read status), read with the Foldspace tools: this command never reaches Foldspace itself",
+    ],
+    effects: [
+      "Writes only under .foldspace-dev/ (saved-code/ and agent-kept/) and, for apply, agent/",
+      "Changes nothing about saving or publishing: those follow repo_read command instructions",
+      "check names each ref to pull and the folder to write it into (pull[].into); it pulls nothing itself",
+      "apply copies agent/ to .foldspace-dev/agent-kept/<time>/ first, then merges file by file against what this folder last pulled: a file only one side changed takes that side; one both changed takes the saved version and is listed in conflicts",
+      "On a first pull (nothing remembered), the saved code wins every difference, and of the files it lacks only agent/actions/, agent/api/ and agent/views/ go back",
+      "agent/runtime/ is the build's: differences there are never conflicts",
+    ],
+    next: [
+      "check with pull: read agent/ at each ref into its into folder (repo_read tree and file), then npx foldspace sync apply",
+      "check up to date: save as repo_read command instructions says, with base_sha = baseSha",
+      "apply: follow its next - conflicts mean putting this session's change back on top; then npm run build",
+      "After each save: npx foldspace sync saved with the commit_sha and committed_paths it returned",
+    ],
+  }),
   Object.freeze({
     name: "build",
     entry: "build-cli.mjs",
@@ -577,6 +622,7 @@ export const CLI_COMMANDS = Object.freeze([
 export const CAPABILITY_CATALOGUE = Object.freeze([
   ["project.scaffold", "Create a new configured project on local disk"],
   ["project.upgrade", "Update the harness version the consuming project uses"],
+  ["project.sync", "Merge the agent's saved code, read with the Foldspace tools, into agent/"],
   ["artifact.build", "Build the portable dist/index.js action artifact"],
   ["browser.launch", "Launch an isolated local Chrome profile"],
   ["browser.cdp", "Connect to local Chrome through CDP"],
@@ -656,9 +702,10 @@ export function createCliRegistry({ packageName, packageVersion, env = process.e
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents run attach --daemon; foreground attach is for someone watching the terminal.",
-      "If update.outdated is true, ask the human before npx foldspace upgrade --yes.",
-      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Ask the human to agree to the upgrade; set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
+      "If update.autoUpgrade is true (a newer version in the same line), run npx foldspace upgrade --yes without asking and tell the human in one plain line; if update.outdated is true across a line, ask the human first.",
+      "If update.broken is true, this version was withdrawn and build and attach refuse to run. Within the same line, upgrade without asking; across a line, ask the human to agree to the upgrade, and set FOLDSPACE_SKIP_UPDATE_CHECK=1 only if they decline.",
       "observe looks at the app, and ask tests the agent through its panel; both work while attach runs.",
+      "With a code project, pull the saved code with `npx foldspace sync` at session start, before each new experience and before each save or publish (manual: \"Several builders, one agent\"); saving and publishing follow repo_read command instructions.",
       "`foldspace deploy` is for Foldspace staff only: never run or offer it - it is not the `deploy` tool. With a code project, putting the agent's code in front of their users is yours, as the manual's \"Done, and what you say at the end\" says: save with `repo_write`; publish to dev with the `deploy` tool (say you are doing it, then do it - unless its dev preview comes back with no warnings, which means this agent loads dev for its users: then ask first, as for production); check dev with `npx foldspace attach --stop`, `npx foldspace published dev` and `npx foldspace ask \"<question>\" --retry 2`; and publish to production only once that check passed and the human says yes. The dev check and production need a site that loads the agent by itself: after `attach --bootstrap` or `--replace`, publish to dev only, keep attach running, and the rest is a step the Foldspace team does with the human. If `published` says this window cannot show dev, say so in one sentence, attach again, and stop after dev. Without a code project, or when a Foldspace tool refuses (except a save refused because someone saved after you read: redo it as `repo_read` command `instructions` says), the Foldspace team does it with the human (https://foldspace.ai/demo, support@foldspace.ai).",
     ],
   };

package/src/customer-subdomain.mjs

@@ -0,0 +1,149 @@
+// A product that gives each customer their own subdomain - acme.example.com,
+// globex.example.com - must never ship one customer's address: the agent is
+// built signed in to one customer, and every user of every customer would get
+// the code. This module is the one place that decides what "looks like one
+// customer's subdomain" means, for `observe` (which asks the builder) and for
+// lint (which refuses the fixed address). Pure: no network, no filesystem.
+
+import { siteOf } from "./observe-core.mjs";
+
+export const SUBDOMAIN_PLACEHOLDER = "{subdomain}";
+
+// First parts of an address that name a part of the product, a region or an
+// environment - not a customer. Wrong in either direction costs little: a
+// miss here only means the builder is asked one question too many.
+const GENERIC_LABELS = new Set([
+  "app", "apps", "api", "apis", "www", "web", "my", "portal", "dashboard", "admin", "console",
+  "secure", "login", "auth", "accounts", "account", "id", "sso", "oauth", "cloud", "platform",
+  "go", "dev", "develop", "staging", "stage", "test", "qa", "uat", "sandbox", "demo", "beta",
+  "preview", "prod", "production", "live", "global", "m", "mobile", "mail", "help", "support",
+  "docs", "status", "cdn", "static", "assets", "media", "files", "home", "client", "clients",
+  "members", "manage", "manager", "internal", "backoffice", "ops", "studio", "hub", "workspace",
+  "office", "online", "service", "services", "gateway", "data", "reports", "reporting",
+  "analytics", "insights", "billing", "pay", "payments", "shop", "store", "events", "connect",
+]);
+
+// app2, app-eu1, api-staging, eu, us-east-1, na3 ...
+const GENERIC_PATTERN =
+  /^(?:app|api|web|www|eu|us|na|ap|uk|au|ca|de|fr|jp|in|sg|emea|apac|latam)(?:[-_]?[a-z]*\d+|(?:[-_][a-z]+)+(?:[-_]?\d+)?)?$/;
+
+export function isGenericLabel(label) {
+  const value = String(label || "").toLowerCase();
+  return GENERIC_LABELS.has(value) || GENERIC_PATTERN.test(value);
+}
+
+function hostOf(value) {
+  const text = String(value || "").trim().toLowerCase();
+  if (!text) return "";
+  try {
+    return new URL(/^[a-z][a-z0-9+.-]*:\/\//.test(text) ? text : `https://${text}`).hostname.replace(/\.$/, "");
+  } catch {
+    return "";
+  }
+}
+
+/** The first part of a host in front of the product's own domain (`acme` in acme.example.com), or null. A leading `www.` is skipped. */
+export function leftmostLabel(hostOrUrl) {
+  const host = hostOf(hostOrUrl);
+  if (!host || /^[\d.]+$/.test(host) || host === "localhost" || host.endsWith(".localhost")) return null;
+  const labels = host.split(".");
+  if (labels[0] === "www") labels.shift();
+  const siteLabels = siteOf(labels.join(".")).split(".").length;
+  return labels.length > siteLabels ? labels[0] : null;
+}
+
+/**
+ * The customer label to watch for in addresses, given the app's own host and
+ * what the project says (`PER_CUSTOMER_SUBDOMAIN`): `false` - none; `true` -
+ * the first part of the host, whatever it is; undecided - the first part only
+ * when it does not read as a part of the product, a region or an environment.
+ */
+export function customerLabel(appHost, decided) {
+  if (decided === false) return null;
+  const label = leftmostLabel(appHost);
+  if (!label) return null;
+  if (decided === true) return label;
+  return isGenericLabel(label) ? null : label;
+}
+
+/** Whether an address names that customer: a part of its host, or a segment of its path. `{subdomain}` never counts. */
+export function addressNamesLabel(url, label) {
+  if (!label) return false;
+  const want = label.toLowerCase();
+  let parsed;
+  try {
+    parsed = new URL(String(url).replace(/\{subdomain\}/g, "x-subdomain-x"));
+  } catch {
+    return false;
+  }
+  const parts = (text) => text.toLowerCase().split(/[./]/).filter(Boolean);
+  const named = (part) => part === want || part.split(/[-_]/).includes(want);
+  return parts(parsed.hostname).some(named) || parts(decodeURIComponent(parsed.pathname)).some(named);
+}
+
+/**
+ * What API_BASE should say instead of a fixed address that names one
+ * customer: the path alone when the backend is on the app's own host,
+ * otherwise the address with `{subdomain}` where the customer was.
+ */
+export function suggestedApiBase(url, appHost, label) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return `/api`;
+  }
+  const path = parsed.pathname.replace(/\/$/, "");
+  if (parsed.hostname.toLowerCase() === hostOf(appHost)) return path || "/";
+  const swap = (part) =>
+    part.toLowerCase() === label.toLowerCase()
+      ? SUBDOMAIN_PLACEHOLDER
+      : part
+          .split("-")
+          .map((piece) => (piece.toLowerCase() === label.toLowerCase() ? SUBDOMAIN_PLACEHOLDER : piece))
+          .join("-");
+  const host = parsed.hostname.split(".").map(swap).join(".");
+  const swappedPath = path.split("/").map(swap).join("/");
+  return `${parsed.protocol}//${host}${parsed.port ? `:${parsed.port}` : ""}${swappedPath}`;
+}
+
+/** `PER_CUSTOMER_SUBDOMAIN` as written in agent/constants.ts: true, false, or undefined while undecided. */
+export function readCustomerSubdomainSetting(constantsText) {
+  const match = /export\s+const\s+PER_CUSTOMER_SUBDOMAIN\b[^=]*=\s*(true|false)\b/.exec(String(constantsText || ""));
+  return match ? match[1] === "true" : undefined;
+}
+
+/**
+ * For `observe`: when the page's address looks like one customer's own
+ * subdomain and the project has not settled it, say so and what to ask.
+ * `requestUrls` are the calls the page made; one that names the same
+ * customer is the strongest sign, and is reported.
+ */
+export function customerSubdomainHint(pageUrl, requestUrls = [], decided) {
+  if (decided !== undefined) return null;
+  const pageHost = hostOf(pageUrl);
+  const label = customerLabel(pageHost, undefined);
+  if (!label) return null;
+  const seenIn = [];
+  for (const url of requestUrls) {
+    let host;
+    try {
+      host = new URL(url).hostname.toLowerCase();
+    } catch {
+      continue;
+    }
+    if (addressNamesLabel(url, label) && !seenIn.includes(host)) seenIn.push(host);
+    if (seenIn.length >= 4) break;
+  }
+  const site = siteOf(pageHost.replace(/^www\./, ""));
+  return {
+    label,
+    pageHost,
+    ...(seenIn.length ? { backendHosts: seenIn } : {}),
+    hint:
+      `The address starts with "${label}." - that may be one customer's own subdomain, with other customers on other.${site}. ` +
+      `Ask the human once, as a choice: does each of their customers get their own address like ${pageHost}? ` +
+      `Yes: set PER_CUSTOMER_SUBDOMAIN = true in agent/constants.ts and write API_BASE from the page's address ("/api", or "https://{subdomain}.…") - never the address you observed. ` +
+      `No: set PER_CUSTOMER_SUBDOMAIN = false.`,
+  };
+}