@schlenkr/ragents 0.1.4 → 0.1.6

package/plugins/ragents.browser/provision.ts

@@ -1,18 +1,18 @@
 import { spawn } from "node:child_process";
 import { access, constants } from "node:fs/promises";
-import { createRequire } from "node:module";
 import path from "node:path";
 import { chromium } from "playwright-core";
+import { BROWSER_EXECUTABLE_VARIABLE } from "@ragents/workspace-executor";
 import {
+  hostPackageFolder,
   provisionGap,
   provisionReady,
   type PluginProvision,
-} from "@aicontainer/server/plugin-support/provision.js";
+} from "@ragents/host/plugin-support/provision.js";
 
 const executable = async (file: string): Promise<boolean> => access(file, constants.X_OK).then(() => true, () => false);
 
-const playwrightCli = (): string =>
-  path.join(path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json")), "cli.js");
+const playwrightCli = (): string => path.join(hostPackageFolder("playwright-core"), "cli.js");
 
 const install = (log: (line: string) => void): Promise<void> => new Promise((resolve, reject) => {
   const child = spawn(process.execPath, [playwrightCli(), "install", ...(process.platform === "linux" ? ["--with-deps"] : []), "chromium"], { stdio: ["ignore", "pipe", "pipe"] });
@@ -24,17 +24,18 @@ const install = (log: (line: string) => void): Promise<void> => new Promise((res
 // Playwright verwaltet seinen Browsercache selbst; der Werkzeugordner des Plugins bleibt leer.
 export const createBrowserProvision = (): PluginProvision => ({
   check: async () => {
-    const configured = process.env.BROWSER_EXECUTABLE_PATH;
+    const configured = process.env[BROWSER_EXECUTABLE_VARIABLE];
     if (configured) {
       return await executable(configured)
         ? provisionReady
-        : provisionGap("browser", `BROWSER_EXECUTABLE_PATH nennt ${configured}; dort gibt es keinen ausführbaren Browser`, false);
+        : provisionGap("browser", `${BROWSER_EXECUTABLE_VARIABLE} nennt ${configured}; dort gibt es keinen ausführbaren Browser`, false);
     }
     const bundled = chromium.executablePath();
     return await executable(bundled)
       ? provisionReady
-      : provisionGap("chromium", `Chromium fehlt unter ${bundled}; entweder BROWSER_EXECUTABLE_PATH in der Profilsektion ragents.browser `
-        + "auf einen vorhandenen Chrome setzen oder die Provisionierung den Browser laden lassen", true);
+      : provisionGap("chromium", `Chromium fehlt unter ${bundled}; entweder ${BROWSER_EXECUTABLE_VARIABLE} auf einen vorhandenen Chrome `
+        + "setzen (auf einem Server in der Profilsektion ragents.browser, auf einem Arbeitsplatz in seiner Umgebung) oder die "
+        + "Provisionierung den Browser laden lassen", true);
   },
   apply: async (_target, log) => {
     const state = await createBrowserProvision().check("");

package/plugins/ragents.browser/ragents-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "ragents.browser",
+  "exports": {
+    "server": ["server/contract"]
+  }
+}

package/plugins/ragents.browser/server/browser.ts

@@ -1,83 +1,51 @@
 import { randomUUID } from "node:crypto";
-import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { constants } from "node:fs";
-import { homedir } from "node:os";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { chromium, type Browser, type Locator, type Page } from "playwright-core";
-import { RUN_MARKER_ENV, safeProcessEnvironment } from "@aicontainer/workspace-executor";
-import { documentsApiPrefix } from "@aicontainer/plugins/ragents.documents/server/files-route.js";
-import type { BrowserEvidence, BrowserRuntime, BrowserSnapshot, BrowserTarget } from "./contract.js";
-
-export interface BrowserViewport {
-  width: number;
-  height: number;
-}
+import {
+  BROWSER_OPERATIONS,
+  type BrowserCheck,
+  type BrowserCheckResult,
+  type BrowserPageState,
+  type BrowserSnapshot,
+  type BrowserStep,
+  type BrowserTarget,
+  type BrowserViewport,
+} from "@ragents/workspace-executor";
+import type { SandboxServices } from "@ragents/host/plugin-support/workspace-sandbox-host.js";
+import { documentsApiPrefix } from "@ragents/plugins/ragents.documents/contract.js";
+import type { BrowserCallOptions, BrowserEvidence, BrowserRuntime } from "./contract.js";
 
 export const DEFAULT_VIEWPORT: BrowserViewport = { width: 1920, height: 1080 };
 
-interface BrowserSession {
-  browser: Promise<Browser>;
-  page?: Page;
-  viewport: BrowserViewport;
-  queue: Promise<void>;
-  closed: boolean;
-  errors: string[];
-  screenshots: { name: string; url: string }[];
-  checkedAt?: string;
-}
-
 interface SavedCapture {
   name: string;
   path: string;
 }
 
-export interface BrowserOptions {
-  filesFor: (runId: string) => Promise<string>;
-  executablePath?: string;
-  timeoutMs?: number;
-  checkTimeoutMs?: number;
-  launch?: (runId: string) => Promise<Browser>;
+/** Was der Server von der Seite eines Runs weiß: den zuletzt gemeldeten Stand und die Zeit der letzten bestandenen Prüfung. */
+interface ObservedPage {
+  url: string;
+  checkedAt?: string;
+  errors: string[];
+  screenshots: string[];
 }
 
-export interface BrowserCheck {
-  target?: BrowserTarget;
-  text?: string;
-  url?: string;
-  count?: number;
-  noErrors?: boolean;
+export interface BrowserOptions {
+  sandbox: Pick<SandboxServices, "execute">;
+  filesFor: (runId: string) => Promise<string>;
 }
 
-const errorText = (error: unknown): string => error instanceof Error ? error.message : String(error);
-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;
-};
+const capturePath = (id: string): string => `browser/${id}.png`;
 
+/** Die Browserprüfung eines Runs: die Seite lebt beim Executor des Runs, Evidenz, Aufnahmen und Viewport hält der Server. */
 export class RunBrowser implements BrowserRuntime {
   readonly #options: BrowserOptions;
-  readonly #sessions = new Map<string, BrowserSession>();
-  readonly #lastScreenshots = new Map<string, string>();
+  readonly #pages = new Map<string, ObservedPage>();
+  readonly #viewports = new Map<string, BrowserViewport>();
   readonly #captures = new Map<string, SavedCapture[]>();
   readonly #captureLoads = new Map<string, Promise<void>>();
-  readonly #versions = new Map<string, number>();
+  readonly #captureWrites = new Map<string, Promise<void>>();
+  readonly #generations = new Map<string, number>();
   #shutdown = false;
 
   constructor(options: BrowserOptions) {
@@ -92,198 +60,194 @@ export class RunBrowser implements BrowserRuntime {
     return pending;
   }
 
-  async open(runId: string, url: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    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.#shutdown) throw new Error("Der Browserdienst ist beendet.");
-    const version = this.#versions.get(runId) ?? 0;
+  async open(runId: string, url: string, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    options.signal?.throwIfAborted();
+    this.#assertRunning();
+    const generation = this.#generation(runId);
     await this.restore(runId);
-    signal?.throwIfAborted();
-    if (this.#shutdown) throw new Error("Der Browserdienst ist beendet.");
-    if (version !== (this.#versions.get(runId) ?? 0)) throw new Error("Der Browser wurde beendet.");
-    if (!this.#sessions.has(runId)) {
-      const session: BrowserSession = {
-        browser: this.#launch(runId),
-        queue: Promise.resolve(),
-        closed: false,
-        errors: [],
-        screenshots: [],
-        viewport: DEFAULT_VIEWPORT,
-      };
-      this.#sessions.set(runId, session);
-      void session.browser.catch(() => {
-        session.closed = true;
-        if (this.#sessions.get(runId) === session) this.#sessions.delete(runId);
-      });
-    }
-    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);
-    });
+    options.signal?.throwIfAborted();
+    this.#assertRunning();
+    if (generation !== this.#generation(runId)) throw new Error("Der Browser wurde beendet.");
+    return this.#run(runId, BROWSER_OPERATIONS.open, { url, viewport: this.#viewports.get(runId) ?? DEFAULT_VIEWPORT }, options);
   }
 
-  snapshot(runId: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#perform(runId, signal, (session, page) => this.#snapshot(session, page));
+  snapshot(runId: string, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    return this.#run(runId, BROWSER_OPERATIONS.snapshot, null, options);
   }
 
-  viewport(runId: string, viewport: BrowserViewport, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#perform(runId, signal, async (session, page) => {
-      session.viewport = viewport;
-      await page.setViewportSize(viewport);
-      return this.#snapshot(session, page);
-    });
+  /** Der gewählte Viewport gilt für den Run, auch für einen später neu gestarteten Browser. */
+  async viewport(runId: string, viewport: BrowserViewport, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    const snapshot = await this.#run<BrowserSnapshot>(runId, BROWSER_OPERATIONS.viewport, viewport, options);
+    this.#viewports.set(runId, viewport);
+    return snapshot;
   }
 
-  click(runId: string, target: BrowserTarget, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#action(runId, target, signal, (locator) => locator.click());
+  click(runId: string, target: BrowserTarget, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    return this.#run(runId, BROWSER_OPERATIONS.click, { target }, options);
   }
 
-  fill(runId: string, target: BrowserTarget, value: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#action(runId, target, signal, (locator) => locator.fill(value));
+  fill(runId: string, target: BrowserTarget, value: string, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    return this.#run(runId, BROWSER_OPERATIONS.fill, { target, value }, options);
   }
 
-  select(runId: string, target: BrowserTarget, label: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#action(runId, target, signal, (locator) => locator.selectOption({ label }));
+  select(runId: string, target: BrowserTarget, label: string, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    return this.#run(runId, BROWSER_OPERATIONS.select, { target, label }, options);
   }
 
-  press(runId: string, target: BrowserTarget, key: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
-    return this.#action(runId, target, signal, (locator) => locator.press(key));
+  press(runId: string, target: BrowserTarget, key: string, options: BrowserCallOptions = {}): Promise<BrowserSnapshot> {
+    return this.#run(runId, BROWSER_OPERATIONS.press, { target, key }, options);
   }
 
-  check(runId: string, input: BrowserCheck, signal?: AbortSignal): Promise<{ checkedAt: string; url: string; assertions: string[] }> {
-    return this.#perform(runId, signal, async (session, page) => {
-      session.checkedAt = undefined;
-      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.#checkTimeout();
-      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");
-      }
-      const checkedAt = new Date().toISOString();
-      session.checkedAt = checkedAt;
-      return { checkedAt, url: page.url(), assertions };
-    });
+  /** Die Zeit einer bestandenen Prüfung ist die des Servers, damit sie sich mit seinen übrigen Zeiten vergleichen lässt. */
+  async check(runId: string, input: BrowserCheck, options: BrowserCallOptions = {}): Promise<{ checkedAt: string; url: string; assertions: string[] }> {
+    const generation = this.#generation(runId);
+    const { result, page } = await this.#execute<BrowserCheckResult>(runId, generation, BROWSER_OPERATIONS.check, input, options);
+    const checkedAt = new Date().toISOString();
+    this.#observe(runId, generation, page, checkedAt);
+    return { checkedAt, url: result.url, assertions: result.assertions };
   }
 
-  screenshot(runId: string, input: { label?: string; fullPage?: boolean }, signal?: AbortSignal): Promise<{
+  async screenshot(runId: string, input: { label?: string; fullPage?: boolean }, options: BrowserCallOptions = {}): Promise<{
     name: string;
     path: string;
     url: string;
     markdown: string;
     capturedAt: string;
   }> {
-    return this.#perform(runId, signal, async (session, page) => {
-      const directory = await this.#options.filesFor(runId);
-      const filename = `browser/${randomUUID()}.png`;
-      const absolute = path.join(directory, filename);
-      await mkdir(path.dirname(absolute), { recursive: true });
-      await page.screenshot({ path: absolute, fullPage: input.fullPage ?? false, type: "png", timeout: this.#timeout() });
-      const name = input.label?.trim() || "Browseraufnahme";
-      const url = this.#captureUrl(runId, filename);
-      const captures = [...this.#captures.get(runId) ?? [], { name, path: filename }];
-      const manifest = path.join(directory, "browser", ".captures.json");
-      const temporary = `${manifest}.${randomUUID()}.tmp`;
-      await writeFile(temporary, JSON.stringify(captures), "utf8");
-      await rename(temporary, manifest);
-      this.#captures.set(runId, captures);
-      this.#lastScreenshots.set(runId, absolute);
-      session.screenshots.push({ name, url });
-      return { name, path: filename, url, markdown: `![${name.replace(/[\[\]\\]/g, "")}](${url})`, capturedAt: new Date().toISOString() };
-    });
+    await this.restore(runId);
+    const id = randomUUID();
+    const image = await this.#run<string>(runId, BROWSER_OPERATIONS.screenshot, { id, fullPage: input.fullPage ?? false }, options);
+    const capture = { name: input.label?.trim() || "Browseraufnahme", path: capturePath(id) };
+    await this.#store(runId, capture, Buffer.from(image, "base64"));
+    const url = this.#captureUrl(runId, capture.path);
+    return {
+      ...capture,
+      url,
+      markdown: `![${capture.name.replace(/[\[\]\\]/g, "")}](${url})`,
+      capturedAt: new Date().toISOString(),
+    };
   }
 
   async image(runId: string): Promise<Buffer> {
-    const filename = this.#lastScreenshots.get(runId);
-    if (!filename) throw new Error("Für diesen Run gibt es noch keinen Browser-Screenshot. Zuerst browser_screenshot aufrufen.");
-    return readFile(filename);
+    const latest = this.#captures.get(runId)?.at(-1);
+    if (!latest) throw new Error("Für diesen Run gibt es noch keinen Browser-Screenshot. Zuerst browser_screenshot aufrufen.");
+    return readFile(path.join(await this.#options.filesFor(runId), latest.path));
   }
 
   evidence(runId: string): BrowserEvidence {
-    const session = this.#sessions.get(runId);
-    const screenshots = (this.#captures.get(runId) ?? []).map((entry) => ({ name: entry.name, url: this.#captureUrl(runId, entry.path) }));
-    if (!session || session.closed) return { screenshots, currentScreenshots: [], errors: [] };
+    const captures = this.#captures.get(runId) ?? [];
+    const shown = (capture: SavedCapture) => ({ name: capture.name, url: this.#captureUrl(runId, capture.path) });
+    const screenshots = captures.map(shown);
+    const page = this.#pages.get(runId);
+    if (!page) return { screenshots, currentScreenshots: [], errors: [] };
+    const current = page.screenshots
+      .map((id) => captures.find((capture) => capture.path === capturePath(id)))
+      .filter((capture): capture is SavedCapture => capture !== undefined);
     return {
-      ...(session.checkedAt ? { checkedAt: session.checkedAt } : {}),
-      ...(session.page ? { url: session.page.url() } : {}),
+      ...(page.checkedAt ? { checkedAt: page.checkedAt } : {}),
+      url: page.url,
       screenshots,
-      currentScreenshots: [...session.screenshots],
-      errors: [...session.errors],
+      currentScreenshots: current.map(shown),
+      errors: [...page.errors],
     };
   }
 
+  /** Schließt den Browser beim Executor des Runs; ein nicht verbundener Arbeitsplatz hält nichts, was sich jetzt schließen ließe. */
   async close(runId: string): Promise<void> {
-    this.#versions.set(runId, (this.#versions.get(runId) ?? 0) + 1);
-    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;
+    this.#forget(runId);
+    await this.#options.sandbox.execute(runId, BROWSER_OPERATIONS.close, null, { whenReachable: true });
   }
 
   async delete(runId: string): Promise<void> {
     await this.close(runId);
-    this.#lastScreenshots.delete(runId);
+    this.#viewports.delete(runId);
     this.#captures.delete(runId);
     this.#captureLoads.delete(runId);
+    this.#captureWrites.delete(runId);
   }
 
   async shutdown(): Promise<void> {
     this.#shutdown = true;
-    const results = await Promise.allSettled([...this.#sessions.keys()].map((runId) => this.delete(runId)));
-    this.#lastScreenshots.clear();
+    const results = await Promise.allSettled([...this.#pages.keys()].map((runId) => this.close(runId)));
+    this.#viewports.clear();
     this.#captures.clear();
     this.#captureLoads.clear();
-    const failed = results.find((result) => result.status === "rejected");
-    if (failed?.status === "rejected") throw failed.reason;
+    this.#captureWrites.clear();
+    const failed = results.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) throw failed.reason;
+  }
+
+  #assertRunning(): void {
+    if (this.#shutdown) throw new Error("Der Browserdienst ist beendet.");
+  }
+
+  #generation(runId: string): number {
+    return this.#generations.get(runId) ?? 0;
+  }
+
+  /** Ein geschlossener Browser hat keine Seite mehr; Ergebnisse, die vorher begonnen haben, zählen danach nicht. */
+  #forget(runId: string): void {
+    this.#generations.set(runId, this.#generation(runId) + 1);
+    this.#pages.delete(runId);
+  }
+
+  async #run<T>(runId: string, operation: string, input: unknown, options: BrowserCallOptions): Promise<T> {
+    const generation = this.#generation(runId);
+    const { result, page } = await this.#execute<T>(runId, generation, operation, input, options);
+    this.#observe(runId, generation, page);
+    return result;
+  }
+
+  async #execute<T>(runId: string, generation: number, operation: string, input: unknown, options: BrowserCallOptions): Promise<BrowserStep<T>> {
+    try {
+      return await this.#options.sandbox.execute(runId, operation, input, options) as BrowserStep<T>;
+    } catch (error) {
+      await this.#resync(runId, generation);
+      throw error;
+    }
+  }
+
+  /** Nach einem gescheiterten Aufruf fragt der Server den Stand der Seite nach; wer ihn nicht nennen kann, hat keine Seite. */
+  async #resync(runId: string, generation: number): Promise<void> {
+    const page = await this.#options.sandbox.execute(runId, BROWSER_OPERATIONS.state, null, { whenReachable: true })
+      .then((value) => value as BrowserPageState | null, () => null);
+    this.#observe(runId, generation, page);
   }
 
-  async #launch(runId: string): Promise<Browser> {
-    if (this.#options.launch) return this.#options.launch(runId);
-    const executablePath = this.#options.executablePath ?? chromium.executablePath();
-    try { await access(executablePath, constants.X_OK); }
-    catch { throw new Error("Kein ausführbarer Browser vorhanden. BROWSER_EXECUTABLE_PATH in ragents.browser konfigurieren "
-      + "(z.B. Google Chrome) oder im Repo pnpm exec playwright-core install chromium ausführen."); }
-    return chromium.launch({
-      executablePath,
-      headless: true,
-      timeout: this.#timeout(),
-      env: { ...safeProcessEnvironment(process.env), HOME: homedir(), [RUN_MARKER_ENV]: runId },
+  /** Nur eine bestandene Prüfung setzt die Zeit; jeder andere Stand behält sie, solange die Seite geprüft bleibt. */
+  #observe(runId: string, generation: number, page: BrowserPageState | null, checkedAt?: string): void {
+    if (generation !== this.#generation(runId)) return;
+    if (!page) {
+      this.#pages.delete(runId);
+      return;
+    }
+    const stamp = page.checked ? checkedAt ?? this.#pages.get(runId)?.checkedAt : undefined;
+    this.#pages.set(runId, {
+      url: page.url,
+      errors: page.errors,
+      screenshots: page.screenshots,
+      ...(stamp ? { checkedAt: stamp } : {}),
     });
   }
 
+  /** Legt eine Aufnahme in die Dateiablage des Runs und schreibt die Aufnahmeliste atomar; die Aufnahmen eines Runs der Reihe nach. */
+  #store(runId: string, capture: SavedCapture, image: Buffer): Promise<void> {
+    const previous = this.#captureWrites.get(runId) ?? Promise.resolve();
+    const pending = previous.then(async () => {
+      const directory = await this.#options.filesFor(runId);
+      await mkdir(path.join(directory, "browser"), { recursive: true });
+      await writeFile(path.join(directory, capture.path), image);
+      const captures = [...this.#captures.get(runId) ?? [], capture];
+      const manifest = path.join(directory, "browser", ".captures.json");
+      const temporary = `${manifest}.${randomUUID()}.tmp`;
+      await writeFile(temporary, JSON.stringify(captures), "utf8");
+      await rename(temporary, manifest);
+      this.#captures.set(runId, captures);
+    });
+    this.#captureWrites.set(runId, pending.then(() => undefined, () => undefined));
+    return pending;
+  }
+
   #captureUrl(runId: string, filename: string): string {
     return `${documentsApiPrefix}/runs/${encodeURIComponent(runId)}/files/content?path=${encodeURIComponent(filename)}`;
   }
@@ -304,90 +268,5 @@ export class RunBrowser implements BrowserRuntime {
       throw new Error("Die gespeicherte Browser-Aufnahmeliste dieses Runs ist beschädigt.");
     }
     this.#captures.set(runId, captures);
-    const latest = captures.at(-1) as SavedCapture | undefined;
-    if (latest) this.#lastScreenshots.set(runId, path.join(directory, latest.path));
-  }
-
-  #timeout(): number { return this.#options.timeoutMs ?? 15_000; }
-
-  #checkTimeout(): number { return this.#options.checkTimeoutMs ?? Math.min(5_000, this.#timeout()); }
-
-  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.checkedAt = undefined;
-    session.screenshots = [];
-    session.errors = [];
-  }
-
-  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.#timeout());
-    context.setDefaultNavigationTimeout(this.#timeout());
-    const page = await context.newPage();
-    const addError = (text: string) => {
-      session.errors.push(text.slice(0, 2000));
-      if (session.errors.length > 100) session.errors.shift();
-    };
-    page.on("console", (message) => { if (message.type() === "error") addError(`Konsole: ${message.text()}`); });
-    page.on("pageerror", (error) => addError(`JavaScript: ${error.message}`));
-    page.on("requestfailed", (request) => addError(`Netzwerk: ${request.method()} ${request.url()} ${request.failure()?.errorText}`));
-    page.on("response", (response) => { if (response.status() >= 400) addError(`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<T> {
-    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;
-      } 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<BrowserSnapshot> {
-    return this.#perform(runId, signal, async (session, page) => {
-      session.checkedAt = undefined;
-      session.screenshots = [];
-      await action(browserLocator(page, target)).catch(withAmbiguityHint);
-      return this.#snapshot(session, page);
-    });
-  }
-
-  async #snapshot(session: BrowserSession, page: Page): Promise<BrowserSnapshot> {
-    const snapshot = await page.locator("body").ariaSnapshot({ mode: "ai", timeout: this.#timeout() });
-    return { url: page.url(), title: await page.title(), snapshot: snapshot.slice(0, maxSnapshotLength),
-      truncated: snapshot.length > maxSnapshotLength, errors: [...session.errors] };
   }
 }

package/plugins/ragents.browser/server/contract.ts

@@ -1,16 +1,7 @@
-import { serviceToken } from "@aicontainer/ragents";
+import { serviceToken } from "@ragents/engine";
+import type { BrowserSnapshot } from "@ragents/workspace-executor";
 
-export interface BrowserTarget {
-  role?: string;
-  name?: string;
-  label?: string;
-  text?: string;
-  testId?: string;
-  css?: string;
-  frame?: string;
-  nth?: number;
-  first?: boolean;
-}
+export type { BrowserSnapshot, BrowserTarget } from "@ragents/workspace-executor";
 
 export interface BrowserEvidence {
   checkedAt?: string;
@@ -20,16 +11,14 @@ export interface BrowserEvidence {
   errors: string[];
 }
 
-export interface BrowserSnapshot {
-  url: string;
-  title: string;
-  snapshot: string;
-  truncated: boolean;
-  errors: string[];
+/** Wer eine Operation an der Seite auslöst: bei einem Werkzeugaufruf dessen Kennung, dazu der Abbruch. */
+export interface BrowserCallOptions {
+  signal?: AbortSignal;
+  toolCallId?: string;
 }
 
 export interface BrowserRuntime {
-  open: (runId: string, url: string, signal?: AbortSignal) => Promise<BrowserSnapshot>;
+  open: (runId: string, url: string, options?: BrowserCallOptions) => Promise<BrowserSnapshot>;
   evidence: (runId: string) => BrowserEvidence;
 }