@schlenkr/ragents 0.1.0

package/plugins/ragents.reference/run-scripts/learning-afternoon/tests/program.test.ts

@@ -0,0 +1,223 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ActorInput, CapabilityContracts } from "@ragents/server";
+import { createTestContext } from "@ragents/server/testing";
+import program from "../src/server.ts";
+import type { LearningState } from "../src/state.ts";
+
+const inputOf = (content: string): ActorInput => ({ id: "input", content, artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null });
+const setupInput = inputOf(JSON.stringify({ input: null, options: {} }));
+const startInput = inputOf("START_LEARNING_AFTERNOON");
+const eventOf = (helper: string, type: string, payload: Record<string, unknown>, eventId = `${helper}-${type}`): ActorInput => ({
+  ...inputOf(""),
+  subscriptionId: "ideas",
+  sourceEventIds: [eventId],
+  event: { type, eventId, sequence: 1, occurredAt: "2026-09-13T12:00:00.000Z", sourceActorId: `actor-learning-${helper}`, sourceActorHandle: `learning-${helper}`, payload: { turnId: `turn-${helper}`, ...payload } },
+});
+
+function setup(options: { missingProfile?: boolean; failDispatch?: string; beforeDispatch?: (actor: string) => Promise<void> } = {}) {
+  const calls: { name: string; input: unknown }[] = [];
+  const history: CapabilityContracts["event_query"]["output"] = [];
+  const functions = Object.fromEntries([
+    "model_list", "agent_spawn", "canvas_layout_replace", "run_configure", "actor_input", "event_subscribe", "event_unsubscribe", "event_query",
+  ].map((name) => [name, async (input: unknown) => {
+    calls.push({ name, input });
+    if (name === "model_list") return { profiles: options.missingProfile ? [] : [{ name: "standard", driver: "agent", description: "Testprofil", turnTimeoutMs: null, isolateWorkspace: false, provider: "test", model: "test" }], models: [] };
+    if (name === "agent_spawn") {
+      const handle = (input as { handle: string }).handle;
+      return { id: `actor-${handle}`, handle };
+    }
+    if (name === "event_subscribe") return {
+      subscriptionId: "ideas", subscriberId: "test-actor", sourceActorIds: ["actor-learning-experiment", "actor-learning-quiz"],
+      sources: ["@learning-experiment", "@learning-quiz"], sourceActorKinds: null,
+      eventTypes: ["turn.finished", "turn.interrupted", "actor.stopped"], includeSelf: false,
+      createdBy: "test-actor", createdAt: "2026-09-13T12:00:00.000Z", createdSequence: 1, status: "active",
+    };
+    if (name === "event_query") return history.filter((event) => (input as { actorIds: string[] }).actorIds.includes(event.actorId));
+    if (name === "actor_input") {
+      const actor = (input as { actor: string }).actor;
+      await options.beforeDispatch?.(actor);
+      if (actor === options.failDispatch) throw new Error("Auftrag konnte nicht gesendet werden.");
+      return [{ type: "actor.input.enqueued", payload: { actorId: `actor-${actor.slice(1)}`, inputId: `input-${actor.slice(1)}` } }];
+    }
+    return [];
+  }]));
+  return { calls, context: Object.assign(createTestContext<{ board?: LearningState; subscriptionId?: string }>({ state: {}, functions }), { history }) };
+}
+
+function record(context: ReturnType<typeof setup>["context"], helper: string, type: string, payload: Record<string, unknown>) {
+  context.history.push({ eventId: `event-${context.history.length}`, actorId: `actor-learning-${helper}`, causationId: null, commandId: "test", correlationId: null,
+    occurredAt: "2026-09-13T12:00:00Z", runId: "test", schemaVersion: 3, sequence: context.history.length + 1, type, payload: { turnId: `turn-${helper}`, ...payload } });
+}
+
+async function begin(context: ReturnType<typeof setup>["context"]) {
+  await program.onInput(setupInput, context);
+  await program.onInput(startInput, context);
+  for (const helper of ["experiment", "quiz"]) record(context, helper, "turn.started", { inputId: `input-learning-${helper}` });
+}
+
+async function complete(context: ReturnType<typeof setup>["context"], helper: string, text: string) {
+  record(context, helper, "model.output.completed", { text });
+  await program.onInput(eventOf(helper, "turn.finished", { outcome: "completed" }), context);
+}
+
+test("Start richtet nur zwei reine Helfer und die eigene App ein; erst der Button stellt einen Auftrag an den Besitzer", async () => {
+  const { context, calls } = setup();
+  await program.onInput(setupInput, context);
+  assert.equal(context.state.read().board?.phase, "ready");
+  assert.equal(calls.filter((call) => call.name === "agent_spawn").length, 2);
+  for (const call of calls.filter((call) => call.name === "agent_spawn")) {
+    assert.deepEqual((call.input as { tools: string[] }).tools, []);
+    assert.equal((call.input as { profile: string }).profile, "standard");
+  }
+  assert.equal(calls.some((call) => call.name === "actor_input" || call.name === "event_subscribe"), false);
+  const before = structuredClone(context.state.read());
+  const callCount = calls.length;
+  await assert.rejects(async () => program.onInput(setupInput, context), /keine freien Chatnachrichten/);
+  assert.deepEqual(context.state.read(), before);
+  assert.equal(calls.length, callCount);
+  await program.functions.start({}, context);
+  assert.deepEqual(calls.at(-1), { name: "actor_input", input: { actor: "@test", content: "START_LEARNING_AFTERNOON" } });
+  assert.equal(context.state.read().board?.phase, "ready");
+});
+
+test("der Input-Handler abonniert zuerst und sendet beide unabhängigen Aufträge parallel genau einmal", async () => {
+  const pending: (() => void)[] = [];
+  const { context, calls } = setup({ beforeDispatch: () => new Promise<void>((resolve) => pending.push(resolve)) });
+  await program.onInput(setupInput, context);
+  const starting = program.onInput(startInput, context);
+  for (let attempt = 0; attempt < 20 && pending.length < 2; attempt++) await Promise.resolve();
+  assert.equal(pending.length, 2, "Beide Inputs beginnen, bevor einer fertig ist.");
+  assert.equal(calls.filter((call) => call.name === "event_subscribe").length, 1);
+  for (const resolve of pending) resolve();
+  await starting;
+  await program.onInput(startInput, context);
+  await program.functions.start({}, context);
+  assert.equal(calls.filter((call) => call.name === "actor_input").length, 2);
+  assert.equal(context.state.read().board?.phase, "working");
+});
+
+for (const phase of ["ready", "working", "complete"]) {
+  test(`freie Chatnachrichten werden bei ${phase} abgelehnt und erhalten die Ideen`, async () => {
+    const { context, calls } = setup();
+    if (phase === "ready") {
+      await program.onInput(setupInput, context);
+    } else {
+      await begin(context);
+      await complete(context, "experiment", "Die Experimentidee ist fertig.");
+      if (phase === "complete") await complete(context, "quiz", "Die Quizidee ist fertig.");
+    }
+    assert.equal(context.state.read().board?.phase, phase);
+    const before = structuredClone(context.state.read());
+    const callCount = calls.length;
+    const content = "Sammle bitte noch einmal neue Ideen für den Lernnachmittag.";
+    await assert.rejects(async () => program.onInput(inputOf(content), context), /keine freien Chatnachrichten.*Startknopf.*neuer Run/);
+    assert.deepEqual(context.state.read(), before);
+    assert.equal(calls.length, callCount);
+    if (phase === "ready") {
+      await program.onInput(startInput, context);
+      assert.equal(context.state.read().board?.phase, "working");
+    } else if (phase === "working") {
+      await complete(context, "quiz", "Die Quizidee ist fertig.");
+      assert.equal(context.state.read().board?.phase, "complete");
+      assert.equal(context.state.read().board?.helpers[0]?.text, "Die Experimentidee ist fertig.");
+    }
+  });
+}
+
+for (const order of [["experiment", "quiz"], ["quiz", "experiment"]]) {
+  test(`sammelt Antworten in beliebiger Reihenfolge: ${order.join(", ")}`, async () => {
+    const { context, calls } = setup();
+    await begin(context);
+    await complete(context, order[0]!, "Erste echte Antwort");
+    assert.equal(context.state.read().board?.phase, "working");
+    await complete(context, order[1]!, "Zweite echte Antwort");
+    const board = context.state.read().board!;
+    assert.equal(board.phase, "complete");
+    assert.equal(board.helpers.find((helper) => helper.id === order[0])?.text, "Erste echte Antwort");
+    assert.equal(board.helpers.find((helper) => helper.id === order[1])?.text, "Zweite echte Antwort");
+    assert.equal(calls.filter((call) => call.name === "event_unsubscribe").length, 1);
+    for (let count = 0; count < 10; count++) await complete(context, order[0]!, "Späte Antwort");
+    assert.deepEqual(context.state.read().board, board);
+    assert.equal(calls.filter((call) => call.name === "actor_input").length, 2);
+  });
+}
+
+test("ignoriert falsche Actors, Inputs, Turns, Abos und doppelte Antworten", async () => {
+  const { context } = setup();
+  await program.onInput(setupInput, context);
+  await program.onInput(startInput, context);
+  record(context, "experiment", "turn.started", { inputId: "fremd", turnId: "fremd" });
+  record(context, "experiment", "model.output.completed", { text: "Fremd", turnId: "fremd" });
+  record(context, "experiment", "turn.started", { inputId: "input-learning-experiment" });
+  record(context, "experiment", "model.output.completed", { text: "Meine Idee" });
+  const before = context.state.read();
+  await program.onInput(eventOf("foreign", "turn.finished", { outcome: "completed" }), context);
+  await program.onInput(eventOf("experiment", "turn.finished", { outcome: "completed", turnId: "fremd" }), context);
+  await program.onInput({ ...eventOf("experiment", "turn.finished", { outcome: "completed" }), subscriptionId: "fremd" }, context);
+  assert.deepEqual(context.state.read(), before);
+  const answer = eventOf("experiment", "turn.finished", { outcome: "completed" });
+  await program.onInput(answer, context);
+  await program.onInput(answer, context);
+  assert.equal(context.state.read().board?.helpers[0]?.text, "Meine Idee");
+  assert.equal(context.state.read().board?.helpers[0]?.status, "complete");
+});
+
+for (const ending of ["failed", "interrupted", "empty", "stopped"]) {
+  test(`ein ${ending}-Ergebnis erhält die erfolgreiche Idee des anderen Helfers`, async () => {
+    const { context, calls } = setup();
+    await begin(context);
+    await complete(context, "quiz", "Das Quiz ist fertig.");
+    await program.onInput(eventOf("experiment", ending === "stopped" ? "actor.stopped" : ending === "interrupted" ? "turn.interrupted" : "turn.finished", { outcome: ending === "empty" ? "completed" : "failed", ...(ending === "empty" ? {} : { reason: "Modellfehler" }) }), context);
+    assert.equal(context.state.read().board?.phase, "error");
+    assert.equal(context.state.read().board?.helpers[0]?.status, "error");
+    assert.ok(context.state.read().board?.helpers[0]?.error);
+    assert.equal(context.state.read().board?.helpers[1]?.text, "Das Quiz ist fertig.");
+    assert.equal(calls.filter((call) => call.name === "actor_input").length, 2);
+    assert.equal(calls.filter((call) => call.name === "event_unsubscribe").length, 1);
+  });
+}
+
+test("ein gescheiterter Input verhindert den Auftrag des anderen Helfers nicht", async () => {
+  const { context } = setup({ failDispatch: "@learning-experiment" });
+  await begin(context);
+  assert.equal(context.state.read().board?.helpers[0]?.status, "error");
+  assert.equal(context.state.read().board?.phase, "working");
+  await complete(context, "quiz", "Eine Quizidee.");
+  assert.equal(context.state.read().board?.phase, "error");
+  assert.equal(context.state.read().board?.helpers[1]?.status, "complete");
+});
+
+test("ohne Standardprofil wird kein Helfer angelegt", async () => {
+  const { context, calls } = setup({ missingProfile: true });
+  await assert.rejects(async () => program.onInput(setupInput, context), /Modellprofil standard fehlt/);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list"]);
+  assert.deepEqual(context.state.read(), {});
+});
+
+test("der gemeinsame Ablauf liefert Helferaufträge, Prompt und parallele Graphzweige", async () => {
+  const { learningWorkflow, helperSteps } = await import("../src/workflow.ts");
+  const { learningWorkflowState, initialState } = await import("../src/state.ts");
+  const { workflowGraph } = await import("@ragents/workflow");
+  const { context, calls } = setup();
+  await begin(context);
+  const spawns = calls.filter((call) => call.name === "agent_spawn");
+  assert.equal(spawns.length, helperSteps.length);
+  for (const spawn of spawns) {
+    const prompt = (spawn.input as { prompt: string }).prompt;
+    assert.match(prompt, /Bearbeite ausschließlich diese Aufgabe/);
+    assert.match(prompt, /Beispielfrage/);
+    assert.match(prompt, /gefährliche Stoffe/);
+  }
+  assert.deepEqual(calls.filter((call) => call.name === "actor_input").map((call) => (call.input as { content: string }).content), helperSteps.map((step) => step.goal));
+  const initial = workflowGraph(learningWorkflow, learningWorkflowState(initialState));
+  assert.ok(initial.nodes.every((node) => node.status === "pending"));
+  assert.deepEqual(initial.edges.map((edge) => [edge.source, edge.target]), [["experiment", "collect"], ["quiz", "collect"]]);
+  await complete(context, "quiz", "Eine Quizidee.");
+  const partial = workflowGraph(learningWorkflow, learningWorkflowState(context.state.read().board!));
+  assert.deepEqual(partial.nodes.map((node) => [node.id, node.status]), [["experiment", "active"], ["quiz", "done"], ["collect", "active"]]);
+  await program.onInput(eventOf("experiment", "actor.stopped", {}), context);
+  const failed = workflowGraph(learningWorkflow, learningWorkflowState(context.state.read().board!));
+  assert.deepEqual(failed.nodes.map((node) => [node.id, node.status]), [["experiment", "blocked"], ["quiz", "done"], ["collect", "blocked"]]);
+  assert.match(failed.nodes.find((node) => node.id === "collect")!.detail!, /1 von 2/);
+});

