sf-builder-agent 0.7.0

package/dist/sse-client.js

@@ -0,0 +1,59 @@
+/**
+ * SSE client — listens for browser-automation commands from the server.
+ */
+import { EventSource } from "eventsource";
+export function connectSSE(baseUrl, sessionId, token, onCommand, onError) {
+    const url = `${baseUrl}/api/sessions/${sessionId}/agent/commands?token=${encodeURIComponent(token)}`;
+    let es = null;
+    let closed = false;
+    let retryDelay = 1_000;
+    const MAX_RETRY = 30_000;
+    function connect() {
+        if (closed)
+            return;
+        es = new EventSource(url);
+        es.addEventListener("command", (evt) => {
+            try {
+                const data = JSON.parse(evt.data);
+                onCommand(data);
+                // Reset backoff on successful message
+                retryDelay = 1_000;
+            }
+            catch (err) {
+                console.error("\u274C Failed to parse command:", err instanceof Error ? err.message : err);
+            }
+        });
+        es.addEventListener("ping", () => {
+            // Keep-alive — nothing to do
+        });
+        es.addEventListener("open", () => {
+            console.log("\u2705 Connected to command stream");
+            retryDelay = 1_000;
+        });
+        es.onerror = (err) => {
+            if (closed)
+                return;
+            const message = err && typeof err === "object" && "message" in err
+                ? err.message
+                : "SSE connection error";
+            console.error(`\u274C SSE error: ${message}  — reconnecting in ${retryDelay / 1_000}s`);
+            onError(new Error(message));
+            // Close the broken connection and schedule reconnect
+            es?.close();
+            es = null;
+            setTimeout(() => {
+                retryDelay = Math.min(retryDelay * 2, MAX_RETRY);
+                connect();
+            }, retryDelay);
+        };
+    }
+    connect();
+    return {
+        close() {
+            closed = true;
+            es?.close();
+            es = null;
+        },
+    };
+}
+//# sourceMappingURL=sse-client.js.map

package/dist/sse-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-client.js","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAS1C,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,SAAiB,EACjB,KAAa,EACb,SAA6C,EAC7C,OAA+B;IAE/B,MAAM,GAAG,GAAG,GAAG,OAAO,iBAAiB,SAAS,yBAAyB,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IAErG,IAAI,EAAE,GAAuB,IAAI,CAAC;IAClC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,SAAS,GAAG,MAAM,CAAC;IAEzB,SAAS,OAAO;QACd,IAAI,MAAM;YAAE,OAAO;QAEnB,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;QAE1B,EAAE,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,GAAiB,EAAE,EAAE;YACnD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAoB,CAAC;gBACrD,SAAS,CAAC,IAAI,CAAC,CAAC;gBAChB,sCAAsC;gBACtC,UAAU,GAAG,KAAK,CAAC;YACrB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CACX,iCAAiC,EACjC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YAC/B,6BAA6B;QAC/B,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YAC/B,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;YAClD,UAAU,GAAG,KAAK,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;YAC1B,IAAI,MAAM;gBAAE,OAAO;YAEnB,MAAM,OAAO,GACX,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,SAAS,IAAI,GAAG;gBAChD,CAAC,CAAE,GAAsC,CAAC,OAAO;gBACjD,CAAC,CAAC,sBAAsB,CAAC;YAE7B,OAAO,CAAC,KAAK,CAAC,qBAAqB,OAAO,uBAAuB,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC;YACxF,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAE5B,qDAAqD;YACrD,EAAE,EAAE,KAAK,EAAE,CAAC;YACZ,EAAE,GAAG,IAAI,CAAC;YAEV,UAAU,CAAC,GAAG,EAAE;gBACd,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;gBACjD,OAAO,EAAE,CAAC;YACZ,CAAC,EAAE,UAAU,CAAC,CAAC;QACjB,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,CAAC;IAEV,OAAO;QACL,KAAK;YACH,MAAM,GAAG,IAAI,CAAC;YACd,EAAE,EAAE,KAAK,EAAE,CAAC;YACZ,EAAE,GAAG,IAAI,CAAC;QACZ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "sf-builder-agent",
+  "version": "0.7.0",
+  "description": "Desktop agent for SalesForce Agent Creator — executes browser automation commands",
+  "type": "module",
+  "bin": {
+    "sf-builder-agent": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "puppeteer": "^23.0.0",
+    "eventsource": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "tsx": "^4.19.0"
+  }
+}

