@schlenkr/ragents 0.1.0

package/plugins/ragents.browser/skills/browser-testing/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: browser-testing
+description: Prüfe eine laufende Webanwendung mit echten Browseraktionen, sichtbaren Ergebnissen und Screenshots.
+---
+
+# Webanwendung prüfen
+
+Verwende die TypeScript-Funktionen `browser_open`, `browser_snapshot`, `browser_click`,
+`browser_fill`, `browser_select`, `browser_press`, `browser_check`, `browser_viewport`,
+`browser_screenshot` und `browser_close`. Lade deren genaue Verträge mit `typescript_api`.
+
+1. Starte die Anwendung mit ihren tatsächlichen Diensten und warte auf deren Bereitschaft.
+2. Öffne ihre HTTP-Adresse mit `browser_open`. Jeder Run hat einen eigenen Browser ohne
+   übernommene Anmeldung. Melde fehlende Dienste und Browser-Voraussetzungen ausdrücklich.
+3. Lies den Snapshot und bediene den tatsächlichen Nutzerweg. Wähle Ziele über sichtbare
+   Rollen/Namen oder Feldbeschriftungen, beispielsweise `{ role: "button", name: "Speichern" }`.
+   Die Auflösung erfolgt im Browser. Snapshot-IDs werden nicht abgeschrieben.
+4. Prüfe Erfolg und relevante Fehlerfälle mit `browser_check`: sichtbares Ergebnis, Zieladresse
+   und Browserfehler. Ein Typecheck oder Screenshot allein belegt keinen erfolgreichen Nutzerweg.
+   Nach jeder Aktion ist eine neue Prüfung nötig. Erfinde keine Ergebnisse bei fehlendem Netz.
+5. Erzeuge mit `browser_screenshot` echte Aufnahmen. Übernimm `url` oder `markdown`
+   programmatisch in den Ergebnisbericht oder die Mini-App. Das Bild liegt in der Dateiablage
+   dieses Runs. Das native Werkzeug `browser_view_screenshot` zeigt Dir die letzte Aufnahme
+   ohne Pfadangabe; dafür benötigt Dein Modell Bildunterstützung. Der Viewport ist standardmäßig
+   1920 x 1080 (16:9); für schmale Layouts oder kleine Bildschirme stellst Du ihn mit
+   `browser_viewport` um und prüfst danach erneut.
+6. Benenne geprüfte Schritte und verbleibende Grenzen. Schließe den Browser nach Abschluss;
+   Aufnahmen bleiben erhalten. Run-Stopp und Serverende schließen ihn ebenfalls.
+
+Die Browseraktionen verwenden Playwright-Locators mit automatischem Warten. Mehrdeutige Ziele
+sind Fehler, die die Kandidaten nennen; wähle dann mit `nth` (0-basiert) oder `first: true` im
+Ziel einen Treffer, oder prüfe die Anzahl sichtbarer Treffer mit `count` in `browser_check`.
+Sichtbarkeitsprüfungen warten höchstens 5 Sekunden, Aktionen länger; ein fehlendes Element
+kostet also keine lange Wartezeit. Native Selects verwenden `browser_select`; eigene Auswahlmenüs werden geklickt.
+Mit `target.frame` wählst Du ein Iframe per CSS. Neue Fenster werden ausdrücklich gemeldet;
+dieser Ablauf bedient eine Seite. Verdeckte Elemente werden nicht per JavaScript angeklickt.

package/plugins/ragents.documents/contract.ts

