@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/server/client-contracts.ts

@@ -0,0 +1,187 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+function readContracts(repoRoot: string): { names: string[]; files: Record<string, string> } {
+  const filename = path.join(repoRoot, "plugins/ragents.actor-programs/client-ui/contracts.d.ts");
+  const options: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler, jsx: ts.JsxEmit.ReactJSX,
+    strict: true, skipLibCheck: true, esModuleInterop: true,
+    declaration: true, emitDeclarationOnly: true,
+  };
+  const program = ts.createProgram([filename], options);
+  const source = program.getSourceFile(filename);
+  if (!source) throw new Error("Der öffentliche UI-Vertrag fehlt.");
+  const checker = program.getTypeChecker();
+  const module = checker.getSymbolAtLocation(source);
+  if (!module) throw new Error("Der öffentliche UI-Vertrag ist kein Modul.");
+  const names = checker.getExportsOfModule(module).filter((entry) => {
+    const symbol = entry.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(entry) : entry;
+    return /^[A-Z]/.test(entry.name) && (symbol.flags & ts.SymbolFlags.Value) && checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration ?? source).getCallSignatures().length > 0;
+  }).map((entry) => entry.name).sort((a, b) => a.localeCompare(b, "en"));
+  if (!names.length) throw new Error("Der öffentliche UI-Vertrag exportiert keine Komponenten.");
+  const files: Record<string, string> = {};
+  const visited = new Set<string>();
+  const diagnostics: ts.Diagnostic[] = [...program.getOptionsDiagnostics()];
+  const collect = (file: ts.SourceFile) => {
+    if (visited.has(file.fileName)) return;
+    visited.add(file.fileName);
+    const relative = path.relative(repoRoot, file.fileName).replaceAll(path.sep, "/");
+    if (relative.startsWith("../") || relative.includes("node_modules/")) throw new Error("Ein lokaler UI-Typverweis verlässt die öffentlichen Repository-Quellen.");
+    diagnostics.push(...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file));
+    let text = file.isDeclarationFile ? file.text : "";
+    if (!file.isDeclarationFile) {
+      const emitted = program.emit(file, (filename, content) => { if (filename.endsWith(".d.ts")) text = content; }, undefined, true);
+      diagnostics.push(...emitted.diagnostics);
+      if (!text) throw new Error(`UI-Typdeklarationen fehlen: ${relative}`);
+    }
+    files[relative.replace(/(?<!\.d)\.tsx?$/, ".d.ts")] = text;
+    const declaration = ts.createSourceFile(file.fileName, text, ts.ScriptTarget.Latest, true);
+    const references = ts.preProcessFile(text, true, true);
+    for (const reference of references.importedFiles) {
+      if (!reference.fileName.startsWith(".")) continue;
+      const resolved = ts.resolveModuleName(reference.fileName, file.fileName, options, ts.sys).resolvedModule;
+      const dependency = resolved && program.getSourceFile(resolved.resolvedFileName);
+      if (!dependency) throw new Error(`Nicht auflösbarer lokaler UI-Typverweis: ${relative}: ${reference.fileName}`);
+      collect(dependency);
+    }
+    for (const reference of declaration.referencedFiles) {
+      const dependency = program.getSourceFile(path.resolve(path.dirname(file.fileName), reference.fileName));
+      if (!dependency) throw new Error(`Nicht auflösbarer UI-Typdateiverweis: ${relative}: ${reference.fileName}`);
+      collect(dependency);
+    }
+  };
+  collect(source);
+  if (diagnostics.length) throw new Error(`Der öffentliche UI-Vertrag kann nicht geprüft werden: ${diagnostics.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")).join("; ")}`);
+  return { names, files: Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b, "en"))) };
+}
+
+let cached: ReturnType<typeof readContracts> | undefined;
+const contracts = (repoRoot?: string) => repoRoot === undefined
+  ? cached ??= readContracts(fileURLToPath(new URL("../../../", import.meta.url)))
+  : readContracts(repoRoot);
+
+export function readClientUiContractFiles(repoRoot?: string): Record<string, string> {
+  return { ...contracts(repoRoot).files };
+}
+
+export function readClientUiComponentNames(repoRoot?: string): string[] {
+  return [...contracts(repoRoot).names];
+}
+
+export function readClientUiComponentContracts(component: string, repoRoot?: string): Record<string, string> {
+  if (!contracts(repoRoot).names.includes(component)) throw new Error(`Unbekanntes Control ${component}. Gültig: ${contracts(repoRoot).names.join(", ")}`);
+  return readClientUiExportContracts(component, repoRoot);
+}
+
+export function readClientUiExportContracts(component: string, repoRoot?: string): Record<string, string> {
+  const root = repoRoot ?? fileURLToPath(new URL("../../../", import.meta.url));
+  const catalog = contracts(repoRoot);
+  const files = new Map(Object.entries(catalog.files).map(([name, text]) => [path.resolve(root, name), text]));
+  const options: ts.CompilerOptions = { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, strict: true, skipLibCheck: true };
+  const host = ts.createCompilerHost(options);
+  const originalRead = host.readFile.bind(host);
+  const originalExists = host.fileExists.bind(host);
+  host.readFile = (name) => files.get(path.resolve(name)) ?? originalRead(name);
+  host.fileExists = (name) => {
+    const absolute = path.resolve(name);
+    if (files.has(absolute)) return true;
+    if (files.has(absolute.replace(/(?<!\.d)\.tsx?$/, ".d.ts"))) return false;
+    return originalExists(name);
+  };
+  host.getSourceFile = (name, languageVersion) => {
+    const text = host.readFile(name);
+    return text === undefined ? undefined : ts.createSourceFile(name, text, languageVersion, true);
+  };
+  const entry = path.join(root, "plugins/ragents.actor-programs/client-ui/contracts.d.ts");
+  const program = ts.createProgram([entry], options, host);
+  const checker = program.getTypeChecker();
+  const selected = new Set<ts.Statement>();
+  const imported = new Set<ts.Declaration>();
+  const bridges = new Map<ts.SourceFile, Map<string, ts.Symbol>>();
+  const visitedExports = new Set<string>();
+  const resolve = (symbol: ts.Symbol) => symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  const local = (file: ts.SourceFile) => files.has(path.resolve(file.fileName));
+  const exportFrom = (file: ts.SourceFile, name: string): void => {
+    const key = `${file.fileName}:${name}`;
+    if (visitedExports.has(key)) return;
+    visitedExports.add(key);
+    const module = checker.getSymbolAtLocation(file);
+    const symbol = module && checker.getExportsOfModule(module).find((item) => item.name === name);
+    if (!symbol) throw new Error(`UI-Typverweis fehlt: ${file.fileName}: ${name}`);
+    const target = resolve(symbol);
+    const declaration = target.declarations?.find((item) => local(item.getSourceFile()));
+    if (!declaration) return;
+    if (declaration.getSourceFile() !== file || target.name !== name) {
+      const exports = bridges.get(file) ?? new Map<string, ts.Symbol>();
+      exports.set(name, target);
+      bridges.set(file, exports);
+    }
+    visit(target);
+  };
+  const visit = (symbol: ts.Symbol): void => {
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+      for (const declaration of symbol.declarations ?? []) {
+        if (!local(declaration.getSourceFile())) continue;
+        imported.add(declaration);
+        if (ts.isImportSpecifier(declaration) || ts.isImportClause(declaration)) {
+          const clause = ts.isImportSpecifier(declaration) ? declaration.parent.parent : declaration;
+          const statement = clause.parent;
+          const module = checker.getSymbolAtLocation(statement.moduleSpecifier);
+          const file = module?.declarations?.find(ts.isSourceFile);
+          if (file && local(file)) exportFrom(file, ts.isImportSpecifier(declaration) ? (declaration.propertyName ?? declaration.name).text : "default");
+        }
+      }
+      visit(resolve(symbol));
+      return;
+    }
+    for (const declaration of symbol.declarations ?? []) {
+      if (!local(declaration.getSourceFile())) continue;
+      let node: ts.Node = declaration;
+      while (node.parent && !ts.isSourceFile(node.parent)) node = node.parent;
+      if (!ts.isStatement(node) || ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || selected.has(node)) continue;
+      selected.add(node);
+      const scan = (child: ts.Node): void => {
+        if (ts.isIdentifier(child)) {
+          const dependency = checker.getSymbolAtLocation(child);
+          if (dependency) visit(dependency);
+        }
+        ts.forEachChild(child, scan);
+      };
+      scan(node);
+    }
+  };
+  const source = program.getSourceFile(entry);
+  if (!source) throw new Error("Der öffentliche UI-Vertrag fehlt.");
+  exportFrom(source, component);
+  const printer = ts.createPrinter();
+  const result: Record<string, string> = {};
+  for (const file of program.getSourceFiles().filter(local)) {
+    const declarations = file.statements.filter((statement) => selected.has(statement));
+    const exported = bridges.get(file);
+    if (!declarations.length && !exported) continue;
+    const lines: string[] = [];
+    for (const statement of file.statements) {
+      if (!ts.isImportDeclaration(statement) || !statement.importClause) continue;
+      const clause = statement.importClause;
+      const name = imported.has(clause) ? clause.name : undefined;
+      const bindings = clause.namedBindings;
+      const named = bindings && ts.isNamedImports(bindings)
+        ? ts.factory.updateNamedImports(bindings, bindings.elements.filter((item) => imported.has(item)))
+        : bindings && imported.has(bindings) ? bindings : undefined;
+      if (!name && (!named || ts.isNamedImports(named) && named.elements.length === 0)) continue;
+      lines.push(printer.printNode(ts.EmitHint.Unspecified, ts.factory.updateImportDeclaration(statement, statement.modifiers, ts.factory.updateImportClause(clause, clause.isTypeOnly, name, named), statement.moduleSpecifier, statement.attributes), file));
+    }
+    lines.push(...declarations.map((statement) => statement.getFullText(file).trim()));
+    for (const [name, target] of exported ?? []) {
+      const declaration = target.declarations!.find((item) => local(item.getSourceFile()))!;
+      const targetFile = declaration.getSourceFile();
+      const relative = path.relative(path.dirname(file.fileName), targetFile.fileName).replaceAll(path.sep, "/").replace(/\.d\.ts$/, "");
+      const specifier = relative.startsWith(".") ? relative : `./${relative}`;
+      lines.push(`export { ${target.name}${name === target.name ? "" : ` as ${name}`} }${targetFile === file ? "" : ` from ${JSON.stringify(specifier)}`};`);
+    }
+    result[path.relative(root, file.fileName).replaceAll(path.sep, "/")] = `${lines.join("\n\n")}\n`;
+  }
+  return Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b, "en")));
+}

