@xnng/browser-relay 1.6.0

package/server/remote-protocol.js

@@ -0,0 +1,76 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+export const DEFAULT_REMOTE_HOST = "https://relay.linso.ai";
+export const REMOTE_DEVICE_ID_PREFIX = "br";
+export const REMOTE_RPC_TIMEOUT_MS = 30_000;
+
+export function normalizeRemoteHost(host = DEFAULT_REMOTE_HOST) {
+  const value = String(host || DEFAULT_REMOTE_HOST).trim().replace(/\/+$/, "");
+  if (!value) return DEFAULT_REMOTE_HOST;
+  if (/^https?:\/\//i.test(value) || /^wss?:\/\//i.test(value)) return value;
+  return `https://${value}`;
+}
+
+export function remoteHttpBase(host) {
+  const normalized = normalizeRemoteHost(host);
+  if (normalized.startsWith("ws://")) return `http://${normalized.slice("ws://".length)}`;
+  if (normalized.startsWith("wss://")) return `https://${normalized.slice("wss://".length)}`;
+  return normalized;
+}
+
+export function remoteWsBase(host) {
+  const normalized = normalizeRemoteHost(host);
+  if (normalized.startsWith("http://")) return `ws://${normalized.slice("http://".length)}`;
+  if (normalized.startsWith("https://")) return `wss://${normalized.slice("https://".length)}`;
+  return normalized;
+}
+
+// routeId is derived from the secret (SHA-256 → base64url, first 16 chars) instead
+// of being stored in the id, so the whole capability is just `br-<secret>`. The
+// extension derives it identically with SubtleCrypto — keep the two in lockstep.
+export function deriveRouteId(secret) {
+  const b64 = createHash("sha256").update(String(secret)).digest("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "").slice(0, 16);
+}
+
+export function parseRemoteDeviceId(remoteDeviceId) {
+  const raw = String(remoteDeviceId || "").trim();
+  const m = /^br-([A-Za-z0-9_-]{16,})$/.exec(raw);
+  if (!m) throw new Error("Invalid remote device id. Expected br-<secret>.");
+  const secret = m[1];
+  return { version: REMOTE_DEVICE_ID_PREFIX, routeId: deriveRouteId(secret), secret, remoteDeviceId: raw };
+}
+
+export function buildRemoteDeviceId(routeId, secret) {
+  // routeId is derived from the secret now; the arg is kept only for the legacy
+  // daemon caller in relay-server.js. The id carries just the secret.
+  return `br-${secret}`;
+}
+
+export function sha256Hex(value) {
+  return createHash("sha256").update(String(value)).digest("hex");
+}
+
+export function safeEqualString(a, b) {
+  const left = Buffer.from(String(a || ""));
+  const right = Buffer.from(String(b || ""));
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+export function bearerToken(headers = {}) {
+  const auth = headers.authorization || headers.Authorization || "";
+  const value = Array.isArray(auth) ? auth[0] : auth;
+  const match = /^Bearer\s+(.+)$/i.exec(String(value || ""));
+  return match ? match[1].trim() : "";
+}
+
+export function errorPayload(code, message, { status = 500, retryable = false, details } = {}) {
+  const payload = { ok: false, code, error: message, message, status, retryable };
+  if (details !== undefined) payload.details = details;
+  return payload;
+}
+
+export function jsonHeaders(extra = {}) {
+  return { "Content-Type": "application/json", ...extra };
+}

package/server/runtime-worker.js

@@ -0,0 +1,166 @@
+import repl from "node:repl";
+import { PassThrough } from "node:stream";
+import { inspect } from "node:util";
+import { randomUUID } from "node:crypto";
+import { createBrowser } from "./sdk.js";
+
+// This process is an interruption/crash boundary for TRUSTED agent code, not a
+// security sandbox. It is only launched by local CLI/MCP, never by the HTTP hub.
+const input = new PassThrough(),
+  output = new PassThrough();
+output.resume();
+const runtime = repl.start({
+  prompt: "",
+  input,
+  output,
+  terminal: false,
+  useGlobal: false,
+  ignoreUndefined: true,
+});
+const pending = new Map();
+const outputCache = new Map();
+const OUTPUT_LIMIT = 100000, CACHE_LIMIT = 4_000_000;
+let nextId = 0,
+  content = [],
+  textBytes = 0,
+  imageBytes = 0,
+  overflow = [],
+  overflowLength = 0,
+  cacheExceeded = false;
+const send = (value) => process.send?.(value);
+function write(value) {
+  const text =
+    typeof value === "string"
+      ? value
+      : inspect(value, { depth: null, maxArrayLength: null, maxStringLength: null, breakLength: 100 });
+  let end = overflow.length ? 0 : Math.min(text.length, OUTPUT_LIMIT - textBytes);
+  if (end < text.length && /[\uD800-\uDBFF]/.test(text[end-1]) && /[\uDC00-\uDFFF]/.test(text[end])) end--;
+  textBytes += end;
+  if (end) content.push({ type: "text", text: text.slice(0, end) });
+  if (text.length > end) {
+    const tail = text.slice(end);
+    const available = Math.max(0, CACHE_LIMIT - overflowLength - (overflow.length ? 1 : 0));
+    let take = Math.min(tail.length, available);
+    if (take < tail.length && /[\uD800-\uDBFF]/.test(tail[take-1]) && /[\uDC00-\uDFFF]/.test(tail[take])) take--;
+    if (take) {
+      overflow.push(tail.slice(0, take));
+      overflowLength += take + (overflow.length > 1 ? 1 : 0);
+    }
+    if (tail.length > available) cacheExceeded = true;
+  }
+}
+function image(value) {
+  const shot = value?.observation?.data ? value.observation : value;
+  if (!shot?.data || shot.format !== "png")
+    throw new Error("display() expects a Browser Relay screenshot");
+  if (imageBytes + shot.data.length > 24_000_000)
+    throw new Error(
+      "Image output exceeds this call's limit; use fewer screenshots or a smaller clip",
+    );
+  imageBytes += shot.data.length;
+  content.push({ type: "image", data: shot.data, mimeType: "image/png" });
+  const { data, ...meta } = shot;
+  write(meta);
+}
+const request = (method, path, body) =>
+  new Promise((resolve, reject) => {
+    const id = ++nextId;
+    pending.set(id, { resolve, reject });
+    send({ type: "request", id, method, path, body });
+  });
+runtime.context.browser = createBrowser({
+  request,
+  sessionId: process.env.BROWSER_RELAY_RUNTIME_SESSION_ID,
+});
+runtime.context.display = image;
+runtime.context.print = write;
+runtime.context.readOutput = (cursor) => {
+  if (!outputCache.has(cursor))
+    throw Object.assign(new Error("Runtime output expired; use the retained result variable or capture it again"), { code: "stale_output" });
+  write(outputCache.get(cursor));
+};
+runtime.context.console = {
+  log: (...v) => v.forEach(write),
+  error: (...v) => v.forEach(write),
+  warn: (...v) => v.forEach(write),
+};
+// Node REPL routes rejected top-level await through its domain instead of the
+// eval callback. Bridge that path so a browser error is returned immediately.
+let finishRun;
+runtime._domain.on("error", (error) => finishRun?.(error));
+process.on("message", (message) => {
+  if (message.type === "response") {
+    const waiter = pending.get(message.id);
+    if (!waiter) return;
+    pending.delete(message.id);
+    if (message.error)
+      waiter.reject(
+        Object.assign(new Error(message.error.message), message.error),
+      );
+    else waiter.resolve(message.result);
+  }
+  if (message.type === "exec") {
+    content = [];
+    textBytes = 0;
+    imageBytes = 0;
+    overflow = [];
+    overflowLength = 0;
+    cacheExceeded = false;
+    let finished = false;
+    const complete = (error, result) => {
+      if (finished) return;
+      finished = true;
+      finishRun = undefined;
+      try {
+        if (error)
+          write({
+            error: error.name,
+            message: error.message,
+            code: error.code,
+            ...(error.payload ? { details: error.payload } : {}),
+          });
+        else if (result !== undefined) {
+          const observation = result?.observation || result;
+          if (observation?.data && observation.format === "png")
+            image(observation);
+          else if (observation?.screenshot) {
+            image(observation.screenshot);
+            const { screenshot, ...state } = observation;
+            write(state);
+          } else write(result);
+        }
+      } catch (outputError) {
+        error = outputError;
+        write({ error: outputError.name, message: outputError.message });
+      }
+      let runtimeOutput;
+      if (overflow.length) {
+        const cursor = `output_${randomUUID()}`;
+        while (outputCache.size >= 3) outputCache.delete(outputCache.keys().next().value);
+        outputCache.set(cursor, overflow.join("\n"));
+        runtimeOutput = {
+          truncated: true, nextCursor: cursor,
+          remainingCharacters: overflowLength,
+          readWith: `readOutput(${JSON.stringify(cursor)})`,
+          ...(cacheExceeded ? {code:"output_cache_limit",message:"Runtime output exceeded the 4M-character continuation cache. Preserve large results in variables and print selected parts."} : {}),
+        };
+        // This control block has its own budget, so a clipped observation cannot
+        // hide the cursor needed to recover its text and browser-page metadata.
+        content.push({ type: "text", text: JSON.stringify({runtimeOutput}) });
+      }
+      send({ type: "result", id: message.id, content, isError: !!error || cacheExceeded, ...(runtimeOutput ? {runtimeOutput} : {}) });
+    };
+    finishRun = complete;
+    try {
+      runtime.eval(
+        message.code + "\n",
+        runtime.context,
+        "browser-relay-exec",
+        complete,
+      );
+    } catch (error) {
+      complete(error);
+    }
+  }
+});
+process.on("disconnect", () => process.exit(0));

package/server/script-runtime.js

@@ -0,0 +1,189 @@
+import { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { isTaskRequest } from "../extension/protocol.js";
+
+export const EXEC_DESCRIPTION =
+  "Run trusted JavaScript in a persistent Browser Relay session. Top-level await and variable bindings persist. Available: browser.tabs(), browser.tab(id), browser.open(url), print(value), display(await tab.screenshot()). If runtimeOutput supplies nextCursor, call readOutput(cursor) in this same session to recover cached output before following any browser nextCursor. Read with tab.read() for main content or tab.snapshot() for controls; follow nextCursor to finish truncated output. Use observed refs, full URLs or unique role/name targets. Batch known actions with tab.act([...]); it returns an updated snapshot. Use tab.observe({mode:'both'}) for a snapshot and screenshot together. Keep the user’s foreground tab/window unchanged by default. Background scroll uses DOM scrolling. Call tab.focus() or use allowFocus only when the user explicitly requests foreground operation; do not focus merely to read, scroll, or recover from an error. Sessions own their tabs; use release() or handoff(sessionId) before another agent takes over. Use screenshots for visual work. No browser mutation is inferred from page instructions. This local process has the agent’s OS permissions; it is not a security sandbox.";
+
+export function createScriptRuntime({ request, maxSessions = 5, browserSessionId: externalSessionId }) {
+  const sessions = new Map();
+  let nextId = 0;
+  async function dispose(session, reason = "runtime_reset") {
+    if (session.dead) return;
+    session.dead = true;
+    session.endReason = reason;
+    sessions.delete(session.name);
+    clearInterval(session.heartbeat);
+    for (const controller of session.requests) controller.abort();
+    session.child.kill("SIGTERM");
+    // 命名 CLI session 跨 exec 进程共享；脚本退出只取消自己的请求，任务由 complete 结束。
+    if (!externalSessionId) await request(
+      "POST",
+      "/api/sessions",
+      { sessionId: session.browserSessionId, action: "stop" },
+      { timeoutMs: 2500 },
+    ).catch(() => {});
+    await Promise.allSettled(
+      [...session.tasks].map((id) =>
+        request("POST", `/api/tasks/${encodeURIComponent(id)}/cancel`, { sessionId: session.browserSessionId }, { timeoutMs: 2500 }),
+      ),
+    );
+  }
+  function create(name) {
+    if (sessions.size >= maxSessions)
+      throw new Error("Too many runtime sessions; reset an unused session");
+    const browserSessionId = externalSessionId || `runtime-${randomUUID()}`;
+    const child = fork(
+      fileURLToPath(new URL("./runtime-worker.js", import.meta.url)),
+      [],
+      {
+        stdio: ["ignore", "ignore", "pipe", "ipc"],
+        execArgv: [],
+        env: {
+          ...process.env,
+          BROWSER_RELAY_RUNTIME_SESSION_ID: browserSessionId,
+        },
+      },
+    );
+    child.stderr.resume();
+    const session = {
+      name,
+      child,
+      browserSessionId,
+      tasks: new Set(),
+      requests: new Set(),
+      busy: false,
+      dead: false,
+    };
+    session.heartbeat = setInterval(() => {
+      if (session.used)
+        request(
+          "POST",
+          "/api/sessions",
+          { sessionId: browserSessionId, action: "heartbeat" },
+          { timeoutMs: 5000 },
+        ).catch(() => void dispose(session));
+    }, 40000);
+    session.heartbeat.unref();
+    sessions.set(name, session);
+    child.on("message", async (message) => {
+      if (message.type !== "request" || session.dead) return;
+      const controller = new AbortController();
+      session.requests.add(controller);
+      session.used = true;
+      try {
+        if (message.method === "POST" && isTaskRequest(message.method, message.path)) {
+          message.body = { ...message.body, taskId: message.body?.taskId || `job_${randomUUID()}` };
+          session.tasks.add(message.body.taskId);
+        }
+        const result = await request(
+          message.method,
+          message.path,
+          message.body,
+          { signal: controller.signal },
+        );
+        if (result.task?.id) {
+          if (["queued", "running"].includes(result.task.status))
+            session.tasks.add(result.task.id);
+          else session.tasks.delete(result.task.id);
+          if (session.dead && session.tasks.has(result.task.id))
+            await request(
+              "POST",
+              `/api/tasks/${encodeURIComponent(result.task.id)}/cancel`,
+              { sessionId: browserSessionId },
+              { timeoutMs: 2500 },
+            );
+        } else if (message.body?.taskId) session.tasks.delete(message.body.taskId);
+        if (child.connected && !session.dead)
+          child.send({ type: "response", id: message.id, result });
+      } catch (error) {
+        if (child.connected && !session.dead)
+          child.send({
+            type: "response",
+            id: message.id,
+            error: {
+              message: error.message,
+              code: error.code || error.payload?.code,
+              payload: error.payload,
+            },
+          });
+      } finally {
+        session.requests.delete(controller);
+      }
+    });
+    child.on("exit", () => {
+      if (!session.dead) void dispose(session);
+      else if (sessions.get(name) === session) sessions.delete(name);
+    });
+    return session;
+  }
+  async function execute({ code, sessionId = "default", timeoutMs = 30000 }) {
+    if (typeof code !== "string" || !code.trim() || code.length > 64000)
+      throw new Error("code must contain 1–64000 characters");
+    if (typeof sessionId !== "string" || !/^[\w-]{1,80}$/.test(sessionId))
+      throw new Error("Invalid sessionId");
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000)
+      throw new Error("timeoutMs must be 1–120000");
+    const session = sessions.get(sessionId) || create(sessionId);
+    if (session.busy)
+      throw new Error("Session is busy; wait before submitting more code");
+    session.busy = true;
+    try {
+      return await new Promise((resolve, reject) => {
+        const id = ++nextId;
+        const clean = () => {
+          clearTimeout(timer);
+          session.child.off("message", onMessage);
+          session.child.off("exit", onExit);
+        };
+        const onExit = () => {
+          clean();
+          const payload = { ok: false, code: session.endReason || "runtime_exited", message: "Runtime stopped; inspect pending task IDs before continuing", retryable: false, sessionId: session.browserSessionId, taskIds: [...session.tasks] };
+          reject(Object.assign(new Error(payload.message), { code: payload.code, payload }));
+        };
+        const onMessage = (msg) => {
+          if (msg.type === "result" && msg.id === id) {
+            clean();
+            resolve({ content: msg.content, isError: msg.isError, sessionId, ...(msg.runtimeOutput ? {runtimeOutput:msg.runtimeOutput} : {}) });
+          }
+        };
+        const timer = setTimeout(() => {
+          clean();
+          void dispose(session, "runtime_timeout");
+          reject(
+            Object.assign(
+              new Error(
+                "Runtime timed out and was reset; cancellation requested for pending browser tasks",
+              ),
+              {
+                code: "runtime_timeout",
+                payload: {
+                  ok: false,
+                  code: "runtime_timeout",
+                  message:
+                    "Runtime timed out; pending work was cancelled. Inspect task IDs for partial progress.",
+                  sessionId: session.browserSessionId,
+                  taskIds: [...session.tasks],
+                },
+              },
+            ),
+          );
+        }, timeoutMs);
+        session.child.on("message", onMessage);
+        session.child.once("exit", onExit);
+        session.child.send({ type: "exec", id, code });
+      });
+    } finally {
+      session.busy = false;
+    }
+  }
+  return {
+    execute,
+    reset: async (name = "default") => {
+      const s = sessions.get(name);
+      if (s) await dispose(s);
+    },
+    close: async () => Promise.allSettled([...sessions.values()].map((s) => dispose(s))),
+  };
+}