@schlenkr/ragents 0.1.0

package/plugins/ragents.reference/run-scripts/balcony-wizard/tests/program.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createTestContext } from "@ragents/server/testing";
+import program from "../src/server.js";
+
+const input = { id: "start", content: JSON.stringify({ input: null, options: {} }), artifactIds: [], sourceEventIds: [], subscriptionId: null, event: null };
+
+function setup(options: { missingProfile?: boolean; failActivation?: boolean } = {}) {
+  const calls: { name: string; input: unknown }[] = [];
+  const functions = Object.fromEntries([
+    "model_list", "agent_spawn", "actor_program_activate", "canvas_layout_replace", "run_configure",
+  ].map((name) => [name, (value: unknown) => {
+    calls.push({ name, input: value });
+    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 = (value as { handle: string }).handle;
+      return { id: `actor-${handle}`, handle };
+    }
+    if (name === "actor_program_activate" && options.failActivation) throw new Error("View kann nicht aktiviert werden.");
+    if (name === "actor_program_activate") {
+      const activation = value as { name: string; actor: string };
+      return { name: activation.name, actor: activation.actor, views: 1, active: true };
+    }
+    return [];
+  }]));
+  const context = createTestContext<{ built?: boolean }>({ state: {}, functions });
+  return { calls, context };
+}
+
+test("richtet einen Berater ohne Werkzeuge und seine eigene Canvas-App ein", async () => {
+  const { calls, context } = setup();
+  await program.onInput!(input, context);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list", "agent_spawn", "actor_program_activate", "canvas_layout_replace", "run_configure"]);
+  assert.deepEqual(calls.find((call) => call.name === "agent_spawn")?.input, {
+    handle: "balcony-advisor", displayName: "Balkon-Berater", profile: "standard", tools: [],
+    prompt: (calls[1]!.input as { prompt: string }).prompt,
+  });
+  assert.deepEqual(calls[2]!.input, { name: "balcony-app", actor: "@balcony-advisor" });
+  assert.deepEqual(calls[3]!.input, { nodes: [{ entity: "app:@balcony-advisor/main" }] });
+  assert.deepEqual(calls[4]!.input, { title: "Dein Balkon", primaryActor: "@balcony-advisor" });
+  assert.deepEqual(context.state.read(), { built: true });
+  await program.onInput!(input, context);
+  assert.equal(calls.length, 5);
+});
+
+test("fehlendes Modellprofil baut keinen unbrauchbaren Berater", async () => {
+  const { calls, context } = setup({ missingProfile: true });
+  await assert.rejects(async () => program.onInput!(input, context), /Modellprofil standard fehlt/);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list"]);
+  assert.deepEqual(context.state.read(), {});
+});
+
+test("eine fehlgeschlagene View-Aktivierung setzt weder Canvas noch Erfolgszustand", async () => {
+  const options = { failActivation: true };
+  const { calls, context } = setup(options);
+  await assert.rejects(async () => program.onInput!(input, context), /View kann nicht aktiviert/);
+  assert.deepEqual(calls.map((call) => call.name), ["model_list", "agent_spawn", "actor_program_activate"]);
+  assert.deepEqual(context.state.read(), {});
+});

package/plugins/ragents.reference/run-scripts/conversation-circle/RUN.md

@@ -0,0 +1,14 @@
+---
+title: Gesprächsrunde einrichten
+description: "Ein vorbereitetes Setup zeigt die Parametrisierung durch einen Startleitfaden und die Anordnung einer Gesprächsrunde. Der Koordinator führt anschließend die Runden."
+order: 120
+guide: ragents.reference.conversation-circle
+tags: Run-Scripts, Anwendungsfall, Konzeptdemo, Startleitfaden, Agententeams, Canvas-Layout
+---
+
+Dasselbe Ziel wie die Skill "Gesprächsrunde auf der Fläche", aber deterministisch: das Script
+stellt mira, jon und ada als gewöhnliche LLMs auf, gestaltet die Fläche und übergibt dem Koordinator
+das Briefing.
+Die Karte prüft das Modell, dieses Script prüft die Plattform.
+
+Der Leitfaden übergibt `{ "topic": "...", "rounds": 2 }`. `topic` enthält 1 bis 160 Zeichen, `rounds` ist eine ganze Zahl von 1 bis 5. Der Startwert `null` wählt ausdrücklich das Thema "Sollten Innenstädte autofrei werden?" und zwei Runden. Andere unvollständige oder ungültige Werte werden vor dem Aufbau abgelehnt. Thema und Rundenzahl steuern die Darstellung und den Auftrag, das Thema auch den Run-Titel.

