@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/web/chat-state.ts

@@ -0,0 +1,37 @@
+import type { SessionContext } from "@aicontainer/web/PluginRegistry";
+import type { ChatSnapshot } from "../client-ui/contracts";
+import { actorChatMessages } from "@aicontainer/plugins/ragents.orchestration/web/actor-conversation";
+import { runViewFrom } from "@aicontainer/plugins/ragents.orchestration/web/run-view";
+import { programChatNotice } from "@aicontainer/web/chat/chat-target";
+
+export const resolveChatActor = (session: SessionContext, target: string) => {
+  const view = runViewFrom(session.runView);
+  if (!view || view.id !== session.session.id) throw new Error("Die Laufansicht für diesen Chat ist noch nicht verfügbar");
+  const actor = target === "primary"
+    ? view.actors.find((entry) => entry.id === view.primaryActorId)
+    : view.actors.find((entry) => entry.handle === target.replace(/^@/, ""));
+  if (!actor || actor.kind === "human") {
+    const names = view.actors.filter((entry) => entry.kind !== "human").map((entry) => `@${entry.handle}`).join(", ");
+    throw new Error(`Das Chat-Ziel ist nicht verfügbar. Erlaubt sind primary und: ${names || "noch keine Actors"}`);
+  }
+  return { view, actor };
+};
+
+export const chatSnapshotOf = (session: SessionContext, target: string): ChatSnapshot => {
+  try {
+    const { view, actor } = resolveChatActor(session, target);
+    const primary = actor.id === view.primaryActorId;
+    const error = actor.kind === "script" ? programChatNotice : session.conversationError ?? (!session.connected
+      ? "Die Verbindung zum Run ist unterbrochen"
+      : actor.lifecycle?.kind === "stopped" ? "Dieser Actor ist gestoppt und nimmt keine Eingaben mehr an" : undefined);
+    return {
+      owner: actor.id,
+      messages: actorChatMessages(view, actor, session.messages, session.actorConversations?.[actor.id]),
+      running: primary ? session.running : actor.lifecycle?.kind === "running",
+      ...(actor.kind === "script" ? { readOnly: true } : {}),
+      ...(error ? { error } : {}),
+    };
+  } catch (error) {
+    return { messages: [], running: false, error: error instanceof Error ? error.message : String(error) };
+  }
+};

package/plugins/ragents.actor-programs/web/context.ts

@@ -0,0 +1,30 @@
+import { createContext, useContext } from "react";
+import type { ActorProgramsApi, ActorProgramsListing, RunAppInvocation } from "./api";
+import type { JsonValue } from "./bridge";
+
+export interface ActorProgramsContextValue {
+  api: ActorProgramsApi;
+  error: string | undefined;
+  fullscreenAppId: string | undefined;
+  listing: ActorProgramsListing | undefined;
+  openFullscreen: (appId: string) => void;
+  closeFullscreen: () => void;
+  refresh: () => Promise<void>;
+  invoke: (
+    appId: string,
+    revision: string,
+    actionId: string,
+    requestId: string,
+    input: JsonValue,
+  ) => Promise<RunAppInvocation>;
+  runId: string;
+}
+
+export const ActorProgramsContext = createContext<ActorProgramsContextValue | undefined>(undefined);
+export const useOptionalActorPrograms = () => useContext(ActorProgramsContext);
+
+export const useActorPrograms = (): ActorProgramsContextValue => {
+  const value = useOptionalActorPrograms();
+  if (!value) throw new Error("Der Actor-Programm-Provider ist nicht aktiv");
+  return value;
+};

package/plugins/ragents.actor-programs/web/function-call.ts

@@ -0,0 +1,28 @@
+import type { RunAppInvocation, ActorProgramsApi, RunScriptTool } from "./api";
+import type { JsonValue } from "./bridge";
+
+const waitForPoll = (signal: AbortSignal): Promise<void> => new Promise((resolve, reject) => {
+  signal.throwIfAborted();
+  const finish = (): void => { signal.removeEventListener("abort", abort); resolve(); };
+  const timer = setTimeout(finish, 350);
+  const abort = (): void => { clearTimeout(timer); reject(signal.reason); };
+  signal.addEventListener("abort", abort, { once: true });
+});
+
+export const invokeActorFunction = async (
+  api: ActorProgramsApi,
+  runId: string,
+  tool: Pick<RunScriptTool, "actorHandle" | "functionId" | "revision">,
+  input: JsonValue,
+  signal: AbortSignal,
+  changed: (invocation: RunAppInvocation) => void,
+): Promise<RunAppInvocation> => {
+  let invocation = await api.invokeFunction(runId, tool.actorHandle, tool.revision, tool.functionId, crypto.randomUUID().replaceAll("-", ""), input, signal);
+  changed(invocation);
+  while (invocation.status === "queued" || invocation.status === "running") {
+    await waitForPoll(signal);
+    invocation = await api.functionInvocation(runId, tool.actorHandle, invocation.id, signal);
+    changed(invocation);
+  }
+  return invocation;
+};

