@schlenkr/ragents 0.1.5 → 0.1.7

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

@@ -1,27 +1,45 @@
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
+import { lstatSync, readFileSync, renameSync } from "node:fs";
 import path from "node:path";
 import { Type, type TSchema } from "typebox";
 import { Value } from "typebox/value";
-import { agentTools, assertJsonValue, canonicalHash, defineRunFunction, defineToolAvailability, emptyUsage, runCapabilityContractHash, scriptInputOf, schemaComplaints, type Actor, type ActorProgramExecutor, type RunFunction, type CommandContext, type ExecutableActor, type JsonValue, type Orchestration, type PluginContext, type RunCapabilityDescriptor, type RunView, type TurnRequest, type TurnResult, } from "@aicontainer/ragents";
-import { ACTOR_PROGRAMS_STATE_ID, ACTOR_INVOCATIONS_STATE_ID, ACTOR_SCRIPT_STATE_ID, ACTOR_STATE_ID, resolveActorView, type ActorDataState, type ActorFunctionDefinition, type ActorFunctionInvocation, type ActorProgramDefinition, type ActorProgramState, type ActorScriptState, type ActorViewListing, } from "../contract.js";
-import type { ActorProgramSource, ActorProgramsService } from "@aicontainer/server/plugin-support/actor-programs/service.js";
-import { jsonValue, jsonBytes, MAX_INVOCATIONS_STATE_BYTES } from "@aicontainer/server/plugin-support/actor-programs/limits.js";
-import { agentCapabilityBinding, operatorCapabilityBinding } from "@aicontainer/server/plugin-support/actor-programs/capability-resolver.js";
-import type { ActorOperationPort } from "@aicontainer/server/plugin-support/actor-programs/operations.js";
-import { compileClientProject, installClientSdk } from "./client-compiler.js";
-import { compileAppBackend, installServerSdk, prepareAppProject, prepareAppWorkspace, projectSourceFiles, readAppPackage, typecheckServerProject } from "./app-project.js";
-import { syncWorkspaceOwnership } from "@aicontainer/server/plugin-support/workspace-ownership.js";
-import { runManagedProcess, type WorkspaceProcessContext } from "@aicontainer/workspace-executor";
-import { runModuleTemplates, templateById } from "./templates.js";
-import { FRAME_BODY_CLASS, FRAME_DOCUMENT_CLASS, FRAME_ROOT_CLASS } from "../client-ui/frame-layout.js";
-import { buildTailwind } from "./tailwind.js";
-import type { AskService } from "@aicontainer/plugins/ragents.ask/server/contract.js";
+import { actorByHandle, actorDescriptionMaxLength, agentTools, assertJsonValue, canonicalHash, defineRunFunction, defineToolAvailability, emptyUsage, handleKey, runCapabilityContractHash, scriptInputOf, schemaComplaints, type Actor, type ActorProgramExecutor, type RunFunction, type CommandContext, type ExecutableActor, type JsonValue, type Orchestration, type PluginContext, type RunCapabilityDescriptor, type RunView, type TurnRequest, type TurnResult, } from "@ragents/engine";
+import { ACTOR_PROGRAMS_STATE_ID, ACTOR_INVOCATIONS_STATE_ID, ACTOR_SCRIPT_STATE_ID, ACTOR_STATE_ID, resolveActorView, type ActorDataState, type ActorFunctionDefinition, type ActorFunctionInvocation, type ActorProgramDefinition, type ActorProgramState, type ActorScriptState, type ActorViewListing, } from "@ragents/host/plugin-support/actor-programs/contract.js";
+import type { ActorProgramSource, ActorProgramsService } from "@ragents/host/plugin-support/actor-programs/service.js";
+import { jsonValue, jsonBytes, MAX_INVOCATIONS_STATE_BYTES } from "./limits.js";
+import { agentCapabilityBinding, operatorCapabilityBinding } from "./capability-resolver.js";
+import type { ActorOperationPort } from "./operations.js";
+import { compileClientProject, installClientSdk } from "@ragents/host/plugin-support/actor-programs/client-compiler.js";
+import { compileAppBackend, installServerSdk, prepareAppProject, prepareAppWorkspace, projectSourceFiles, readAppPackage, typecheckServerProject, type AppContract } from "@ragents/host/plugin-support/actor-programs/app-project.js";
+import { syncWorkspaceOwnership } from "@ragents/host/plugin-support/workspace-ownership.js";
+import { runManagedProcess, sandboxedLaunch, type WorkspaceProcessContext } from "@ragents/workspace-executor";
+import { runModuleTemplates, templateById, templateFiles } from "./templates.js";
+import { createTestReport, testReporterArgument } from "./test-report.js";
+import { FRAME_BODY_CLASS, FRAME_DOCUMENT_CLASS, FRAME_ROOT_CLASS } from "@ragents/host/plugin-support/actor-programs/client-runtime.js";
+import { buildTailwind } from "@ragents/host/plugin-support/actor-programs/tailwind.js";
+import type { AskService } from "@ragents/plugins/ragents.ask/server/contract.js";
 const NAME = /^[a-z][a-z0-9-]{0,63}$/;
 const errorText = (error: unknown): string => error instanceof Error ? error.message : String(error);