package/plugins/ragents.actor-programs/server/client-runtime.ts

@@ -0,0 +1,16 @@
+import { fileURLToPath } from "node:url";
+import { buildSync } from "esbuild";
+
+/** Third-party stylesheets every mini-app frame needs: syntax colors, diff markup and the flow diagram. */
+const entries = ["../../../apps/web/src/highlighting.css", "../../../apps/web/src/diff-view.css", "./flow-diagram.css"];
+
+export const browserRuntimeStyles = buildSync({
+  stdin: {
+    contents: entries.map((file) => `@import "${file}";`).join("\n"),
+    resolveDir: fileURLToPath(new URL("../client-ui/", import.meta.url)),
+    loader: "css",
+  },
+  bundle: true,
+  write: false,
+  minify: true,
+}).outputFiles[0].text;

package/plugins/ragents.actor-programs/server/controls-template.ts

@@ -0,0 +1,118 @@
+import type { ActorProgramTemplate } from "./templates";
+
+export const controlsTemplate: ActorProgramTemplate = {
+  id: "controls",
+  title: "UI-Controls ausprobieren",
+  description: "Lokale Demo mit Formular, Tabelle, Dateien, Aufgaben, Ablaufdiagramm, SVG-Verbindungen, Nachrichten, Dokument und Diff ohne Funktionsaufrufe.",
+  files: {
+    "package.json": `{
+  "name": "controls",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "UI-Controls ausprobieren",
+    "description": "Eine lokale Demo der vorhandenen Mini-App-Controls. Werte und Dateien bleiben in dieser Ansicht.",
+    "views": [
+      {
+        "id": "main",
+        "client": "src/client.tsx",
+        "width": 640,
+        "height": 640
+      }
+    ]
+  }
+}
+`,
+    "src/client.tsx": `import React from "react";
+import { createRoot } from "react-dom/client";
+import * as UI from "@ragents/client/ui";
+
+type FormValues = Parameters<typeof UI.Form>[0]["values"];
+type Row = { id: string; name: string; count: number };
+const rows: Row[] = [
+  { id: "analysis", name: "Analyse", count: 12 },
+  { id: "review", name: "Review", count: 4 },
+  { id: "notes", name: "Dokumentation", count: 8 },
+];
+
+const App = () => {
+  const [values, setValues] = React.useState<FormValues>({ title: "Ergebnisse prüfen", notes: "", count: 3, mode: "review", approved: false });
+  const [selected, setSelected] = React.useState<string[]>([]);
+  const [files, setFiles] = React.useState<File[]>([]);
+  const [result, setResult] = React.useState("Noch keine Formularwerte übernommen.");
+  const [messages, setMessages] = React.useState<Parameters<typeof UI.MessageList>[0]["messages"]>([
+    { key: "editorial", sender: "Redaktion", text: "Der Hinweis soll **kurz und verständlich** bleiben." },
+    { key: "review", sender: "Textprüfung", text: "Öffnungszeiten und Reparaturhinweis bleiben erhalten." },
+  ]);
+  const [done, setDone] = React.useState(false);
+  return <UI.AppLayout title="UI-Controls ausprobieren" description="Lokale Demo: keine Agenten, Uploads oder Serveraktionen. Werte und Dateiauswahl bleiben nur in dieser Ansicht und werden beim Neuladen zurückgesetzt.">
+    <UI.Stack gap="large">
+      <UI.Form title="Formular" fields={[
+        { id: "title", label: "Auftrag", type: "text", placeholder: "Was soll bearbeitet werden?", required: true },
+        { id: "notes", label: "Hinweise", type: "textarea", rows: 3, placeholder: "Was soll bei der Bearbeitung berücksichtigt werden?", hint: "Mehrzeiliger Text bleibt im Formular ausgerichtet." },
+        { id: "count", label: "Anzahl", type: "number", placeholder: "Anzahl der Ergebnisse", hint: "1 bis 10 Ergebnisse.", required: true, min: 1, max: 10 },
+        { id: "mode", label: "Modus", type: "select", options: [{ value: "review", label: "Prüfen" }, { value: "draft", label: "Entwerfen" }] },
+        { id: "approved", label: "Auswahl bestätigt", type: "checkbox", required: true },
+      ]} values={values} onChange={setValues} onSubmit={async (next) => { setResult(JSON.stringify(next, null, 2)); }} submitLabel="Werte lokal anzeigen" />
+      <UI.Stack gap="small">
+        <UI.DataTable<Row> title="Datentabelle" rows={rows} rowKey={(row) => row.id} filterable
+          selectedKeys={selected} onSelectionChange={setSelected}
+          columns={[{ id: "name", label: "Arbeit", value: (row) => row.name, sortable: true }, { id: "count", label: "Ergebnisse", value: (row) => row.count, sortable: true }]}
+          actions={[{ id: "select", label: "Auswählen", onClick: (row) => { setSelected([row.id]); } }]} />
+        <p aria-live="polite">{selected.length} Zeilen ausgewählt</p>
+      </UI.Stack>
+      <UI.FilePicker label="Lokale Dateiauswahl" files={files} onChange={setFiles} maxFiles={5} maxBytes={10 * 1024 * 1024} />
+      <UI.Stack gap="small">
+        <UI.TaskProgress title="Beispielaufgaben" tasks={[
+          { id: "read", label: "Unterlagen lesen", status: "done" },
+          { id: "review", label: "Ergebnisse prüfen", status: done ? "done" : "pending", description: "Lokaler Beispielstatus, kein laufender Actor." },
+        ]} />
+        <UI.Stack direction="row"><UI.Button onClick={() => setDone((current) => !current)}>Beispielstatus umschalten</UI.Button></UI.Stack>
+      </UI.Stack>
+      <UI.Stack gap="small">
+        <h2>Ablaufdiagramm</h2>
+        <p>Das Diagramm erhält seinen Zustand aus denselben Daten wie die Aufgabenliste.</p>
+        <UI.FlowDiagram label={done ? "Eingang, Prüfung fertig, Ergebnis bereit" : "Eingang, Prüfung läuft, Ergebnis ausstehend"}
+          nodes={[
+            { id: "input", label: "Eingang", detail: "Unterlagen liegen vor", status: "done", kind: "service" },
+            { id: "check", label: "Prüfung", detail: done ? "Prüfung abgeschlossen" : "Unterlagen werden geprüft", status: done ? "done" : "active", kind: "agent" },
+            { id: "result", label: "Ergebnis", detail: done ? "Ergebnis bereit" : "Wartet auf die Prüfung", status: done ? "done" : "pending", kind: "actor" },
+          ]}
+          edges={[{ source: "input", target: "check" }, { source: "check", target: "result" }]} />
+      </UI.Stack>
+      <UI.Stack gap="small">
+        <h2>SVG-Verbindungen</h2>
+        <p>SvgEdge zeichnet die Kanten. Knoten, Beschriftungen und Positionen stehen im Code dieser Ansicht.</p>
+        <svg viewBox="0 0 360 160" role="img" aria-label={done ? "Eingang fertig, Prüfung abgeschlossen, Ergebnis bereit" : "Eingang fertig, Prüfung läuft, Ergebnis offen"}
+          className="block h-auto w-full text-[13px]">
+          <UI.SvgEdge d="M112 42 L144 42" tone={done ? "success" : "warning"} active={!done} />
+          <UI.SvgEdge d="M252 42 C320 42 320 118 252 118" arrow={done ? "end" : "none"} tone={done ? "success" : "neutral"} lineStyle={done ? "solid" : "dashed"} />
+          <UI.SvgEdge d="M144 118 C64 118 64 96 64 72" arrow="both" tone="accent" />
+          {[{ x: 8, y: 12, label: "Eingang", status: "Fertig" },
+            { x: 148, y: 12, label: "Prüfung", status: done ? "Fertig" : "Läuft" },
+            { x: 148, y: 88, label: "Ergebnis", status: done ? "Bereit" : "Offen" }].map((node) => <g key={node.label}>
+              <rect x={node.x} y={node.y} width="104" height="56" rx="8" className="fill-background stroke-border-strong" />
+              <text x={node.x + 52} y={node.y + 23} textAnchor="middle" className="fill-foreground font-semibold">{node.label}</text>
+              <text x={node.x + 52} y={node.y + 42} textAnchor="middle" className="fill-muted-foreground text-[11px]">{node.status}</text>
+            </g>)}
+        </svg>
+      </UI.Stack>
+      <UI.Stack gap="small">
+        <UI.MessageList messages={messages} label="Lokale Redaktionsnotizen" />
+        <UI.Stack direction="row"><UI.Button onClick={() => setMessages((current) => [...current, {
+          key: "note-" + current.length, sender: current.length % 2 ? "Textprüfung" : "Redaktion",
+          text: "Lokale Beispielnotiz " + (current.length - 1) + ": Diese Nachricht wurde gerade ergänzt.",
+        }])}>Lokale Nachricht ergänzen</UI.Button></UI.Stack>
+      </UI.Stack>
+      <UI.DocumentViewer title="Lokales Formularergebnis" format="text" content={result} />
+      <UI.DiffViewer title="Beispieländerung" patch={"--- a/result.txt\\n+++ b/result.txt\\n@@ -1 +1 @@\\n-Status: offen\\n+Status: geprüft"} />
+    </UI.Stack>
+  </UI.AppLayout>;
+};
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);
+`,
+  },
+};