package/plugins/ragents.actor-programs/web/function-input.ts

@@ -0,0 +1,40 @@
+import type { RunToolParameter } from "./api";
+import { isJsonValue, type JsonValue } from "./bridge";
+
+const parseParameter = (parameter: RunToolParameter, form: FormData): JsonValue | undefined => {
+  const raw = String(form.get(parameter.name) ?? "");
+  if (parameter.type === "boolean") {
+    if (parameter.required) return form.has(parameter.name);
+    return raw === "" ? undefined : raw === "true";
+  }
+  if (raw === "" && !parameter.required) return undefined;
+  if (parameter.type === "string") return raw;
+  if (!raw.trim()) throw new Error(`${parameter.name}: Bitte einen Wert eingeben.`);
+  if (parameter.type === "number" || parameter.type === "integer") {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || parameter.type === "integer" && !Number.isInteger(value)) {
+      throw new Error(`${parameter.name} ist keine gültige ${parameter.type === "integer" ? "Ganzzahl" : "Zahl"}.`);
+    }
+    return value;
+  }
+  if (parameter.type === "string[]" && !raw.trimStart().startsWith("[")) {
+    return raw.split(/\r?\n|,/).map((entry) => entry.trim()).filter(Boolean);
+  }
+  let value: unknown;
+  try { value = JSON.parse(raw); }
+  catch { throw new Error(`${parameter.name}: Bitte gültiges JSON eingeben.`); }
+  if (!isJsonValue(value)) throw new Error(`${parameter.name}: Kein gültiger JSON-Wert.`);
+  if (parameter.type === "string[]" && (!Array.isArray(value) || !value.every((entry) => typeof entry === "string"))) {
+    throw new Error(`${parameter.name}: Bitte eine Liste aus Texten eingeben.`);
+  }
+  if (parameter.type === "number[]" && (!Array.isArray(value) || !value.every((entry) => typeof entry === "number"))) {
+    throw new Error(`${parameter.name}: Bitte eine JSON-Liste aus Zahlen eingeben.`);
+  }
+  return value;
+};
+
+export const actorFunctionInput = (parameters: readonly RunToolParameter[], form: FormData): Record<string, JsonValue> =>
+  Object.fromEntries(parameters.flatMap((parameter) => {
+    const value = parseParameter(parameter, form);
+    return value === undefined ? [] : [[parameter.name, value]];
+  }));

package/plugins/ragents.actor-programs/web/index.tsx