package/plugins/ragents.reference/run-scripts/moderated-round/RUN.md

@@ -0,0 +1,12 @@
+---
+title: Moderierte Runde ohne Koordinator
+description: "Ein vorbereiteter Aufbau zeigt einen Run, der von Anfang an ohne Koordinator arbeitet. Der Moderator wird Primary-Actor und direkter Ansprechpartner im Chat."
+order: 130
+coordinator: false
+tags: Run-Scripts, Anwendungsfall, Konzeptdemo, Primary-Actor, Agententeams
+---
+
+Referenzfall für `coordinator: false`: der Host spawnt keinen Koordinator, das Script wählt mit
+`run_configure` den Moderator als Primary-Actor und setzt den Run-Titel. Der Chat bindet sich, sobald
+der Primary-Actor feststeht. Der Moderator behält seinen eigenen Actor-Prompt auch als Primary-Actor; den konkreten Auftrag
+erhält er über den ersten ActorInput. Ein Startwert `{ "topic": "..." }` setzt das Thema.

package/plugins/ragents.reference/run-scripts/moderated-round/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "moderated-round",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Moderierte Runde ohne Koordinator",
+    "backend": "src/server.ts"
+  }
+}

package/plugins/ragents.reference/run-scripts/moderated-round/src/server.ts

