@schlenkr/ragents 0.1.5 → 0.1.6

package/packages/workspace-executor/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@aicontainer/workspace-executor",
+  "name": "@ragents/workspace-executor",
   "version": "0.1.0",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@aicontainer/agent": "workspace:*",
+    "@ragents/agent": "workspace:*",
     "typescript": "^5.9.0",
     "typescript-language-server": "6.0.0",
     "vscode-jsonrpc": "^9.0.2"

package/packages/workspace-executor/src/bash-launch.ts

@@ -0,0 +1,45 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { getShellConfig } from "@ragents/agent";
+
+/** Ein Befehl des Werkzeugs bash, so wie er startet: Programm, Argumente und Umgebung. */
+export interface BashLaunch {
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly env: NodeJS.ProcessEnv;
+}
+
+/** Unter Windows sucht RAgents keine Bash; der Executor nennt die mitgebrachte. */
+const missingWindowsBash = (): Error => new Error(
+  "Unter Windows arbeitet das Werkzeug bash nur mit der Bash, die RAgents mitbringt, und für diesen Executor ist keine genannt. "
+  + "Die VS-Code-Erweiterung bringt sie in ihrer Windows-Fassung (win32-x64, win32-arm64) unter dist/bash/<plattform>/usr/bin/bash.exe mit "
+  + "und reicht sie an Arbeitsplatz und lokalen Host weiter; ein Host oder Arbeitsplatz ohne Erweiterung braucht RAGENTS_BASH mit dem Pfad dieser bash.exe.",
+);
+
+/** Die Windows-Umgebung der Bash: ihr usr/bin vorn im PATH, damit find.exe und sort.exe aus System32 nicht gewinnen; MSYSTEM gehört einer Git-Bash-Anmeldung. */
+const windowsBashEnvironment = (env: NodeJS.ProcessEnv, bin: string): NodeJS.ProcessEnv => {
+  const pathNames = Object.keys(env).filter((name) => name.toUpperCase() === "PATH");
+  const current = pathNames.map((name) => env[name]).find((value) => value !== undefined && value !== "");
+  const kept = Object.entries(env).filter(([name]) => !pathNames.includes(name) && name !== "MSYSTEM");
+  return { ...Object.fromEntries(kept), PATH: current ? `${bin}${path.win32.delimiter}${current}` : bin };
+};
+
+/** Wie ein Befehl in der Bash dieses Executors startet; die Plattform ist für Prüfungen wählbar. */
+export const bashLaunch = (
+  bash: string | undefined,
+  command: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): BashLaunch => {
+  if (platform === "win32" && bash === undefined) throw missingWindowsBash();
+  if (bash !== undefined && !existsSync(bash)) {
+    throw new Error(`Die Bash dieses Executors fehlt: ${bash}. Unter Windows gehört sie zur Erweiterung (dist/bash/<plattform>) oder steht in RAGENTS_BASH.`);
+  }
+  const shell = getShellConfig(bash, platform);
+  if (!/bash(\.exe)?$/i.test(shell.shell)) throw new Error(`${shell.shell} ist keine Bash; das Werkzeug heißt bash und der Prompt beschreibt bash`);
+  return {
+    command: shell.shell,
+    args: [...shell.args, command],
+    env: platform === "win32" ? windowsBashEnvironment(env, path.win32.dirname(shell.shell)) : env,
+  };
+};

package/packages/workspace-executor/src/browser/contract.ts