@@ -0,0 +1,96 @@
+import {
+  pluginRoutePrefixFrom,
+  type SessionProviderProps,
+  type WebPlugin,
+  type WebPluginDescriptor,
+} from "@aicontainer/web/PluginRegistry";
+import { createActorProgramsApi } from "./api";
+import { ORCHESTRATION_TAB_ID } from "@aicontainer/plugins/ragents.orchestration/web/constants";
+import {
+  actorProgramApps,
+  RUN_TOOLS_TAB_ID,
+  ActorProgramsHeader,
+  ActorProgramsProvider,
+  ToolsBadge,
+  ToolsPanel,
+} from "./AppsPanel";
+import { FullscreenHost } from "./FullscreenHost";
+import {
+  ActorProgramCanvasElement,
+  ActorProgramToolCardSection,
+  actorProgramCanvasElements,
+} from "./EmbeddedApps";
+
+export const ACTOR_PROGRAMS_PLUGIN_ID = "ragents.actor-programs";
+
+function IconTools() {
+  return (
+    <svg aria-hidden fill="none" height="15" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.7" viewBox="0 0 24 24" width="15">
+      <path d="M14.5 6.5 17.5 3.5l3 3-3 3" />
+      <path d="m9.5 17.5-3 3-3-3 3-3" />
+      <path d="M13 5H9a4 4 0 0 0-4 4v5.5M11 19h4a4 4 0 0 0 4-4V9.5" />
+    </svg>
+  );
+}
+
+const configuredPlugin = (descriptor: WebPluginDescriptor, routePrefix: string): WebPlugin => {
+  const api = createActorProgramsApi(routePrefix);
+
+  function Provider({ children, session }: SessionProviderProps) {
+    return (
+      <ActorProgramsProvider api={api} session={session}>
+        {children}
+        <FullscreenHost session={session} />
+      </ActorProgramsProvider>
+    );
+  }
+
+  return {
+    ...descriptor,
+    needsRunView: true,
+    SessionProvider: Provider,
+    sessionHeaders: [{
+      id: "ragents.actor-programs.quick-list",
+      placement: "canvas",
+      order: 250,
+      Header: ActorProgramsHeader,
+    }],
+    cardSections: [{
+      id: "ragents.actor-programs.tools",
+      order: 400,
+      Section: ActorProgramToolCardSection,
+    }],
+    canvasElements: [{
+      id: "ragents.actor-programs.apps",
+      order: 400,
+      select: actorProgramCanvasElements,
+      Element: ActorProgramCanvasElement,
+    }],
+    entityPresenters: [{
+      reveal: (entity, session) => {
+        if (entity.type !== "run-app") return undefined;
+        const entry = actorProgramApps(session).find((app) => app.id === entity.id);
+        if (!entry || entry.app.visible === false) return undefined;
+        return { tabId: ORCHESTRATION_TAB_ID, selection: entity };
+      },
+    }],
+    workspaceTabs: [
+      {
+        readRight: "runs.inspect",
+        id: RUN_TOOLS_TAB_ID,
+        label: "Funktionen",
+        order: 251,
+        Icon: IconTools,
+        Panel: ToolsPanel,
+        Badge: ToolsBadge,
+      },
+    ],
+  };
+};
+
+const descriptor: WebPluginDescriptor = { id: ACTOR_PROGRAMS_PLUGIN_ID };
+
+export const webPlugin: WebPlugin = {
+  ...descriptor,
+  activate: (config) => configuredPlugin(descriptor, pluginRoutePrefixFrom(descriptor.id, config)),
+};

package/plugins/ragents.actor-programs/web/invocations.ts

@@ -0,0 +1,43 @@
+import type { ActorProgramsApi, RunApp, RunAppInvocation } from "./api";
+
+type InvocationTarget = { invocationId: string } & (
+  | { kind: "app"; appId: string }
+  | { kind: "function"; actorHandle: string }
+);
+
+export const activeActorInvocations = (apps: readonly RunApp[], includeFunctions = true): InvocationTarget[] => {
+  const appIds = new Set(apps.map((app) => app.id));
+  const active = new Map<string, InvocationTarget>();
+  for (const app of apps) for (const invocation of app.invocations) {
+    if (invocation.status === "queued" || invocation.status === "running") {
+      if (!includeFunctions && !appIds.has(invocation.appId)) continue;
+      active.set(`${invocation.actorId}/${invocation.id}`, appIds.has(invocation.appId)
+        ? { kind: "app", appId: invocation.appId, invocationId: invocation.id }
+        : { kind: "function", actorHandle: invocation.actorHandle, invocationId: invocation.id });
+    }
+  }
+  return [...active.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, target]) => target);
+};
+
+export const readActorInvocation = (
+  api: ActorProgramsApi,
+  runId: string,
+  target: InvocationTarget,
+  signal?: AbortSignal,
+): Promise<RunAppInvocation> => target.kind === "app"
+  ? api.invocation(runId, target.appId, target.invocationId, signal)
+  : api.functionInvocation(runId, target.actorHandle, target.invocationId, signal);
+
+export const invocationTime = (invocation: RunAppInvocation): number => {
+  const raw = invocation.status === "queued"
+    ? invocation.createdAt
+    : invocation.status === "running"
+      ? invocation.startedAt
+      : invocation.finishedAt;
+  const parsed = Date.parse(raw);
+  return Number.isNaN(parsed) ? 0 : parsed;
+};
+
+export const latestInvocation = (app: RunApp): RunAppInvocation | undefined =>
+  app.invocations.reduce<RunAppInvocation | undefined>((latest, invocation) =>
+    !latest || invocationTime(invocation) >= invocationTime(latest) ? invocation : latest, undefined);

package/plugins/ragents.actor-programs/web/program-state.ts