@@ -0,0 +1,60 @@
+import { defineActor } from "@ragents/server";
+import { Type } from "typebox";
+
+const contract = {
+  state: Type.Object({ built: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+  functions: {},
+  input: { capabilities: ["model_list", "agent_spawn", "run_configure", "actor_input"] },
+} as const;
+
+type Start = { input: { topic?: string } | null };
+
+const guestOf = (name: string): string =>
+  name === "kai" ? "Du bist Kai, pragmatisch und knapp." : "Du bist Lena, gründlich und abwägend.";
+
+export default defineActor(contract, {
+  functions: {},
+  onInput: async (input, context) => {
+    const state = context.state.read();
+    if (state && state.built) return;
+    const start = JSON.parse(input.content) as Start;
+    const topic = start.input && start.input.topic ? start.input.topic : "Was macht ein gutes Team aus?";
+
+    const catalog = await context.functions.model_list({});
+    const profiles = catalog.profiles.filter((profile) => profile.driver === "agent" && profile.name !== "coordinator");
+    const first = profiles[0];
+    if (!first) throw new Error("Kein Agentenprofil außer dem Koordinator; agent_spawn braucht eines.");
+
+    const moderator = await context.functions.agent_spawn({
+      handle: "moderator",
+      displayName: "Moderator",
+      prompt: "Du moderierst eine Gesprächsrunde zwischen dem Benutzer und zwei Gästen.",
+      profile: first.name,
+      tools: ["actor_input", "event_subscribe", "event_unsubscribe", "event_subscription_list"],
+    });
+    const guests: string[] = [];
+    for (const name of ["kai", "lena"]) {
+      const guest = await context.functions.agent_spawn({
+        handle: name,
+        prompt: `${guestOf(name)} Antworte mit höchstens zwei Sätzen.`,
+        profile: first.name,
+        tools: [],
+      });
+      guests.push(`@${guest.handle}`);
+    }
+
+    await context.functions.run_configure({
+      title: `Moderierte Runde: ${topic}`,
+      primaryActor: `@${moderator.handle}`,
+    });
+
+    await context.functions.actor_input({
+      actor: `@${moderator.handle}`,
+      content: "Du bist der Moderator dieses Runs und sprichst direkt mit dem Benutzer im Chat; einen Koordinator gibt es nicht. "
+        + `Deine Gäste sind ${guests.join(" und ")}. Hole ihre Beiträge ein und beziehe sie in die Gesprächsrunde ein. `
+        + `Thema: "${topic}". Begrüße den Benutzer mit zwei Sätzen, nenne das Thema und frage, ob er die erste Frage stellt oder du beginnen sollst.`,
+    });
+
+    context.state.replace({ built: true });
+  },
+});

package/plugins/ragents.reference/run-scripts/moderated-round/tests/helpers.ts

@@ -0,0 +1,26 @@
+import { createTestContext } from "@ragents/server/testing";
+
+export const setupContext = (profiles = [{ name: "coordinator", driver: "agent" }, { name: "standard", driver: "agent" }]) => {
+  const calls: { name: string; input: unknown }[] = [];
+  const functions = Object.fromEntries(["model_list", "agent_spawn", "run_configure", "actor_input", "canvas_layout_replace", "actor_program_activate"].map((name) => [name, (input: unknown) => {
+    calls.push({ name, input });
+    if (name === "agent_spawn") {
+      const handle = (input as { handle: string }).handle;
+      return { id: `actor-${handle}`, handle };
+    }
+    if (name === "actor_program_activate") {
+      const value = input as { name: string; actor: string };
+      return { name: value.name, actor: value.actor, views: 1, active: true };
+    }
+    return name === "model_list" ? {
+      profiles: profiles.map((profile) => ({ ...profile, description: "Testprofil", turnTimeoutMs: null,
+        isolateWorkspace: false, provider: "test", model: "test" })), models: [],
+    } : [];
+  }]));
+  return { calls, context: createTestContext<{ built?: boolean }>({ state: {}, functions }) };
+};
+
+export const startInput = (input: unknown) => ({
+  id: "start", content: JSON.stringify({ input, options: {} }), artifactIds: [],
+  sourceEventIds: [], subscriptionId: null, event: null,
+});

package/plugins/ragents.reference/run-scripts/moderated-round/tests/program.test.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import program from "../src/server.ts";
+import { setupContext, startInput } from "./helpers.ts";
+
+test("stellt Moderator und Gäste auf und übergibt ihm den Chat", async () => {
+  const { calls, context } = setupContext();
+  await program.onInput!(startInput({ topic: "Gute Zusammenarbeit" }), context);
+  assert.deepEqual(calls.filter((call) => call.name === "agent_spawn").map((call) => (call.input as { handle: string }).handle), ["moderator", "kai", "lena"]);
+  assert.deepEqual(calls.filter((call) => call.name === "agent_spawn").map((call) => (call.input as { tools: string[] }).tools), [["actor_input", "event_subscribe", "event_unsubscribe", "event_subscription_list"], [], []]);
+  assert.deepEqual(calls.find((call) => call.name === "run_configure")?.input, { title: "Moderierte Runde: Gute Zusammenarbeit", primaryActor: "@moderator" });
+  assert.match(JSON.stringify(calls.at(-1)), /Gute Zusammenarbeit/);
+  assert.deepEqual(context.state.read(), { built: true });
+  const completedCalls = calls.length;
+  await program.onInput!(startInput(null), context);
+  assert.equal(calls.length, completedCalls);
+});
+
+test("ohne ein nutzbares Agentenprofil bleibt der Aufbau unverändert", async () => {
+  const { calls, context } = setupContext([{ name: "coordinator", driver: "agent" }]);
+  await assert.rejects(async () => program.onInput!(startInput(null), context), /Kein Agentenprofil/);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list"]);
+  assert.deepEqual(context.state.read(), {});
+});

package/plugins/ragents.reference/run-scripts/shared-actor-list/RUN.md

@@ -0,0 +1,18 @@
+---
+title: Sammelboard einrichten
+description: "Ein vorbereitetes Setup zeigt einen LLM-Listenhelfer mit eigener Funktion, Mini-App und gemeinsamem Zustand. Ein Startleitfaden legt Titel und ersten Eintrag fest."
+order: 100
+guide: ragents.reference.shared-actor-list
+tags: Run-Scripts, Anwendungsfall, Konzeptdemo, Startleitfaden, Actor-Funktionen, Actor-Zustand, Mini-Apps, LLM-Actor mit View
+---
+
+Das Setup legt einen echten LLM-Listenhelfer an und bindet das mitgelieferte Programm
+`actors/shared-list/` an ihn. Seine Funktion `append_to_list` und die React-View teilen den
+intrinsischen Zustand dieses Actors. `actor_program_activate` prüft und aktiviert das bereits
+vom Host kopierte Paket. Ein eigener App-Actor oder eine zweite Listenimplementierung entsteht nicht.
+
+Der Leitfaden übergibt `{ "title": "...", "firstEntry": "..." }`. Der Titel hat 1 bis 160 Zeichen,
+der erste Eintrag 1 bis 2000 Zeichen. `null` startet mit "Gemeinsame Liste" und
+"Hallo aus dem Run-Script". Ungültige Werte werden vor dem Aufbau abgelehnt. Nach dem Aufbau
+bekommt der Listenhelfer den ausdrücklichen Auftrag, den ersten Eintrag über seine Funktion
+anzulegen. Die Pakettests prüfen Konfiguration, Zustand und die tatsächliche Aufrufreihenfolge.

package/plugins/ragents.reference/run-scripts/shared-actor-list/actors/shared-list/package.json

@@ -0,0 +1,16 @@
+{
+  "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"
+      }
+    ]
+  }
+}

