@schlenkr/ragents 0.1.5 → 0.1.7

package/bundles/ragents.reference/run-scripts/conversation-circle/tests/program.test.ts

@@ -0,0 +1,34 @@
+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 { root: unknown };
+  assert.deepEqual(layout.root, { direction: "vertical", weights: [1, 1], children: [
+    { entity: "@mira" },
+    { direction: "horizontal", weights: [1, 1], children: [{ entity: "@jon" }, { entity: "@ada" }] },
+  ] });
+  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/bundles/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 die Rolle `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.
+Die Vorlage 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/bundles/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" }]
+  }
+}

package/bundles/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/bundles/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/bundles/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/bundles/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("The #root element is missing.");
+createRoot(root).render(<App />);

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

@@ -0,0 +1,137 @@
+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";
+
+
+type Tile = { entity: string } | { direction: "vertical"; weights: [number, number]; children: [Tile, Tile] };
+
+function stackedTiles(entities: string[]): Tile {
+  const [first, ...rest] = entities;
+  return rest.length === 0 ? { entity: first! } : { direction: "vertical", weights: [1, rest.length], children: [{ entity: first! }, stackedTiles(rest)] };
+}
+
+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("Die Rolle 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({
+        root: {
+          direction: "horizontal",
+          weights: [1, 1],
+          children: [{ entity: `app:@${context.actor.handle}/main` }, stackedTiles(helpers.map((helper) => `@learning-${helper.id}`))],
+        },
+      });
+      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/bundles/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: `Helper ${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} of ${state.helpers.length} ideas collected.`,
+    },
+  } };
+}

package/bundles/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: "Ready", working: "The helpers are working", complete: "Both ideas are ready", error: "Finished with an error" };
+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}`}>Two helpers, one collection</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} ideas</span>
+      </header>
+      <p className="mt-3.5 mb-5">One idea each for an afternoon with primary-school children: explore together and test knowledge through play.</p>
+      {preview && <p className={`mb-4 ${noteClass}`}>Preview with example ideas. No recorded AI responses.</p>}
+      <WorkflowDiagram definition={learningWorkflow} state={learningWorkflowState(state)} label="Learning afternoon workflow" direction="down" viewport="fit-width" />
+      <section className="mt-5 rounded-lg border border-border bg-card p-4" aria-label="Shared result list">
+        <div className={`${rowClass} flex-wrap`}><h2 className="text-base font-semibold">Shared result list</h2><span className={noteClass}>Collected automatically</span></div>
+        {entries.length === 0 ? <p className="py-5 text-sm text-muted-foreground">Completed ideas appear here.</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 ? "Sending tasks" : phaseLabels[state.phase]}</p>
+        {state.phase === "ready" && <Button onClick={onStart} disabled={pending || !onStart}>Collect ideas</Button>}
+      </footer>
+      {error && <p className="mt-2 text-destructive" role="alert">{error}</p>}
+    </main>
+  );
+}

package/bundles/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: "Learning afternoon",
+  roles: {
+    helper: { title: "Idea helper", prompt: "prompts/helper.md" },
+    collection: { title: "Automatic collection" },
+  },
+  steps: [
+    {
+      id: "experiment", title: "A simple experiment", role: "helper",
+      goal: "Create exactly one experiment idea for an afternoon with primary-school children.",
+      prompt: "prompts/experiment.md",
+      completion: { source: "agent", description: "The helper provided one concrete idea as text." },
+      freedom: { mode: "fixed", description: "Choose the material and experiment freely; provide exactly one idea." },
+    },
+    {
+      id: "quiz", title: "A short learning quiz", role: "helper",
+      goal: "Create exactly one quiz idea for an afternoon with primary-school children.",
+      prompt: "prompts/quiz.md",
+      completion: { source: "agent", description: "The helper provided one concrete idea as text." },
+      freedom: { mode: "fixed", description: "Choose the topic and format freely; provide exactly one idea." },
+    },
+    {
+      id: "collect", title: "Collect ideas", role: "collection",
+      goal: "Show the responses from both independent helpers in one shared result list.",
+      completion: { source: "service", description: "Both helpers have finished; successful ideas and errors remain visible." },
+      freedom: { mode: "fixed", description: "Keep responses unchanged and do not generate another model response." },
+    },
+  ],
+  transitions: [
+    { from: "experiment", to: "collect" },
+    { from: "quiz", to: "collect" },
+  ],
+});
+
+export const helperSteps = learningWorkflow.steps.filter((step) => step.role === "helper");

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

@@ -0,0 +1,218 @@
+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", sources: ["@learning-experiment", "@learning-quiz"] };
+    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 null;
+  }]));
+  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), /Rolle 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 of 2/);
+});

package/bundles/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/bundles/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"
+  }
+}