package/plugins/ragents.reference/run-scripts/conversation-circle/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "conversation-circle",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Gesprächsrunde einrichten",
+    "backend": "src/server.ts"
+  }
+}

package/plugins/ragents.reference/run-scripts/conversation-circle/src/server.ts

@@ -0,0 +1,87 @@
+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", "canvas_layout_replace", "actor_input", "run_configure"] },
+} as const;
+
+type Start = { input: unknown };
+
+const settingsFrom = (value: unknown): { topic: string; rounds: number } => {
+  if (value === null) return { topic: "Sollten Innenstädte autofrei werden?", rounds: 2 };
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Startwert braucht topic (1 bis 160 Zeichen) und rounds (ganze Zahl von 1 bis 5).");
+  }
+  const settings = value as Record<string, unknown>;
+  if (Object.keys(settings).some((key) => key !== "topic" && key !== "rounds")
+    || typeof settings.topic !== "string" || !settings.topic.trim() || settings.topic.trim().length > 160
+    || typeof settings.rounds !== "number" || !Number.isInteger(settings.rounds) || settings.rounds < 1 || settings.rounds > 5) {
+    throw new Error("Startwert braucht topic (1 bis 160 Zeichen) und rounds (ganze Zahl von 1 bis 5).");
+  }
+  return { topic: settings.topic.trim(), rounds: settings.rounds };
+};
+
+const roleOf = (name: string): string => {
+  if (name === "mira") return "Du bist Mira und fragst neugierig nach.";
+  if (name === "jon") return "Du bist Jon und widersprichst höflich.";
+  return "Du bist Ada und suchst den gemeinsamen Nenner.";
+};
+
+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 topic = settings.topic;
+    const rounds = settings.rounds;
+
+    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: `Gesprächsrunde: ${topic}` });
+
+    const participants: string[] = [];
+    for (const name of ["mira", "jon", "ada"]) {
+      const participant = await context.functions.agent_spawn({
+        handle: name,
+        prompt: `${roleOf(name)} Antworte ausschließlich mit einem kurzen Satz als nächstem Gesprächsbeitrag.`,
+        profile: first.name,
+        tools: [],
+      });
+      participants.push(`@${participant.handle}`);
+    }
+
+    await context.functions.canvas_layout_replace({
+      nodes: [
+        { entity: "shape:thema" },
+        { id: "runde", group: "circle", label: "Runde", frame: true },
+        { entity: participants[0]!, parent: "runde" },
+        { entity: participants[1]!, parent: "runde" },
+        { entity: participants[2]!, parent: "runde" },
+      ],
+      shapes: [{ id: "thema", kind: "diamond", text: topic }],
+      lines: [
+        { from: participants[0]!, to: participants[1]!, arrow: "end", label: "gibt weiter" },
+        { from: participants[1]!, to: participants[2]!, arrow: "end", label: "gibt weiter" },
+        { from: participants[2]!, to: participants[0]!, arrow: "end", label: "gibt weiter" },
+        { from: "shape:thema", to: participants[0]!, style: "dashed", label: "Auftakt" },
+      ],
+    });
+
+    await context.functions.actor_input({
+      actor: "@coordinator",
+      content: `Die Runde steht: ${participants.join(", ")} sind aufgestellt, die Fläche ist gestaltet. Thema: "${topic}". `
+        + `Führe genau ${rounds} Gesprächsrunden durch: in jeder Runde ${participants.join(", ")} in dieser Reihenfolge. `
+        + "Jeder erhält die bisherigen Beiträge. Ändere die Fläche nicht. "
+        + "Fasse das Gespräch am Ende in drei Sätzen zusammen.",
+    });
+
+    context.state.replace({ built: true });
+  },
+});