package/plugins/ragents.reference/run-scripts/shared-actor-list/actors/shared-list/src/client.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { context, useAppState } from "@ragents/client";
+import * as UI from "@ragents/client/ui";
+
+type FormValues = Parameters<typeof UI.Form>[0]["values"];
+
+const App = () => {
+  const state = useAppState();
+  const [values, setValues] = React.useState<FormValues>({ text: "" });
+  const [status, setStatus] = React.useState("Bereit");
+  const entries = state.entries ?? [];
+
+  const append = async (next: FormValues): Promise<void> => {
+    const answer = await context.capabilities.call("append", { text: String(next.text ?? "") });
+    setValues({ text: "" });
+    setStatus(`Hinzugefügt: ${answer.text}`);
+  };
+
+  return (
+    <UI.AppLayout title="Gemeinsame Liste" description={<>{entries.length} {entries.length === 1 ? "Eintrag" : "Einträge"}</>}>
+      <UI.Grid>
+        <UI.Form fields={[
+          { id: "text", label: "Neuer Eintrag", type: "textarea", placeholder: "Text eingeben" },
+        ]} values={values} onChange={setValues} onSubmit={append} submitLabel="Hinzufügen" />
+        <UI.Stack>
+          <p className="text-muted-foreground" role="status">{status}</p>
+          <ul className="border-t border-border">
+            {entries.map((entry, index) => <li className="min-h-8 border-b border-border-soft py-1.5 [overflow-wrap:anywhere]" key={index}>{entry}</li>)}
+          </ul>
+        </UI.Stack>
+      </UI.Grid>
+    </UI.AppLayout>
+  );
+};
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);