@@ -0,0 +1,71 @@
+export const BROWSER_OPERATIONS = {
+  open: "browser.open",
+  snapshot: "browser.snapshot",
+  viewport: "browser.viewport",
+  click: "browser.click",
+  fill: "browser.fill",
+  select: "browser.select",
+  press: "browser.press",
+  check: "browser.check",
+  screenshot: "browser.screenshot",
+  state: "browser.state",
+  close: "browser.close",
+} as const;
+
+/** Nennt einen eigenen Chrome; auf einem Server setzt ihn die Profilsektion `ragents.browser`, auf einem Arbeitsplatz seine Umgebung. */
+export const BROWSER_EXECUTABLE_VARIABLE = "BROWSER_EXECUTABLE_PATH";
+
+export interface BrowserTarget {
+  role?: string;
+  name?: string;
+  label?: string;
+  text?: string;
+  testId?: string;
+  css?: string;
+  frame?: string;
+  nth?: number;
+  first?: boolean;
+}
+
+export interface BrowserViewport {
+  width: number;
+  height: number;
+}
+
+export interface BrowserSnapshot {
+  url: string;
+  title: string;
+  snapshot: string;
+  truncated: boolean;
+  errors: string[];
+}
+
+export interface BrowserCheck {
+  target?: BrowserTarget;
+  text?: string;
+  url?: string;
+  count?: number;
+  noErrors?: boolean;
+}
+
+/** Was eine bestandene Prüfung belegt; die Zeit setzt, wer die Evidenz des Runs hält. */
+export interface BrowserCheckResult {
+  url: string;
+  assertions: string[];
+}
+
+/** Der Stand der Seite nach einer Operation; der Aufrufer hält daraus die Evidenz des Runs. */
+export interface BrowserPageState {
+  url: string;
+  /** Seit der letzten Aktion oder Navigation hat eine Prüfung bestanden. */
+  checked: boolean;
+  errors: string[];
+  /** Die Kennungen der Aufnahmen seit der letzten Aktion oder Navigation, so wie der Aufrufer sie vergeben hat. */
+  screenshots: string[];
+}
+
+/** Das Ergebnis einer Operation an der Seite und der Stand, in dem sie die Seite hinterlässt. */
+export interface BrowserStep<T> {
+  result: T;
+  page: BrowserPageState;
+}

package/packages/workspace-executor/src/browser/module.ts

@@ -0,0 +1,74 @@
+import type { Browser } from "playwright-core";
+import { WorkspaceOperationError } from "../errors.js";
+import type { WorkspaceModuleFactory } from "../module.js";
+import { BROWSER_OPERATIONS, type BrowserCheck, type BrowserTarget, type BrowserViewport } from "./contract.js";
+import { BrowserPages } from "./pages.js";
+import { launchChromium } from "./playwright.js";
+
+const BROWSER_TIMEOUT_MS = 15_000;
+
+export interface BrowserModuleOptions {
+  /** Startet den Browser eines Runs; ohne Angabe Chrome über playwright-core aus dem Host dieser Maschine. */
+  launch?: (runId: string) => Promise<Browser>;
+  timeoutMs?: number;
+  checkTimeoutMs?: number;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("browser-input-invalid", message, 400);
+
+const fieldsOf = (input: unknown): Readonly<Record<string, unknown>> => {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) throw invalid("Die Eingabe einer Browseroperation ist ein Objekt");
+  return input as Readonly<Record<string, unknown>>;
+};
+
+const textOf = (input: unknown, key: string): string => {
+  const value = fieldsOf(input)[key];
+  if (typeof value !== "string") throw invalid(`Die Browseroperation braucht ${key} als Text`);
+  return value;
+};
+
+const targetOf = (input: unknown): BrowserTarget => {
+  const value = fieldsOf(input).target;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalid("Die Browseroperation braucht ein Ziel");
+  return value as BrowserTarget;
+};
+
+const viewportOf = (input: unknown): BrowserViewport => {
+  const { width, height } = fieldsOf(input);
+  if (typeof width !== "number" || typeof height !== "number" || !Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw invalid("Ein Viewport braucht Breite und Höhe als positive ganze Zahlen");
+  }
+  return { width, height };
+};
+
+/** Der Browser eines Runs auf dieser Maschine: Seite, Aktionen, Prüfungen und Aufnahmen; Evidenz und Ablage hält der Aufrufer. */
+export const browserModule = (options: BrowserModuleOptions = {}): WorkspaceModuleFactory => (host) => {
+  const timeoutMs = options.timeoutMs ?? BROWSER_TIMEOUT_MS;
+  const pages = new BrowserPages({
+    launch: options.launch ?? (async (runId) => launchChromium((await host.contextFor(runId)).hostRoot, runId, timeoutMs)),
+    timeoutMs,
+    checkTimeoutMs: options.checkTimeoutMs ?? Math.min(5_000, timeoutMs),
+  });
+  return {
+    operations: {
+      [BROWSER_OPERATIONS.open]: ({ runId, input, signal }) =>
+        pages.open(runId, textOf(input, "url"), viewportOf(fieldsOf(input).viewport), signal),
+      [BROWSER_OPERATIONS.snapshot]: ({ runId, signal }) => pages.snapshot(runId, signal),
+      [BROWSER_OPERATIONS.viewport]: ({ runId, input, signal }) => pages.viewport(runId, viewportOf(input), signal),
+      [BROWSER_OPERATIONS.click]: ({ runId, input, signal }) => pages.click(runId, targetOf(input), signal),
+      [BROWSER_OPERATIONS.fill]: ({ runId, input, signal }) => pages.fill(runId, targetOf(input), textOf(input, "value"), signal),
+      [BROWSER_OPERATIONS.select]: ({ runId, input, signal }) => pages.select(runId, targetOf(input), textOf(input, "label"), signal),
+      [BROWSER_OPERATIONS.press]: ({ runId, input, signal }) => pages.press(runId, targetOf(input), textOf(input, "key"), signal),
+      [BROWSER_OPERATIONS.check]: ({ runId, input, signal }) => pages.check(runId, fieldsOf(input) as BrowserCheck, signal),
+      [BROWSER_OPERATIONS.screenshot]: ({ runId, input, signal }) =>
+        pages.screenshot(runId, textOf(input, "id"), fieldsOf(input).fullPage === true, signal),
+      [BROWSER_OPERATIONS.state]: async ({ runId }) => pages.state(runId),
+      [BROWSER_OPERATIONS.close]: async ({ runId }) => {
+        await pages.close(runId);
+        return null;
+      },
+    },
+    stopRun: (runId) => pages.close(runId),
+    shutdown: () => pages.shutdown(),
+  };
+};