package/plugins/ragents.reference/run-scripts/conversation-circle/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/conversation-circle/tests/program.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import program from "../src/server.ts";
+import { setupContext, startInput } from "./helpers.ts";
+
+test("Thema und Rundenzahl steuern Teilnehmer, Fläche und Auftrag", async () => {
+  const { calls, context } = setupContext();
+  await program.onInput!(startInput({ topic: "Teamfrühstück", rounds: 3 }), context);
+  assert.deepEqual(calls.filter((call) => call.name === "agent_spawn").map((call) => (call.input as { handle: string }).handle), ["mira", "jon", "ada"]);
+  assert.deepEqual(calls.find((call) => call.name === "run_configure")?.input, { title: "Gesprächsrunde: Teamfrühstück" });
+  const layout = calls.find((call) => call.name === "canvas_layout_replace")?.input as { shapes: { text: string }[]; lines: unknown[] };
+  assert.equal(layout.shapes[0].text, "Teamfrühstück");
+  assert.equal(layout.lines.length, 4);
+  assert.match(JSON.stringify(calls.at(-1)), /genau 3 Gesprächsrunden/);
+  assert.deepEqual(context.state.read(), { built: true });
+  const completedCalls = calls.length;
+  await program.onInput!(startInput(null), context);
+  assert.equal(calls.length, completedCalls);
+});
+
+test("null hat einen ausdrücklichen Standard, ungültige Werte lösen keine Wirkung aus", async () => {
+  const initial = setupContext();
+  await program.onInput!(startInput(null), initial.context);
+  assert.match(JSON.stringify(initial.calls), /Sollten Innenstädte autofrei werden/);
+  assert.match(JSON.stringify(initial.calls.at(-1)), /genau 2 Gesprächsrunden/);
+  for (const input of [{ topic: "Plan" }, { topic: "", rounds: 2 }, { topic: "Plan", rounds: 6 }, { topic: "Plan", rounds: 1.5 }, { topic: "Plan", rounds: 2, extra: true }, "Plan"]) {
+    const { calls, context } = setupContext();
+    await assert.rejects(async () => program.onInput!(startInput(input), context), /Startwert braucht topic/);
+    assert.deepEqual(calls, []);
+    assert.deepEqual(context.state.read(), {});
+  }
+});

package/plugins/ragents.reference/run-scripts/learning-afternoon/RUN.md

@@ -0,0 +1,24 @@
+---
+title: Lernnachmittag
+description: "Eine vorbereitete Parallelrunde zeigt zwei unabhängig arbeitende KI-Helfer und einen TypeScript-Sammler. Die Mini-App übernimmt einmalig je eine Antwort."
+order: 150
+coordinator: false
+tags: Run-Scripts, Anwendungsfall, Konzeptdemo, Mini-Apps, TypeScript-Actors, Agententeams, Subscriptions, Primary-Actor
+---
+
+Das vorbereitete TypeScript-Programm richtet zwei KI-Helfer ohne Werkzeuge ein und zeigt seine
+eigene Mini-App. Beide verwenden das Modellprofil `standard`. Ein Koordinator ist nicht nötig;
+der TypeScript-Actor steuert den Ablauf und ist der Primary-Actor.
+
+Erst "Ideen sammeln" beauftragt die beiden Helfer: Helfer A schlägt ein einfaches Experiment
+vor, Helfer B ein kleines Lernquiz. Jeder liefert genau eine Idee für einen Lernnachmittag mit
+Grundschulkindern. Die Aufträge sind unabhängig und werden gleichzeitig abgeschickt. Die App
+zeigt den Stand jedes Helfers und übernimmt seine abgeschlossene Antwort in die gemeinsame
+Ergebnisliste. Die Ideen sind echte Modellantworten und werden nicht fachlich geprüft.
+
+Ein Fehler bei einem Helfer lässt das Ergebnis des anderen stehen. Leere Antworten und
+unterbrochene Modell-Turns erscheinen als Fehler. Der Ablauf startet einmal und wiederholt
+weder Aufträge noch fehlgeschlagene Antworten automatisch. Für neue Ideen beginnt ein neuer Run.
+Der Einstieg benötigt keine Startwerte und löst vor dem Button keinen Modellaufruf aus.
+
+Die Homepage verwendet dieselbe React-Ansicht mit ausdrücklich markierten Vorschaudaten.

package/plugins/ragents.reference/run-scripts/learning-afternoon/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "learning-afternoon",
+  "private": true,
+  "type": "module",
+  "ragents": {
+    "title": "Lernnachmittag",
+    "backend": "src/server.ts",
+    "views": [{ "id": "main", "client": "src/client.tsx", "width": 620, "height": 550 }]
+  }
+}