package/plugins/ragents.reference/run-scripts/shared-actor-list/actors/shared-list/src/contract.ts

@@ -0,0 +1,15 @@
+import { Type } from "typebox";
+
+export const contract = {
+  state: Type.Object({ entries: Type.Optional(Type.Array(Type.String())) }, {"additionalProperties": false}),
+  functions: {
+    append: {
+      label: "Eintrag hinzufügen",
+      description: "Hängt den eingegebenen Text an die gemeinsame Liste an.",
+      input: Type.Object({ text: Type.String({"description": "Der Text für den neuen Listeneintrag."}) }, {"additionalProperties": false}),
+      output: Type.Object({ text: Type.String(), entries: Type.Array(Type.String()) }, {"additionalProperties": false}),
+      capabilities: [],
+      tool: {"name": "append_to_list", "targets": ["self"], "card": true},
+    },
+  },
+} as const;

package/plugins/ragents.reference/run-scripts/shared-actor-list/actors/shared-list/src/server.ts

@@ -0,0 +1,14 @@
+import { defineActor } from "@ragents/server";
+import { contract } from "./contract.ts";
+
+export default defineActor(contract, {
+  functions: {
+    append: async (input, context) => {
+      const text = input.text.trim();
+      const state = context.state.read();
+      const entries = [...(state.entries ?? []), text];
+      context.state.replace({ entries });
+      return { text, entries };
+    },
+  },
+});

