@foldspace_npm/harness 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @foldspace_npm/harness
+
+Build, inject and verify Foldspace agent experiences against a live app.
+
+**This package is the part that is the same in both architectures.** Everything
+else about how a builder runs differs between them; this does not.
+
+---
+
+## The two architectures
+
+| | **A — local** *(today)* | **B — remote** *(designed, unbuilt)* |
+|---|---|---|
+| Who runs the agent | Claude Code on the builder's desktop | Claude Agent SDK in GCP |
+| Whose browser | an isolated Chrome the harness launches | the user's **own** Chrome |
+| How code reaches the page | CDP injection | Web Store extension injects a `<script src>` from the CDN |
+| Prerequisites | Claude Code, a client repo, Node, an isolated Chrome profile | the extension installed |
+| Session and cookies | in a profile the harness creates | the user's own, untouched |
+| Code and history | a git repo on the builder's machine | a workspace in the hosted environment |
+
+"Export to repo" moves a build from B to A — **and it is only a copy, not a
+rewrite, while `agent/` is identical in both.** Keeping it identical is the
+constraint this package exists to protect.
+
+### What is genuinely shared
+
+- `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
+  nothing more. The actions built for Figma run unmodified in either track.
+- `foldspace-build` — esbuild → `dist/index.js`
+- `foldspace-deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`
+- fixtures and tests
+- **the verb interface** below
+
+### What differs — only the transport
+
+| Verb | A (CDP) | B (extension) |
+|---|---|---|
+| `loadBundle` | `addScriptToEvaluateOnNewDocument` | `<script src>` at the deployed CDN path |
+| `evaluate` | `Runtime.evaluate` | content-script message |
+| `screenshot` | `Page.captureScreenshot` | `tabs.captureVisibleTab` |
+| `relaxCSP` | `Page.setBypassCSP` | `declarativeNetRequest` header rules |
+| `navigate` | `Page.navigate` | `tabs.update` |
+
+Detail and status: [`src/transports/README.md`](src/transports/README.md).
+
+### Why one package rather than two
+
+Splitting `harness-local` and `harness-remote` forks `build` and `deploy` — the
+exact failure this package was created to end. And the verb interface only stays
+honest while both implementations sit behind it; separate them and "the same
+action runs in both modes" quietly stops being true.
+
+A hosted container installs this and never calls `inject`. That is kilobytes of
+dead weight, against a contract that cannot drift.
+
+---
+
+## Use
+
+### Create a project
+
+Create a configured actions project from the template bundled with the installed
+harness version:
+
+```bash
+npm exec --package=@foldspace_npm/harness -- foldspace init my-agent \
+  --product-id FR8JUQZAQRZB \
+  --agent-api-name my-agent \
+  --domain app.example.com \
+  --name "My Agent"
+```
+
+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 \
+  --domain app.example.com
+```
+
+Until `@foldspace_npm/harness` is published, install the local checkout in the
+generated project instead of running the standard install step:
+
+```bash
+cd ../my-agent
+npm install --ignore-scripts --save-dev /absolute/path/to/harness
+```
+
+`--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
+HTTP(S) URL without a port or path.
+
+For safety, `init` requires a target path that does not exist. It does not
+install dependencies, initialize Git, or overwrite files. After creation:
+
+```bash
+cd my-agent
+npm install --ignore-scripts
+npm run build
+npm run inject
+npm run attach
+```
+
+The generated npm scripts intentionally remain the normal project interface;
+`foldspace init` is the one-time project creation command.
+
+### Add the harness to an existing project
+
+```bash
+npm i -D @foldspace_npm/harness
+```
+
+```json
+{ "scripts": {
+    "dev":    "foldspace-build --watch",
+    "build":  "foldspace-build",
+    "inject": "foldspace-inject",
+    "attach": "foldspace-attach",
+    "deploy": "foldspace-deploy"
+} }
+```
+
+| Command | A | B |
+|---|:--:|:--:|
+| `foldspace init` | ✅ | ✅ |
+| `foldspace-build` | ✅ | ✅ |
+| `foldspace-deploy` | ✅ | ✅ — it *is* the delivery mechanism |
+| `foldspace-inject` | ✅ | — no browser to launch |
+| `foldspace-attach` | ✅ | replaced by the extension bridge |
+
+Every command resolves the **consuming** repo — `process.cwd()`, or
+`FOLDSPACE_PROJECT_DIR` so a hosted builder can point it at a workspace it
+controls. Config comes from the consumer's `foldspace.dev.json`.
+
+---
+
+## Why this package exists at all
+
+`scripts/` used to be copied into every client repo, and copies fork. By
+2026-08-25 `client-template` held one fix and a client repo held four others,
+and **neither had all five**:
+
+| Fix | Why it matters |
+|---|---|
+| SDK load guard + retry | On an app with no `document.body` at document-start the append throws; the old guard tested for the stub, so nothing retried and the agent silently never loaded |
+| Worker release on auto-attach | Auto-attach pauses every worker until the attaching client releases it — the harness froze the app's own workers for the whole session |
+| `agentIds` enumeration | `agent({apiName})` returns the OVERLAY handle; arming it on an embedded copilot leaves real conversations untagged |
+| `--no-test-mode` | Test mode was armed unconditionally, hiding exactly what initial setup needs to see |
+| Honest badge | It asserted `TEST MODE` whether or not test mode was on |
+
+Two further changes came from packaging it: the bundle is **injected** rather
+than fetched from a dev server — which removed `express` and `concurrently`, 95
+packages, and is the precondition for driving a browser that cannot reach the
+build machine — and `inject` now records the port that `attach` reads, since
+they previously disagreed by construction.

package/bin/attach.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+/**
+ * Attach to the Chrome launched by inject.mjs and serve local actions to it.
+ *
+ * Two modes, picked automatically:
+ *
+ *  swap (default)  The client app already embeds Foldspace. We
+ *                  intercept the remote-actions bundle request and fulfill it
+ *                  with dist/index.js from disk. This is the CDP equivalent of
+ *                  the production extension's redirect rule, and it reuses the
+ *                  page's own agent instead of creating a second one.
+ *
+ *  --bootstrap     The app has no Foldspace. Inject the SDK bootstrap from the
+ *                  generated extension/index.js before page scripts run.
+ *
+ * Chrome 136+ removed --load-extension and does not run content scripts for
+ * CDP-loaded extensions, so neither path uses the extension at runtime.
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
+// hosted builder point the harness at a workspace it controls.
+const root = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const extDir = path.join(root, ".foldspace-dev", "extension");
+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.
+function portFromState() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, ".foldspace-dev", "state.json"), "utf8")).debugPort;
+  } catch {
+    return null;
+  }
+}
+const portArgIndex = process.argv.indexOf("--port");
+const port = String(
+  (portArgIndex > -1 && process.argv[portArgIndex + 1]) ||
+    process.env.CDP_PORT ||
+    portFromState() ||
+    "9222",
+);
+const bootstrap = process.argv.includes("--bootstrap");
+// Test mode keeps conversations out of the customer's default list. Turn it off
+// only when you WANT the conversations and action calls to show up in the
+// Foldspace dashboard — a brand-new agent during initial setup, where there is
+// no production traffic to pollute.
+const noTestMode = process.argv.includes("--no-test-mode");
+// The badge used to hardcode "TEST MODE" whether or not test mode was on — a
+// string that asserts you are safe while you are not. It now states what is
+// actually true. --no-badge drops it entirely, for recording a demo.
+const noBadge = process.argv.includes("--no-badge");
+const badgeText = noTestMode
+  ? "FOLDSPACE DEV \u00b7 local actions \u00b7 LIVE"
+  : "FOLDSPACE DEV \u00b7 local actions \u00b7 TEST MODE";
+
+// Agent api name for setTestMode — from the same config inject.mjs used.
+const cfg = JSON.parse(fs.readFileSync(path.join(root, "foldspace.dev.json"), "utf8"));
+const cfgTarget = cfg.targets[cfg.defaultTarget] || {};
+const agentApiName =
+  process.env.AGENT_API_NAME ||
+  (process.argv.includes("--agent")
+    ? process.argv[process.argv.indexOf("--agent") + 1]
+    : cfgTarget.agentApiName);
+
+// Refuse to run against an uninitialised template. Without this, attach injects
+// the literal placeholder as an agent api name and the page fails with an opaque
+// "Failed to fetch agent config: status 400" — after having already broken the
+// app's own agent.
+const PLACEHOLDERS = ["AGENT_API_NAME", "PRODUCT_ID", "__APP_DOMAIN__", "__APP_ORIGIN__"];
+const unresolved = PLACEHOLDERS.filter((ph) =>
+  agentApiName === ph || JSON.stringify(cfgTarget).includes(ph)
+);
+if (unresolved.length) {
+  console.error(
+    `attach: foldspace.dev.json still contains placeholders: ${unresolved.join(", ")}\n` +
+    `        Run "node scripts/init.mjs" first, or pass --agent <apiName>.\n` +
+    `        Refusing to run — injecting a placeholder breaks the app's agent.`
+  );
+  process.exit(1);
+}
+
+const manifest = JSON.parse(fs.readFileSync(path.join(extDir, "manifest.json"), "utf8"));
+const hostPatterns = manifest.content_scripts[0].matches.map((m) =>
+  m.replace("*://", "").replace("/*", "")
+);
+const hostMatches = (url) => {
+  let h;
+  try { h = new URL(url).hostname; } catch { return false; }
+  return hostPatterns.some((p) =>
+    p.startsWith("*.") ? h === p.slice(2) || h.endsWith(p.slice(1)) : h === p
+  );
+};
+
+// Any remote-actions bundle, dev or prod, for any product/agent.
+const ACTIONS_PATTERN = "*/agent/actions/*";
+
+const badgeSrc = `(() => {
+  if (window.top !== window.self) return;
+  const add = () => {
+    if (document.getElementById("foldspace-dev-badge") || !document.body) return;
+    const b = document.createElement("div");
+    b.id = "foldspace-dev-badge";
+    b.textContent = ${JSON.stringify(badgeText)};
+    b.style.cssText = "position:fixed;top:0;left:0;z-index:2147483647;background:#3247F2;color:#fff;font:700 10px/1 ui-monospace,Menlo,monospace;letter-spacing:.12em;padding:5px 10px;border-bottom-right-radius:4px;pointer-events:none;box-shadow:0 1px 6px rgba(0,0,0,.35)";
+    document.body.appendChild(b);
+  };
+  add();
+  document.addEventListener("DOMContentLoaded", add);
+  setInterval(add, 2000);
+})();`;
+
+// Flag every local session as test traffic so it is excluded from analytics and
+// hidden from the default conversation list.
+// https://docs.foldspace.ai/reference/test-mode.md
+//
+// A handle is scoped by mode: window.foldspace.agent({apiName}) alone returns
+// the OVERLAY instance. On an app that embeds the copilot that is NOT the
+// instance serving the chat, so arming it succeeds, logs success, and leaves
+// the real conversations untagged — the failure that actually leaks. Enumerate
+// foldspace.agentIds() — each id is shaped "<mode>-<apiName>" — and arm every
+// one. See the playbook's test-mode rule.
+const testModeSrc = `(() => {
+  if (window.top !== window.self) return;
+  const AGENT = ${JSON.stringify(agentApiName)};
+  // Log once per instance; setTestMode itself is re-applied on every pass so an
+  // instance that is torn down and rebuilt gets re-armed.
+  const logged = new Set();
+
+  const armAll = () => {
+    const fs = window.foldspace;
+    if (!fs) return;
+
+    let ids = null;
+    try {
+      if (typeof fs.agentIds === "function") ids = fs.agentIds();
+    } catch (e) {}
+
+    // Older SDK with no agentIds(): the unscoped handle is all there is.
+    if (!ids) {
+      try {
+        fs.agent({ apiName: AGENT }).setTestMode(true);
+        if (!logged.has(AGENT)) {
+          logged.add(AGENT);
+          console.log("[foldspace-dev] test mode ON (" + AGENT + " — SDK has no agentIds(), overlay handle only)");
+        }
+      } catch (e) {
+        console.warn("[foldspace-dev] setTestMode failed:", e && e.message);
+      }
+      return;
+    }
+
+    for (const id of ids) {
+      const cut = id.indexOf("-");
+      if (cut < 1) continue;
+      try {
+        fs.agent({ apiName: id.slice(cut + 1), mode: id.slice(0, cut).toUpperCase() })
+          .setTestMode(true);
+        if (!logged.has(id)) {
+          logged.add(id);
+          console.log("[foldspace-dev] test mode ON (" + id + ")");
+        }
+      } catch (e) {
+        console.warn("[foldspace-dev] setTestMode failed for " + id + ":", e && e.message);
+      }
+    }
+  };
+
+  const arm = () => {
+    try { window.foldspace("when", "ready", armAll); } catch (e) {}
+    armAll();
+
+    // The instance serving the chat is built when the copilot panel opens, long
+    // after "ready" — arming once is too early. Keep arming.
+    setInterval(armAll, 1000);
+
+    let queued = false;
+    const armSoon = () => {
+      if (queued) return;
+      queued = true;
+      setTimeout(() => { queued = false; armAll(); }, 200);
+    };
+    try {
+      const obs = new MutationObserver(armSoon);
+      const observe = () => {
+        if (document.body) obs.observe(document.body, { childList: true, subtree: true });
+      };
+      if (document.body) observe();
+      else document.addEventListener("DOMContentLoaded", observe);
+    } catch (e) {}
+  };
+
+  if (window.foldspace) return arm();
+  // The app bootstraps its own SDK — wait for it rather than racing it.
+  let n = 0;
+  const t = setInterval(() => {
+    if (window.foldspace) { clearInterval(t); arm(); }
+    else if (++n > 200) clearInterval(t);
+  }, 50);
+})();`;
+
+let nextId = 1;
+const pending = new Map();
+const prepared = 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.
+const sessions = new Map();
+let served = 0;
+
+const call = (ws, method, params = {}, sessionId) =>
+  new Promise((resolve) => {
+    const id = nextId++;
+    pending.set(id, resolve);
+    ws.send(JSON.stringify({ id, method, params, sessionId }));
+  });
+
+async function prepare(ws, sessionId, url) {
+  if (prepared.has(sessionId)) return;
+  prepared.add(sessionId);
+
+  await call(ws, "Page.enable", {}, sessionId);
+  await call(ws, "Runtime.enable", {}, sessionId);
+  await call(ws, "Page.setBypassCSP", { enabled: true }, sessionId);
+
+  // Workers spawned by this page attach through THIS session, not the browser
+  // one, so the browser-level setAutoAttach does not cover them and they start
+  // paused. Say so here too, or the app's workers freeze for the session.
+  await call(ws, "Target.setAutoAttach", {
+    autoAttach: true, waitForDebuggerOnStart: false, flatten: true,
+  }, sessionId);
+
+  await call(ws, "Fetch.enable", {
+    patterns: [{ urlPattern: ACTIONS_PATTERN, requestStage: "Request" }],
+  }, sessionId);
+
+  // The action bundle, injected rather than fetched. This is what lets the
+  // harness drop the dev server — and what makes a non-local browser possible,
+  // since a remote Chrome can never reach localhost.
+  const scripts = [];
+  if (fs.existsSync(bundlePath)) {
+    scripts.push(fs.readFileSync(bundlePath, "utf8"));
+  } else {
+    console.log(`  !! ${path.relative(root, bundlePath)} missing — run "npm run dev"`);
+  }
+  if (!noBadge) scripts.push(badgeSrc);
+  if (!noTestMode) scripts.push(testModeSrc);
+  if (bootstrap) scripts.push(fs.readFileSync(path.join(extDir, "index.js"), "utf8"));
+  for (const source of scripts) {
+    await call(ws, "Page.addScriptToEvaluateOnNewDocument", { source, runImmediately: true }, sessionId);
+  }
+
+  console.log(`  attached -> ${url}`);
+  await call(ws, "Page.reload", { ignoreCache: true }, sessionId);
+}
+
+async function onEvent(ws, msg) {
+  const { method, params, sessionId } = msg;
+
+  if (method === "Target.attachedToTarget") {
+    const t = params.targetInfo;
+    if (t.type === "page") {
+      sessions.set(t.targetId, params.sessionId);
+      if (hostMatches(t.url)) await prepare(ws, params.sessionId, t.url);
+    } else {
+      // Auto-attach pauses workers on start until the attaching client says go.
+      // We do not instrument workers — but if we never release them they stay
+      // frozen for the whole session. On an app that does real work in workers
+      // that is a broken app, and Chrome tells the user "Debugger paused in
+      // another tab". Only this session can release them; a second CDP client
+      // sending runIfWaitingForDebugger has no effect.
+      await call(ws, "Runtime.runIfWaitingForDebugger", {}, params.sessionId);
+    }
+    return;
+  }
+
+  // A target we already know about navigated. If it just entered a matching
+  // host, arm it now.
+  if (method === "Target.targetInfoChanged") {
+    const t = params.targetInfo;
+    if (t.type === "page" && hostMatches(t.url)) {
+      const sid = sessions.get(t.targetId);
+      if (sid) await prepare(ws, sid, t.url);
+    }
+    return;
+  }
+
+  if (method === "Fetch.requestPaused") {
+    const { requestId, request } = params;
+    if (!fs.existsSync(bundlePath)) {
+      console.log(`  !! dist/index.js missing — run "npm run dev"`);
+      await call(ws, "Fetch.continueRequest", { requestId }, sessionId);
+      return;
+    }
+    const body = fs.readFileSync(bundlePath);
+    served++;
+    console.log(`  served local actions (${(body.length / 1024).toFixed(0)}kb) for ${request.url.slice(0, 78)}`);
+    await call(ws, "Fetch.fulfillRequest", {
+      requestId,
+      responseCode: 200,
+      responseHeaders: [
+        { name: "content-type", value: "application/javascript; charset=utf-8" },
+        { name: "access-control-allow-origin", value: "*" },
+        { name: "cache-control", value: "no-store" },
+      ],
+      body: body.toString("base64"),
+    }, sessionId);
+    return;
+  }
+
+  if (method === "Runtime.consoleAPICalled") {
+    const text = (params.args || [])
+      .map((a) => (a.value !== undefined ? a.value : a.description || ""))
+      .join(" ");
+    if (/foldspace-dev|remote actions|identified|Error/i.test(text) && !/IO (entry|callback)/.test(text)) {
+      console.log(`  [page] ${text.slice(0, 160)}`);
+    }
+  }
+}
+
+let ws;
+
+// Declared before connect() wires ws.onclose: a socket that closes during
+// startup would otherwise reach onDisconnect() while keepAlive is still in the
+// 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();
+  ws = new WebSocket(ver.webSocketDebuggerUrl);
+  await new Promise((resolve, reject) => {
+    ws.onopen = resolve;
+    ws.onerror = reject;
+  });
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pending.has(m.id)) { pending.get(m.id)(m.result); pending.delete(m.id); }
+    else if (m.method) onEvent(ws, m);
+  };
+  ws.onclose = () => { void onDisconnect(); };
+  await call(ws, "Target.setDiscoverTargets", { discover: true });
+  await call(ws, "Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+  return ver;
+}
+
+const ver = await connect();
+
+console.log(`Attached to ${ver.Browser} on :${port}`);
+console.log(`Mode:  ${bootstrap ? "bootstrap (inject SDK)" : "swap (reuse the app's agent)"}`);
+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`);
+
+process.on("SIGINT", () => {
+  console.log(`\nDetached. Served the local bundle ${served} time(s).`);
+  process.exit(0);
+});
+
+// A closed socket does not mean the browser closed. Chrome drops the CDP
+// connection on target churn and transient errors too, and exiting on those
+// silently ends the swap while the user keeps browsing — the page then loads
+// the deployed bundle with no signal that anything changed. Reconnect, and
+// only give up once the debugging port is genuinely gone.
+async function browserIsUp() {
+  try {
+    const r = await fetch(`http://localhost:${port}/json/version`);
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+async function onDisconnect() {
+  prepared.clear();
+  sessions.clear();
+  for (let attempt = 1; attempt <= 10; attempt++) {
+    await new Promise((r) => setTimeout(r, Math.min(500 * attempt, 3000)));
+    if (!(await browserIsUp())) {
+      clearInterval(keepAlive);
+      console.log("\nBrowser closed. Detaching.");
+      process.exit(0);
+    }
+    try {
+      console.log(`  connection lost — reconnecting (${attempt}/10)…`);
+      await connect();
+      console.log("  reconnected. Swap is live again.");
+      return;
+    } catch {
+      // fall through and retry
+    }
+  }
+  clearInterval(keepAlive);
+  console.error("\nCould not reconnect after 10 attempts. Detaching — "
+    + "the page is now loading the DEPLOYED bundle, not your local build.");
+  process.exit(1);
+}