-const complaints = (lines: readonly string[], fallback: string): string =>
-    lines.map((line) => line.trim()).filter((line) => line !== "").join("\n") || fallback;
+const maxShownComplaints = 10;
+const maxComplaintLength = 240;
+/** A failed check names the count and the first complaints; `lines` keeps all of them for actor_program_diagnostics. */
+const checkFailure = (title: string, lines: readonly string[], fallback: string): Error => {
+    const all = [...new Set(lines.map((line) => line.trim()).filter((line) => line !== ""))];
+    if (all.length === 0)
+        return new Error(fallback);
+    const shown = all.slice(0, maxShownComplaints).map((line) => line.length > maxComplaintLength ? `${line.slice(0, maxComplaintLength - 3)}...` : line);
+    const omitted = all.length - shown.length;
+    return Object.assign(new Error([
+        `${title}: ${all.length} Fehler.`,
+        ...shown,
+        ...(omitted > 0 ? [`... und ${omitted} weitere; alle mit actor_program_diagnostics.`] : []),
+    ].join("\n")), { lines: all });
+};
+const actorDescriptionOf = (text: string | undefined): string | undefined => {
+    const line = (text ?? "").replace(/\s+/g, " ").trim();
+    return line.length <= actorDescriptionMaxLength ? line || undefined : `${line.slice(0, actorDescriptionMaxLength - 3).trimEnd()}...`;
+};
 const exposed = defineToolAvailability({ availability: "conditional", availabilityDetail: "Veröffentlichte Funktion eines aktiven Actors im Run." }, () => true);
 const objectSchema = { type: "object", additionalProperties: true };
 const checked = (schema: object, value: unknown, label: string): JsonValue => {
@@ -45,6 +63,31 @@ const inside = async (directory: string, relative: string): Promise<string> => {
         throw new Error(`Ungültige oder zu große Paketdatei ${relative}.`);
     return readFile(file, "utf8");
 };
+const occupied = (file: string): boolean => {
+    try {
+        lstatSync(file);
+        return true;
+    }
+    catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT")
+            return false;
+        throw error;
+    }
+};
+const packageExists = (name: string): Error => new Error(`Das Paket ${name} existiert bereits.`);
+// Prüfung und rename synchron hintereinander, weil rename einen leeren Zielordner still ersetzt.
+const commitPackage = (staged: string, directory: string, name: string): void => {
+    if (occupied(directory))
+        throw packageExists(name);
+    try {
+        renameSync(staged, directory);
+    }
+    catch (error) {
+        if (["EEXIST", "ENOTEMPTY", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? ""))
+            throw packageExists(name);
+        throw error;
+    }
+};
 const descriptor = (tool: RunFunction): RunCapabilityDescriptor => ({ id: tool.name, label: tool.label, description: tool.description, schema: tool.schema, resultSchema: tool.resultSchema });
 interface BackendBinding {
     id: string;
@@ -83,7 +126,8 @@ export interface ActorProgramRuntimeOptions {
     agentToolsFor: (runId: string, actorId: string, provisional?: ExecutableActor) => Promise<readonly RunFunction[]>;
     askService: () => AskService;
     reservedToolNames: () => readonly string[];
-    processContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
+    /** Programme, Tests und Builds laufen auf dem Server, auch bei einem Arbeitsbereich auf einem Arbeitsplatz. */
+    serverProcessContextFor: (runId: string) => Promise<WorkspaceProcessContext>;
     operations: ActorOperationPort;
     directoryFor: (runId: string) => string;
     scriptSources: (entryId: string, name: string) => readonly ActorProgramSource[] | undefined;
@@ -98,6 +142,8 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
         completed: Promise<unknown>;
     }>();
     readonly #installing = new Set<string>();
+    readonly #creating = new Set<string>();
+    readonly #staged = new Set<string>();
     readonly #removing = new Set<string>();
     readonly #knownRuns = new Set<string>();
     readonly #epochs = new Map<string, number>();
@@ -128,8 +174,8 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
         return actor;
     }
     resolveActor(runId: string, callerId: string, reference: string): ExecutableActor {
-        const name = reference.replace(/^@/, "").toLowerCase();
-        const found = this.view(runId).actors.find((candidate) => reference === "self" ? candidate.id === callerId : candidate.handle === name);
+        const actors = this.view(runId).actors;
+        const found = reference === "self" ? actors.find((candidate) => candidate.id === callerId) : actorByHandle(actors, reference);
         if (!found)
             throw new Error(`Actor ${reference} ist unbekannt.`);
         return this.actor(runId, found.id);
@@ -198,32 +244,50 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
     }
     async workspaceDirectory(runId: string): Promise<string> { this.#knownRuns.add(runId); return prepareAppWorkspace(path.join(this.#options.directoryFor(runId), "actor-workspace")); }
     templates() { return runModuleTemplates.map(({ id, title, description }) => ({ id, title, description })); }
-    async scaffold(runId: string, name: string, templateId: string) {
+    async #create<T>(runId: string, name: string, build: (directory: string) => Promise<T>): Promise<{ directory: string; built: T }> {
         this.#assertName(name);
-        const directory = path.join(await this.workspaceDirectory(runId), name);
-        if (await lstat(directory).then(() => true, () => false))
-            throw new Error(`Das Paket ${name} existiert bereits.`);
-        await mkdir(directory, { recursive: true });
-        for (const [relative, content] of Object.entries(templateById(templateId).files)) {
-            const file = path.join(directory, safePath(relative));
-            await mkdir(path.dirname(file), { recursive: true });
-            const source = relative === "package.json" ? JSON.stringify({ ...JSON.parse(content), name }, null, 2) + "\n" : content;
-            await writeFile(file, source, { flag: "wx" });
+        const actors = await this.workspaceDirectory(runId);
+        const directory = path.join(actors, name);
+        const key = `${runId}\0${name}`;
+        if (this.#creating.has(key))
+            throw new Error(`Das Paket ${name} wird gerade angelegt.`);
+        if (occupied(directory))
+            throw packageExists(name);
+        this.#creating.add(key);
+        const staging = path.join(path.dirname(actors), ".staging");
+        const staged = path.join(staging, `${name}-${randomUUID()}`);
+        this.#staged.add(staged);
+        try {
+            await mkdir(staging, { recursive: true });
+            for (const entry of await readdir(staging))
+                if (!this.#staged.has(path.join(staging, entry)))
+                    await rm(path.join(staging, entry), { recursive: true, force: true });
+            await mkdir(staged);
+            const built = await build(staged);
+            commitPackage(staged, directory, name);
+            return { directory, built };
+        }
+        finally {
+            this.#creating.delete(key);
+            this.#staged.delete(staged);
+            await rm(staged, { recursive: true, force: true });
         }
-        await prepareAppProject(directory);
-        const pkg = await readAppPackage(directory);
-        const backend = pkg.backend ? await compileAppBackend({ directory, backend: pkg.backend, runId, executor: this.runtime().nativeTypeScriptExecutor }) : undefined;
-        await installClientSdk(directory, { stateSchema: backend?.contract.state ?? objectSchema, actions: Object.entries(backend?.contract.functions ?? {}).map(([id, fn]) => ({ id, inputSchema: fn.input, resultSchema: fn.output })) });
-        return { name, directory: `@actors/${name}`, files: (await projectSourceFiles(directory)).map((file) => file.path) };
+    }
+    async scaffold(runId: string, name: string, templateId: string) {
+        const sources = Object.entries(templateFiles(templateById(templateId), name)).map(([file, content]) => ({ path: file, content }));
+        const { built: files } = await this.#create(runId, name, async (directory) => {
+            await this.#writeSources(directory, sources);
+            await prepareAppProject(directory);
+            const pkg = await readAppPackage(directory);
+            const backend = pkg.backend ? await compileAppBackend({ directory, backend: pkg.backend, runId, executor: this.runtime().nativeTypeScriptExecutor }) : undefined;
+            await installClientSdk(directory, { stateSchema: backend?.contract.state ?? objectSchema, actions: Object.entries(backend?.contract.functions ?? {}).map(([id, fn]) => ({ id, inputSchema: fn.input, resultSchema: fn.output })) });
+            return (await projectSourceFiles(directory)).map((file) => file.path);
+        });
+        return { name, directory: `@actors/${name}`, files };
     }
     async importPackage(context: CommandContext, runId: string, name: string, files: readonly ActorProgramSource[], signal?: AbortSignal, scriptEntryId?: string) {
-        this.#assertName(name);
-        const directory = path.join(await this.workspaceDirectory(runId), name);
-        if (await lstat(directory).then(() => true, () => false))
-            throw new Error(`Das Paket ${name} existiert bereits.`);
-        await mkdir(directory, { recursive: true });
+        const { directory } = await this.#create(runId, name, (staged) => this.#writeSources(staged, files));
         try {
-            await this.#writeSources(directory, files);
             if (scriptEntryId)
                 this.runtime().replacePluginState(this.operatorContext(runId), runId, { pluginId: ACTOR_SCRIPT_STATE_ID, scope: { kind: "run" }, state: { version: 1, entryId: scriptEntryId } });
             await this.activate(context, runId, name, signal);
@@ -251,7 +315,7 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
             throw new Error("Aufrufender Actor fehlt.");
         const provisional: ExecutableActor = owner ?? {
             id: "pending", handle: name, displayName: pkg.title, kind: "script", grants: caller.grants.filter((grant) => grant.delegable),
-            createdAt: new Date().toISOString(), createdBy: callerId, execution: { driver: { kind: "script", config: {} }, workspacePath: null, turnTimeoutMs: null }, lifecycle: { kind: "idle", since: new Date().toISOString() }, usage: emptyUsage(), toolNames: null, openedToolNames: [],
+            createdAt: new Date().toISOString(), createdBy: callerId, description: actorDescriptionOf(pkg.description) ?? null, execution: { driver: { kind: "script", config: {} }, workspacePath: null, turnTimeoutMs: null }, lifecycle: { kind: "idle", since: new Date().toISOString() }, usage: emptyUsage(), toolNames: null, openedToolNames: [],
         };
         const available = (await this.#options.agentToolsFor(runId, provisional.id, owner ? undefined : provisional)).map(descriptor);
         for (const operation of this.#options.operations.list())
@@ -259,7 +323,7 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
                 available.push(operation);
         await installServerSdk(directory, available);
         const backend = pkg.backend ? await compileAppBackend({ directory, backend: pkg.backend, runId, executor: this.runtime().nativeTypeScriptExecutor, signal }) : undefined;
-        const contract: import("./app-project.js").AppContract = backend?.contract ?? { state: objectSchema, functions: {} };
+        const contract: AppContract = backend?.contract ?? { state: objectSchema, functions: {} };
         if (contract.input && owner?.kind === "agent")
             throw new Error("Ein LLM-Actor verarbeitet Eingaben mit seinem Agententreiber; onInput ist nur für TypeScript-Actors erlaubt.");
         if (contract.state.type !== "object")
@@ -294,14 +358,16 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
         const hasServerFiles = pkg.backend || (await projectSourceFiles(directory)).some((file) => /^tests\/.*\.tsx?$/.test(file.path));
         const serverErrors = hasServerFiles ? typecheckServerProject(directory, pkg.backend) : [];
         if (serverErrors.length)
-            throw new Error(complaints(serverErrors, `Die Typprüfung von ${name} schlug ohne Meldung fehl.`));
+            throw checkFailure(`Typprüfung von ${name}`, serverErrors, `Die Typprüfung von ${name} schlug ohne Meldung fehl.`);
         const clients: CompiledProgram["clients"] = [];
         const views: ActorProgramDefinition["views"] = [];
         for (const view of pkg.views ?? []) {
             const client = await compileClientProject({ directory, entryPoint: view.client, stateSchema: contract.state, actions: functions.map((fn) => ({ id: fn.id, inputSchema: fn.inputSchema, resultSchema: fn.resultSchema })) });
             if (!client.valid)
-                throw new Error(complaints(client.diagnostics.map((item) => `${item.fileName} ${item.message}`),
-                    `Der Client-Build von ${view.client} schlug ohne Meldung fehl.`));
+                throw checkFailure(`Client-Build von ${view.client}`,
+                    client.diagnostics.filter((item) => item.category === "error").map((item) =>
+                        `${item.fileName ?? view.client}${item.start ? `:${item.start.line}:${item.start.column}` : ""} ${item.message.replace(/\s*\n\s*/g, " ")}`),
+                    `Der Client-Build von ${view.client} schlug ohne Meldung fehl.`);
             const styles = view.styles ? await inside(directory, view.styles) : "";
             if (/@import\b|url\s*\(\s*["']?\s*(?:https?:|\/\/)/i.test(styles))
                 throw new Error("Ansichts-CSS darf keine externen Ressourcen laden.");
@@ -337,13 +403,15 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
             const definition = compiled.definition;
             const tests = compiled.files.filter((file) => /^tests\/.*\.test\.tsx?$/.test(file.path));
             if (tests.length) {
-                const processContext = await this.#options.processContextFor(runId);
-                let output = "";
-                const result = await runManagedProcess({ command: process.execPath, args: ["--import", "tsx", "--test", ...tests.map((file) => file.path)], cwd: compiled.directory,
+                const processContext = await this.#options.serverProcessContextFor(runId);
+                const report = await createTestReport(compiled.directory);
+                let stderr = "";
+                const launch = await sandboxedLaunch(processContext, { command: process.execPath, args: ["--import", "tsx", "--test", testReporterArgument, ...tests.map((file) => file.path)] });
+                const result = await runManagedProcess({ command: launch.command, args: [...launch.args], cwd: compiled.directory,
                     env: processContext.env, uid: processContext.uid, gid: processContext.gid, label: `Tests ${name}`, signal, timeoutMs: 60000,
-                    onStdout: (chunk) => { output = (output + chunk.toString()).slice(-12000); }, onStderr: (chunk) => { output = (output + chunk.toString()).slice(-12000); } });
+                    onStdout: (chunk) => report.stdout(chunk.toString()), onStderr: (chunk) => { stderr = (stderr + chunk.toString()).slice(-12000); } });
                 if (result.code !== 0 || result.timedOut)
-                    throw new Error(`Tests für ${name} fehlgeschlagen:\n${output}`);
+                    throw new Error(report.report(name, { code: result.code, timedOut: result.timedOut, stderr }));
             }
             if (canonicalHash(compiled.files) !== canonicalHash(await projectSourceFiles(compiled.directory)))
                 throw new Error("Paketdateien wurden während der Prüfung geändert; erneut aktivieren.");
@@ -376,7 +444,7 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
                 await writeFile(path.join(definition.directory, client.file), client.javaScript);
             await writeFile(path.join(definition.directory, definition.stylesFile), compiled.frameStyles);
             await writeFile(path.join(definition.directory, "sources.json"), JSON.stringify(compiled.files));
-            await syncWorkspaceOwnership(definition.directory, await this.#options.processContextFor(runId));
+            await syncWorkspaceOwnership(definition.directory, await this.#options.serverProcessContextFor(runId));
             signal?.throwIfAborted();
             if (epoch !== this.invocationPermit(runId))
                 throw new Error("Der Run wurde während der Aktivierung gestoppt.");
@@ -399,8 +467,17 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
                 }
             jsonValue({ version: 1, program: definition }, "Actor-Programm");
             if (compiled.createActor) {
-                const caller = this.view(runId).actors.find((actor) => actor.id === context.actorId)!;
-                this.runtime().createScriptActor(context, runId, { handle: name, displayName: definition.title, grants: caller.grants.filter((grant) => grant.delegable), toolNames: null });
+                const actors = this.view(runId).actors;
+                const caller = actors.find((actor) => actor.id === context.actorId)!;
+                const holder = actors.find((actor) => actor.handle === name);
+                if (holder?.kind === "script" && holder.lifecycle.kind === "stopped") {
+                    checked(definition.stateSchema, this.data(runId, holder.id).values, "Actor-Zustand");
+                    this.runtime().restartActor(context, runId, holder.id, "Actor-Paket erneut aktiviert");
+                }
+                else if (holder)
+                    throw new Error(`Handle @${name} gehört bereits dem ${holder.kind !== "human" && holder.lifecycle.kind === "stopped" ? "gestoppten" : "aktiven"} Actor ${holder.displayName}; nur ein gestoppter TypeScript-Actor wird beim Aktivieren neu gestartet. Wähle einen anderen Paketnamen.`);
+                else
+                    this.runtime().createScriptActor(context, runId, { handle: name, displayName: definition.title, description: actorDescriptionOf(definition.description), grants: caller.grants.filter((grant) => grant.delegable), toolNames: null });
                 const actor = this.resolveActor(runId, context.actorId, `@${name}`);
                 definition.actorId = actor.id;
                 definition.actorHandle = actor.handle;
@@ -597,7 +674,7 @@ export class ActorProgramRuntime implements ActorProgramsService, ActorProgramEx
         return this.#start(runId, program, viewId, revision, functionId, requestId, input, permit);
     }
     startFunctionInvocation(runId: string, actorHandle: string, revision: string, functionId: string, requestId: string, input: unknown, permit = this.invocationPermit(runId)) {
-        const program = this.programs(runId).find((entry) => entry.actorHandle === actorHandle.replace(/^@/, ""));
+        const program = this.programs(runId).find((entry) => entry.actorHandle === handleKey(actorHandle));
         if (!program)
             throw new Error("Der Actor veröffentlicht kein Programm.");
         return this.#start(runId, program, program.name, revision, functionId, requestId, input, permit);

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

@@ -1,33 +1,24 @@
+import type { AppPackage } from "@ragents/host/plugin-support/actor-programs/app-project.js";
 import { controlsTemplate } from "./controls-template";
 
 export interface ActorProgramTemplate {
   id: string;
   title: string;
   description: string;
-  files: Readonly<Record<string, string>>;
+  ragents: AppPackage;
+  files: Readonly<Record<string, string>> & { readonly "package.json"?: never };
 }
 
 const blank: ActorProgramTemplate = {
   id: "blank",
   title: "Leere Mini-App",
   description: "Eine reine React-View am vorhandenen Actor ohne zusätzliche Serverfunktion.",
+  ragents: {
+    title: "Meine View",
+    description: "Eine kleine Bedienoberfläche des vorhandenen Actors.",
+    views: [{ id: "main", client: "src/client.tsx" }],
+  },
   files: {
-    "package.json": `{
-  "name": "actor-view",
-  "private": true,
-  "type": "module",
-  "ragents": {
-    "title": "Meine View",
-    "description": "Eine kleine Bedienoberfläche des vorhandenen Actors.",
-    "views": [
-      {
-        "id": "main",
-        "client": "src/client.tsx"
-      }
-    ]
-  }
-}
-`,
     "src/client.tsx": `import { createRoot } from "react-dom/client";
 import * as UI from "@ragents/client/ui";
 
@@ -48,25 +39,12 @@ const chat: ActorProgramTemplate = {
   id: "chat",
   title: "Actor-Chat",
   description: "Wiederverwendbarer Chat mit Verlauf und optionaler Eingabe an den Actor dieser View.",
+  ragents: {
+    title: "Actor-Chat",
+    description: "Zeigt das Gespräch mit einem Actor und sendet ihm Benutzereingaben.",
+    views: [{ id: "main", client: "src/client.tsx" }],
+  },
   files: {
-    "package.json": `{
-  "name": "actor-chat",
-  "private": true,
-  "type": "module",
-  "ragents": {
-    "title": "Actor-Chat",
-    "description": "Zeigt das Gespräch mit einem Actor und sendet ihm Benutzereingaben.",
-    "views": [
-      {
-        "id": "main",
-        "client": "src/client.tsx",
-        "width": 480,
-        "height": 420
-      }
-    ]
-  }
-}
-`,
     "src/client.tsx": `import { createRoot } from "react-dom/client";
 import * as UI from "@ragents/client/ui";
 import { context } from "@ragents/client";
@@ -86,24 +64,13 @@ const textAnalysis: ActorProgramTemplate = {
   id: "text-analysis",
   title: "Textanalyse",
   description: "Ein TypeScript-Actor analysiert Texte mit eigener Funktion, Zustand und React-View.",
+  ragents: {
+    title: "Textanalyse",
+    description: "Zählt Zeichen, Wörter und Zeilen und merkt sich die Zahl der Analysen.",
+    backend: "src/server.ts",
+    views: [{ id: "main", client: "src/client.tsx" }],
+  },
   files: {
-    "package.json": `{
-  "name": "text-analysis",
-  "private": true,
-  "type": "module",
-  "ragents": {
-    "title": "Textanalyse",
-    "description": "Zählt Zeichen, Wörter und Zeilen und merkt sich die Zahl der Analysen.",
-    "backend": "src/server.ts",
-    "views": [
-      {
-        "id": "main",
-        "client": "src/client.tsx"
-      }
-    ]
-  }
-}
-`,
     "src/client.tsx": `import React from "react";
 import { createRoot } from "react-dom/client";
 import { context, useAppState } from "@ragents/client";
@@ -200,18 +167,12 @@ const headlessCounter: ActorProgramTemplate = {
   id: "headless-counter",
   title: "Zähler ohne Oberfläche",
   description: "Ein TypeScript-Actor zählt Eingaben in seinem Zustand und bietet dieselbe Arbeit als Funktion an.",
+  ragents: {
+    title: "Zähler",
+    description: "Sammelt eingehende Texte ohne Modellaufrufe oder Oberfläche.",
+    backend: "src/server.ts",
+  },
   files: {
-    "package.json": `{
-  "name": "headless-counter",
-  "private": true,
-  "type": "module",
-  "ragents": {
-    "title": "Zähler",
-    "description": "Sammelt eingehende Texte ohne Modellaufrufe oder Oberfläche.",
-    "backend": "src/server.ts"
-  }
-}
-`,
     "src/contract.ts": `import { Type } from "typebox";
 
 const state = Type.Object({
@@ -285,24 +246,13 @@ const sharedList: ActorProgramTemplate = {
   id: "shared-list",
   title: "Gemeinsame Liste eines Actors",
   description: "Ein Actor besitzt eine Funktion und eine React-View für denselben Listenstand.",
+  ragents: {
+    title: "Gemeinsame Liste",
+    description: "Sammelt Texte aus der App und aus einem Agenten-Werkzeug in einer gemeinsamen Liste.",
+    backend: "src/server.ts",
+    views: [{ id: "main", client: "src/client.tsx" }],
+  },
   files: {
-    "package.json": `{
-  "name": "shared-list",
-  "private": true,
-  "type": "module",
-  "ragents": {
-    "title": "Gemeinsame Liste",
-    "description": "Sammelt Texte aus der App und aus einem Agenten-Werkzeug in einer gemeinsamen Liste.",
-    "backend": "src/server.ts",
-    "views": [
-      {
-        "id": "main",
-        "client": "src/client.tsx"
-      }
-    ]
-  }
-}
-`,
     "src/client.tsx": `import React from "react";
 import { createRoot } from "react-dom/client";
 import { context, useAppState } from "@ragents/client";
@@ -393,6 +343,11 @@ test("ergänzt Einträge ohne vorhandene Einträge zu verlieren", async () => {
 
 export const runModuleTemplates = [blank, chat, controlsTemplate, textAnalysis, headlessCounter, sharedList] as const;
 
+export const templateFiles = (template: ActorProgramTemplate, name: string): Readonly<Record<string, string>> => ({
+  "package.json": `${JSON.stringify({ name, private: true, type: "module", ragents: template.ragents }, null, 2)}\n`,
+  ...template.files,
+});
+
 export const templateById = (id: string): ActorProgramTemplate => {
   const template = runModuleTemplates.find((candidate) => candidate.id === id);
   if (!template) throw new Error(`Unbekannte Actor-Programm-Vorlage ${id}. Gültig: ${runModuleTemplates.map((entry) => entry.id).join(", ")}.`);

package/plugins/ragents.actor-programs/server/test-report.ts

@@ -0,0 +1,106 @@
+import { realpath } from "node:fs/promises";
+
+/** A node:test reporter that writes one JSON line per passed test, failed test and stderr line of a test file. */
+const reporterSource = `
+import { inspect } from "node:util";
+const shown = (value) => inspect(value, { depth: 4, breakLength: Infinity, maxArrayLength: 20, maxStringLength: 200 }).slice(0, 300);
+export default async function* (source) {
+  for await (const { type, data } of source) {
+    if (type === "test:pass" && data.details?.type !== "suite") yield JSON.stringify({ kind: "pass" }) + "\\n";
+    if (type === "test:fail" && data.details?.type !== "suite" && data.details?.error?.failureType !== "subtestsFailed") {
+      const error = data.details.error;
+      const cause = error.cause instanceof Error ? error.cause : error;
+      const assertion = cause.code === "ERR_ASSERTION";
+      yield JSON.stringify({ kind: "fail", name: data.name, file: data.file ?? null, line: data.line ?? null, column: data.column ?? null,
+        message: String(cause.message), generated: cause.generatedMessage === true, stack: String(cause.stack ?? ""),
+        ...(assertion ? { expected: shown(cause.expected), actual: shown(cause.actual) } : {}) }) + "\\n";
+    }
+    if (type === "test:stderr") yield JSON.stringify({ kind: "stderr", file: data.file ?? null, message: String(data.message) }) + "\\n";
+  }
+}
+`;
+
+export const testReporterArgument = `--test-reporter=data:text/javascript,${encodeURIComponent(reporterSource)}`;
+
+type TestRecord =
+    | { kind: "pass" }
+    | { kind: "fail"; name: string; file: string | null; line: number | null; column: number | null; message: string; generated: boolean; stack: string; expected?: string; actual?: string }
+    | { kind: "stderr"; file: string | null; message: string };
+
+const maxDetailed = 10;
+const frameLine = /^\s+at /;
+
+/** The lines of an error output that name the error, without stack frames, code excerpts and the Node version. */
+const errorLines = (lines: readonly string[]): string[] => {
+    const meaningful = lines.map((line) => line.trimEnd()).filter((line) => line.trim() !== "" && !frameLine.test(line) && !/^Node\.js v\d/.test(line) && !/^\s*\^+$/.test(line));
+    const named = meaningful.filter((line) => /^[A-Za-z]*Error\b/.test(line));
+    return (named.length > 0 ? named : meaningful.slice(-5)).slice(0, 5);
+};
+
+/** Collects the reporter lines of a test run and turns them into a short failure report: counts, and per failed test its name, message, expected and actual values and its place in the program. */
+export const createTestReport = async (directory: string) => {
+    const roots = [...new Set([directory, await realpath(directory)])].sort((left, right) => right.length - left.length);
+    const relative = (text: string): string => roots.reduce((result, root) => result.replaceAll(`file://${root}/`, "").replaceAll(`${root}/`, ""), text);
+    const failures: Extract<TestRecord, { kind: "fail" }>[] = [];
+    const stderrByFile = new Map<string, string[]>();
+    const unparsed: string[] = [];
+    let passed = 0;
+    let failed = 0;
+    let pending = "";
+
+    const record = (line: string): void => {
+        if (line.trim() === "") return;
+        let parsed: TestRecord;
+        try {
+            parsed = JSON.parse(line) as TestRecord;
+        } catch {
+            unparsed.push(line);
+            return;
+        }
+        if (parsed.kind === "pass") passed += 1;
+        if (parsed.kind === "fail") {
+            failed += 1;
+            if (failures.length < maxDetailed) failures.push(parsed);
+        }
+        if (parsed.kind === "stderr") {
+            const lines = stderrByFile.get(parsed.file ?? "") ?? [];
+            stderrByFile.set(parsed.file ?? "", [...lines, ...parsed.message.split("\n")].slice(-50));
+        }
+    };
+
+    const placeOf = (failure: Extract<TestRecord, { kind: "fail" }>): string => {
+        const frame = failure.stack.split("\n").filter((line) => frameLine.test(line)).map(relative)
+            .map((line) => /\(?([^\s()]+:\d+:\d+)\)?\s*$/.exec(line)?.[1])
+            .find((place) => place !== undefined && !place.startsWith("/") && !place.startsWith("node:") && !place.includes("node_modules/"));
+        const declared = failure.file === null ? failure.name : `${relative(failure.file)}${failure.line === null ? "" : `:${failure.line}:${failure.column ?? 1}`}`;
+        return frame ?? declared;
+    };
+
+    const describe = (failure: Extract<TestRecord, { kind: "fail" }>): string => {
+        const fileOutput = failure.message === "test failed" && failure.file !== null ? stderrByFile.get(failure.file) ?? stderrByFile.get(relative(failure.file)) : undefined;
+        const message = fileOutput ? errorLines(fileOutput).join("; ") : failure.generated ? failure.message.split("\n")[0]!.replace(/:$/, "") : failure.message.trim().slice(0, 500);
+        const values = failure.expected === undefined || failure.expected === failure.actual ? "" : ` - erwartet ${failure.expected}, tatsächlich ${failure.actual}`;
+        return `- ${failure.name} (${placeOf(failure)}): ${relative(message)}${relative(values)}`;
+    };
+
+    return {
+        stdout: (chunk: string): void => {
+            const lines = (pending + chunk).split("\n");
+            pending = lines.pop() ?? "";
+            lines.forEach(record);
+        },
+        report: (name: string, outcome: { code: number | null; timedOut: boolean; stderr: string }): string => {
+            record(pending);
+            pending = "";
+            const summary = outcome.timedOut
+                ? `Tests für ${name} nach Zeitüberschreitung abgebrochen: ${passed} bestanden, ${failed} fehlgeschlagen.`
+                : `Tests für ${name} fehlgeschlagen: ${passed} bestanden, ${failed} fehlgeschlagen.`;
+            const details = failures.map(describe);
+            const more = failed > failures.length ? [`... und ${failed - failures.length} weitere`] : [];
+            const withoutResult = failed === 0
+                ? [`Der Testlauf endete${outcome.code === null ? "" : ` mit Code ${outcome.code}`} ohne fehlgeschlagenen Test:`, ...errorLines([...unparsed, ...outcome.stderr.split("\n")]).map(relative)]
+                : [];
+            return [summary, ...details, ...more, ...withoutResult].join("\n");
+        },
+    };
+};

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

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
-import { defineRunFunction, defineToolAvailability, holdsUsable, type RunFunction, type ToolContributor } from "@aicontainer/ragents";
-import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { defineRunFunction, defineToolAvailability, holdsUsable, type RunFunction, type ToolContributor } from "@ragents/engine";
+import { toolDescriptorFrom } from "@ragents/host/plugin-support/agent-tool.js";
 import type { ActorProgramRuntime } from "./runtime.js";
 import type { createProjectDiagnostics } from "./project-diagnostics.js";
 const metadata = [
@@ -8,7 +8,7 @@ const metadata = [
     { name: "actor_program_activate", label: "Activate Actor Program", description: "Typecheck, build and test a package, then activate its functions and optional views.", longDescription: "actor self or @handle attaches to an existing actor; omitted creates a TypeScript actor for a backend, or attaches static views to self." },
     { name: "actor_program_list", label: "List Actor Programs", description: "List active actor packages, functions and views." },
     { name: "actor_program_remove", label: "Remove Actor Program", description: "Detach functions and views and stop the backend.", longDescription: "A TypeScript actor is stopped; an LLM actor retains its agent behavior." },
-    { name: "actor_view_set_visibility", label: "Show or hide Actor View", description: "Set Canvas visibility by package-name/view-key or @handle/view-key.", longDescription: "Use names you chose; the server resolves the view ID. A unique view title also works." },
+    { name: "actor_view_set_visibility", label: "Show or hide Actor View", description: "Set surface visibility by package-name/view-key or @handle/view-key.", longDescription: "Use names you chose; the server resolves the view ID. A unique view title also works." },
     { name: "actor_program_diagnostics", label: "Actor Program Diagnostics", description: "Read the last project diagnostics.", longDescription: "Changed errors are automatically supplied before the next model request." },
 ] as const;
 export const actorProgramManagementToolNames = metadata.map((entry) => entry.name);
@@ -20,7 +20,7 @@ const managementTools = (runtime: ActorProgramRuntime, diagnostics: Diagnostics)
     defineRunFunction({ ...metadata[1], schema: Type.Object({ name, actor: Type.Optional(Type.String()) }, { additionalProperties: false }), resultSchema: Type.Object({ name: Type.String(), actor: Type.String(), views: Type.Number(), active: Type.Literal(true) }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.activate(scope.context(id), scope.caller.runId, input.name, scope.signal, input.actor) }),
     defineRunFunction({ ...metadata[2], schema: Type.Object({}, { additionalProperties: false }), resultSchema: Type.Array(Type.Object({ name: Type.String(), actor: Type.String(), functions: Type.Array(Type.String()), views: Type.Array(Type.Object({ name: Type.String(), title: Type.String(), visible: Type.Boolean() })) })), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope) => runtime.list(scope.caller.runId) }),
     defineRunFunction({ ...metadata[3], schema: Type.Object({ name }, { additionalProperties: false }), resultSchema: Type.Object({ removed: Type.String() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.remove(scope.context(id), scope.caller.runId, input.name) }),
-    defineRunFunction({ ...metadata[4], schema: Type.Object({ view: Type.String({ minLength: 1, description: "package-name/view-key or @handle/view-key of an activated view, without the Canvas entity prefix app:. No generated IDs needed." }), visible: Type.Boolean() }, { additionalProperties: false }), resultSchema: Type.Object({ view: Type.String(), visible: Type.Boolean() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.setVisibility(scope.context(id), scope.caller.runId, input.view, input.visible) }),
+    defineRunFunction({ ...metadata[4], schema: Type.Object({ view: Type.String({ minLength: 1, description: "package-name/view-key or @handle/view-key of an activated view, without the surface entity prefix app:. No generated IDs needed." }), visible: Type.Boolean() }, { additionalProperties: false }), resultSchema: Type.Object({ view: Type.String(), visible: Type.Boolean() }, { additionalProperties: false }), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, id, input) => runtime.setVisibility(scope.context(id), scope.caller.runId, input.view, input.visible) }),
     defineRunFunction({ ...metadata[5], schema: Type.Object({ name: Type.Optional(name) }, { additionalProperties: false }), resultSchema: Type.String(), available: actorProgramToolsAvailable, executionMode: "sequential", run: (scope, _id, input) => diagnostics.latest(scope.caller.runId, scope.caller.actorId, input.name) }),
 ];
 export const createActorProgramToolContributors = (runtime: ActorProgramRuntime, diagnostics: Diagnostics): readonly ToolContributor[] => [

package/plugins/ragents.actor-programs/summary.hbs

@@ -2,7 +2,7 @@
 
 Use TypeScript snippets for one-time work. Actors can own functions, shared state and React views. Create the closest template with
 `actor_program_create`, read its existing files in `@actors/<name>/`, adapt what is needed,
-then `actor_program_activate`. Reuse its code and tests; Bash uses `$RAGENTS_ACTORS_DIR`.
+then `actor_program_activate`. Reuse its code and tests; `bash` runs there with `cwd: "@actors/<name>"`.
 Call these functions through `context.functions` in `typescript_eval`; `typescript_api` gives
 the current contracts. Published actor functions join that same API during the current turn.
 Bind existing actors with `self` or `@handle`. A backend without a binding creates a TypeScript