@@ -0,0 +1,68 @@
+import { ACTOR_PROGRAMS_STATE_ID, ACTOR_STATE_ID } from "../contract";
+import { isRecord } from "@aicontainer/web/lib/guards";
+import { runViewFrom } from "@aicontainer/plugins/ragents.orchestration/web/contract";
+import type { ActorProgramsListing } from "./api";
+import { isJsonValue } from "./bridge";
+
+export interface ActorProgramView {
+  id: string;
+  title: string;
+  actorId: string;
+  actorHandle: string;
+  revision: string;
+  app: Record<string, unknown>;
+}
+
+export const actorProgramSourceReference = (runView: unknown, actorId: string): { name: string; revision: string } | undefined => {
+  const view = runViewFrom(runView);
+  const entry = view?.pluginStates.find((entry) => entry.pluginId === ACTOR_PROGRAMS_STATE_ID
+    && entry.scope.kind === "actor" && entry.scope.actorId === actorId);
+  if (!entry || !isRecord(entry.state) || entry.state.program === null) return undefined;
+  const program = entry.state.program;
+  if (!isRecord(program) || program.actorId !== actorId || typeof program.name !== "string" || typeof program.revision !== "string") {
+    throw new Error("Die Quellcode-Zuordnung des Actor-Programms ist ungültig.");
+  }
+  return { name: program.name, revision: program.revision };
+};
+
+export const actorProgramViews = (runView: unknown): ActorProgramView[] => {
+  const view = runViewFrom(runView);
+  if (!view) return [];
+  return view.pluginStates.flatMap((entry): ActorProgramView[] => {
+    if (entry.pluginId !== ACTOR_PROGRAMS_STATE_ID || entry.scope.kind !== "actor") return [];
+    const actorId = entry.scope.actorId;
+    const actor = view.actors.find((actor) => actor.id === actorId);
+    if (!actor || actor.kind === "human" || actor.lifecycle?.kind === "stopped") return [];
+    if (!isRecord(entry.state) || !isRecord(entry.state.program)) return [];
+    const program = entry.state.program;
+    if (program.actorId !== actor.id || program.actorHandle !== actor.handle || typeof program.revision !== "string" || !Array.isArray(program.views)) {
+      throw new Error(`Das Ansichtsprogramm von @${actor.handle} ist ungültig.`);
+    }
+    return program.views.map((app) => {
+      if (!isRecord(app) || typeof app.id !== "string" || typeof app.title !== "string") throw new Error(`Eine Ansicht von @${actor.handle} ist ungültig.`);
+      return { id: app.id, title: app.title, actorId: actor.id, actorHandle: actor.handle, revision: program.revision as string, app };
+    });
+  });
+};
+
+export const currentActorListing = (listing: ActorProgramsListing | undefined, runView: unknown): ActorProgramsListing | undefined => {
+  const view = runViewFrom(runView);
+  if (!listing || !view) return undefined;
+  const currentViews = new Map(actorProgramViews(view).map((entry) => [entry.id, entry]));
+  const activeActors = new Set(view.actors.filter((actor) => actor.kind !== "human" && actor.lifecycle?.kind !== "stopped").map((actor) => actor.id));
+  return {
+    ...listing,
+    apps: listing.apps.flatMap((app) => {
+      const current = currentViews.get(app.id);
+      if (!current || current.actorId !== app.actorId || current.revision !== app.revision) return [];
+      const state = view.pluginStates.find((entry) => entry.pluginId === ACTOR_STATE_ID && entry.scope.kind === "actor" && entry.scope.actorId === app.actorId);
+      const values = state ? state.state : app.state.values;
+      if (!isJsonValue(values)) throw new Error(`Der Zustand von @${app.actorHandle} ist kein JSON-Wert.`);
+      return [{ ...app, visible: current.app.visible !== false,
+        state: { ...app.state, values } }];
+    }),
+    tools: listing.tools.filter((tool) => activeActors.has(tool.actorId) && view.pluginStates.some((entry) =>
+      entry.pluginId === ACTOR_PROGRAMS_STATE_ID && entry.scope.kind === "actor" && entry.scope.actorId === tool.actorId
+      && isRecord(entry.state) && isRecord(entry.state.program) && entry.state.program.revision === tool.revision)),
+  };
+};

package/plugins/ragents.actor-programs/web/state-revision.ts