package/plugins/ragents.reference/run-scripts/learning-afternoon/prompts/experiment.md

@@ -0,0 +1 @@
+Wenn Du die Experimentaufgabe erhältst, schlage eine Beobachtung vor, die Kinder mit einfachen Alltagsmaterialien gemeinsam machen können. Beschreibe das benötigte Material, die Durchführung und was die Kinder dabei entdecken können. Vermeide Feuer, gefährliche Stoffe und aufwendige Geräte.

package/plugins/ragents.reference/run-scripts/learning-afternoon/prompts/helper.md

@@ -0,0 +1,5 @@
+Du lieferst genau eine konkrete Idee für einen Lernnachmittag mit Grundschulkindern. Zwei Helfer arbeiten unabhängig voneinander; die Anwendung sammelt ihre Antworten automatisch.
+
+Deine nächste Nachricht nennt Deine konkrete Aufgabe. Bearbeite ausschließlich diese Aufgabe, auch wenn der gemeinsame Ablauf weitere Schritte beschreibt. Übernimm weder die Aufgabe des anderen Helfers noch die Sammlung.
+
+Antworte auf Deutsch als kurzer normaler Text: ein Titel und zwei bis drei Sätze zu Material und Ablauf. Keine Rückfragen, keine Werkzeuge, keine weiteren Aufgaben. Wähle bei offenen Einzelheiten selbst eine einfache, altersgerechte Lösung. Halte den Vorschlag mit einfachen Materialien und ohne gefährliche Experimente umsetzbar.

package/plugins/ragents.reference/run-scripts/learning-afternoon/prompts/quiz.md

@@ -0,0 +1 @@
+Wenn Du die Quizaufgabe erhältst, schlage ein kurzes gemeinsames Wissensspiel vor. Nenne ein kindgerechtes Thema, erkläre die Spielweise und gib eine kleine Beispielfrage. Das Spiel soll mit einfachen Materialien auskommen und alle Kinder beteiligen.

package/plugins/ragents.reference/run-scripts/learning-afternoon/src/client.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { context, useAppState } from "@ragents/client";
+import { LearningAfternoonView } from "./view.js";
+import { initialState } from "./state.js";
+
+function App() {
+  const state = useAppState();
+  const [pending, setPending] = React.useState(false);
+  const [error, setError] = React.useState<string>();
+  const start = async () => {
+    setPending(true);
+    setError(undefined);
+    try {
+      await context.capabilities.call("start", {});
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setPending(false);
+    }
+  };
+  return <LearningAfternoonView state={state.board ?? initialState} onStart={state.board ? start : undefined} pending={pending} error={error} />;
+}
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Das Wurzelelement #root fehlt.");
+createRoot(root).render(<App />);

package/plugins/ragents.reference/run-scripts/learning-afternoon/src/server.ts