package/plugins/ragents.actor-programs/server/controls-tool.ts

@@ -0,0 +1,48 @@
+import { Type } from "typebox";
+import { defineRunFunction, defineToolAvailability, type ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { readClientUiComponentNames, readClientUiComponentContracts } from "./client-contracts.js";
+import { actorProgramGuide } from "./prompts.js";
+
+const available = defineToolAvailability({ availability: "always", availabilityDetail: "Typisierte UI-Referenz der installierten Actor-Programm-Extension." }, () => true);
+const metadata = {
+  name: "actor_program_controls",
+  label: "Actor-Programm-Anleitung und Controls nachschlagen",
+  description: "Read Mini-App control contracts or the actor-program authoring guide.",
+  longDescription: "With topic: guide, explain the TypeScript package workflow through actor_program_activate. Otherwise list control names, or select one component (for example Form) for its TypeScript props and supporting types. Import controls from @ragents/client/ui and use these exact props.",
+};
+
+export const describeClientControls = (component?: string) => {
+  const components = readClientUiComponentNames();
+  if (component === undefined) return { components };
+  if (!components.includes(component)) throw new Error(`Unbekanntes Control ${component}. Gültig: ${components.join(", ")}`);
+  return { components, component, files: readClientUiComponentContracts(component) };
+};
+
+export const createControlsToolContributor = (): ToolContributor => ({
+  name: "ragents.actor-programs.controls",
+  descriptors: [toolDescriptorFrom(metadata, available)],
+  tools: () => [defineRunFunction({
+    ...metadata,
+    available,
+    schema: Type.Object({
+      topic: Type.Optional(Type.Union([Type.Literal("controls"), Type.Literal("guide")], { description: "Default controls: query component names or types. Guide: read the short package workflow without component." })),
+      component: Type.Optional(Type.String({ minLength: 1, description: "Optional control name from the catalog, without UI. prefix. Only valid when topic is controls or omitted." })),
+    }, { additionalProperties: false }),
+    resultSchema: Type.Union([
+      Type.Object({ guide: Type.String() }, { additionalProperties: false }),
+      Type.Object({
+        components: Type.Array(Type.String()),
+        component: Type.Optional(Type.String()),
+        files: Type.Optional(Type.Record(Type.String(), Type.String())),
+      }, { additionalProperties: false }),
+    ]),
+    run: async (_scope, _call, input) => {
+      if (input.topic === "guide") {
+        if (input.component !== undefined) throw new Error("component ist nur bei topic: controls oder ohne topic erlaubt; für topic: guide lasse component weg.");
+        return { guide: await actorProgramGuide.render({}) };
+      }
+      return describeClientControls(input.component);
+    },
+  })],
+});

package/plugins/ragents.actor-programs/server/index.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+import type { PluginHost, RAgentsPlugin } from "@aicontainer/ragents";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { runtimeProviderToken, sessionGuardToken } from "@aicontainer/server/ragents/host-services.js";
+import { askServiceToken } from "@aicontainer/plugins/ragents.ask/server/contract.js";
+import { agentToolsFrom } from "./agent-tools.js";
+import { createActorProgramMethods } from "./methods.js";
+import { createMiniAppFrameRoutes, miniAppsApiPrefix } from "./routes.js";
+import { ActorProgramRuntime } from "./runtime.js";
+import { actorProgramManagementToolNames, actorProgramToolsAvailable, createActorProgramToolContributors } from "./tool-contributor.js";
+import { createControlsToolContributor } from "./controls-tool.js";
+import { actorProgramSummary } from "./prompts.js";
+import { sandboxServicesToken } from "@aicontainer/server/plugin-support/workspace-sandbox-host.js";
+import { actorProgramsToken } from "@aicontainer/server/plugin-support/actor-programs/service.js";
+import { createProjectDiagnostics } from "./project-diagnostics.js";
+const actorProgramsPlugin = (pluginHost: PluginHost): RAgentsPlugin => ({
+    manifest: { id: "ragents.actor-programs" },
+    register: (host) => {
+        const runtime = new ActorProgramRuntime({
+            runtime: host.service(runtimeProviderToken), agentToolsFor: agentToolsFrom(pluginHost), askService: () => host.service(askServiceToken), reservedToolNames: () => pluginHost.tools.describe().map((entry) => entry.name),
+            processContextFor: (runId) => host.service(sandboxServicesToken).processContextFor(runId),
+            operations: { operation: (id) => host.operation(id), invoke: (id, context, input) => host.invokeOperation(id, context, input), list: () => pluginHost.operations.describe() },
+            directoryFor: (runId) => host.storage.session(runId, "programs"),
+            scriptSources: (entryId, name) => {
+                const script = pluginHost.startEntries.scriptPackage(entryId);
+                return !script ? undefined : script.handle === name ? script.files : script.programs.find((program) => program.name === name)?.files;
+            },
+        });
+        host.provide(actorProgramsToken, runtime);
+        const diagnostics = createProjectDiagnostics({
+            workspaceFor: (runId) => runtime.workspaceDirectory(runId), check: (runId, name, actorId, signal) => runtime.check(runId, name, actorId, signal),
+            applies: (runId, actorId) => {
+                const view = host.service(runtimeProviderToken)().view(runId);
+                const actor = view.actors.find((candidate) => candidate.id === actorId);
+                return !!actor && actor.kind !== "human" && actorProgramToolsAvailable(actor, view) && (actor.toolNames === null || actor.toolNames.some((name) => (actorProgramManagementToolNames as readonly string[]).includes(name)));
+            },
+        });
+        host.agentRuntime(diagnostics.contribution);
+        host.clientConfig({ routePrefix: miniAppsApiPrefix });
+        host.methods(...createActorProgramMethods({ ensureSession: host.service(sessionGuardToken), runtime }));
+        host.http(...createMiniAppFrameRoutes({ ensureSession: host.service(sessionGuardToken), runtime }));
+        host.lifecycle({ id: "ragents.actor-programs.lifecycle",
+            initialize: () => host.service(sandboxServicesToken).registerWorkspaceRoot({ id: "ragents.actor-programs", alias: "@actors", environmentVariable: "RAGENTS_ACTORS_DIR", directoryFor: (runId) => runtime.workspaceDirectory(runId), ownershipDirectoryFor: async (runId) => path.dirname(await runtime.workspaceDirectory(runId)) }),
+            prepareSession: ({ runId }) => runtime.prepareSession(runId), stopSession: ({ runId, signal }) => runtime.stopSession(runId, signal),
+            deleteSession: async ({ runId }) => { diagnostics.forget(runId); await runtime.deleteSession(runId); }, shutdown: () => runtime.shutdown(),
+        });
+        host.prompts(actorProgramSummary);
+        host.functions(createControlsToolContributor(), ...createActorProgramToolContributors(runtime, diagnostics));
+    },
+});
+export const plugin: PluginModule = { requires: ["ragents.ask"], create: actorProgramsPlugin };

package/plugins/ragents.actor-programs/server/methods.ts

@@ -0,0 +1,72 @@
+import { DomainError, implement, type MethodContribution } from "@aicontainer/ragents";
+import { actorProgramContracts } from "../contract.js";
+import type { ActorProgramRuntime } from "./runtime.js";
+
+const MAX_INPUT_BYTES = 64 * 1024;
+
+export interface ActorProgramMethodOptions {
+  ensureSession: (runId: string) => void;
+  runtime: ActorProgramRuntime;
+}
+
+const failed = (cause: unknown, code: string, status: number): DomainError => cause instanceof DomainError
+  ? cause
+  : new DomainError(code, cause instanceof Error ? cause.message : String(cause), status);
+
+const guarded = <T>(code: string, status: number, work: () => T): T => {
+  try {
+    return work();
+  } catch (cause) {
+    throw failed(cause, code, status);
+  }
+};
+
+const checkedInput = (input: unknown): unknown => {
+  if (Buffer.byteLength(JSON.stringify(input ?? null), "utf8") > MAX_INPUT_BYTES)
+    throw new DomainError("input-too-large", `Die Aktionseingabe ist größer als ${MAX_INPUT_BYTES} Byte.`, 413);
+  return input;
+};
+
+export const createActorProgramMethods = (options: ActorProgramMethodOptions): MethodContribution[] => {
+  const session = (runId: string, code: string, status: number): void =>
+    guarded(code, status, () => options.ensureSession(runId));
+  return [
+    implement(actorProgramContracts.apps, ({ runId }, { access }) => {
+      session(runId, "run-unavailable", 400);
+      return {
+        apps: options.runtime.apps(runId),
+        tools: access.can("runs.inspect") ? options.runtime.runLocalTools(runId) : [],
+      };
+    }),
+    implement(actorProgramContracts.source, async ({ runId, moduleId }) => {
+      session(runId, "run-unavailable", 404);
+      try {
+        return await options.runtime.moduleSource(runId, moduleId);
+      } catch (cause) {
+        throw failed(cause, "actor-program-unknown", 404);
+      }
+    }),
+    implement(actorProgramContracts.action, ({ runId, appId, revision, actionId, requestId, input }) => {
+      session(runId, "run-unavailable", 400);
+      return guarded("action-rejected", 400, () => {
+        const permit = options.runtime.invocationPermit(runId);
+        return options.runtime.startInvocation(runId, appId, revision, actionId, requestId, checkedInput(input), permit);
+      });
+    }),
+    implement(actorProgramContracts.invocation, ({ runId, appId, invocationId }) => {
+      session(runId, "run-unavailable", 404);
+      return guarded("invocation-unknown", 404, () => options.runtime.invocation(runId, appId, invocationId));
+    }),
+    implement(actorProgramContracts.function, ({ runId, actorHandle, revision, functionId, requestId, input }) => {
+      session(runId, "run-unavailable", 400);
+      return guarded("function-rejected", 400, () => {
+        const permit = options.runtime.invocationPermit(runId);
+        return options.runtime.startFunctionInvocation(runId, actorHandle, revision, functionId, requestId, checkedInput(input), permit);
+      });
+    }),
+    implement(actorProgramContracts.functionInvocation, ({ runId, actorHandle, invocationId }) => {
+      session(runId, "run-unavailable", 404);
+      return guarded("invocation-unknown", 404, () => options.runtime.invocation(runId, actorHandle, invocationId));
+    }),
+  ];
+};

package/plugins/ragents.actor-programs/server/project-diagnostics.ts

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import type { AgentContribution } from "@aicontainer/ragents";
+import { projectSourceFiles } from "./app-project.js";
+
+const entryType = "ragents.actor-programs.project-diagnostics";
+const maxDeltaLines = 8;
+const maxLineLength = 240;
+
+interface ProgramDiagnostics {
+  fingerprint: string;
+  errors: string[];
+}
+
+export interface ProjectDiagnosticsSnapshot {
+  version: 1;
+  programs: Record<string, ProgramDiagnostics>;
+}
+
+export interface ProjectDiagnosticsOptions {
+  workspaceFor: (runId: string) => string | Promise<string>;
+  check: (runId: string, programName: string, actorId: string, signal?: AbortSignal) => Promise<unknown>;
+  applies?: (runId: string, actorId: string) => boolean;
+}
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+const fingerprintOf = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const errorLines = (error: unknown): string[] => {
+  const lines = messageOf(error).split("\n").map((line) => line.trim()).filter(Boolean);
+  const issues = lines.filter((line) => !/^(Build failed with \d+ errors?:|.*(?:Typprüfung|Typecheck|Diagnostik).*:)$/i.test(line));
+  return [...new Set(issues.length ? issues : lines)];
+};
+const allErrors = (snapshot: ProjectDiagnosticsSnapshot): string[] => Object.entries(snapshot.programs)
+  .sort(([left], [right]) => left.localeCompare(right))
+  .flatMap(([programName, program]) => program.errors.map((error) => `${programName}: ${error}`));
+const isSnapshot = (value: unknown): value is ProjectDiagnosticsSnapshot => {
+  if (value === null || typeof value !== "object") return false;
+  const snapshot = value as ProjectDiagnosticsSnapshot;
+  return snapshot.version === 1 && snapshot.programs !== null && typeof snapshot.programs === "object"
+    && Object.values(snapshot.programs).every((program) => program && typeof program.fingerprint === "string"
+      && Array.isArray(program.errors) && program.errors.every((error) => typeof error === "string"));
+};
+
+export const createProjectDiagnostics = (options: ProjectDiagnosticsOptions) => {
+  const snapshots = new Map<string, Map<string, ProjectDiagnosticsSnapshot>>();
+  const remember = (runId: string, actorId: string, snapshot: ProjectDiagnosticsSnapshot): void => {
+    const agents = snapshots.get(runId) ?? new Map<string, ProjectDiagnosticsSnapshot>();
+    agents.set(actorId, snapshot);
+    snapshots.set(runId, agents);
+  };
+  const contribution: AgentContribution = {
+    id: entryType,
+    tools: [],
+    resolve: ({ runId, agentId }) => options.applies?.(runId, agentId) === false ? [] : [{
+      name: entryType,
+      factory: (agent) => {
+        agent.on("context", async (event, context) => {
+          context.signal?.throwIfAborted();
+          const stored = context.sessionManager.getBranch().filter((entry) => entry.type === "custom" && entry.customType === entryType).at(-1);
+          const previous = stored?.type === "custom" && isSnapshot(stored.data) ? stored.data : { version: 1 as const, programs: {} };
+          const next: ProjectDiagnosticsSnapshot = { version: 1, programs: {} };
+          let changed = false;
+          try {
+            const directory = await options.workspaceFor(runId);
+            const entries = await readdir(directory, { withFileTypes: true }).catch((error: NodeJS.ErrnoException) => {
+              if (error.code === "ENOENT") return [];
+              throw error;
+            });
+            for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+              if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+              context.signal?.throwIfAborted();
+              let fingerprint: string;
+              let errors: string[] = [];
+              try {
+                if (entry.isSymbolicLink()) throw new Error("Actor-Projekte dürfen keine Symlinks sein.");
+                fingerprint = fingerprintOf(await projectSourceFiles(path.join(directory, entry.name)));
+              } catch (error) {
+                errors = errorLines(error);
+                fingerprint = fingerprintOf({ errors });
+              }
+              const prior = previous.programs[entry.name];
+              if (prior?.fingerprint === fingerprint) {
+                next.programs[entry.name] = prior;
+                continue;
+              }
+              changed = true;
+              if (errors.length === 0) {
+                try { await options.check(runId, entry.name, agentId, context.signal); }
+                catch (error) {
+                  context.signal?.throwIfAborted();
+                  errors = errorLines(error);
+                }
+              }
+              next.programs[entry.name] = { fingerprint, errors };
+            }
+          } catch (error) {
+            context.signal?.throwIfAborted();
+            const errors = errorLines(error);
+            Object.assign(next.programs, previous.programs);
+            next.programs["(Workspace)"] = { fingerprint: fingerprintOf({ errors }), errors };
+          }
+          if (JSON.stringify(Object.keys(previous.programs).sort()) !== JSON.stringify(Object.keys(next.programs).sort())) changed = true;
+          if (JSON.stringify(previous) !== JSON.stringify(next)) changed = true;
+          context.signal?.throwIfAborted();
+          remember(runId, agentId, next);
+          if (!changed) return;
+          agent.appendEntry(entryType, next);
+          const before = new Set(allErrors(previous));
+          const after = new Set(allErrors(next));
+          const added = [...after].filter((error) => !before.has(error));
+          const resolved = [...before].filter((error) => !after.has(error));
+          const changes = [...added.map((error) => `Neu: ${error}`), ...resolved.map((error) => `Behoben: ${error}`)];
+          const lines = changes.slice(0, maxDeltaLines).map((line) => line.length > maxLineLength ? `${line.slice(0, maxLineLength - 3)}...` : line);
+          const omitted = changes.length - lines.length;
+          const content = [
+            `Actor-Programm-Projektprüfung (TypeScript und Build): ${after.size} Fehler in ${Object.keys(next.programs).length} Projekten; ${added.length} neu, ${resolved.length} behoben.`,
+            ...lines,
+            ...(omitted > 0 ? [`${omitted} weitere Änderungen. Vollständiger letzter Stand: actor_program_diagnostics.`] : []),
+          ].join("\n");
+          return { messages: [...event.messages, { role: "custom" as const, customType: entryType, content, display: false, timestamp: Date.now() }] };
+        });
+      },
+    }],
+  };
+  return {
+    contribution,
+    latest(runId: string, actorId: string, programName?: string): string {
+      const snapshot = snapshots.get(runId)?.get(actorId);
+      if (!snapshot) return "Noch kein Actor-Programm-Projektstand für diesen Agenten geprüft.";
+      const programs = Object.entries(snapshot.programs).filter(([id]) => programName === undefined || id === programName);
+      if (programs.length === 0) return programName ? `Kein geprüfter Projektstand für ${programName}.` : "Keine Actor-Programm-Projekte vorhanden.";
+      return programs.sort(([left], [right]) => left.localeCompare(right)).map(([id, program]) =>
+        [`${id}: ${program.errors.length} Fehler`, ...program.errors].join("\n")).join("\n\n");
+    },
+    forget(runId: string): void { snapshots.delete(runId); },
+  };
+};