package/packages/workspace-executor/src/browser/pages.ts

@@ -0,0 +1,298 @@
+import type { Browser, Locator, Page } from "playwright-core";
+import type {
+  BrowserCheck,
+  BrowserCheckResult,
+  BrowserPageState,
+  BrowserSnapshot,
+  BrowserStep,
+  BrowserTarget,
+  BrowserViewport,
+} from "./contract.js";
+
+interface BrowserSession {
+  readonly browser: Promise<Browser>;
+  readonly viewport: BrowserViewport;
+  page?: Page;
+  queue: Promise<void>;
+  closed: boolean;
+  checked: boolean;
+  errors: string[];
+  /** Adressen, deren fehlgeschlagene Anfrage schon gemeldet ist; HTTP-Status, Konsole und Netzwerk melden dieselbe Ursache nur einmal. */
+  failedRequests: Set<string>;
+  screenshots: string[];
+}
+
+export interface BrowserPagesOptions {
+  launch: (runId: string) => Promise<Browser>;
+  timeoutMs: number;
+  checkTimeoutMs: number;
+}
+
+const errorText = (error: unknown): string => error instanceof Error ? error.message : String(error);
+const endedError = (): Error => new Error("Der Browserdienst dieses Executors ist beendet.");
+const maxSnapshotLength = 40_000;
+const ambiguityHint = "Wähle mit nth (0-basiert) oder first: true im Ziel einen Treffer, oder prüfe die Anzahl mit count in browser_check.";
+
+const withAmbiguityHint = (error: unknown): never => {
+  if (error instanceof Error && error.message.includes("strict mode violation")) throw new Error(`${error.message}\n${ambiguityHint}`, { cause: error });
+  throw error;
+};
+
+export const browserLocator = (page: Page, target: BrowserTarget): Locator => {
+  const selectors = [target.role, target.label, target.text, target.testId, target.css].filter((value) => value !== undefined);
+  if (selectors.length !== 1 || (target.name !== undefined && target.role === undefined)) {
+    throw new Error("Ein Browserziel braucht genau role (optional name), label, text, testId oder css.");
+  }
+  if (target.nth !== undefined && target.first) throw new Error("Ein Browserziel verwendet entweder nth oder first, nicht beides.");
+  const root = target.frame ? page.frameLocator(target.frame) : page;
+  const base = target.role ? root.getByRole(target.role as Parameters<Page["getByRole"]>[0], { name: target.name, exact: true })
+    : target.label ? root.getByLabel(target.label, { exact: true })
+      : target.text ? root.getByText(target.text, { exact: true })
+        : target.testId ? root.getByTestId(target.testId)
+          : root.locator(target.css!);
+  return target.first ? base.first() : target.nth !== undefined ? base.nth(target.nth) : base;
+};
+
+/** Je Run ein Browser mit einer Seite auf dieser Maschine; die Aktionen eines Runs laufen der Reihe nach. */
+export class BrowserPages {
+  readonly #options: BrowserPagesOptions;
+  readonly #sessions = new Map<string, BrowserSession>();
+  #shutDown = false;
+
+  constructor(options: BrowserPagesOptions) {
+    this.#options = options;
+  }
+
+  async open(runId: string, url: string, viewport: BrowserViewport, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    if (this.#shutDown) throw endedError();
+    const parsed = new URL(url);
+    if (!["http:", "https:"].includes(parsed.protocol)) throw new Error("browser_open braucht eine HTTP- oder HTTPS-Adresse.");
+    signal?.throwIfAborted();
+    if (!this.#sessions.has(runId)) this.#start(runId, viewport);
+    return this.#perform(runId, signal, async (session, page) => {
+      this.#resetEvidence(session);
+      const response = await page.goto(parsed.href, { waitUntil: "domcontentloaded" });
+      if (response && !response.ok()) throw new Error(`Browsernavigation fehlgeschlagen: HTTP ${response.status()} (${page.url()}).`);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  snapshot(runId: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, (session, page) => this.#snapshot(session, page));
+  }
+
+  viewport(runId: string, viewport: BrowserViewport, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      await page.setViewportSize(viewport);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  click(runId: string, target: BrowserTarget, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.click());
+  }
+
+  fill(runId: string, target: BrowserTarget, value: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.fill(value));
+  }
+
+  select(runId: string, target: BrowserTarget, label: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.selectOption({ label }));
+  }
+
+  press(runId: string, target: BrowserTarget, key: string, signal?: AbortSignal): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#action(runId, target, signal, (locator) => locator.press(key));
+  }
+
+  check(runId: string, input: BrowserCheck, signal?: AbortSignal): Promise<BrowserStep<BrowserCheckResult>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      session.checked = false;
+      if (!input.target && input.text === undefined && input.url === undefined && input.noErrors !== true) {
+        throw new Error("browser_check braucht mindestens target, text, url oder noErrors: true.");
+      }
+      if (input.count !== undefined && (!input.target || input.target.nth !== undefined || input.target.first)) {
+        throw new Error("count in browser_check braucht ein target ohne nth oder first und zählt dessen sichtbare Treffer.");
+      }
+      const timeout = this.#options.checkTimeoutMs;
+      const assertions: string[] = [];
+      if (input.target && input.count !== undefined) {
+        const visible = browserLocator(page, input.target).filter({ visible: true });
+        const found = await this.#waitForCount(visible, input.count, timeout);
+        if (found !== input.count) throw new Error(`Erwartet ${input.count} sichtbare Treffer, gefunden ${found}.`);
+        assertions.push(`${input.count} sichtbare Treffer`);
+      } else if (input.target) {
+        const locator = browserLocator(page, input.target);
+        await locator.waitFor({ state: "visible", timeout }).catch(withAmbiguityHint);
+        assertions.push("Ziel ist sichtbar");
+        if (input.text !== undefined) {
+          try { await locator.filter({ hasText: input.text }).waitFor({ state: "visible", timeout }); }
+          catch (error) { throw new Error(`Erwarteter Text fehlt im Ziel: ${input.text}`, { cause: error }); }
+          assertions.push(`Text im Ziel: ${input.text}`);
+        }
+      } else if (input.text !== undefined) {
+        await page.getByText(input.text, { exact: false }).first().waitFor({ state: "visible", timeout });
+        assertions.push(`Sichtbarer Text: ${input.text}`);
+      }
+      if (input.url !== undefined) {
+        await page.waitForURL(input.url, { timeout });
+        assertions.push(`Adresse: ${input.url}`);
+      }
+      if (input.noErrors !== false) {
+        if (session.errors.length > 0) throw new Error(`Browserfehler: ${session.errors.join("\n")}`);
+        assertions.push("Keine erfassten Browser- oder Netzwerkfehler seit der Navigation");
+      }
+      session.checked = true;
+      return { url: page.url(), assertions };
+    });
+  }
+
+  /** Nimmt die Seite als PNG auf und liefert es Base64-kodiert; `id` merkt sich die Seite als aktuelle Aufnahme. */
+  screenshot(runId: string, id: string, fullPage: boolean, signal?: AbortSignal): Promise<BrowserStep<string>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      const image = await page.screenshot({ fullPage, type: "png", timeout: this.#options.timeoutMs });
+      session.screenshots.push(id);
+      return image.toString("base64");
+    });
+  }
+
+  /** Der Stand der Seite, ohne auf laufende Aktionen zu warten; ohne offene Seite `null`. */
+  state(runId: string): BrowserPageState | null {
+    const session = this.#sessions.get(runId);
+    return session && !session.closed && session.page ? this.#stateOf(session, session.page) : null;
+  }
+
+  async close(runId: string): Promise<void> {
+    const session = this.#sessions.get(runId);
+    if (!session) return;
+    session.closed = true;
+    this.#sessions.delete(runId);
+    const browser = await session.browser.catch(() => undefined);
+    if (browser) await browser.close();
+    await session.queue;
+  }
+
+  /** Schließt jeden Browser; danach startet keiner mehr, weil niemand ihn schließen würde. */
+  async shutdown(): Promise<void> {
+    this.#shutDown = true;
+    const results = await Promise.allSettled([...this.#sessions.keys()].map((runId) => this.close(runId)));
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
+  }
+
+  #start(runId: string, viewport: BrowserViewport): void {
+    const session: BrowserSession = {
+      browser: this.#launch(runId),
+      viewport,
+      queue: Promise.resolve(),
+      closed: false,
+      checked: false,
+      errors: [],
+      failedRequests: new Set(),
+      screenshots: [],
+    };
+    this.#sessions.set(runId, session);
+    void session.browser.catch(() => {
+      session.closed = true;
+      if (this.#sessions.get(runId) === session) this.#sessions.delete(runId);
+    });
+  }
+
+  async #launch(runId: string): Promise<Browser> {
+    return this.#options.launch(runId);
+  }
+
+  async #waitForCount(locator: Locator, expected: number, timeout: number): Promise<number> {
+    const deadline = Date.now() + timeout;
+    let found = await locator.count();
+    while (found !== expected && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      found = await locator.count();
+    }
+    return found;
+  }
+
+  #resetEvidence(session: BrowserSession): void {
+    session.checked = false;
+    session.screenshots = [];
+    session.errors = [];
+    session.failedRequests = new Set();
+  }
+
+  async #page(session: BrowserSession): Promise<Page> {
+    if (session.closed) throw new Error("Der Browser wurde beendet.");
+    if (session.page) return session.page;
+    const browser = await session.browser;
+    if (session.closed) throw new Error("Der Browser wurde beendet.");
+    const context = await browser.newContext({ viewport: session.viewport });
+    context.setDefaultTimeout(this.#options.timeoutMs);
+    context.setDefaultNavigationTimeout(this.#options.timeoutMs);
+    const page = await context.newPage();
+    const addError = (text: string) => {
+      session.errors.push(text.slice(0, 2000));
+      if (session.errors.length > 100) session.errors.shift();
+    };
+    const addRequestError = (url: string, text: string) => {
+      if (session.failedRequests.has(url)) return;
+      session.failedRequests.add(url);
+      addError(text);
+    };
+    page.on("console", (message) => {
+      if (message.type() !== "error") return;
+      const source = message.text().startsWith("Failed to load resource") ? message.location().url : "";
+      if (source) addRequestError(source, `Konsole: ${message.text()} (${source})`);
+      else addError(`Konsole: ${message.text()}`);
+    });
+    page.on("pageerror", (error) => addError(`JavaScript: ${error.message}`));
+    page.on("requestfailed", (request) => addRequestError(request.url(), `Netzwerk: ${request.method()} ${request.url()} ${request.failure()?.errorText}`));
+    page.on("response", (response) => { if (response.status() >= 400) addRequestError(response.url(), `HTTP ${response.status()}: ${response.url()}`); });
+    page.on("framenavigated", (frame) => { if (frame === page.mainFrame()) this.#resetEvidence(session); });
+    page.on("popup", (popup) => {
+      addError(`Die Anwendung hat ein neues Fenster geöffnet: ${popup.url()}. Popups werden nicht bedient.`);
+      void popup.close().catch((error) => addError(`Fenster schließen: ${errorText(error)}`));
+    });
+    session.page = page;
+    return page;
+  }
+
+  #perform<T>(runId: string, signal: AbortSignal | undefined, action: (session: BrowserSession, page: Page) => Promise<T>): Promise<BrowserStep<T>> {
+    if (this.#shutDown) return Promise.reject(endedError());
+    const session = this.#sessions.get(runId);
+    if (!session || session.closed) return Promise.reject(new Error("Für diesen Run ist kein Browser offen. Zuerst browser_open aufrufen."));
+    const pending = session.queue.then(async () => {
+      signal?.throwIfAborted();
+      const abort = () => { void this.close(runId).catch((error) => console.error("Browserstopp fehlgeschlagen:", errorText(error))); };
+      signal?.addEventListener("abort", abort, { once: true });
+      try {
+        const page = await this.#page(session);
+        signal?.throwIfAborted();
+        const result = await action(session, page);
+        signal?.throwIfAborted();
+        if (session.closed) throw new Error("Der Browser wurde beendet.");
+        return { result, page: this.#stateOf(session, page) };
+      } finally {
+        signal?.removeEventListener("abort", abort);
+      }
+    });
+    session.queue = pending.then(() => undefined, () => undefined);
+    return pending;
+  }
+
+  #action(runId: string, target: BrowserTarget, signal: AbortSignal | undefined, action: (locator: Locator) => Promise<unknown>): Promise<BrowserStep<BrowserSnapshot>> {
+    return this.#perform(runId, signal, async (session, page) => {
+      session.checked = false;
+      session.screenshots = [];
+      await action(browserLocator(page, target)).catch(withAmbiguityHint);
+      return this.#snapshot(session, page);
+    });
+  }
+
+  #stateOf(session: BrowserSession, page: Page): BrowserPageState {
+    return { url: page.url(), checked: session.checked, errors: [...session.errors], screenshots: [...session.screenshots] };
+  }
+
+  async #snapshot(session: BrowserSession, page: Page): Promise<BrowserSnapshot> {
+    const snapshot = await page.locator("body").ariaSnapshot({ mode: "ai", timeout: this.#options.timeoutMs });
+    return { url: page.url(), title: await page.title(), snapshot: snapshot.slice(0, maxSnapshotLength),
+      truncated: snapshot.length > maxSnapshotLength, errors: [...session.errors] };
+  }
+}

