synaptic-playwright-sidecar 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# Synaptic Playwright Sidecar
+
+In-repo browser sidecar used by Synaptic's Elixir planner (`browser_task`).
+
+## Why this exists
+
+- Synaptic (Elixir) is the planner/brain.
+- This sidecar executes primitive browser actions only.
+- Contract:
+  - `POST /session/start`
+  - `POST /action`
+  - `POST /session/close`
+
+## Install and run
+
+From the repository root:
+
+```bash
+cd sidecar/playwright
+npm install
+npm run start
+```
+
+By default the server listens on `127.0.0.1:3456`.
+
+## Environment variables
+
+- `PORT` (default `3456`)
+- `HOST` (default `127.0.0.1`)
+- `BROWSER_TYPE` (`chromium`, `firefox`, `webkit`; default `chromium`)
+- `BROWSER_HEADLESS` (`true`/`false`; default `true`)
+- `BROWSER_HUMAN_EMULATION` (`true`/`false`; default `true`)
+- `BROWSER_CHANNEL` (default none; in human emulation on Chromium defaults to `chrome`)
+- `BROWSER_USER_AGENT` (optional default UA used in human emulation)
+- `BROWSER_LOCALE` (optional default locale used in human emulation)
+- `BROWSER_TIMEZONE_ID` (optional default timezone used in human emulation)
+- `BROWSER_COLOR_SCHEME` (optional default color scheme, e.g. `light` or `dark`)
+- `DEFAULT_ACTION_TIMEOUT_MS` (default `30000`)
+
+## API examples
+
+### `POST /session/start`
+
+Request:
+
+```json
+{
+  "session_id": "optional-session-id",
+  "session_options": {
+    "headless": false,
+    "viewport": { "width": 1400, "height": 900 },
+    "human_emulation": true,
+    "user_agent": "optional custom UA",
+    "locale": "pl-PL",
+    "timezone_id": "Europe/Warsaw",
+    "color_scheme": "light",
+    "channel": "chrome",
+    "storage_state_path": "/absolute/or/relative/path/to/storage-state.json"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "session_id": "optional-session-id",
+  "browser_type": "chromium",
+  "headless": false,
+  "session_options": {
+    "headless": false,
+    "viewport": { "width": 1400, "height": 900 },
+    "human_emulation": true,
+    "user_agent": null,
+    "locale": null,
+    "timezone_id": null,
+    "color_scheme": null,
+    "channel": null,
+    "storage_state_path": "/absolute/or/relative/path/to/storage-state.json"
+  },
+  "created_at": "2026-02-21T00:00:00.000Z"
+}
+```
+
+When `session_options.storage_state_path` is set:
+- `/session/start` loads existing storage state from that path (if file exists).
+- `/session/close` writes current context storage state to that path.
+
+### `POST /action`
+
+Request:
+
+```json
+{
+  "session_id": "optional-session-id",
+  "action": "navigate",
+  "params": {
+    "url": "https://example.com"
+  },
+  "timeout_ms": 15000
+}
+```
+
+Success response:
+
+```json
+{
+  "ok": true,
+  "action": "navigate",
+  "result": {
+    "url": "https://example.com/"
+  }
+}
+```
+
+Failure response:
+
+```json
+{
+  "ok": false,
+  "action": "navigate",
+  "error": {
+    "code": "action_timeout",
+    "message": "Timeout 15000ms exceeded.",
+    "retryable": true
+  }
+}
+```
+
+### `POST /session/close`
+
+Request:
+
+```json
+{
+  "session_id": "optional-session-id"
+}
+```
+
+Response:
+
+```json
+{
+  "ok": true,
+  "session_id": "optional-session-id"
+}
+```
+
+## Supported action enum (v1)
+
+- `navigate`
+- `click`
+- `type`
+- `select`
+- `wait_for`
+- `extract_text`
+- `extract_json`
+- `screenshot`
+- `get_url`
+- `get_title`
+- `press`
+- `scroll`

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "synaptic-playwright-sidecar",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "In-repo Playwright sidecar for Synaptic browser actions",
+  "author": "bionaut",
+  "main": "src/server.mjs",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/server.mjs",
+    "dev": "node --watch src/server.mjs",
+    "check": "node --check src/server.mjs",
+    "prepublishOnly": "npm run check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "playwright": "^1.52.0"
+  },
+  "keywords": [
+    "synaptic",
+    "playwright",
+    "browser",
+    "sidecar"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bionaut/synaptic.git",
+    "directory": "sidecar/playwright"
+  },
+  "bugs": {
+    "url": "https://github.com/bionaut/synaptic/issues"
+  },
+  "homepage": "https://github.com/bionaut/synaptic#readme"
+}