@@ -0,0 +1,16 @@
+import { ACTOR_PROGRAMS_STATE_ID, ACTOR_INVOCATIONS_STATE_ID, ACTOR_STATE_ID } from "../contract";
+import { runViewFrom } from "@aicontainer/plugins/ragents.orchestration/web/contract";
+
+export const actorProgramsRevision = (runView: unknown): string => {
+  const view = runViewFrom(runView);
+  const programActors = new Set(view?.pluginStates.filter((entry) => entry.pluginId === ACTOR_PROGRAMS_STATE_ID && entry.scope.kind === "actor")
+    .map((entry) => entry.scope.kind === "actor" ? entry.scope.actorId : "") ?? []);
+  return JSON.stringify({
+    actors: view?.actors.filter((actor) => programActors.has(actor.id)).map((actor) => [actor.id, actor.handle, actor.lifecycle?.kind === "stopped"]).sort(([left], [right]) => String(left).localeCompare(String(right))) ?? [],
+    states: (view?.pluginStates ?? [])
+      .filter((entry) => entry.pluginId === ACTOR_PROGRAMS_STATE_ID || entry.pluginId === ACTOR_INVOCATIONS_STATE_ID
+        || entry.pluginId === ACTOR_STATE_ID && entry.scope.kind === "actor" && programActors.has(entry.scope.actorId))
+      .map((entry) => [`${entry.pluginId}:${entry.scope.kind === "actor" ? entry.scope.actorId : "run"}`, entry.state])
+      .sort(([left], [right]) => String(left).localeCompare(String(right))),
+  });
+};

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

