@schlenkr/ragents 0.1.0

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

@@ -0,0 +1,393 @@
+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 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;
+}
+
+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>;
+}
+
+export interface BrowserCheck {
+  target?: BrowserTarget;
+  text?: string;
+  url?: string;
+  count?: number;
+  noErrors?: boolean;
+}
+
+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;
+};
+
+export class RunBrowser implements BrowserRuntime {
+  readonly #options: BrowserOptions;
+  readonly #sessions = new Map<string, BrowserSession>();
+  readonly #lastScreenshots = new Map<string, string>();
+  readonly #captures = new Map<string, SavedCapture[]>();
+  readonly #captureLoads = new Map<string, Promise<void>>();
+  readonly #versions = new Map<string, number>();
+  #shutdown = false;
+
+  constructor(options: BrowserOptions) {
+    this.#options = options;
+  }
+
+  restore(runId: string): Promise<void> {
+    const loading = this.#captureLoads.get(runId);
+    if (loading) return loading;
+    const pending = this.#restore(runId).catch((error) => { this.#captureLoads.delete(runId); throw error; });
+    this.#captureLoads.set(runId, pending);
+    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;
+    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);
+    });
+  }
+
+  snapshot(runId: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
+    return this.#perform(runId, signal, (session, page) => this.#snapshot(session, page));
+  }
+
+  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);
+    });
+  }
+
+  click(runId: string, target: BrowserTarget, signal?: AbortSignal): Promise<BrowserSnapshot> {
+    return this.#action(runId, target, signal, (locator) => locator.click());
+  }
+
+  fill(runId: string, target: BrowserTarget, value: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
+    return this.#action(runId, target, signal, (locator) => locator.fill(value));
+  }
+
+  select(runId: string, target: BrowserTarget, label: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
+    return this.#action(runId, target, signal, (locator) => locator.selectOption({ label }));
+  }
+
+  press(runId: string, target: BrowserTarget, key: string, signal?: AbortSignal): Promise<BrowserSnapshot> {
+    return this.#action(runId, target, signal, (locator) => locator.press(key));
+  }
+
+  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 };
+    });
+  }
+
+  screenshot(runId: string, input: { label?: string; fullPage?: boolean }, signal?: AbortSignal): 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() };
+    });
+  }
+
+  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);
+  }
+
+  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: [] };
+    return {
+      ...(session.checkedAt ? { checkedAt: session.checkedAt } : {}),
+      ...(session.page ? { url: session.page.url() } : {}),
+      screenshots,
+      currentScreenshots: [...session.screenshots],
+      errors: [...session.errors],
+    };
+  }
+
+  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;
+  }
+
+  async delete(runId: string): Promise<void> {
+    await this.close(runId);
+    this.#lastScreenshots.delete(runId);
+    this.#captures.delete(runId);
+    this.#captureLoads.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();
+    this.#captures.clear();
+    this.#captureLoads.clear();
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected") throw failed.reason;
+  }
+
+  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 },
+    });
+  }
+
+  #captureUrl(runId: string, filename: string): string {
+    return `${documentsApiPrefix}/runs/${encodeURIComponent(runId)}/files/content?path=${encodeURIComponent(filename)}`;
+  }
+
+  async #restore(runId: string): Promise<void> {
+    const directory = await this.#options.filesFor(runId);
+    const manifest = path.join(directory, "browser", ".captures.json");
+    let content: string;
+    try { content = await readFile(manifest, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      this.#captures.set(runId, []);
+      return;
+    }
+    const captures: unknown = JSON.parse(content);
+    if (!Array.isArray(captures) || captures.some((entry) => !entry || typeof entry.name !== "string"
+      || typeof entry.path !== "string" || !/^browser\/[a-f0-9-]{36}\.png$/.test(entry.path))) {
+      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

@@ -0,0 +1,36 @@
+import { serviceToken } from "@aicontainer/ragents";
+
+export interface BrowserTarget {
+  role?: string;
+  name?: string;
+  label?: string;
+  text?: string;
+  testId?: string;
+  css?: string;
+  frame?: string;
+  nth?: number;
+  first?: boolean;
+}
+
+export interface BrowserEvidence {
+  checkedAt?: string;
+  url?: string;
+  screenshots: { name: string; url: string }[];
+  currentScreenshots: { name: string; url: string }[];
+  errors: string[];
+}
+
+export interface BrowserSnapshot {
+  url: string;
+  title: string;
+  snapshot: string;
+  truncated: boolean;
+  errors: string[];
+}
+
+export interface BrowserRuntime {
+  open: (runId: string, url: string, signal?: AbortSignal) => Promise<BrowserSnapshot>;
+  evidence: (runId: string) => BrowserEvidence;
+}
+
+export const browserRuntimeToken = serviceToken<BrowserRuntime>("ragents.browser.runtime");

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

@@ -0,0 +1,35 @@
+import type { RAgentsPlugin } from "@aicontainer/ragents";
+import { declaredEnvironment } from "@aicontainer/server/plugin-support/plugin-config.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { documentStoreToken } from "@aicontainer/server/ragents/document-store.js";
+import { RunBrowser } from "./browser.js";
+import { browserRuntimeToken } from "./contract.js";
+import { createBrowserFunctions, createBrowserImageContribution } from "./tools.js";
+
+export const browserConfigDescriptors = [{ key: "BROWSER_EXECUTABLE_PATH", source: "environment" }] as const;
+const env = declaredEnvironment(browserConfigDescriptors);
+
+const browserPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.browser" },
+  register: (host) => {
+    const documents = host.service(documentStoreToken);
+    const browser = new RunBrowser({
+      filesFor: (runId) => documents.directoryFor(runId),
+      executablePath: env.optional("BROWSER_EXECUTABLE_PATH"),
+    });
+    host.config(...browserConfigDescriptors);
+    host.provide(browserRuntimeToken, browser);
+    host.functions(...createBrowserFunctions(browser));
+    host.agentRuntime(createBrowserImageContribution(browser));
+    host.lifecycle({
+      id: "ragents.browser.lifecycle",
+      prepareSession: ({ runId }) => browser.restore(runId),
+      stopSession: ({ runId }) => browser.close(runId),
+      afterStopSession: ({ runId }) => browser.close(runId),
+      deleteSession: ({ runId }) => browser.delete(runId),
+      shutdown: () => browser.shutdown(),
+    });
+  },
+};
+
+export const plugin: PluginModule = { requires: ["ragents.documents"], create: () => browserPlugin };

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

@@ -0,0 +1,197 @@
+import { Type } from "typebox";
+import { defineRunFunction, type AgentContribution, type RunFunction } from "@aicontainer/ragents";
+import { alwaysAvailable } from "@aicontainer/server/plugin-support/tool-availability.js";
+import { RunBrowser } from "./browser.js";
+
+const targetSchema = Type.Object({
+  role: Type.Optional(Type.String({ minLength: 1, description: "Accessible role, e.g. button, textbox, link, combobox." })),
+  name: Type.Optional(Type.String({ description: "Exact accessible name for role." })),
+  label: Type.Optional(Type.String({ minLength: 1, description: "Exact form label." })),
+  text: Type.Optional(Type.String({ minLength: 1, description: "Exact visible text." })),
+  testId: Type.Optional(Type.String({ minLength: 1, description: "data-testid value." })),
+  css: Type.Optional(Type.String({ minLength: 1, description: "CSS selector for elements without useful accessible names." })),
+  frame: Type.Optional(Type.String({ minLength: 1, description: "CSS selector of an iframe containing the target." })),
+  nth: Type.Optional(Type.Integer({ minimum: 0, description: "0-based index among all matches when the target matches several elements; not together with first." })),
+  first: Type.Optional(Type.Boolean({ description: "Use the first match when the target matches several elements; not together with nth." })),
+}, { additionalProperties: false, description: "Use exactly one of role (with optional name), label, text, testId, css. Resolve semantic targets server-side; never copy snapshot element IDs. Ambiguous targets are errors naming the candidates unless nth or first selects one." });
+
+const snapshotSchema = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  snapshot: Type.String(),
+  truncated: Type.Boolean(),
+  errors: Type.Array(Type.String()),
+}, { additionalProperties: false });
+
+const emptySchema = Type.Object({}, { additionalProperties: false });
+const targetInputSchema = Type.Object({ target: targetSchema }, { additionalProperties: false });
+const screenshotDescription = "Capture the real browser page into this run's document library. The returned URL and Markdown display it to the user. Call browser_view_screenshot to inspect the latest capture as an image without copying a path.";
+
+export const createBrowserFunctions = (browser: RunBrowser): RunFunction[] => [
+  defineRunFunction({
+    name: "browser_open",
+    label: "Browser öffnen",
+    description: "Open an HTTP(S) page in this run's isolated headless browser. Returns its accessible structure and browser errors. Reuses the current run browser; other runs have separate cookies and processes.",
+    schema: Type.Object({ url: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.open(caller.runId, input.url, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_snapshot",
+    label: "Browser lesen",
+    description: "Read the current real page's accessible structure, title, URL and errors. Use role/name or labels for subsequent actions; snapshot reference IDs never need to be copied.",
+    schema: emptySchema,
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }) => ({ ...await browser.snapshot(caller.runId, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_click",
+    label: "Im Browser klicken",
+    description: "Click a uniquely identified visible element with Playwright auto-waiting. Returns the actual resulting page. Ambiguous or absent targets are errors.",
+    schema: targetInputSchema,
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.click(caller.runId, input.target, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_fill",
+    label: "Browserfeld ausfüllen",
+    description: "Fill an input or textarea by accessible label or another semantic target, firing the normal input events. Returns the resulting page.",
+    schema: Type.Object({ target: targetSchema, value: Type.String() }, { additionalProperties: false }),
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.fill(caller.runId, input.target, input.value, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_select",
+    label: "Im Browser auswählen",
+    description: "Choose an option by its visible label in a native select element. For custom dropdowns use browser_click on the trigger and the visible option.",
+    schema: Type.Object({ target: targetSchema, label: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.select(caller.runId, input.target, input.label, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_press",
+    label: "Browsertaste drücken",
+    description: "Focus a target and press a Playwright key or chord such as Enter, Escape, Tab or ControlOrMeta+A. Returns the resulting page.",
+    schema: Type.Object({ target: targetSchema, key: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    resultSchema: snapshotSchema,
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.press(caller.runId, input.target, input.key, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_check",
+    label: "Browserergebnis prüfen",
+    description: "Assert visible target/text, resulting URL and absence of browser errors. Fails on mismatch; records successful evidence for this page until the next action/navigation/error. Supply at least one assertion. Browser errors are checked by default. Visibility assertions wait at most 5 seconds, shorter than actions.",
+    schema: Type.Object({
+      target: Type.Optional(targetSchema),
+      text: Type.Optional(Type.String({ minLength: 1 })),
+      url: Type.Optional(Type.String({ minLength: 1 })),
+      count: Type.Optional(Type.Integer({ minimum: 0, description: "Expected number of visible matches of target instead of exactly one; 0 asserts absence. Requires target without nth or first." })),
+      noErrors: Type.Optional(Type.Boolean({ description: "true (default): the check also fails on any browser error collected since the last navigation. false: ignore browser errors and judge only the assertions; use this when the page has known noise such as 404s or third-party script errors that are not part of the check." })),
+    }, { additionalProperties: false }),
+    resultSchema: Type.Object({ checkedAt: Type.String(), url: Type.String(), assertions: Type.Array(Type.String()) }, { additionalProperties: false }),
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: ({ caller, signal }, _id, input) => browser.check(caller.runId, input, signal),
+  }),
+  defineRunFunction({
+    name: "browser_viewport",
+    label: "Browsergröße setzen",
+    description: "Resize the page viewport in CSS pixels, for example to check a narrow layout. The default is 1920 x 1080 (16:9) and screenshots use the viewport size at scale 1; the chosen size stays for the run until changed again. Returns the resulting page.",
+    schema: Type.Object({
+      width: Type.Integer({ minimum: 320, maximum: 3840 }),
+      height: Type.Integer({ minimum: 240, maximum: 2160 }),
+    }, { additionalProperties: false }),
+    resultSchema: snapshotSchema,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }, _id, input) => ({ ...await browser.viewport(caller.runId, input, signal) }),
+  }),
+  defineRunFunction({
+    name: "browser_screenshot",
+    label: "Browser aufnehmen",
+    description: screenshotDescription,
+    schema: Type.Object({ label: Type.Optional(Type.String({ maxLength: 200 })), fullPage: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+    resultSchema: Type.Object({
+      name: Type.String(),
+      path: Type.String(),
+      url: Type.String(),
+      markdown: Type.String(),
+      capturedAt: Type.String(),
+    }, { additionalProperties: false }),
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: ({ caller, signal }, _id, input) => browser.screenshot(caller.runId, input, signal),
+  }),
+  defineRunFunction({
+    name: "browser_view_screenshot",
+    label: "Browseraufnahme ansehen",
+    description: "View this run's latest screenshot as native image input without a path. Invoke this native tool directly to receive pixels; calling it through TypeScript only verifies image availability. Requires an image-capable model for native image input.",
+    nativeTool: true,
+    schema: emptySchema,
+    resultSchema: Type.String(),
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller, signal }) => {
+      signal?.throwIfAborted();
+      await browser.image(caller.runId);
+      return "Letzte Browseraufnahme dieses Runs ist verfügbar.";
+    },
+  }),
+  defineRunFunction({
+    name: "browser_close",
+    label: "Browser schließen",
+    description: "Close this run's browser and discard its cookies. Saved screenshots remain in the document library.",
+    schema: emptySchema,
+    resultSchema: Type.Object({ closed: Type.Boolean() }, { additionalProperties: false }),
+    nativeTool: true,
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async ({ caller }) => { await browser.close(caller.runId); return { closed: true }; },
+  }),
+];
+
+export const createBrowserImageContribution = (browser: RunBrowser): AgentContribution => {
+  return {
+    id: "ragents.browser.image",
+    tools: [],
+    resolve: ({ runId }) => [{
+      name: "ragents.browser.image",
+      factory: (agent) => {
+        agent.on("tool_result", async (event, context) => {
+          if (event.toolName !== "browser_view_screenshot" || event.isError) return;
+          try {
+            context.signal?.throwIfAborted();
+            if (!context.model?.input.includes("image")) throw new Error("Das gewählte Modell unterstützt keine Bilder. Screenshot über die Dokumente ansehen oder ein bildfähiges Modell wählen.");
+            const data = (await browser.image(runId)).toString("base64");
+            context.signal?.throwIfAborted();
+            return { content: [
+              { type: "text" as const, text: "Letzte Browseraufnahme dieses Runs." },
+              { type: "image" as const, data, mimeType: "image/png" },
+            ] };
+          } catch (error) {
+            return { content: [{ type: "text" as const, text: error instanceof Error ? error.message : String(error) }], isError: true };
+          }
+        });
+      },
+    }],
+  };
+};