package/src/browser.ts

@@ -0,0 +1,338 @@
+/**
+ * Browser — Puppeteer launcher and command executor.
+ *
+ * Handles all CommandType operations including shadow-DOM traversal,
+ * label-based element lookup, and screenshot capture.
+ */
+
+import puppeteer, { type Browser, type Page, type ElementHandle } from "puppeteer";
+
+// ─── Launch ──────────────────────────────────────────────────────────
+
+export async function launchBrowser(): Promise<{ browser: Browser; page: Page }> {
+  const browser = await puppeteer.launch({
+    headless: false,
+    defaultViewport: { width: 1440, height: 900 },
+    args: [
+      "--start-maximized",
+      "--disable-blink-features=AutomationControlled",
+    ],
+  });
+
+  const pages = await browser.pages();
+  const page = pages[0] ?? (await browser.newPage());
+
+  return { browser, page };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Walk through shadow roots and resolve the final selector.
+ */
+async function findElement(
+  page: Page,
+  selector: string,
+  shadowPath?: string[]
+): Promise<ElementHandle<Element>> {
+  if (shadowPath && shadowPath.length > 0) {
+    // Walk shadow DOM tree
+    let root = await page.evaluateHandle(() => document as unknown as Element);
+
+    for (const pathSelector of shadowPath) {
+      root = await page.evaluateHandle(
+        (el: Element, sel: string) => {
+          const host = el.querySelector(sel);
+          if (!host) throw new Error(`Shadow host not found: ${sel}`);
+          return (host.shadowRoot as unknown as Element) ?? host;
+        },
+        root,
+        pathSelector
+      );
+    }
+
+    const handle = await page.evaluateHandle(
+      (el: Element, sel: string) => {
+        const found = el.querySelector(sel);
+        if (!found) throw new Error(`Element not found in shadow DOM: ${sel}`);
+        return found;
+      },
+      root,
+      selector
+    );
+
+    return handle as ElementHandle<Element>;
+  }
+
+  const el = await page.$(selector);
+  if (!el) throw new Error(`Element not found: ${selector}`);
+  return el;
+}
+
+/**
+ * Try to locate an input/textarea/select by its associated <label> text.
+ */
+async function findByLabel(
+  page: Page,
+  label: string
+): Promise<ElementHandle<Element> | null> {
+  const handle = await page.evaluateHandle((labelText: string) => {
+    const labels = [...document.querySelectorAll("label")];
+    const match = labels.find((l) =>
+      l.textContent?.trim().includes(labelText)
+    );
+    if (!match) return null;
+
+    // If the label has a `for` attribute, use it
+    if (match.htmlFor) {
+      return document.getElementById(match.htmlFor);
+    }
+    // Otherwise look for an input nested inside the label
+    return match.querySelector("input, textarea, select");
+  }, label);
+
+  // evaluateHandle returns a JSHandle — check if the inner value is null
+  const element = handle.asElement();
+  if (!element) {
+    await handle.dispose();
+    return null;
+  }
+
+  return element as ElementHandle<Element>;
+}
+
+/**
+ * Find an element by its visible text content.
+ */
+async function findByText(
+  page: Page,
+  selector: string,
+  text: string
+): Promise<ElementHandle<Element>> {
+  const handle = await page.evaluateHandle(
+    (sel: string, txt: string) => {
+      const candidates = [...document.querySelectorAll(sel || "*")];
+      const match = candidates.find((el) =>
+        el.textContent?.trim().includes(txt)
+      );
+      if (!match) throw new Error(`No element with text "${txt}" found`);
+      return match;
+    },
+    selector,
+    text
+  );
+
+  return handle as ElementHandle<Element>;
+}
+
+// ─── Command Executor ────────────────────────────────────────────────
+
+export interface CommandResult {
+  success: boolean;
+  result?: unknown;
+  error?: string;
+  screenshot?: string;
+  shutdown?: boolean;
+}
+
+export async function executeCommand(
+  page: Page,
+  commandType: string,
+  payload: Record<string, unknown>
+): Promise<CommandResult> {
+  try {
+    switch (commandType) {
+      // ── navigate ──
+      case "navigate": {
+        const url = payload.url as string;
+        await page.goto(url, { waitUntil: "networkidle2", timeout: 30_000 });
+        return { success: true, result: { url } };
+      }
+
+      // ── click ──
+      case "click": {
+        const selector = payload.selector as string;
+        const shadowPath = payload.shadowPath as string[] | undefined;
+        const text = payload.text as string | undefined;
+
+        let el: ElementHandle<Element>;
+        if (text) {
+          el = await findByText(page, selector, text);
+        } else {
+          el = await findElement(page, selector, shadowPath);
+        }
+        await el.click();
+        return { success: true };
+      }
+
+      // ── fill ──
+      case "fill": {
+        const selector = payload.selector as string;
+        const value = payload.value as string;
+        const shadowPath = payload.shadowPath as string[] | undefined;
+        const label = payload.label as string | undefined;
+
+        let el: ElementHandle<Element> | null = null;
+
+        // Try label-based lookup first
+        if (label) {
+          el = await findByLabel(page, label);
+        }
+
+        // Fall back to selector / shadow path
+        if (!el) {
+          el = await findElement(page, selector, shadowPath);
+        }
+
+        // Clear existing value then type the new one
+        await el.click({ clickCount: 3 }); // select all
+        await el.press("Backspace");
+        await el.type(value);
+        return { success: true };
+      }
+
+      // ── select ──
+      case "select": {
+        const selector = payload.selector as string;
+        const value = payload.value as string;
+        const shadowPath = payload.shadowPath as string[] | undefined;
+
+        if (shadowPath && shadowPath.length > 0) {
+          const el = await findElement(page, selector, shadowPath);
+          await page.evaluate(
+            (selectEl: Element, val: string) => {
+              (selectEl as HTMLSelectElement).value = val;
+              selectEl.dispatchEvent(new Event("change", { bubbles: true }));
+            },
+            el,
+            value
+          );
+        } else {
+          await page.select(selector, value);
+        }
+        return { success: true };
+      }
+
+      // ── screenshot ──
+      case "screenshot": {
+        const fullPage = (payload.fullPage as boolean) ?? false;
+        const buf = await page.screenshot({
+          fullPage,
+          encoding: "base64",
+        });
+        return { success: true, screenshot: buf as string };
+      }
+
+      // ── evaluate ──
+      case "evaluate": {
+        const script = payload.script as string;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const result = await page.evaluate(script);
+        return { success: true, result };
+      }
+
+      // ── waitForSelector ──
+      case "waitForSelector": {
+        const selector = payload.selector as string;
+        const timeout = (payload.timeout as number) ?? 10_000;
+        const shadowPath = payload.shadowPath as string[] | undefined;
+
+        if (shadowPath && shadowPath.length > 0) {
+          // Poll for element inside shadow DOM
+          const deadline = Date.now() + timeout;
+          let found = false;
+          while (Date.now() < deadline) {
+            try {
+              await findElement(page, selector, shadowPath);
+              found = true;
+              break;
+            } catch {
+              await new Promise((r) => setTimeout(r, 250));
+            }
+          }
+          if (!found) {
+            throw new Error(
+              `Timed out waiting for ${selector} in shadow DOM`
+            );
+          }
+        } else {
+          await page.waitForSelector(selector, { timeout });
+        }
+        return { success: true };
+      }
+
+      // ── waitForNavigation ──
+      case "waitForNavigation": {
+        const timeout = (payload.timeout as number) ?? 15_000;
+        await page.waitForNavigation({ timeout });
+        return { success: true };
+      }
+
+      // ── keyboard ──
+      case "keyboard": {
+        const key = payload.key as string;
+        await page.keyboard.press(key as Parameters<typeof page.keyboard.press>[0]);
+        return { success: true };
+      }
+
+      // ── scroll ──
+      case "scroll": {
+        const selector = (payload.selector as string) ?? null;
+        const direction = payload.direction as "up" | "down";
+        const amount = (payload.amount as number) ?? 300;
+
+        await page.evaluate(
+          (sel: string | null, dir: string, amt: number) => {
+            const target = sel ? document.querySelector(sel) : window;
+            if (!target) throw new Error(`Scroll target not found: ${sel}`);
+
+            const delta = dir === "down" ? amt : -amt;
+            if (target === window) {
+              window.scrollBy(0, delta);
+            } else {
+              (target as Element).scrollBy(0, delta);
+            }
+          },
+          selector,
+          direction,
+          amount
+        );
+        return { success: true };
+      }
+
+      // ── hover ──
+      case "hover": {
+        const selector = payload.selector as string;
+        const shadowPath = payload.shadowPath as string[] | undefined;
+        const el = await findElement(page, selector, shadowPath);
+        await el.hover();
+        return { success: true };
+      }
+
+      // ── delay ──
+      case "delay": {
+        const ms = (payload.ms as number) ?? 1_000;
+        await new Promise((r) => setTimeout(r, ms));
+        return { success: true };
+      }
+
+      // ── ping ──
+      case "ping": {
+        return { success: true };
+      }
+
+      // ── shutdown ──
+      case "shutdown": {
+        return { success: true, shutdown: true };
+      }
+
+      default:
+        return { success: false, error: `Unknown command type: ${commandType}` };
+    }
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/heartbeat.ts

@@ -0,0 +1,48 @@
+/**
+ * Heartbeat — periodically pings the server so it knows we're alive.
+ */
+
+export function startHeartbeat(
+  baseUrl: string,
+  sessionId: string,
+  token: string,
+  intervalMs = 10_000
+): { stop: () => void } {
+  let timer: ReturnType<typeof setInterval> | null = null;
+
+  const tick = async () => {
+    try {
+      const res = await fetch(
+        `${baseUrl}/api/sessions/${sessionId}/agent/heartbeat`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}` },
+        }
+      );
+      if (res.ok) {
+        console.log("\uD83D\uDC93 Heartbeat sent");
+      } else {
+        console.error(`\u274C Heartbeat rejected (${res.status})`);
+      }
+    } catch (err) {
+      console.error(
+        "\u274C Heartbeat error:",
+        err instanceof Error ? err.message : err
+      );
+    }
+  };
+
+  timer = setInterval(tick, intervalMs);
+
+  // Send an initial heartbeat immediately
+  tick();
+
+  return {
+    stop() {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * sf-builder-agent — Desktop CLI for SalesForce Agent Creator.
+ *
+ * Connects to the web app, receives browser automation commands via SSE,
+ * executes them in a visible Chrome window, and reports results back.
+ */
+
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { pair } from "./pairing.js";
+import { connectSSE } from "./sse-client.js";
+import { launchBrowser, executeCommand } from "./browser.js";
+import { reportResult } from "./reporter.js";
+import { startHeartbeat } from "./heartbeat.js";
+import type { Browser } from "puppeteer";
+
+// ─── Arg Parsing ─────────────────────────────────────────────────────
+
+function parseArgs(argv: string[]): {
+  code?: string;
+  session?: string;
+  url: string;
+} {
+  const args: Record<string, string> = {};
+  for (let i = 2; i < argv.length; i++) {
+    const key = argv[i];
+    const val = argv[i + 1];
+    if (key === "--code" && val) {
+      args.code = val;
+      i++;
+    } else if (key === "--session" && val) {
+      args.session = val;
+      i++;
+    } else if (key === "--url" && val) {
+      args.url = val;
+      i++;
+    }
+  }
+  return {
+    code: args.code,
+    session: args.session,
+    url: args.url ?? "https://sf-builder.cmgfinancial.ai",
+  };
+}
+
+// ─── Prompt Helper ───────────────────────────────────────────────────
+
+async function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(question);
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  let code = args.code;
+  let sessionId = args.session;
+  const baseUrl = args.url;
+
+  // Interactive prompts if args are missing
+  if (!sessionId) {
+    sessionId = await prompt("Enter session ID: ");
+    if (!sessionId) {
+      console.error("\u274C Session ID is required");
+      process.exit(1);
+    }
+  }
+  if (!code) {
+    code = await prompt("Enter pairing code: ");
+    if (!code) {
+      console.error("\u274C Pairing code is required");
+      process.exit(1);
+    }
+  }
+
+  // ── Step 1: Pair ──
+  console.log("\uD83D\uDD17 Pairing...");
+  let token: string;
+  try {
+    const pairResult = await pair(baseUrl, sessionId, code);
+    token = pairResult.token;
+    sessionId = pairResult.sessionId;
+    console.log("\u2705 Paired successfully");
+  } catch (err) {
+    console.error(
+      "\u274C Pairing failed:",
+      err instanceof Error ? err.message : err
+    );
+    process.exit(1);
+  }
+
+  // ── Step 2: Launch Browser ──
+  console.log("\uD83C\uDF10 Launching browser...");
+  let browser: Browser;
+  let page: Awaited<ReturnType<typeof launchBrowser>>["page"];
+  try {
+    const launched = await launchBrowser();
+    browser = launched.browser;
+    page = launched.page;
+    console.log("\u2705 Browser ready");
+  } catch (err) {
+    console.error(
+      "\u274C Browser launch failed:",
+      err instanceof Error ? err.message : err
+    );
+    process.exit(1);
+  }
+
+  // ── Step 3: Start Heartbeat ──
+  const heartbeat = startHeartbeat(baseUrl, sessionId, token);
+
+  // ── Step 4: Connect to command stream ──
+  console.log("\uD83D\uDCE1 Connecting to command stream...");
+
+  const sse = connectSSE(
+    baseUrl,
+    sessionId,
+    token,
+    async (command) => {
+      const label = command.stepKey
+        ? `${command.commandType} (step: ${command.stepKey})`
+        : command.commandType;
+
+      const payloadHint =
+        command.commandType === "navigate"
+          ? ` \u2192 ${command.payload.url}`
+          : "";
+
+      console.log(`\u26A1 Executing: ${label}${payloadHint}`);
+
+      const result = await executeCommand(page, command.commandType, command.payload);
+
+      if (result.success) {
+        console.log(`\u2705 Command complete: ${command.commandType}`);
+      } else {
+        console.error(
+          `\u274C Command failed: ${command.commandType} \u2014 ${result.error}`
+        );
+      }
+
+      // Report back to server
+      const resultPayload: Record<string, unknown> = {};
+      if (result.result !== undefined) resultPayload.result = result.result;
+      if (result.screenshot) resultPayload.screenshot = result.screenshot;
+      if (result.error) resultPayload.error = result.error;
+
+      await reportResult(
+        baseUrl,
+        sessionId!,
+        token,
+        command.id,
+        result.success ? "success" : "error",
+        Object.keys(resultPayload).length > 0 ? resultPayload : undefined
+      );
+
+      // Handle shutdown command
+      if (result.shutdown) {
+        console.log("\uD83D\uDC4B Shutting down (server requested)...");
+        shutdown();
+      }
+    },
+    (err) => {
+      console.error(`\u274C SSE error: ${err.message}`);
+    }
+  );
+
+  // ── Graceful Shutdown ──
+  let shuttingDown = false;
+
+  function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    console.log("\uD83D\uDC4B Shutting down...");
+
+    sse.close();
+    heartbeat.stop();
+
+    browser
+      .close()
+      .catch(() => {})
+      .finally(() => {
+        process.exit(0);
+      });
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Keep alive
+  process.stdin.resume();
+}
+
+main().catch((err) => {
+  console.error("\u274C Fatal error:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});