package/packages/workspace-executor/src/browser/playwright.ts

@@ -0,0 +1,52 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { Browser } from "playwright-core";
+import { RUN_MARKER_ENV } from "../run-marker.js";
+import { safeProcessEnvironment } from "../safe-environment.js";
+import { BROWSER_EXECUTABLE_VARIABLE } from "./contract.js";
+
+type Playwright = typeof import("playwright-core");
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);
+
+/** playwright-core liegt in den node_modules des Hosts dieser Maschine und wird erst im Aufruf geladen, nie mit dem Executor. */
+export const hostPlaywright = (hostRoot: string | undefined): Playwright => {
+  if (!hostRoot) {
+    throw new Error("Für die Browserprüfung ist auf diesem Rechner kein Host bekannt, aus dem sich playwright-core auflösen "
+      + "ließe. Ein Arbeitsplatz bekommt ihn mit der ersten Verbindung zu einem verteilenden Server oder über die "
+      + "Einstellung ragents.hostPath");
+  }
+  const load = createRequire(path.join(hostRoot, "package.json"));
+  try {
+    return load("playwright-core") as Playwright;
+  } catch (cause) {
+    throw new Error(`playwright-core liegt nicht im Host ${hostRoot}: ${messageOf(cause)}`);
+  }
+};
+
+/** Der Chrome dieser Maschine: der aus ihrer Umgebung, sonst das Chromium, das die Provisionierung für playwright-core holt. */
+export const browserExecutable = async (playwright: Playwright, environment: NodeJS.ProcessEnv = process.env): Promise<string> => {
+  const configured = environment[BROWSER_EXECUTABLE_VARIABLE];
+  const candidate = configured ? configured : playwright.chromium.executablePath();
+  if (await access(candidate, constants.X_OK).then(() => true, () => false)) return candidate;
+  throw new Error((configured
+    ? `${BROWSER_EXECUTABLE_VARIABLE} nennt ${configured}; dort gibt es auf diesem Rechner keinen ausführbaren Browser. `
+    : `Auf diesem Rechner gibt es keinen ausführbaren Browser: ${BROWSER_EXECUTABLE_VARIABLE} ist nicht gesetzt und Chromium fehlt unter ${candidate}. `)
+    + "Ein Arbeitsplatz holt Chromium mit pnpm provision --workspace, ein Server mit pnpm provision <profil>; "
+    + `${BROWSER_EXECUTABLE_VARIABLE} nennt einen vorhandenen Chrome, auf einem Server in der Profilsektion ragents.browser, `
+    + "auf einem Arbeitsplatz in seiner Umgebung.");
+};
+
+/** Startet Chrome headless mit der Umgebung dieser Maschine und dem Marker des Runs, damit die Prozessanzeige ihn zuordnet. */
+export const launchChromium = async (hostRoot: string | undefined, runId: string, timeoutMs: number): Promise<Browser> => {
+  const playwright = hostPlaywright(hostRoot);
+  return playwright.chromium.launch({
+    executablePath: await browserExecutable(playwright),
+    headless: true,
+    timeout: timeoutMs,
+    env: { ...safeProcessEnvironment(process.env), HOME: homedir(), [RUN_MARKER_ENV]: runId },
+  });
+};