@@ -0,0 +1,33 @@
+import { Type, type Static } from "typebox";
+import { defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+
+const fileEntry = Type.Object({
+  path: Type.String({ minLength: 1 }),
+  size: Type.Integer({ minimum: 0 }),
+  modifiedAt: Type.String({ minLength: 1 }),
+}, { additionalProperties: false });
+
+const filesListing = Type.Object({
+  groups: Type.Array(Type.Object({
+    directory: Type.String({ minLength: 1 }),
+    files: Type.Array(fileEntry),
+  }, { additionalProperties: false })),
+  loose: Type.Array(fileEntry),
+  truncated: Type.Boolean(),
+}, { additionalProperties: false });
+
+export type RunFileEntry = Static<typeof fileEntry>;
+
+export type RunFilesListing = Static<typeof filesListing>;
+
+export const documentsContracts = {
+  files: defineOperation({
+    id: "ragents.documents.files",
+    description: "Die Dateiablage eines Laufs als Gruppen und lose Dateien. Recht: runs.read.",
+    rights: ["runs.read"],
+    input: Type.Object({
+      runId: Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" }),
+    }, { additionalProperties: false }),
+    result: filesListing,
+  }),
+};

package/plugins/ragents.documents/prompt.hbs

@@ -0,0 +1,18 @@
+# File store and documents
+
+This run has a file store outside the working directory. It is not a path in bash; the only way
+to put something there is the tool `document_write`.
+
+- Create one subdirectory per topic: `<topic>/<file>`.
+- Put documents, reports and temporary products there - NOT into the working directory, unless
+  they are part of the actual assignment.
+- `document_write` takes the full `content` of the file. For a file of the working directory,
+  `read` it first and pass the content here.
+- The user sees these files in the "Dokumente" area of the interface, grouped by subdirectory.
+- When you spawn agents, name in their assignment the store path they are supposed to write to.
+
+If the user wants to see the content of a file or a document, show it COMPLETELY via
+`show_document` (title = file name or document name) - never paraphrase or shorten. Files of the
+file store you show via `path`, relative to the store. Everything else - files from your working
+directory and content you produced yourself - you pass via `content`; `path` finds nothing outside
+the file store.

package/plugins/ragents.documents/server/config.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { declaredEnvironment } from "@aicontainer/server/plugin-support/plugin-config.js";
+
+export const ragentsDocumentsConfigDescriptors = [
+  { key: "DOCUMENTS_DIR", source: "environment" },
+] as const;
+
+const env = declaredEnvironment(ragentsDocumentsConfigDescriptors);
+
+const externalRoot = env.optional("DOCUMENTS_DIR");
+
+export const ragentsDocumentsConfig = Object.freeze({
+  externalRoot: externalRoot ? path.resolve(externalRoot) : undefined,
+});

package/plugins/ragents.documents/server/document-write-tool.ts

@@ -0,0 +1,45 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Type } from "typebox";
+import { defineRunFunction, type RunFunction } from "@aicontainer/ragents";
+import { alwaysAvailable } from "@aicontainer/server/plugin-support/tool-availability.js";
+
+export const documentWriteToolMetadata = {
+  name: "document_write",
+  label: "Dokument ablegen",
+  nativeTool: true,
+  description: "Legt eine Datei mit dem übergebenen Inhalt in der Dateiablage dieses Runs ab.",
+  longDescription: "Dokumente, Berichte und Zwischenprodukte gehören in die Dateiablage, nicht ins "
+    + "Arbeitsverzeichnis - dort steht nur, was zum Auftrag selbst gehört. Der Benutzer sieht die "
+    + "Ablage im Bereich \"Dokumente\", nach Unterordnern gruppiert. Soll eine Datei aus dem "
+    + "Arbeitsbereich in die Ablage, lies sie zuerst mit read und übergib den Inhalt hier als content. "
+    + "Die Ablage ist kein Bash-Pfad: sie liegt nicht im Arbeitsbereich und ist nur über dieses Werkzeug "
+    + "beschreibbar.",
+} as const;
+
+const relativeStorePath = (value: string): string => {
+  const normalized = value.replace(/^\.\//, "");
+  if (path.isAbsolute(normalized) || normalized.split("/").includes("..") || normalized.trim() === "") {
+    throw new Error("path muss relativ zur Dateiablage sein, ohne führenden / und ohne ..");
+  }
+  return normalized;
+};
+
+export const createDocumentWriteTool = (filesFor: (runId: string) => Promise<string>): RunFunction =>
+  defineRunFunction({
+    ...documentWriteToolMetadata,
+    schema: Type.Object({
+      path: Type.String({ minLength: 1, description: "Pfad in der Dateiablage, etwa thema/bericht.md" }),
+      content: Type.String({ description: "Der vollständige Inhalt der Datei" }),
+    }, { additionalProperties: false }),
+    resultSchema: Type.String(),
+    available: alwaysAvailable,
+    executionMode: "sequential",
+    run: async (scope, _toolCallId, input) => {
+      const relative = relativeStorePath(input.path);
+      const target = path.join(await filesFor(scope.caller.runId), relative);
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, input.content, "utf8");
+      return `In der Dateiablage abgelegt: ${relative} (${Buffer.byteLength(input.content, "utf8")} Byte)`;
+    },
+  });

package/plugins/ragents.documents/server/files-route.ts