@@ -0,0 +1,202 @@
+export type WorkflowStatus = "pending" | "active" | "done" | "blocked";
+export interface WorkflowItem {
+  label: string;
+  status?: WorkflowStatus | "skipped";
+  detail?: string;
+}
+export interface WorkflowDefinition {
+  id: string;
+  title: string;
+  roles: Readonly<Record<string, { title: string; prompt?: string }>>;
+  steps: readonly {
+    id: string;
+    title: string;
+    role: string;
+    goal: string;
+    prompt?: string;
+    completion: { source: "agent" | "service" | "operator"; description: string };
+    freedom: { mode: "fixed" | "extend"; description: string; allowSkip?: boolean; maxItems?: number };
+    expansion?: { source: string; role: string; mode: "parallel"; maxConcurrent: number };
+  }[];
+  transitions: readonly { from: string; to: string; condition?: string; kind?: "return" }[];
+}
+export interface WorkflowStepState {
+  status: WorkflowStatus;
+  detail?: string;
+  items?: readonly WorkflowItem[];
+}
+export interface WorkflowState {
+  steps: Readonly<Record<string, WorkflowStepState>>;
+  expansions?: Readonly<Record<string, readonly {
+    id: string;
+    title: string;
+    status?: WorkflowStatus;
+    detail?: string;
+    items: readonly WorkflowItem[];
+  }[]>>;
+}
+export interface WorkflowGraph {
+  nodes: { id: string; label: string; detail?: string; status: WorkflowStatus; kind: "actor" | "agent" | "service"; items?: readonly WorkflowItem[] }[];
+  edges: { id: string; source: string; target: string; label?: string; kind?: "return" }[];
+}
+
+function text(value: unknown, name: string): asserts value is string {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} muss ein nicht leerer Text sein.`);
+}
+function object(value: unknown, name: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} muss ein Objekt sein.`);
+}
+function positiveInteger(value: unknown, name: string) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) throw new Error(`${name} muss eine positive ganze Zahl sein.`);
+}
+function optionalText(value: unknown, name: string) {
+  if (value !== undefined && typeof value !== "string") throw new Error(`${name} muss Text sein.`);
+}
+export function validatePromptReference(value: unknown) {
+  text(value, "Promptreferenz");
+  if (!/^[^\\/:]+(?:\/[^\\/:]+)*\.(?:md|hbs)$/.test(value) || value.split("/").some(part => part === "." || part === "..") || /[\x00-\x1f?#]/.test(value)) {
+    throw new Error(`Promptreferenz muss eine relative .md- oder .hbs-Datei innerhalb des Pakets sein: ${value}`);
+  }
+}
+function has(object: object, key: string) { return Object.prototype.hasOwnProperty.call(object, key); }
+
+export function defineWorkflow<const Definition extends WorkflowDefinition>(definition: Definition): Definition {
+  object(definition, "Workflow");
+  text(definition.id, "Workflow-ID");
+  text(definition.title, "Workflowtitel");
+  object(definition.roles, "Rollen");
+  if (Object.keys(definition.roles).length === 0) throw new Error("Ein Workflow benötigt Rollen.");
+  for (const [id, role] of Object.entries(definition.roles)) {
+    text(id, "Rollen-ID"); object(role, "Rolle"); text(role.title, "Rollentitel"); if (role.prompt !== undefined) validatePromptReference(role.prompt);
+  }
+  if (!Array.isArray(definition.steps) || definition.steps.length === 0) throw new Error("Ein Workflow benötigt Schritte.");
+  const ids = new Set<string>();
+  for (const step of definition.steps) {
+    object(step, "Schritt"); text(step.id, "Schritt-ID"); text(step.title, "Schritttitel"); text(step.goal, "Schrittziel"); text(step.role, "Schrittrolle");
+    if (ids.has(step.id)) throw new Error(`Doppelte Schritt-ID: ${step.id}`);
+    ids.add(step.id);
+    if (!has(definition.roles, step.role)) throw new Error(`Unbekannte Rolle: ${step.role}`);
+    if (step.prompt !== undefined) validatePromptReference(step.prompt);
+    object(step.completion, "Abschluss"); text(step.completion.source, "Abschlussquelle"); text(step.completion.description, "Abschlussbeschreibung");
+    if (!["agent", "service", "operator"].includes(step.completion.source)) throw new Error(`Unbekannte Abschlussquelle: ${step.id}`);
+    object(step.freedom, "Freiheitsgrad"); text(step.freedom.mode, "Freiheitsgradmodus"); text(step.freedom.description, "Freiheitsgradbeschreibung");
+    if (!["fixed", "extend"].includes(step.freedom.mode)) throw new Error(`Unbekannter Freiheitsgrad: ${step.id}`);
+    if (step.freedom.allowSkip !== undefined && typeof step.freedom.allowSkip !== "boolean") throw new Error("allowSkip muss ein Wahrheitswert sein.");
+    if (step.freedom.maxItems !== undefined) positiveInteger(step.freedom.maxItems, "maxItems");
+    if (step.expansion !== undefined) {
+      object(step.expansion, "Erweiterung"); text(step.expansion.source, "Erweiterungsquelle"); text(step.expansion.role, "Erweiterungsrolle");
+      if (!has(definition.roles, step.expansion.role)) throw new Error(`Unbekannte Erweiterungsrolle: ${step.expansion.role}`);
+      if (step.expansion.mode !== "parallel") throw new Error("Erweiterungen müssen den Modus parallel verwenden.");
+      positiveInteger(step.expansion.maxConcurrent, "maxConcurrent");
+    }
+  }
+  if (!Array.isArray(definition.transitions)) throw new Error("Übergänge müssen eine Liste sein.");
+  const outgoing = new Map([...ids].map(id => [id, [] as string[]]));
+  const transitions = new Set<string>();
+  for (const transition of definition.transitions) {
+    object(transition, "Übergang"); text(transition.from, "Übergangsquelle"); text(transition.to, "Übergangsziel");
+    if (!ids.has(transition.from) || !ids.has(transition.to)) throw new Error("Ein Übergang verweist auf einen unbekannten Schritt.");
+    optionalText(transition.condition, "Übergangsbedingung");
+    if (transition.kind !== undefined && transition.kind !== "return") throw new Error("Unbekannte Übergangsart.");
+    const key = JSON.stringify([transition.from, transition.to, transition.kind, transition.condition]);
+    if (transitions.has(key)) throw new Error("Doppelter Übergang.");
+    transitions.add(key);
+    if (transition.kind !== "return") outgoing.get(transition.from)!.push(transition.to);
+  }
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (id: string) => {
+    if (visiting.has(id)) throw new Error("Normale Übergänge müssen azyklisch sein; Rückwege benötigen kind: return.");
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const next of outgoing.get(id)!) visit(next);
+    visiting.delete(id); visited.add(id);
+  };
+  for (const id of ids) visit(id);
+  return definition;
+}
+
+export async function workflowInstructions(definition: WorkflowDefinition, role: string, readPrompt: (reference: string) => Promise<string>): Promise<string> {
+  defineWorkflow(definition);
+  if (!has(definition.roles, role)) throw new Error(`Unbekannte Rolle: ${role}`);
+  const owned = definition.steps.filter(step => step.role === role);
+  const selectedRole = definition.roles[role]!;
+  const load = async (reference: string) => {
+    const content = await readPrompt(reference);
+    text(content, `Prompt ${reference}`);
+    return content;
+  };
+  const lines = [`# ${definition.title}`, `Rolle: ${selectedRole.title} (${role})`];
+  if (selectedRole.prompt !== undefined) lines.push(await load(selectedRole.prompt));
+  lines.push("## Ablauf", ...definition.steps.map(step => `- ${step.id}: ${step.title}; zuständig: ${definition.roles[step.role]!.title}`));
+  for (const step of owned) {
+    lines.push(`## ${step.title} (${step.id})`, `Ziel: ${step.goal}`, `Abschluss durch ${step.completion.source}: ${step.completion.description}`,
+      `Freiheitsgrad ${step.freedom.mode}: ${step.freedom.description}`, `Überspringen: ${step.freedom.allowSkip === true ? "nur für eigene optionale Punkte erlaubt, begründen; Pflichtschritte bleiben verbindlich" : "nicht erlaubt"}`);
+    if (step.freedom.maxItems !== undefined) lines.push(`Höchstens ${step.freedom.maxItems} eigene Punkte.`);
+    if (step.expansion) lines.push(`Parallele Erweiterung aus ${step.expansion.source}: Rolle ${step.expansion.role}, höchstens ${step.expansion.maxConcurrent} gleichzeitig.`);
+    if (step.prompt !== undefined) lines.push(await load(step.prompt));
+  }
+  lines.push("## Übergänge", ...definition.transitions.map(transition => `${transition.from} -> ${transition.to}${transition.kind === "return" ? " (Rückweg)" : ""}${transition.condition ? `: ${transition.condition}` : ""}`));
+  return lines.join("\n\n");
+}
+
+function status(value: unknown) {
+  if (!["pending", "active", "done", "blocked"].includes(value as string)) throw new Error(`Unbekannter Schrittstatus: ${String(value)}`);
+}
+function items(value: unknown) {
+  if (!Array.isArray(value)) throw new Error("Punkte müssen eine Liste sein.");
+  for (const item of value) {
+    object(item, "Punkt"); text(item.label, "Punktlabel"); optionalText(item.detail, "Punktdetail");
+    if (item.status !== undefined && !["pending", "active", "done", "blocked", "skipped"].includes(item.status as string)) throw new Error("Unbekannter Punktstatus.");
+  }
+}
+
+export function workflowGraph(definition: WorkflowDefinition, state: WorkflowState): WorkflowGraph {
+  defineWorkflow(definition);
+  object(state, "Workflowzustand"); object(state.steps, "Schrittzustände");
+  const steps = new Map(definition.steps.map(step => [step.id, step]));
+  for (const [id, step] of Object.entries(state.steps)) {
+    if (!steps.has(id)) throw new Error(`Unbekannter Schrittzustand: ${id}`);
+    object(step, "Schrittzustand"); status(step.status); optionalText(step.detail, "Schrittdetail");
+    if (step.items !== undefined) items(step.items);
+  }
+  const sources = new Set(definition.steps.flatMap(step => step.expansion ? [step.expansion.source] : []));
+  if (state.expansions !== undefined) object(state.expansions, "Erweiterungszustände");
+  for (const source of Object.keys(state.expansions ?? {})) if (!sources.has(source)) throw new Error(`Unbekannte Erweiterungsquelle: ${source}`);
+  for (const source of sources) {
+    if (!state.expansions || !has(state.expansions, source)) throw new Error(`Erweiterungsquelle fehlt im Zustand: ${source}`);
+    const groups = state.expansions[source]!;
+    if (!Array.isArray(groups)) throw new Error(`Erweiterungsquelle ${source} muss eine Liste sein.`);
+    const ids = new Set<string>();
+    for (const group of groups) {
+      object(group, "Erweiterungsgruppe"); text(group.id, "Gruppen-ID"); text(group.title, "Gruppentitel");
+      if (ids.has(group.id)) throw new Error(`Doppelte Gruppen-ID: ${group.id}`);
+      ids.add(group.id);
+      if (group.status !== undefined) status(group.status);
+      optionalText(group.detail, "Gruppendetail"); items(group.items);
+    }
+  }
+  const graph: WorkflowGraph = { nodes: [], edges: [] };
+  const groups = new Map<string, string[]>();
+  const nodeIds = new Set(steps.keys());
+  for (const step of definition.steps) {
+    const snapshot = state.steps[step.id];
+    graph.nodes.push({ id: step.id, label: step.title, status: snapshot?.status ?? "pending", kind: step.completion.source === "service" ? "service" : step.completion.source === "agent" ? "agent" : "actor", ...(snapshot?.detail === undefined ? {} : { detail: snapshot.detail }), ...(snapshot?.items === undefined ? {} : { items: snapshot.items }) });
+    if (step.expansion) {
+      const ids: string[] = [];
+      for (const group of state.expansions![step.expansion.source]!) {
+        const id = `expansion:${JSON.stringify([step.id, group.id])}`;
+        if (nodeIds.has(id)) throw new Error(`Erweiterungs-ID kollidiert mit einem Knoten: ${id}`);
+        nodeIds.add(id); ids.push(id);
+        graph.nodes.push({ id, label: group.title, status: group.status ?? "pending", kind: "agent", items: group.items, ...(group.detail === undefined ? {} : { detail: group.detail }) });
+        graph.edges.push({ id: `expansion:${JSON.stringify([step.id, group.id])}`, source: step.id, target: id });
+      }
+      groups.set(step.id, ids);
+    }
+  }
+  definition.transitions.forEach((transition, index) => {
+    const sourceIds = transition.kind === "return" || !groups.get(transition.from)?.length ? [transition.from] : groups.get(transition.from)!;
+    for (const source of sourceIds) graph.edges.push({ id: `transition:${JSON.stringify([index, source])}`, source, target: transition.to, ...(transition.condition === undefined ? {} : { label: transition.condition }), ...(transition.kind === undefined ? {} : { kind: transition.kind }) });
+  });
+  return graph;
+}