package/plugins/ragents.reference/run-scripts/shared-actor-list/actors/shared-list/tests/program.test.ts

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { Static } from "typebox";
+import { createTestContext } from "@ragents/server/testing";
+import { contract } from "../src/contract.ts";
+import program from "../src/server.ts";
+
+test("ergänzt Einträge ohne vorhandene Einträge zu verlieren", async () => {
+  const context = createTestContext<Static<typeof contract.state>>({ state: {} });
+  assert.deepEqual(await program.functions.append({"text": "  Erster Eintrag  "}, context), {"text": "Erster Eintrag", "entries": ["Erster Eintrag"]});
+  assert.deepEqual(await program.functions.append({"text": "Zweiter Eintrag"}, context), {"text": "Zweiter Eintrag", "entries": ["Erster Eintrag", "Zweiter Eintrag"]});
+  assert.deepEqual(context.state.read(), {"entries": ["Erster Eintrag", "Zweiter Eintrag"]});
+});

package/plugins/ragents.reference/run-scripts/shared-actor-list/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "shared-actor-list",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Sammelboard einrichten",
+    "backend": "src/server.ts"
+  }
+}

package/plugins/ragents.reference/run-scripts/shared-actor-list/src/server.ts

@@ -0,0 +1,65 @@
+import { defineActor } from "@ragents/server";
+import { Type } from "typebox";
+
+const contract = {
+  state: Type.Object({ built: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+  functions: {},
+  input: { capabilities: ["model_list", "agent_spawn", "actor_program_activate", "actor_input", "run_configure"] },
+} as const;
+
+type Start = { input: unknown };
+
+const settingsFrom = (value: unknown): { title: string; firstEntry: string } => {
+  if (value === null) return { title: "Gemeinsame Liste", firstEntry: "Hallo aus dem Run-Script" };
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Startwert braucht title (1 bis 160 Zeichen) und firstEntry (1 bis 2000 Zeichen).");
+  }
+  const settings = value as Record<string, unknown>;
+  if (Object.keys(settings).some((key) => key !== "title" && key !== "firstEntry")
+    || typeof settings.title !== "string" || !settings.title.trim() || settings.title.trim().length > 160
+    || typeof settings.firstEntry !== "string" || !settings.firstEntry.trim() || settings.firstEntry.trim().length > 2000) {
+    throw new Error("Startwert braucht title (1 bis 160 Zeichen) und firstEntry (1 bis 2000 Zeichen).");
+  }
+  return { title: settings.title.trim(), firstEntry: settings.firstEntry.trim() };
+};
+
+export default defineActor(contract, {
+  functions: {},
+  onInput: async (input, context) => {
+    const state = context.state.read();
+    if (state && state.built) return;
+    const start = JSON.parse(input.content) as Start;
+    const settings = settingsFrom(start.input);
+    const title = settings.title;
+    const firstEntry = settings.firstEntry;
+
+    const catalog = await context.functions.model_list({});
+    const profiles = catalog.profiles.filter((profile) => profile.driver === "agent" && profile.name !== "coordinator");
+    const first = profiles[0];
+    if (!first) throw new Error("Kein Agentenprofil außer dem Koordinator; agent_spawn braucht eines.");
+
+    await context.functions.run_configure({ title: `Sammelboard: ${title}` });
+
+    const helper = await context.functions.agent_spawn({
+      handle: "listenhelfer",
+      prompt: `Du führst die gemeinsame Sammlung "${title}". Jeden Eintrag, den man dir gibt, hängst du mit deiner Funktion append_to_list an und meldest den neuen Stand.`,
+      profile: first.name,
+      tools: null,
+    });
+
+    await context.functions.actor_program_activate({ name: "shared-list", actor: `@${helper.handle}` });
+
+    await context.functions.actor_input({
+      actor: `@${helper.handle}`,
+      content: `Trage mit deiner Funktion append_to_list den Eintrag ${JSON.stringify(firstEntry)} in die gemeinsame Sammlung ${JSON.stringify(title)} ein und melde den Stand der Liste.`,
+    });
+    await context.functions.actor_input({
+      actor: "@coordinator",
+      content: `Die gemeinsame Sammlung heißt ${JSON.stringify(title)}. Das Run-Script hat das Programm shared-list an @${helper.handle} gebunden. Seine View ist auf dem Canvas sichtbar; der Helfer ergänzt gerade den ersten Eintrag mit append_to_list. `
+        + "Unten unter Actors öffnet sein Name den Inspector mit Chat und Details. Seine Canvas-Karte ist standardmäßig ausgeblendet und lässt sich in der Actors-Liste bei Bedarf einschalten. "
+        + "Erkläre dem Benutzer in drei Sätzen, wie er die sichtbare Liste bedient, den Helfer öffnet und dass View und Funktion denselben Listenstand teilen.",
+    });
+
+    context.state.replace({ built: true });
+  },
+});

package/plugins/ragents.reference/run-scripts/shared-actor-list/tests/helpers.ts

@@ -0,0 +1,26 @@
+import { createTestContext } from "@ragents/server/testing";
+
+export const setupContext = (profiles = [{ name: "coordinator", driver: "agent" }, { name: "standard", driver: "agent" }], suffix = "") => {
+  const calls: { name: string; input: unknown }[] = [];
+  const functions = Object.fromEntries(["model_list", "agent_spawn", "run_configure", "actor_input", "canvas_layout_replace", "actor_program_activate"].map((name) => [name, (input: unknown) => {
+    calls.push({ name, input });
+    if (name === "agent_spawn") {
+      const handle = (input as { handle: string }).handle + suffix;
+      return { id: `actor-${handle}`, handle };
+    }
+    if (name === "actor_program_activate") {
+      const value = input as { name: string; actor: string };
+      return { name: value.name, actor: value.actor, views: 1, active: true };
+    }
+    return name === "model_list" ? {
+      profiles: profiles.map((profile) => ({ ...profile, description: "Testprofil", turnTimeoutMs: null,
+        isolateWorkspace: false, provider: "test", model: "test" })), models: [],
+    } : [];
+  }]));
+  return { calls, context: createTestContext<{ built?: boolean }>({ state: {}, functions }) };
+};
+
+export const startInput = (input: unknown) => ({
+  id: "start", content: JSON.stringify({ input, options: {} }), artifactIds: [],
+  sourceEventIds: [], subscriptionId: null, event: null,
+});

package/plugins/ragents.reference/run-scripts/shared-actor-list/tests/program.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import program from "../src/server.ts";
+import { setupContext, startInput } from "./helpers.ts";
+
+test("bindet die Liste an den echten Listenhelfer und beauftragt seinen ersten Aufruf", async () => {
+  const { calls, context } = setupContext();
+  await program.onInput!(startInput({ title: "Teamfrühstück", firstEntry: "Kaffee" }), context);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list", "run_configure", "agent_spawn", "actor_program_activate", "actor_input", "actor_input"]);
+  assert.equal((calls.find((call) => call.name === "agent_spawn")?.input as { tools: null }).tools, null);
+  assert.deepEqual(calls.find((call) => call.name === "actor_program_activate")?.input, { name: "shared-list", actor: "@listenhelfer" });
+  assert.deepEqual(calls.find((call) => call.name === "run_configure")?.input, { title: "Sammelboard: Teamfrühstück" });
+  const assignment = calls.filter((call) => call.name === "actor_input")[0].input as { actor: string; content: string };
+  assert.equal(assignment.actor, "@listenhelfer");
+  assert.match(assignment.content, /append_to_list/);
+  assert.match(assignment.content, /Kaffee/);
+  assert.deepEqual(context.state.read(), { built: true });
+  const completedCalls = calls.length;
+  await program.onInput!(startInput(null), context);
+  assert.equal(calls.length, completedCalls);
+});
+
+test("Standardstart bleibt definiert und ungültige Werte starten nichts", async () => {
+  const initial = setupContext();
+  await program.onInput!(startInput(null), initial.context);
+  assert.match(JSON.stringify(initial.calls), /Hallo aus dem Run-Script/);
+  for (const input of [{ title: "Plan" }, { title: "", firstEntry: "Kaffee" }, { title: "Plan", firstEntry: "" }, { title: "x".repeat(161), firstEntry: "Kaffee" }, { title: "Plan", firstEntry: "Kaffee", extra: true }, 3]) {
+    const { calls, context } = setupContext();
+    await assert.rejects(async () => program.onInput!(startInput(input), context), /Startwert braucht title/);
+    assert.deepEqual(calls, []);
+    assert.deepEqual(context.state.read(), {});
+  }
+});
+
+test("verwendet den tatsächlich erzeugten Handle für Bindung und Auftrag", async () => {
+  const { calls, context } = setupContext(undefined, "-2");
+  await program.onInput!(startInput(null), context);
+  assert.deepEqual(calls.find((call) => call.name === "actor_program_activate")?.input,
+    { name: "shared-list", actor: "@listenhelfer-2" });
+  const assignment = calls.find((call) => call.name === "actor_input")?.input as { actor: string };
+  assert.equal(assignment.actor, "@listenhelfer-2");
+});