@@ -0,0 +1,127 @@
+import { defineActor } from "@ragents/server";
+import { workflowInstructions } from "@ragents/workflow";
+import { readPrompt } from "@ragents/workflow/prompts";
+import { helperSteps, learningWorkflow } from "./workflow.ts";
+import { Type } from "typebox";
+import { initialState, type HelperState, type LearningState } from "./state.ts";
+
+const helperSchema = Type.Object({
+  id: Type.String(),
+  label: Type.String(),
+  task: Type.String(),
+  status: Type.Union([Type.Literal("waiting"), Type.Literal("working"), Type.Literal("complete"), Type.Literal("error")]),
+  text: Type.String(),
+  error: Type.Optional(Type.String()),
+  actorId: Type.Optional(Type.String()),
+  inputId: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+const contract = {
+  state: Type.Object({
+    board: Type.Optional(Type.Object({
+      phase: Type.Union([Type.Literal("ready"), Type.Literal("working"), Type.Literal("complete"), Type.Literal("error")]),
+      helpers: Type.Array(helperSchema),
+    }, { additionalProperties: false })),
+    subscriptionId: Type.Optional(Type.String()),
+  }, { additionalProperties: false }),
+  functions: {
+    start: {
+      label: "Ideen sammeln",
+      input: Type.Object({}, { additionalProperties: false }),
+      output: Type.Object({}, { additionalProperties: false }),
+      capabilities: ["actor_input"],
+    },
+  },
+  input: { capabilities: ["model_list", "agent_spawn", "canvas_layout_replace", "run_configure", "actor_input", "event_subscribe", "event_unsubscribe", "event_query"] },
+} as const;
+
+const startMarker = "START_LEARNING_AFTERNOON";
+
+
+function boardWith(helpers: HelperState[]): LearningState {
+  const working = helpers.some((helper) => helper.status === "working");
+  return { phase: working ? "working" : helpers.some((helper) => helper.status === "error") ? "error" : "complete", helpers };
+}
+
+export default defineActor(contract, {
+  functions: {
+    start: async (_input, context) => {
+      if (context.state.read().board?.phase !== "ready") return {};
+      await context.functions.actor_input({ actor: `@${context.actor.handle}`, content: startMarker });
+      return {};
+    },
+  },
+  onInput: async (input, context) => {
+    const state = context.state.read();
+    if (state.board && !input.event && input.content !== startMarker) {
+      throw new Error("Der Lernnachmittag versteht keine freien Chatnachrichten. Verwende den Startknopf der Mini-App; für neue Ideen ist ein neuer Run nötig.");
+    }
+    if (!state.board) {
+      const catalog = await context.functions.model_list({});
+      const profile = catalog.profiles.find((entry) => entry.driver === "agent" && entry.name === "standard");
+      if (!profile) throw new Error("Das Modellprofil standard fehlt.");
+      const prompt = await workflowInstructions(learningWorkflow, "helper", readPrompt);
+      const helpers = await Promise.all(initialState.helpers.map(async (helper) => {
+        const actor = await context.functions.agent_spawn({ handle: `learning-${helper.id}`, displayName: helper.label, profile: profile.name, prompt, tools: [] });
+        return { ...helper, actorId: actor.id };
+      }));
+      await context.functions.canvas_layout_replace({ nodes: [
+        ...helpers.map((helper) => ({ entity: `@learning-${helper.id}` })),
+        { entity: `app:@${context.actor.handle}/main` },
+      ] });
+      await context.functions.run_configure({ title: learningWorkflow.title, primaryActor: `@${context.actor.handle}` });
+      context.state.replace({ board: { phase: "ready", helpers } });
+      return;
+    }
+
+    if (state.board.phase === "ready" && !input.event && input.content === startMarker) {
+      const subscription = await context.functions.event_subscribe({
+        sourceActorIds: state.board.helpers.map((helper) => helper.actorId!),
+        eventTypes: ["turn.finished", "turn.interrupted", "actor.stopped"],
+        includeSelf: false,
+      });
+      const results = await Promise.allSettled(state.board.helpers.map(async (helper): Promise<HelperState> => {
+        const step = helperSteps.find((entry) => entry.id === helper.id);
+        if (!step) throw new Error(`Unbekannter Helfer: ${helper.id}`);
+        const content = step.goal;
+        const events = await context.functions.actor_input({ actor: `@learning-${helper.id}`, content });
+        const queued = events.find((event) => event.type === "actor.input.enqueued");
+        if (!queued || queued.type !== "actor.input.enqueued") throw new Error("Der Auftrag wurde nicht bestätigt.");
+        return { ...helper, inputId: queued.payload.inputId, status: "working" };
+      }));
+      const helpers = state.board.helpers.map((helper, index): HelperState => {
+        const result = results[index]!;
+        return result.status === "fulfilled" ? result.value : { ...helper, status: "error", error: result.reason instanceof Error ? result.reason.message : String(result.reason) };
+      });
+      const board = boardWith(helpers);
+      if (board.phase !== "working") await context.functions.event_unsubscribe({ subscriptionId: subscription.subscriptionId, reason: "Beide Aufträge sind beendet." });
+      context.state.replace({ board, subscriptionId: subscription.subscriptionId });
+      return;
+    }
+
+    const event = input.event;
+    if (state.board.phase !== "working" || !event || input.subscriptionId !== state.subscriptionId) return;
+    const helper = state.board.helpers.find((entry) => entry.actorId === event.sourceActorId && entry.status === "working");
+    if (!helper) return;
+    const next = await (async (): Promise<HelperState | undefined> => {
+      if (event.type === "actor.stopped") return { ...helper, status: "error", error: "Der Helfer wurde gestoppt." };
+      if (event.type !== "turn.finished" && event.type !== "turn.interrupted") return;
+      const payload = event.payload;
+      const turnId = payload.turnId;
+      if (typeof turnId !== "string") return;
+      const history = await context.functions.event_query({ actorIds: [helper.actorId!], eventTypes: ["turn.started", "model.output.completed"], limit: 100 });
+      const events = history.map((entry) => ({ type: entry.type, payload: entry.payload as Record<string, unknown> }));
+      const started = events.find((entry) => entry.type === "turn.started" && entry.payload.turnId === turnId);
+      if (!started || started.payload.inputId !== helper.inputId) return;
+      const text = events.filter((entry) => entry.type === "model.output.completed" && entry.payload.turnId === turnId)
+        .map((entry) => typeof entry.payload.text === "string" ? entry.payload.text.trim() : "").filter(Boolean).join("\n\n");
+      if (event.type === "turn.finished" && payload.outcome === "completed" && text) return { ...helper, text, status: "complete" };
+      const error = typeof payload.reason === "string" && payload.reason.trim() ? payload.reason : "Der Helfer hat keine Idee geliefert.";
+      return { ...helper, status: "error", error };
+    })();
+    if (!next) return;
+    const board = boardWith(state.board.helpers.map((entry) => entry.id === next.id ? next : entry));
+    if (board.phase !== "working") await context.functions.event_unsubscribe({ subscriptionId: state.subscriptionId!, reason: "Beide Aufträge sind beendet." });
+    context.state.replace({ ...state, board });
+  },
+});

package/plugins/ragents.reference/run-scripts/learning-afternoon/src/state.ts

@@ -0,0 +1,38 @@
+import type { WorkflowState } from "@ragents/workflow";
+import { helperSteps } from "./workflow.js";
+
+export interface HelperState {
+  id: string;
+  label: string;
+  task: string;
+  status: "waiting" | "working" | "complete" | "error";
+  text: string;
+  error?: string;
+  actorId?: string;
+  inputId?: string;
+}
+
+export interface LearningState {
+  phase: "ready" | "working" | "complete" | "error";
+  helpers: HelperState[];
+}
+
+export const initialState: LearningState = {
+  phase: "ready",
+  helpers: helperSteps.map((step, index) => ({ id: step.id, label: `Helfer ${String.fromCharCode(65 + index)}`, task: step.title, status: "waiting", text: "" })),
+};
+
+const helperStatuses = { waiting: "pending", working: "active", complete: "done", error: "blocked" } as const;
+
+export function learningWorkflowState(state: LearningState): WorkflowState {
+  return { steps: {
+    ...Object.fromEntries(state.helpers.map((helper) => [helper.id, {
+      status: helperStatuses[helper.status],
+      detail: helper.error ?? `${helper.label}: ${helper.task}`,
+    }])),
+    collect: {
+      status: state.phase === "complete" ? "done" : state.phase === "error" ? "blocked" : state.phase === "working" ? "active" : "pending",
+      detail: `${state.helpers.filter((helper) => helper.status === "complete").length} von ${state.helpers.length} Ideen gesammelt.`,
+    },
+  } };
+}

package/plugins/ragents.reference/run-scripts/learning-afternoon/src/view.tsx

@@ -0,0 +1,42 @@
+import React from "react";
+import { Button, WorkflowDiagram } from "@ragents/client/ui";
+import { learningWorkflowState, type LearningState } from "./state.js";
+import { learningWorkflow } from "./workflow.js";
+
+export interface LearningAfternoonProps {
+  state: LearningState;
+  onStart?: (() => void) | undefined;
+  pending?: boolean | undefined;
+  error?: string | undefined;
+  preview?: boolean;
+}
+
+const phaseLabels = { ready: "Bereit", working: "Die Helfer arbeiten", complete: "Beide Ideen sind da", error: "Mit Fehler beendet" };
+const rowClass = "flex items-center justify-between gap-2.5";
+const noteClass = "text-xs text-muted-foreground";
+
+export function LearningAfternoonView({ state, onStart, pending, error, preview }: LearningAfternoonProps) {
+  const entries = state.helpers.filter((helper) => helper.status === "complete");
+  return (
+    <main className="min-h-full bg-background text-base **:min-w-0 **:[overflow-wrap:anywhere]">
+      <header className={`${rowClass} flex-wrap`}>
+        <div><p className={`mb-1.5 ${noteClass}`}>Zwei Helfer, eine Sammlung</p><h1 className="text-[1.55rem] leading-[1.2] font-semibold">{learningWorkflow.title}</h1></div>
+        <span className={`shrink-0 ${noteClass}`}>{entries.length} / {state.helpers.length} Ideen</span>
+      </header>
+      <p className="mt-3.5 mb-5">Je eine Idee für einen Lernnachmittag mit Grundschulkindern: gemeinsam experimentieren und spielerisch Wissen testen.</p>
+      {preview && <p className={`mb-4 ${noteClass}`}>Vorschau mit Beispielideen. Keine aufgenommenen KI-Antworten.</p>}
+      <WorkflowDiagram definition={learningWorkflow} state={learningWorkflowState(state)} label="Ablauf des Lernnachmittags" direction="down" viewport="fit-width" />
+      <section className="mt-5 rounded-lg border border-border bg-card p-4" aria-label="Gemeinsame Ergebnisliste">
+        <div className={`${rowClass} flex-wrap`}><h2 className="text-base font-semibold">Gemeinsame Ergebnisliste</h2><span className={noteClass}>Automatisch gesammelt</span></div>
+        {entries.length === 0 ? <p className="py-5 text-sm text-muted-foreground">Hier erscheinen die fertigen Ideen.</p> : <ol className="mt-3 grid gap-3">
+          {entries.map((helper) => <li className="border-t border-border pt-3" key={helper.id}><strong className={noteClass}>{helper.label}</strong><p className="mt-1.5 whitespace-pre-wrap">{helper.text}</p></li>)}
+        </ol>}
+      </section>
+      <footer className={`${rowClass} mt-4 min-h-9 flex-wrap`}>
+        <p className={noteClass} role="status">{pending ? "Auftrag wird gesendet" : phaseLabels[state.phase]}</p>
+        {state.phase === "ready" && <Button onClick={onStart} disabled={pending || !onStart}>Ideen sammeln</Button>}
+      </footer>
+      {error && <p className="mt-2 text-destructive" role="alert">{error}</p>}
+    </main>
+  );
+}

package/plugins/ragents.reference/run-scripts/learning-afternoon/src/workflow.ts

@@ -0,0 +1,38 @@
+import { defineWorkflow } from "@ragents/workflow";
+
+export const learningWorkflow = defineWorkflow({
+  id: "learning-afternoon",
+  title: "Lernnachmittag",
+  roles: {
+    helper: { title: "Ideenhelfer", prompt: "prompts/helper.md" },
+    collection: { title: "Automatische Sammlung" },
+  },
+  steps: [
+    {
+      id: "experiment", title: "Ein einfaches Experiment", role: "helper",
+      goal: "Entwickle genau eine Experimentidee für einen gemeinsamen Lernnachmittag mit Grundschulkindern.",
+      prompt: "prompts/experiment.md",
+      completion: { source: "agent", description: "Der Helfer hat eine konkrete Idee als Text geliefert." },
+      freedom: { mode: "fixed", description: "Material und Experiment frei wählen; genau eine Idee liefern." },
+    },
+    {
+      id: "quiz", title: "Ein kleines Lernquiz", role: "helper",
+      goal: "Entwickle genau eine Quizidee für einen gemeinsamen Lernnachmittag mit Grundschulkindern.",
+      prompt: "prompts/quiz.md",
+      completion: { source: "agent", description: "Der Helfer hat eine konkrete Idee als Text geliefert." },
+      freedom: { mode: "fixed", description: "Thema und Spielweise frei wählen; genau eine Idee liefern." },
+    },
+    {
+      id: "collect", title: "Ideen gemeinsam sammeln", role: "collection",
+      goal: "Die Antworten beider unabhängig arbeitenden Helfer in der gemeinsamen Ergebnisliste anzeigen.",
+      completion: { source: "service", description: "Beide Helfer sind beendet; erfolgreiche Ideen und Fehler bleiben sichtbar." },
+      freedom: { mode: "fixed", description: "Antworten unverändert übernehmen; keine weitere Modellantwort erzeugen." },
+    },
+  ],
+  transitions: [
+    { from: "experiment", to: "collect" },
+    { from: "quiz", to: "collect" },
+  ],
+});
+
+export const helperSteps = learningWorkflow.steps.filter((step) => step.role === "helper");