package/plugins/ragents.actor-programs/workflow/prompt-reader.ts

@@ -0,0 +1,15 @@
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { validatePromptReference } from "./index.js";
+
+export function createPromptReader(directory: string): (reference: string) => Promise<string> {
+  return async (reference) => {
+    validatePromptReference(reference);
+    const root = await realpath(directory);
+    const filename = await realpath(path.join(root, reference));
+    if (!filename.startsWith(`${root}${path.sep}`)) throw new Error(`Promptdatei liegt außerhalb des Actor-Pakets: ${reference}`);
+    const content = await readFile(filename, "utf8");
+    if (!content.trim()) throw new Error(`Promptdatei ist leer: ${reference}`);
+    return content;
+  };
+}

package/plugins/ragents.ask/ask.hbs

@@ -0,0 +1,4 @@
+# Asking the user
+
+If you need a decision from the user, ask with `ask_user` and name concrete options. A question in
+running text merely ends your turn without waking anyone.

package/plugins/ragents.ask/contract.ts

@@ -0,0 +1,17 @@
+import { Type } from "typebox";
+import { defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+
+export const askContracts = {
+  answer: defineOperation({
+    id: "ragents.ask.answer",
+    description: "Eine Rückfrage des Laufs beantworten oder verwerfen. Rechte: runs.read und runs.write.",
+    rights: ["runs.read", "runs.write"],
+    input: Type.Object({
+      runId: Type.String({ minLength: 1, maxLength: 64, description: "Kennung des Runs" }),
+      actionId: Type.String({ minLength: 1, maxLength: 80, description: "Kennung der Frage" }),
+      answer: Type.Optional(Type.String({ description: "Die Antwort des Benutzers" })),
+      dismiss: Type.Optional(Type.Boolean({ description: "true verwirft die Frage ohne Antwort" })),
+    }, { additionalProperties: false }),
+    result: Type.Null(),
+  }),
+};

package/plugins/ragents.ask/server/answer-method.ts

@@ -0,0 +1,15 @@
+import { DomainError, implement, type MethodContribution } from "@aicontainer/ragents";
+import { askContracts } from "../contract.js";
+import type { RuntimeAskService } from "./ask-service.js";
+
+export const createAnswerMethod = (
+  service: RuntimeAskService,
+  ensureSession: (runId: string) => void,
+): MethodContribution => implement(askContracts.answer, ({ runId, actionId, answer, dismiss }) => {
+  if (dismiss !== true && (typeof answer !== "string" || answer.trim() === "")) {
+    throw new DomainError("answer-missing", "answer ist erforderlich, wenn nicht verworfen wird", 400);
+  }
+  ensureSession(runId);
+  service.answer(runId, actionId, { ...(answer !== undefined ? { answer } : {}), ...(dismiss !== undefined ? { dismiss } : {}) });
+  return null;
+});