package/bin/build-cli.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Thin launcher so the TypeScript build script runs without the consumer
+// needing tsx wired up themselves.
+import { spawn } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const child = spawn(
+  process.execPath,
+  [path.join(here, "..", "node_modules", "tsx", "dist", "cli.mjs"), path.join(here, "build.ts"), ...process.argv.slice(2)],
+  { stdio: "inherit", env: { ...process.env, FOLDSPACE_PROJECT_DIR: process.env.FOLDSPACE_PROJECT_DIR || process.cwd() } },
+);
+child.on("exit", (code) => process.exit(code ?? 0));

package/bin/build.ts

@@ -0,0 +1,82 @@
+import * as esbuild from "esbuild";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectDir = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
+const distDir = path.join(projectDir, "dist");
+const agentActionsEntry = path.join(projectDir, "agent", "actions", "index.ts");
+
+const watchMode = process.argv.includes("--watch");
+
+function buildOptions(): esbuild.BuildOptions {
+  return {
+    entryPoints: [agentActionsEntry],
+    outfile: path.join(distDir, "index.js"),
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    target: "es2022",
+    minify: true,
+    sourcemap: false,
+  };
+}
+
+function rebuildPlugin(): esbuild.Plugin {
+  return {
+    name: "rebuild-notify",
+    setup(build) {
+      build.onEnd((result) => {
+        const time = new Date().toLocaleTimeString();
+        if (result.errors.length === 0) {
+          console.log(`[${time}] Rebuilt: dist/index.js`);
+        } else {
+          console.log(`[${time}] Error: dist/index.js`);
+        }
+      });
+    },
+  };
+}
+
+async function build() {
+  console.log(`Building agent actions...\n`);
+
+  if (!fs.existsSync(agentActionsEntry)) {
+    console.error(`Entry point not found: ${agentActionsEntry}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(distDir)) {
+    fs.mkdirSync(distDir, { recursive: true });
+  }
+
+  try {
+    if (watchMode) {
+      console.log("Watch mode — watching for changes...\n");
+
+      const context = await esbuild.context({
+        ...buildOptions(),
+        plugins: [rebuildPlugin()],
+      });
+
+      await context.watch();
+      console.log("Initial build complete! Watching for changes...\n");
+
+      process.on("SIGINT", async () => {
+        console.log("\nStopping watcher...");
+        await context.dispose();
+        process.exit(0);
+      });
+    } else {
+      await esbuild.build(buildOptions());
+      console.log("Built: dist/index.js");
+      console.log("\nBuild complete!");
+    }
+  } catch (error) {
+    console.error("Build failed:", error);
+    process.exit(1);
+  }
+}
+
+build();