package/src/server.mjs

@@ -0,0 +1,553 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chromium, firefox, webkit } from "playwright";
+
+const PORT = parseInt(process.env.PORT || "3456", 10);
+const HOST = process.env.HOST || "127.0.0.1";
+const REQUEST_BODY_LIMIT_BYTES = 2_000_000;
+const DEFAULT_TIMEOUT_MS = parseInt(process.env.DEFAULT_ACTION_TIMEOUT_MS || "30000", 10);
+const BROWSER_TYPE = (process.env.BROWSER_TYPE || "chromium").toLowerCase();
+const HEADLESS = parseBoolean(process.env.BROWSER_HEADLESS, true);
+const HUMAN_EMULATION = parseBoolean(process.env.BROWSER_HUMAN_EMULATION, true);
+const DEFAULT_CHANNEL = process.env.BROWSER_CHANNEL || null;
+const DEFAULT_USER_AGENT = process.env.BROWSER_USER_AGENT || null;
+const DEFAULT_LOCALE = process.env.BROWSER_LOCALE || null;
+const DEFAULT_TIMEZONE_ID = process.env.BROWSER_TIMEZONE_ID || null;
+const DEFAULT_COLOR_SCHEME = process.env.BROWSER_COLOR_SCHEME || null;
+const DEFAULT_VIEWPORT = { width: 1400, height: 900 };
+
+const sessions = new Map();
+const browserFactory = { chromium, firefox, webkit }[BROWSER_TYPE] || chromium;
+
+const ACTIONS = new Set([
+  "navigate",
+  "click",
+  "type",
+  "select",
+  "wait_for",
+  "extract_text",
+  "extract_json",
+  "screenshot",
+  "get_url",
+  "get_title",
+  "press",
+  "scroll",
+]);
+
+function parseBoolean(input, fallback) {
+  if (input == null) return fallback;
+  const normalized = String(input).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function asPositiveInt(input, fallback) {
+  if (Number.isInteger(input) && input > 0) return input;
+  if (typeof input === "string" && input.trim() !== "") {
+    const parsed = Number.parseInt(input, 10);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  }
+  return fallback;
+}
+
+function jsonResponse(res, statusCode, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(statusCode, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function methodNotAllowed(res) {
+  return jsonResponse(res, 405, { error: { code: "method_not_allowed", message: "Use POST" } });
+}
+
+function notFound(res) {
+  return jsonResponse(res, 404, { error: { code: "not_found", message: "Route not found" } });
+}
+
+function badRequest(res, code, message) {
+  return jsonResponse(res, 400, { error: { code, message } });
+}
+
+function internalError(res, code, message) {
+  return jsonResponse(res, 500, { error: { code, message } });
+}
+
+async function readJson(req) {
+  const chunks = [];
+  let total = 0;
+
+  for await (const chunk of req) {
+    total += chunk.length;
+    if (total > REQUEST_BODY_LIMIT_BYTES) {
+      throw new Error("request_too_large");
+    }
+    chunks.push(chunk);
+  }
+
+  const body = Buffer.concat(chunks).toString("utf8").trim();
+  if (!body) return {};
+
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw new Error("invalid_json");
+  }
+}
+
+function sessionPayload(sessionId, session) {
+  return {
+    session_id: sessionId,
+    browser_type: session.browserType,
+    headless: session.headless,
+    session_options: session.sessionOptions,
+    created_at: session.createdAt,
+  };
+}
+
+async function startSession(body) {
+  const requestedSessionId = typeof body.session_id === "string" ? body.session_id.trim() : "";
+  const sessionId = requestedSessionId || randomUUID();
+
+  if (sessions.has(sessionId)) {
+    return { status: 200, body: { ...sessionPayload(sessionId, sessions.get(sessionId)), reused: true } };
+  }
+
+  const requestedSessionOptions = isObject(body.session_options) ? body.session_options : {};
+  const humanEmulation = resolveHumanEmulation(requestedSessionOptions);
+  const launchOptions = launchOptionsFromSessionOptions(requestedSessionOptions, humanEmulation);
+  const contextOptions = contextOptionsFromSessionOptions(requestedSessionOptions, humanEmulation);
+  const storageStatePath = resolveStorageStatePath(requestedSessionOptions);
+
+  if (storageStatePath && fs.existsSync(storageStatePath)) {
+    contextOptions.storageState = storageStatePath;
+  }
+
+  const browser = await browserFactory.launch(launchOptions);
+  const context = await browser.newContext(contextOptions);
+  if (humanEmulation) {
+    await applyStealthInitScripts(context);
+  }
+  const page = await context.newPage();
+
+  const session = {
+    browser,
+    context,
+    page,
+    browserType: BROWSER_TYPE,
+    headless: launchOptions.headless,
+    sessionOptions: {
+      headless: launchOptions.headless,
+      viewport: contextOptions.viewport || DEFAULT_VIEWPORT,
+      user_agent: contextOptions.userAgent || null,
+      locale: contextOptions.locale || null,
+      timezone_id: contextOptions.timezoneId || null,
+      color_scheme: contextOptions.colorScheme || null,
+      human_emulation: humanEmulation,
+      channel: launchOptions.channel || null,
+      storage_state_path: storageStatePath || null,
+    },
+    storageStatePath,
+    createdAt: new Date().toISOString(),
+  };
+
+  sessions.set(sessionId, session);
+
+  return { status: 200, body: sessionPayload(sessionId, session) };
+}
+
+function launchOptionsFromSessionOptions(sessionOptions, humanEmulation) {
+  const options = {
+    headless: parseBoolean(sessionOptions.headless, HEADLESS),
+  };
+
+  const channel =
+    requireString(sessionOptions, "channel") ||
+    (humanEmulation && BROWSER_TYPE === "chromium" ? DEFAULT_CHANNEL || "chrome" : null);
+  if (channel) options.channel = channel;
+
+  const launchArgs =
+    (Array.isArray(sessionOptions.launch_args) && sessionOptions.launch_args) ||
+    (Array.isArray(sessionOptions.args) && sessionOptions.args) ||
+    [];
+
+  const args = launchArgs.filter((arg) => typeof arg === "string" && arg.trim() !== "");
+  if (humanEmulation && BROWSER_TYPE === "chromium") {
+    args.push("--disable-blink-features=AutomationControlled");
+    options.ignoreDefaultArgs = ["--enable-automation"];
+  }
+
+  if (args.length > 0) {
+    options.args = [...new Set(args)];
+  }
+
+  return options;
+}
+
+function contextOptionsFromSessionOptions(sessionOptions, humanEmulation) {
+  const contextOptions = {
+    viewport: resolveViewport(sessionOptions),
+  };
+
+  const userAgent =
+    requireString(sessionOptions, "user_agent") ||
+    requireString(sessionOptions, "userAgent") ||
+    (humanEmulation ? DEFAULT_USER_AGENT : null);
+  if (userAgent) contextOptions.userAgent = userAgent;
+
+  const locale = requireString(sessionOptions, "locale") || (humanEmulation ? DEFAULT_LOCALE : null);
+  if (locale) contextOptions.locale = locale;
+
+  const timezoneId =
+    requireString(sessionOptions, "timezone_id") ||
+    requireString(sessionOptions, "timezoneId") ||
+    (humanEmulation ? DEFAULT_TIMEZONE_ID : null);
+  if (timezoneId) contextOptions.timezoneId = timezoneId;
+
+  const colorScheme =
+    requireString(sessionOptions, "color_scheme") ||
+    requireString(sessionOptions, "colorScheme") ||
+    (humanEmulation ? DEFAULT_COLOR_SCHEME : null);
+  if (colorScheme) contextOptions.colorScheme = colorScheme;
+
+  return contextOptions;
+}
+
+function resolveHumanEmulation(sessionOptions) {
+  if (typeof sessionOptions.human_emulation === "boolean") return sessionOptions.human_emulation;
+  if (typeof sessionOptions.humanEmulation === "boolean") return sessionOptions.humanEmulation;
+  return HUMAN_EMULATION;
+}
+
+async function applyStealthInitScripts(context) {
+  await context.addInitScript(() => {
+    try {
+      Object.defineProperty(Navigator.prototype, "webdriver", {
+        get: () => undefined,
+        configurable: true,
+      });
+    } catch {
+      // No-op if the browser blocks redefining this property.
+    }
+  });
+}
+
+function resolveViewport(sessionOptions) {
+  if (!isObject(sessionOptions.viewport)) return DEFAULT_VIEWPORT;
+
+  return {
+    width: asPositiveInt(sessionOptions.viewport.width, DEFAULT_VIEWPORT.width),
+    height: asPositiveInt(sessionOptions.viewport.height, DEFAULT_VIEWPORT.height),
+  };
+}
+
+function resolveStorageStatePath(sessionOptions) {
+  const candidate =
+    requireString(sessionOptions, "storage_state_path") || requireString(sessionOptions, "storageStatePath");
+
+  if (!candidate) return null;
+
+  if (path.isAbsolute(candidate)) return candidate;
+  return path.resolve(process.cwd(), candidate);
+}
+
+function getSession(sessionId) {
+  if (typeof sessionId !== "string" || sessionId.trim() === "") return null;
+  return sessions.get(sessionId);
+}
+
+async function closeSession(body) {
+  const sessionId = body.session_id;
+  const session = getSession(sessionId);
+
+  if (!session) {
+    return {
+      status: 404,
+      body: { error: { code: "session_not_found", message: "session not found" }, session_id: sessionId || null },
+    };
+  }
+
+  if (session.storageStatePath) {
+    try {
+      fs.mkdirSync(path.dirname(session.storageStatePath), { recursive: true });
+      await session.context.storageState({ path: session.storageStatePath });
+    } catch {
+      // Best-effort persistence; continue closing even if this fails.
+    }
+  }
+
+  await session.context.close();
+  await session.browser.close();
+  sessions.delete(sessionId);
+
+  return { status: 200, body: { ok: true, session_id: sessionId } };
+}
+
+function resolveTimeoutMs(body, params) {
+  if (Number.isInteger(body.timeout_ms) && body.timeout_ms > 0) return body.timeout_ms;
+  if (params && Number.isInteger(params.timeout_ms) && params.timeout_ms > 0) return params.timeout_ms;
+  return DEFAULT_TIMEOUT_MS;
+}
+
+function actionError(code, message, retryable = false) {
+  return { ok: false, error: { code, message, retryable } };
+}
+
+function requireString(params, key) {
+  const value = params?.[key];
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+async function runAction(session, action, params, timeoutMs) {
+  const page = session.page;
+
+  switch (action) {
+    case "navigate": {
+      const url = requireString(params, "url");
+      if (!url) return actionError("invalid_action_params", "navigate requires params.url");
+
+      const waitUntil = requireString(params, "wait_until") || "domcontentloaded";
+      await page.goto(url, { waitUntil, timeout: timeoutMs });
+      return { ok: true, action, result: { url: page.url() } };
+    }
+
+    case "click": {
+      const selector = requireString(params, "selector");
+      if (!selector) return actionError("invalid_action_params", "click requires params.selector");
+
+      await page.click(selector, { timeout: timeoutMs });
+      return { ok: true, action, result: { selector } };
+    }
+
+    case "type": {
+      const selector = requireString(params, "selector");
+      const text = typeof params?.text === "string" ? params.text : null;
+      if (!selector || text == null)
+        return actionError("invalid_action_params", "type requires params.selector and params.text");
+
+      const clearFirst = parseBoolean(params?.clear, true);
+      if (clearFirst) await page.fill(selector, "", { timeout: timeoutMs });
+      await page.fill(selector, text, { timeout: timeoutMs });
+      return { ok: true, action, result: { selector } };
+    }
+
+    case "select": {
+      const selector = requireString(params, "selector");
+      const value = params?.value;
+      if (!selector || (typeof value !== "string" && !Array.isArray(value))) {
+        return actionError("invalid_action_params", "select requires params.selector and params.value");
+      }
+
+      const selected = await page.selectOption(selector, value, { timeout: timeoutMs });
+      return { ok: true, action, result: { selector, selected } };
+    }
+
+    case "wait_for": {
+      if (typeof params?.ms === "number" && params.ms > 0) {
+        await page.waitForTimeout(params.ms);
+        return { ok: true, action, result: { waited_ms: params.ms } };
+      }
+
+      const selector = requireString(params, "selector");
+      if (selector) {
+        const state = requireString(params, "state") || "visible";
+        await page.waitForSelector(selector, { state, timeout: timeoutMs });
+        return { ok: true, action, result: { selector, state } };
+      }
+
+      const loadState = requireString(params, "load_state");
+      if (loadState) {
+        await page.waitForLoadState(loadState, { timeout: timeoutMs });
+        return { ok: true, action, result: { load_state: loadState } };
+      }
+
+      return actionError(
+        "invalid_action_params",
+        "wait_for requires one of params.ms, params.selector, params.load_state"
+      );
+    }
+
+    case "extract_text": {
+      const selector = requireString(params, "selector") || "body";
+      const text = await page.textContent(selector, { timeout: timeoutMs });
+      return { ok: true, action, result: { selector, text: text || "" } };
+    }
+
+    case "extract_json": {
+      const script = requireString(params, "script");
+      if (!script) return actionError("invalid_action_params", "extract_json requires params.script");
+
+      // Intentionally executes caller-provided extraction code in page context.
+      const extracted = await page.evaluate(new Function(`return (${script});`));
+      return { ok: true, action, result: { data: extracted ?? {} } };
+    }
+
+    case "screenshot": {
+      const fullPage = parseBoolean(params?.full_page, true);
+      const outputPath = requireString(params, "path") || path.join(os.tmpdir(), `synaptic-shot-${randomUUID()}.png`);
+      await page.screenshot({ path: outputPath, fullPage });
+      return { ok: true, action, result: { path: outputPath, full_page: fullPage } };
+    }
+
+    case "get_url":
+      return { ok: true, action, result: { url: page.url() } };
+
+    case "get_title":
+      return { ok: true, action, result: { title: await page.title() } };
+
+    case "press": {
+      const key = requireString(params, "key");
+      const selector = requireString(params, "selector");
+      if (!key) return actionError("invalid_action_params", "press requires params.key");
+      if (selector) await page.focus(selector);
+      await page.keyboard.press(key);
+      return { ok: true, action, result: { key, selector: selector || null } };
+    }
+
+    case "scroll": {
+      const x = Number.isFinite(params?.x) ? params.x : 0;
+      const y = Number.isFinite(params?.y) ? params.y : 600;
+      await page.evaluate(
+        ({ scrollX, scrollY }) => {
+          window.scrollBy(scrollX, scrollY);
+        },
+        { scrollX: x, scrollY: y }
+      );
+      return { ok: true, action, result: { x, y } };
+    }
+
+    default:
+      return actionError("invalid_action", `unsupported action: ${String(action)}`);
+  }
+}
+
+async function handleAction(body) {
+  const sessionId = body.session_id;
+  const action = typeof body.action === "string" ? body.action.trim() : "";
+  const params = body.params && typeof body.params === "object" ? body.params : {};
+
+  if (!action || !ACTIONS.has(action)) {
+    return {
+      status: 400,
+      body: { ok: false, action: action || null, error: { code: "invalid_action", message: "unsupported action" } },
+    };
+  }
+
+  const session = getSession(sessionId);
+  if (!session) {
+    return {
+      status: 404,
+      body: {
+        ok: false,
+        action,
+        error: { code: "session_not_found", message: "session not found", retryable: false },
+      },
+    };
+  }
+
+  const timeoutMs = resolveTimeoutMs(body, params);
+
+  try {
+    const result = await runAction(session, action, params, timeoutMs);
+    return { status: result.ok ? 200 : 400, body: result };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const timeoutLike = message.includes("Timeout") || message.includes("timeout");
+
+    return {
+      status: timeoutLike ? 408 : 500,
+      body: {
+        ok: false,
+        action,
+        error: {
+          code: timeoutLike ? "action_timeout" : "action_failed",
+          message,
+          retryable: timeoutLike,
+        },
+      },
+    };
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    if (!req.url) return notFound(res);
+    if (req.method !== "POST") return methodNotAllowed(res);
+
+    const body = await readJson(req);
+
+    if (req.url === "/session/start") {
+      const { status, body: payload } = await startSession(body);
+      return jsonResponse(res, status, payload);
+    }
+
+    if (req.url === "/action") {
+      const { status, body: payload } = await handleAction(body);
+      return jsonResponse(res, status, payload);
+    }
+
+    if (req.url === "/session/close") {
+      const { status, body: payload } = await closeSession(body);
+      return jsonResponse(res, status, payload);
+    }
+
+    return notFound(res);
+  } catch (error) {
+    if (error instanceof Error && error.message === "invalid_json") {
+      return badRequest(res, "invalid_json", "Request body must be valid JSON");
+    }
+
+    if (error instanceof Error && error.message === "request_too_large") {
+      return badRequest(res, "request_too_large", "Request body exceeds allowed size");
+    }
+
+    return internalError(
+      res,
+      "internal_error",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+});
+
+async function shutdown() {
+  for (const [sessionId, session] of sessions.entries()) {
+    try {
+      await session.context.close();
+      await session.browser.close();
+    } catch {
+      // Best-effort cleanup.
+    } finally {
+      sessions.delete(sessionId);
+    }
+  }
+
+  server.close(() => {
+    process.exit(0);
+  });
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+server.listen(PORT, HOST, () => {
+  console.log(
+    JSON.stringify({
+      event: "playwright_sidecar_started",
+      host: HOST,
+      port: PORT,
+      browser_type: BROWSER_TYPE,
+      headless: HEADLESS,
+      human_emulation: HUMAN_EMULATION,
+    })
+  );
+});