@@ -0,0 +1,137 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { implement, type HttpRouteContribution, type MethodContribution } from "@aicontainer/ragents";
+import { guardedJsonRoute } from "@aicontainer/server/plugin-support/http.js";
+import { documentsContracts, type RunFileEntry, type RunFilesListing } from "../contract.js";
+
+export const documentsApiPrefix = "/api/plugins/ragents.documents";
+
+const contentPattern = /^\/api\/plugins\/ragents\.documents\/runs\/([A-Za-z0-9_-]{1,64})\/files\/content$/;
+
+const MAX_ENTRIES = 1000;
+
+const mediaTypes: Record<string, string> = {
+  ".md": "text/markdown; charset=utf-8",
+  ".markdown": "text/markdown; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".log": "text/plain; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+};
+
+const visibleEntries = async (directory: string) => {
+  const entries = await readdir(directory, { withFileTypes: true });
+  return entries
+    .filter((entry) => !entry.name.startsWith(".") && !entry.isSymbolicLink())
+    .sort((left, right) => left.name.localeCompare(right.name, "de"));
+};
+
+const collectFiles = async (
+  directory: string,
+  relative: string,
+  budget: { remaining: number },
+): Promise<RunFileEntry[]> => {
+  const files: RunFileEntry[] = [];
+  for (const entry of await visibleEntries(directory)) {
+    if (budget.remaining <= 0) break;
+    const absolute = path.join(directory, entry.name);
+    const entryPath = relative ? `${relative}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...await collectFiles(absolute, entryPath, budget));
+    } else if (entry.isFile()) {
+      const info = await lstat(absolute);
+      files.push({ path: entryPath, size: info.size, modifiedAt: info.mtime.toISOString() });
+      budget.remaining -= 1;
+    }
+  }
+  return files;
+};
+
+const listingOf = async (root: string): Promise<RunFilesListing> => {
+  const budget = { remaining: MAX_ENTRIES };
+  const groups: RunFilesListing["groups"] = [];
+  const loose: RunFileEntry[] = [];
+  for (const entry of await visibleEntries(root)) {
+    if (entry.name === "_apps") continue;
+    const absolute = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      const files = await collectFiles(absolute, "", budget);
+      if (files.length > 0) groups.push({ directory: entry.name, files });
+    } else if (entry.isFile() && budget.remaining > 0) {
+      const info = await lstat(absolute);
+      loose.push({ path: entry.name, size: info.size, modifiedAt: info.mtime.toISOString() });
+      budget.remaining -= 1;
+    }
+  }
+  return { groups, loose, truncated: budget.remaining <= 0 };
+};
+
+const resolveInside = async (root: string, relative: string): Promise<string> => {
+  if (!relative || relative.includes("\0") || relative.includes("\\") || path.isAbsolute(relative)
+    || relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    throw new Error("Ungültiger Dateipfad");
+  }
+  const rootReal = await realpath(root);
+  const real = await realpath(path.join(rootReal, relative));
+  if (real !== rootReal && !real.startsWith(rootReal + path.sep)) throw new Error("Ungültiger Dateipfad");
+  return real;
+};
+
+export const runFileExists = async (root: string, relative: string): Promise<boolean> => {
+  try {
+    return (await lstat(await resolveInside(root, relative))).isFile();
+  } catch {
+    return false;
+  }
+};
+
+export interface FilesRouteOptions {
+  filesFor: (runId: string) => Promise<string>;
+  ensureSession: (runId: string) => void;
+}
+
+export const createFilesMethod = (options: FilesRouteOptions): MethodContribution =>
+  implement(documentsContracts.files, async ({ runId }) => {
+    options.ensureSession(runId);
+    return listingOf(await options.filesFor(runId));
+  });
+
+/** Der Inhalt bleibt Auslieferung: ein GET mit dem Medientyp der Datei. */
+export const createFileContentRoute = (options: FilesRouteOptions): HttpRouteContribution => ({
+  id: "ragents.documents.files-content",
+  isApiPath: (pathname) => contentPattern.test(pathname),
+  matches: (request, url) => request.method === "GET" && contentPattern.test(url.pathname),
+  handle: async ({ response, request, url }) => {
+    const match = url.pathname.match(contentPattern);
+    if (!match) throw new Error("Ungültige Dokumente-Route");
+    const [, runId] = match;
+    await guardedJsonRoute({
+      response,
+      request,
+      ensureSession: () => options.ensureSession(runId),
+      errorStatus: 404,
+      handle: async () => {
+        const relative = url.searchParams.get("path") ?? "";
+        const file = await resolveInside(await options.filesFor(runId), relative);
+        const info = await lstat(file);
+        if (!info.isFile()) throw new Error("Ungültiger Dateipfad");
+        const content = await readFile(file);
+        response.writeHead(200, {
+          "Cache-Control": "no-store",
+          "Content-Type": mediaTypes[path.extname(relative).toLowerCase()] ?? "application/octet-stream",
+          "Content-Length": content.byteLength,
+        });
+        response.end(content);
+      },
+    });
+  },
+});

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

@@ -0,0 +1,38 @@
+import path from "node:path";
+import type { RAgentsPlugin } from "@aicontainer/ragents";
+import { createDocumentToolContributor } from "./tool-contributor.js";
+import { createFileContentRoute, createFilesMethod, documentsApiPrefix } from "./files-route.js";
+import { ragentsDocumentsConfig, ragentsDocumentsConfigDescriptors } from "./config.js";
+import { RunDocumentStore } from "./store.js";
+import { pluginAssetPath } from "@aicontainer/server/plugin-support/asset-path.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { boundToTools, handlebarsPrompt } from "@aicontainer/server/plugin-support/prompt.js";
+import { documentStoreToken } from "@aicontainer/server/ragents/document-store.js";
+import { sessionGuardToken } from "@aicontainer/server/ragents/host-services.js";
+
+const promptFile = pluginAssetPath(import.meta.url, "../prompt.hbs");
+
+const documentsPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.documents" },
+  register: (host) => {
+    const store = new RunDocumentStore({
+      sessionDirectory: (runId) => host.storage.session(runId, "documents"),
+      sessionsDirectoryPattern: path.join(host.storage.sessionsRoot, "{runId}", "plugins", host.manifest.id, "documents"),
+      externalRoot: ragentsDocumentsConfig.externalRoot,
+    });
+    const filesFor = (runId: string) => store.directoryFor(runId);
+    host.provide(documentStoreToken, store);
+    host.config(...ragentsDocumentsConfigDescriptors);
+    host.clientConfig({ routePrefix: documentsApiPrefix });
+    host.functions(createDocumentToolContributor(filesFor));
+    host.prompts(boundToTools({ ...handlebarsPrompt("ragents.documents.prompt", 400, promptFile), delivery: "initial" }, "document_write"));
+    const files = { filesFor, ensureSession: host.service(sessionGuardToken) };
+    host.methods(createFilesMethod(files));
+    host.http(createFileContentRoute(files));
+  },
+};
+
+export const plugin: PluginModule = {
+  requires: ["ragents.orchestration"],
+  create: () => documentsPlugin,
+};

package/plugins/ragents.documents/server/show-document-tool.ts

@@ -0,0 +1,73 @@
+import { Type } from "typebox";
+import { defineRunFunction, type RunFunction } from "@aicontainer/ragents";
+import { runFileExists } from "./files-route.js";
+import { facesOperator } from "@aicontainer/server/plugin-support/tool-availability.js";
+
+export const showDocumentToolMetadata = {
+  name: "show_document",
+  label: "Dokument anzeigen",
+  nativeTool: true,
+  description: "Zeigt Dokumente vollständig in der Oberfläche; Dateipfade gelten nur für die Dateiablage dieses Runs.",
+  longDescription: "Nutze dieses Werkzeug IMMER, wenn der Benutzer den "
+    + "Inhalt einer Datei oder ein längeres Dokument sehen möchte - statt den Inhalt in die "
+    + "Chat-Antwort zu kopieren oder zu paraphrasieren. path zeigt ausschließlich eine Datei aus "
+    + "der Dateiablage dieses Runs an, NICHT aus deinem Arbeitsverzeichnis. "
+    + "Alles andere - Dateien des Arbeitsverzeichnisses und selbst erzeugte Inhalte - geht über "
+    + "content; stammt der Inhalt aus einer Datei, übernimm ihn dort WÖRTLICH aus dem letzten "
+    + "read- oder write-Ergebnis, niemals aus dem Gedächtnis neu getippt.",
+} as const;
+
+const sourceRule = "content und path schließen einander aus: gültig sind { title, content, format } für "
+  + "selbst erzeugte Inhalte und Dateien des Arbeitsverzeichnisses und { title, path, format } für Dateien "
+  + "der Dateiablage - genau eines von beiden muss gesetzt sein.";
+
+const titleSchema = Type.String({ description: "Titel der Anzeige, z.B. der Dateiname" });
+const formatSchema = Type.Optional(Type.Union(
+  [Type.Literal("markdown"), Type.Literal("text"), Type.Literal("html")],
+  { description: "Darstellung, Default markdown" }));
+
+const documentSource = (input: { content?: string; path?: string }):
+  | { kind: "content" }
+  | { kind: "file"; path: string } => {
+  if ((input.content === undefined) === (input.path === undefined)) throw new Error(sourceRule);
+
+  return input.path === undefined ? { kind: "content" } : { kind: "file", path: input.path };
+};
+
+export const createShowDocumentTool = (filesFor: (runId: string) => Promise<string>): RunFunction =>
+  defineRunFunction({
+    ...showDocumentToolMetadata,
+    schema: Type.Object({
+      title: titleSchema,
+      content: Type.Optional(Type.String({
+        description: "Der vollständige Inhalt - für Dateien aus dem Arbeitsverzeichnis und für "
+          + "selbst erzeugte Inhalte, also alles, was nicht in der Dateiablage liegt. " + sourceRule,
+      })),
+      path: Type.Optional(Type.String({
+        description: "Datei aus der Dateiablage dieses Runs, relativ zur Ablage (z.B. thema/datei.md). "
+          + "Nur dort abgelegte Dateien sind so anzeigbar - für Pfade des Arbeitsverzeichnisses "
+          + "content nutzen. Der Inhalt wird direkt aus der Datei angezeigt und muss nie "
+          + "abgetippt werden. " + sourceRule,
+      })),
+      format: formatSchema,
+    }, { additionalProperties: false }),
+    resultSchema: Type.String(),
+    available: facesOperator,
+    run: async ({ caller }, _toolCallId, input) => {
+      const source = documentSource(input);
+
+      if (source.kind === "content")
+        return `Dem Benutzer angezeigt: ${input.title}`;
+
+      const path = source.path;
+      if (path.startsWith("/") || path.split("/").includes(".."))
+        throw new Error("path muss relativ zur Dateiablage sein, ohne führenden / und ohne ..");
+      if (!await runFileExists(await filesFor(caller.runId), path))
+        throw new Error(
+          `${source.path} liegt nicht in der Dateiablage dieses Runs. Über path sind nur Dateien der `
+          + "Dateiablage anzeigbar - für Dateien aus dem Arbeitsverzeichnis und für selbst erzeugte "
+          + "Inhalte den Inhalt über content übergeben.",
+        );
+      return `Dem Benutzer angezeigt: ${input.title} (Datei ${path} aus der Dateiablage)`;
+    },
+  });

package/plugins/ragents.documents/server/store.ts

@@ -0,0 +1,35 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { isRunId } from "@aicontainer/ragents";
+import type { DocumentStore, DocumentStoreDescription } from "@aicontainer/server/ragents/document-store.js";
+
+export interface RunDocumentStoreOptions {
+  sessionDirectory: (runId: string) => string;
+  sessionsDirectoryPattern: string;
+  externalRoot: string | undefined;
+}
+
+export class RunDocumentStore implements DocumentStore {
+  readonly #options: RunDocumentStoreOptions;
+
+  constructor(options: RunDocumentStoreOptions) {
+    this.#options = options;
+  }
+
+  async directoryFor(runId: string): Promise<string> {
+    if (!isRunId(runId)) throw new Error(`Ungültige Session-Id: ${runId}`);
+    const directory = this.#options.externalRoot
+      ? path.join(this.#options.externalRoot, runId)
+      : this.#options.sessionDirectory(runId);
+    await mkdir(directory, { recursive: true });
+    return directory;
+  }
+
+  describe(): DocumentStoreDescription {
+    return {
+      directoryPattern: this.#options.externalRoot
+        ? path.join(this.#options.externalRoot, "{runId}")
+        : this.#options.sessionsDirectoryPattern,
+    };
+  }
+}

package/plugins/ragents.documents/server/tool-contributor.ts

@@ -0,0 +1,16 @@
+import type { ToolContributor } from "@aicontainer/ragents";
+import { createDocumentWriteTool, documentWriteToolMetadata } from "./document-write-tool.js";
+import { createShowDocumentTool, showDocumentToolMetadata } from "./show-document-tool.js";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { alwaysAvailable, facesOperator } from "@aicontainer/server/plugin-support/tool-availability.js";
+
+export const createDocumentToolContributor = (
+  filesFor: (runId: string) => Promise<string>,
+): ToolContributor => ({
+  name: "ragents.documents",
+  descriptors: [
+    toolDescriptorFrom(showDocumentToolMetadata, facesOperator),
+    toolDescriptorFrom(documentWriteToolMetadata, alwaysAvailable),
+  ],
+  tools: () => [createShowDocumentTool(filesFor), createDocumentWriteTool(filesFor)],
+});