@schlenkr/ragents 0.1.0

package/plugins/ragents.reference/web/StartGuides.tsx

@@ -0,0 +1,89 @@
+import { useState } from "react";
+import type { EntryGuideContext } from "@aicontainer/web/PluginRegistry";
+import { Button, Card, Input, Textarea } from "@aicontainer/web/ui";
+
+const formClass = "grid gap-5.5 mx-auto max-w-[820px] p-6 text-foreground max-sm:p-4.5";
+const introClass = "leading-[1.6] text-muted-foreground";
+const fieldClass = "grid min-w-0 gap-2.5 [&>span]:font-semibold";
+const hintClass = "leading-[1.5] text-muted-foreground";
+const actionsClass = "flex flex-wrap justify-end gap-2.5 pt-2";
+
+export function ConversationGuide({ onCancel, onComplete }: EntryGuideContext) {
+  const [topic, setTopic] = useState("Sollten Innenstädte autofrei werden?");
+  const [rounds, setRounds] = useState("2");
+  const count = Number(rounds);
+  const valid = topic.trim().length > 0 && Number.isInteger(count) && count >= 1 && count <= 5;
+
+  return (
+    <form className={formClass} onSubmit={(event) => {
+      event.preventDefault();
+      if (valid) onComplete({ topic: topic.trim(), rounds: count });
+    }}>
+      <p className={introClass}>Drei Perspektiven auf eine Frage. Der Koordinator führt durch die Runde und fasst die Ergebnisse zusammen.</p>
+      <label className={fieldClass}>
+        <span>Worüber soll die Runde sprechen?</span>
+        <Textarea autoFocus maxLength={160} onChange={(event) => setTopic(event.target.value)} required rows={3} value={topic} />
+      </label>
+      <div aria-label="Gesprächspartner" className="grid grid-cols-3 gap-3.5 max-sm:grid-cols-1 max-sm:gap-2">
+        {[
+          { name: "Mira", role: "Fragt neugierig nach" },
+          { name: "Jon", role: "Widerspricht höflich" },
+          { name: "Ada", role: "Sucht Gemeinsamkeiten" },
+        ].map((partner) => (
+          <div className="grid gap-[7px] rounded-lg bg-secondary p-3.5" key={partner.name}>
+            <strong>{partner.name}</strong>
+            <span className="text-[0.85rem] leading-[1.4] text-muted-foreground">{partner.role}</span>
+          </div>
+        ))}
+      </div>
+      <label className={fieldClass}>
+        <span>Runden</span>
+        <Input className="max-w-25" max={5} min={1} onChange={(event) => setRounds(event.target.value)} required step={1} type="number" value={rounds} />
+        <small className={hintClass}>1 bis 5 Runden, mit einem Beitrag pro Person und Runde.</small>
+      </label>
+      <div className={actionsClass}>
+        <Button onClick={onCancel} variant="outline">Abbrechen</Button>
+        <Button disabled={!valid} type="submit">Gespräch starten</Button>
+      </div>
+    </form>
+  );
+}
+
+export function SharedBoardGuide({ onCancel, onComplete }: EntryGuideContext) {
+  const [title, setTitle] = useState("Ideen für unser Teamfrühstück");
+  const [firstEntry, setFirstEntry] = useState("Jeder bringt etwas aus seiner Lieblingsküche mit.");
+  const valid = title.trim().length > 0 && firstEntry.trim().length > 0;
+
+  return (
+    <form className={formClass} onSubmit={(event) => {
+      event.preventDefault();
+      if (valid) onComplete({ title: title.trim(), firstEntry: firstEntry.trim() });
+    }}>
+      <p className={introClass}>Sammelt Ideen, Fragen oder Aufgaben an einem Ort. Du ergänzt die Liste in seiner View, der Listenhelfer über sein Werkzeug.</p>
+      <div className="grid grid-cols-2 gap-6 max-sm:grid-cols-1">
+        <div className="grid min-w-0 gap-5.5">
+          <label className={fieldClass}>
+            <span>Was wollt ihr sammeln?</span>
+            <Input autoFocus maxLength={160} onChange={(event) => setTitle(event.target.value)} required value={title} />
+          </label>
+          <label className={fieldClass}>
+            <span>Erster Eintrag</span>
+            <Textarea maxLength={2000} onChange={(event) => setFirstEntry(event.target.value)} required rows={5} value={firstEntry} />
+          </label>
+        </div>
+        <aside aria-label="Vorschau des Sammelboards">
+          <Card className="h-full gap-0 bg-secondary p-5 [overflow-wrap:anywhere]">
+            <small className={hintClass}>So beginnt eure Sammlung</small>
+            <h3 className="mt-3 mb-4.5 text-[1.05rem]">{title.trim() || "Titel der Sammlung"}</h3>
+            <ol className="list-decimal pl-5.5 leading-[1.6] whitespace-pre-wrap"><li>{firstEntry.trim() || "Dein erster Eintrag"}</li></ol>
+            <p className="mt-5.5 text-[0.85rem] leading-[1.5] text-muted-foreground">Der Listenhelfer trägt diesen Eintrag nach dem Start ein. Danach könnt ihr beide ergänzen.</p>
+          </Card>
+        </aside>
+      </div>
+      <div className={actionsClass}>
+        <Button onClick={onCancel} variant="outline">Abbrechen</Button>
+        <Button disabled={!valid} type="submit">Sammelboard starten</Button>
+      </div>
+    </form>
+  );
+}

package/plugins/ragents.reference/web/index.tsx

@@ -0,0 +1,10 @@
+import type { WebPlugin } from "@aicontainer/web/PluginRegistry";
+import { ConversationGuide, SharedBoardGuide } from "./StartGuides";
+
+export const webPlugin: WebPlugin = {
+  id: "ragents.reference",
+  guides: [
+    { id: "ragents.reference.conversation-circle", Guide: ConversationGuide },
+    { id: "ragents.reference.shared-actor-list", Guide: SharedBoardGuide },
+  ],
+};

package/plugins/ragents.todo/contract.ts

@@ -0,0 +1,60 @@
+export const TODO_PLUGIN_ID = "ragents.todo";
+
+export const TODO_STATUSES = ["open", "active", "completed"] as const;
+export const TODO_STATUS_INPUTS = ["open", "active", "completed", "pending", "in_progress", "done"] as const;
+export type TodoStatus = typeof TODO_STATUSES[number];
+
+export interface TodoItem {
+  id: string;
+  text: string;
+  status: TodoStatus;
+}
+
+export interface TodoState {
+  todos: TodoItem[];
+}
+
+export const todoStatusOf = (value: unknown): TodoStatus | undefined => {
+  if (typeof value !== "string") return undefined;
+
+  switch (value.trim().toLowerCase()) {
+    case "open":
+    case "offen":
+    case "pending":
+      return "open";
+    case "active":
+    case "doing":
+    case "in_progress":
+    case "in arbeit":
+    case "running":
+      return "active";
+    case "completed":
+    case "done":
+    case "erledigt":
+    case "finished":
+      return "completed";
+    default:
+      return undefined;
+  }
+};
+
+const itemOf = (value: unknown): TodoItem | undefined => {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Partial<TodoItem>;
+  const status = todoStatusOf(candidate.status);
+
+  return typeof candidate.id === "string" && typeof candidate.text === "string" && status
+    ? { id: candidate.id, text: candidate.text, status }
+    : undefined;
+};
+
+export const todoStateOf = (state: unknown): TodoState | undefined => {
+  const candidate = state as Partial<TodoState> | undefined;
+  if (!Array.isArray(candidate?.todos)) return undefined;
+  const todos = candidate.todos.flatMap((value) => {
+    const item = itemOf(value);
+    return item ? [item] : [];
+  });
+
+  return todos.length === candidate.todos.length ? { todos } : undefined;
+};

package/plugins/ragents.todo/server/index.ts

@@ -0,0 +1,10 @@
+import type { RAgentsPlugin } from "@aicontainer/ragents";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { createTodoToolContributor } from "./tool-contributor.js";
+
+const todoPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.todo" },
+  register: (host) => host.functions(createTodoToolContributor()),
+};
+
+export const plugin: PluginModule = { create: () => todoPlugin };

package/plugins/ragents.todo/server/todo-tool.ts

@@ -0,0 +1,70 @@
+import { Type } from "typebox";
+import {
+  DomainError,
+  defineRunFunction,
+  defineToolAvailability,
+  eventResultSchema,
+  holdsUsable,
+  type RunFunction,
+} from "@aicontainer/ragents";
+import { TODO_PLUGIN_ID, TODO_STATUS_INPUTS, todoStatusOf } from "../contract.js";
+
+export const todoToolMetadata = {
+  name: "todo_replace",
+  label: "Replace To-do List",
+  description: "Replace this agent's complete to-do snapshot with its current progress.",
+  longDescription: "Mark an item completed only AFTER the work actually happened, never in advance; "
+    + "update the list as you go so at most one item is active.",
+} as const;
+
+export const canManageTodos = defineToolAvailability({
+  availability: "conditional",
+  availabilityDetail: "Nur für Agenten mit der Capability plugin.state.write.",
+}, (actor) => actor.kind === "agent" && holdsUsable(actor, "plugin.state.write"));
+
+const checked = (todos: readonly { id: string; text: string; status: string }[]) => {
+  const seen = new Set<string>();
+
+  return todos.map((todo, index) => {
+    const id = todo.id.trim();
+    const text = todo.text.trim();
+    const status = todoStatusOf(todo.status);
+
+    if (!id) throw new DomainError("invalid-todo", `todos[${index}].id ist leer.`, 400);
+    if (!text) throw new DomainError("invalid-todo", `todos[${index}].text ist leer.`, 400);
+    if (!status) throw new DomainError("invalid-todo", `todos[${index}].status ${todo.status} ist unbekannt.`, 400);
+    if (seen.has(id)) throw new DomainError("duplicate-todo-id", `To-do ID ${id} occurs more than once.`, 400);
+
+    seen.add(id);
+
+    return { id, text, status };
+  });
+};
+
+export const createTodoTool = (): RunFunction =>
+  defineRunFunction({
+    ...todoToolMetadata,
+    schema: Type.Object({
+      todos: Type.Array(
+        Type.Object({
+          id: Type.String({ minLength: 1 }),
+          text: Type.String({ minLength: 1 }),
+          status: Type.Union(TODO_STATUS_INPUTS.map((value) => Type.Literal(value)), {
+            description: "open = offen, active = in Arbeit, completed = erledigt; "
+              + "pending, in_progress und done werden ebenfalls angenommen",
+          }),
+        }),
+      ),
+    }),
+    resultSchema: eventResultSchema,
+    available: canManageTodos,
+    run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
+      runtime.replacePluginState(context(toolCallId), caller.runId, {
+        pluginId: TODO_PLUGIN_ID,
+        scope: { kind: "actor", actorId: caller.actorId },
+        state: { todos: checked(input.todos) },
+      });
+
+      return eventsFor(toolCallId);
+    },
+  });

package/plugins/ragents.todo/server/tool-contributor.ts

@@ -0,0 +1,9 @@
+import type { ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { canManageTodos, createTodoTool, todoToolMetadata } from "./todo-tool.js";
+
+export const createTodoToolContributor = (): ToolContributor => ({
+  name: "ragents.todo",
+  descriptors: [toolDescriptorFrom(todoToolMetadata, canManageTodos)],
+  tools: () => [createTodoTool()],
+});

package/plugins/ragents.todo/web/TodoSection.tsx

@@ -0,0 +1,47 @@
+import { actorPluginState, runActorFrom, runViewFrom } from "@aicontainer/plugins/ragents.orchestration/web/contract";
+import { TODO_PLUGIN_ID, todoStateOf, type TodoItem } from "../contract";
+import type { CardSectionContext } from "@aicontainer/web/PluginRegistry";
+import { SectionLabel } from "@aicontainer/web/ui";
+
+const MAX_ITEMS = 12;
+const markerOf = (todo: TodoItem) => todo.status;
+
+const markerClass = "grid size-[15px] mt-px place-items-center rounded-full border-[1.5px] border-foreground/55 text-[0px] not-italic"
+  + " in-data-[status=active]:border-primary in-data-[status=active]:bg-[color-mix(in_srgb,var(--primary)_14%,var(--card))]"
+  + " in-data-[status=completed]:border-success in-data-[status=completed]:bg-success";
+
+export function TodoSection({ actor, session }: CardSectionContext) {
+  const view = runViewFrom(session.runView);
+  if (!view) return null;
+  const state = todoStateOf(actorPluginState(view, TODO_PLUGIN_ID, runActorFrom(actor).id));
+  const todos = state?.todos ?? [];
+  if (todos.length === 0) return null;
+  const done = todos.filter((todo) => markerOf(todo) === "completed").length;
+
+  return (
+    <section className="grid gap-1.5">
+      <SectionLabel>
+        <span>To-do</span>
+        <small>{done}/{todos.length}</small>
+      </SectionLabel>
+      <ul className="grid list-none">
+        {todos.slice(0, MAX_ITEMS).map((todo) => (
+          <li className="grid grid-cols-[15px_minmax(0,1fr)] items-start gap-2 border-t border-border-soft py-1.5 text-[0.74rem] leading-[1.35] first:border-t-0 first:pt-0 last:pb-0"
+            data-status={markerOf(todo)} key={todo.id}>
+            <i aria-hidden className={markerClass}>{markerOf(todo) === "completed" && <IconCheck />}</i>
+            <span className="overflow-hidden text-ellipsis in-data-[status=completed]:opacity-75" title={todo.text}>{todo.text}</span>
+          </li>
+        ))}
+      </ul>
+      {todos.length > MAX_ITEMS && <small className="pl-0.5 text-xs text-muted-foreground">+{todos.length - MAX_ITEMS} weitere</small>}
+    </section>
+  );
+}
+
+function IconCheck() {
+  return (
+    <svg aria-hidden className="size-[11px] fill-none stroke-card [stroke-linecap:round] [stroke-linejoin:round] [stroke-width:2.2]" viewBox="0 0 12 12">
+      <path d="M3.1 6.2 5 8.1l3.9-4.2" />
+    </svg>
+  );
+}

package/plugins/ragents.todo/web/index.ts

@@ -0,0 +1,12 @@
+import { TodoSection } from "./TodoSection";
+import type { WebPlugin } from "@aicontainer/web/PluginRegistry";
+
+export const webPlugin: WebPlugin = {
+  id: "ragents.todo",
+  needsRunView: true,
+  cardSections: [{
+    id: "ragents.todo.items",
+    order: 200,
+    Section: TodoSection,
+  }],
+};

package/plugins/ragents.transcript/server/index.ts

@@ -0,0 +1,20 @@
+import type { RAgentsPlugin, ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { runtimeProviderToken } from "@aicontainer/server/ragents/host-services.js";
+import { canReadTranscripts, createTranscriptTool, transcriptToolMetadata } from "./transcript.js";
+
+const transcriptPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.transcript" },
+  register: (host) => {
+    const runtime = host.service(runtimeProviderToken);
+    const contributor: ToolContributor = {
+      name: "ragents.transcript",
+      descriptors: [toolDescriptorFrom(transcriptToolMetadata, canReadTranscripts)],
+      tools: () => [createTranscriptTool(runtime)],
+    };
+    host.functions(contributor);
+  },
+};
+
+export const plugin: PluginModule = { requires: ["ragents.orchestration"], create: () => transcriptPlugin };

package/plugins/ragents.transcript/server/transcript.ts

@@ -0,0 +1,78 @@
+import { Type } from "typebox";
+import { defineRunFunction, defineToolAvailability, holdsUsable, type JournalEvent, type Orchestration, type RunFunction } from "@aicontainer/ragents";
+
+export interface CompactTranscript { text: string; lines: number; truncated: boolean }
+
+const defaultMaxChars = 20_000;
+const markerReserve = 50;
+const collapse = (text: string, limit: number): string => {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > limit ? `${flat.slice(0, limit - 3)}...` : flat;
+};
+const compactJson = (value: unknown, limit: number): string => collapse(typeof value === "string" ? value : JSON.stringify(value) ?? "", limit);
+
+const lineOf = (event: JournalEvent, actorId: string): string | undefined => {
+  if (event.type === "actor.input.enqueued") {
+    if (event.payload.actorId !== actorId) return undefined;
+    return event.payload.content === undefined ? `> [Ereignis ${event.payload.sourceEventIds[0]}]` : `> ${collapse(event.payload.content, 1000)}`;
+  }
+  if (event.actorId !== actorId) return undefined;
+  switch (event.type) {
+    case "model.output.completed": return event.payload.text.trim() ? collapse(event.payload.text, 4000) : undefined;
+    case "tool.call.started": return `[${event.payload.name}] ${compactJson(event.payload.input, 200)}`;
+    case "tool.call.completed": return `  -> ${compactJson(event.payload.output, 300)}`;
+    case "tool.call.failed": return `  -> Fehler: ${collapse(event.payload.error, 300)}`;
+    case "turn.finished": return event.payload.outcome === "failed" ? `[Turn fehlgeschlagen: ${collapse(event.payload.reason, 300)}]` : undefined;
+    case "turn.interrupted": return `[Turn unterbrochen: ${collapse(event.payload.reason, 300)}]`;
+    default: return undefined;
+  }
+};
+
+export function compactTranscript(events: readonly JournalEvent[], actorId: string, maxChars = defaultMaxChars): CompactTranscript {
+  const lines = events.map((event) => lineOf(event, actorId)).filter((line): line is string => line !== undefined);
+  const total = lines.reduce((sum, line) => sum + line.length + 1, 0);
+  if (total <= maxChars) return { text: lines.join("\n"), lines: lines.length, truncated: false };
+  let dropped = 0;
+  let remaining = total;
+  while (dropped < lines.length && remaining + markerReserve > maxChars) {
+    remaining -= lines[dropped]!.length + 1;
+    dropped += 1;
+  }
+  const kept = lines.slice(dropped);
+  return { text: [`[... ${dropped} frühere Zeilen ausgelassen]`, ...kept].join("\n"), lines: kept.length, truncated: true };
+}
+
+export const transcriptToolMetadata = {
+  name: "actor_transcript",
+  label: "Verlauf verdichten",
+  description: "Liefert den Verlauf eines Actors dieses Runs als kompaktes Transkript: Eingaben, Antworttexte und Werkzeugaufrufe je eine Zeile, Ergebnisse gekürzt, ohne Reasoning. Für Übergaben, Statusberichte und Zusammenfassungen.",
+} as const;
+
+export const canReadTranscripts = defineToolAvailability({
+  availability: "conditional",
+  availabilityDetail: "Für Agenten und Skript-Actors mit der Capability event.subscribe.",
+}, (actor) => actor.kind !== "human" && holdsUsable(actor, "event.subscribe"));
+
+export const createTranscriptTool = (runtime: () => Orchestration): RunFunction =>
+  defineRunFunction({
+    ...transcriptToolMetadata,
+    schema: Type.Object({
+      actor: Type.String({ minLength: 1, description: "Handle mit oder ohne @ oder ID eines Actors dieses Runs" }),
+      maxChars: Type.Optional(Type.Integer({ minimum: 200, maximum: 200_000, description: `Obergrenze in Zeichen, Standard ${defaultMaxChars}; die ältesten Zeilen entfallen zuerst` })),
+    }, { additionalProperties: false }),
+    resultSchema: Type.Object({
+      actorId: Type.String(),
+      handle: Type.String(),
+      text: Type.String(),
+      lines: Type.Integer({ minimum: 0 }),
+      truncated: Type.Boolean(),
+    }, { additionalProperties: false }),
+    available: canReadTranscripts,
+    run: ({ caller }, _toolCallId, input) => {
+      const view = runtime().view(caller.runId);
+      const handle = input.actor.replace(/^@/, "");
+      const actor = view.actors.find((entry) => entry.id === input.actor || entry.handle === handle);
+      if (!actor) throw new Error(`Unbekannter Actor in diesem Run: ${input.actor}`);
+      return { actorId: actor.id, handle: actor.handle, ...compactTranscript(runtime().events(caller.runId), actor.id, input.maxChars) };
+    },
+  });

package/plugins/ragents.watch/contract.ts

@@ -0,0 +1,48 @@
+export const WATCH_PLUGIN_ID = "ragents.watch";
+
+export type WatchDefinition = {
+  id: string;
+  sourceActorId: string;
+  sourceHandle: string;
+  targetActorId: string;
+  targetHandle: string;
+  condition: string;
+  observe?: string;
+  instruction?: string;
+  stallAfterSeconds?: number;
+  createdBy: string;
+};
+
+export type WatchVerdict = {
+  at: string;
+  wake: boolean;
+  reason: string;
+  changes: string[];
+};
+
+export type WatchSummary = {
+  id: string;
+  source: string;
+  target: string;
+  condition: string;
+  observe?: string;
+  stallAfterSeconds?: number;
+  wakes: number;
+  lastEvaluatedAt?: string;
+  lastVerdict?: WatchVerdict;
+};
+
+export type WatchRequest = {
+  source: string;
+  condition: string;
+  target?: string;
+  observe?: string;
+  instruction?: string;
+  stallAfterSeconds?: number;
+};
+
+export interface WatchServiceApi {
+  create(runId: string, callerActorId: string, request: WatchRequest): Promise<WatchSummary>;
+  list(runId: string): WatchSummary[];
+  remove(runId: string, watchId: string, reason: string): void;
+}

package/plugins/ragents.watch/server/condition.ts

@@ -0,0 +1,56 @@
+import { createContext, runInContext } from "node:vm";
+import { compileVirtualTypeScriptAsync, type JsonValue } from "@aicontainer/ragents";
+
+const conditionFile = "watch-condition.ts";
+const RUN_TIMEOUT_MS = 200;
+const REASON_CHARS = 300;
+
+export type WatchPredicate = (now: JsonValue, before: JsonValue) => string | undefined;
+
+export const watchStateDeclarations = `interface WatchTurn { readonly status: string; readonly reason?: string }
+interface WatchSource {
+  readonly lifecycle: "idle" | "running" | "stopped";
+  readonly stopReason?: string;
+  readonly completedTurns: number;
+  readonly lastTurn?: WatchTurn;
+  readonly pendingInputs: number;
+  readonly openQuestions: number;
+  readonly lastOutput?: string;
+}
+interface WatchState {
+  readonly source: WatchSource;
+  readonly observed?: Record<string, unknown>;
+  readonly stalledForSeconds?: number;
+}
+`;
+
+export class WatchConditionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WatchConditionError";
+  }
+}
+
+export const compileWatchCondition = async (condition: string, signal?: AbortSignal): Promise<WatchPredicate> => {
+  if (!condition.trim()) throw new WatchConditionError("Die Weckbedingung darf nicht leer sein.");
+  const compiled = await compileVirtualTypeScriptAsync({
+    sources: [{ fileName: conditionFile, text: `${watchStateDeclarations}\nconst wake = (now: WatchState, before: WatchState): string | undefined => {\n${condition}\n};\n` }],
+    emit: "node",
+  }, { signal });
+  if (!compiled.valid) {
+    throw new WatchConditionError(`Die Weckbedingung ist kein gültiges TypeScript:\n${compiled.diagnostics.map((diagnostic) =>
+      `${diagnostic.start ? `${Math.max(1, diagnostic.start.line - watchStateDeclarations.split("\n").length)}:${diagnostic.start.column} ` : ""}TS${diagnostic.code}: ${diagnostic.message}`).join("\n")}`);
+  }
+  const emitted = compiled.emittedFiles.find((file) => file.fileName.endsWith(".js"));
+  if (!emitted) throw new WatchConditionError("Die Weckbedingung hat keinen JavaScript-Code erzeugt.");
+  const sandbox = createContext(Object.create(null));
+  runInContext(`${emitted.text}\nglobalThis.wake = wake;`, sandbox, { timeout: RUN_TIMEOUT_MS });
+  return (now, before) => {
+    sandbox.now = now;
+    sandbox.before = before;
+    const result: unknown = runInContext("wake(now, before)", sandbox, { timeout: RUN_TIMEOUT_MS });
+    if (result === undefined || result === null || result === false) return undefined;
+    if (typeof result !== "string" || !result.trim()) throw new WatchConditionError(`Die Weckbedingung muss einen Grund als Text oder nichts liefern, nicht ${JSON.stringify(result)}.`);
+    return result.trim().slice(0, REASON_CHARS);
+  };
+};

package/plugins/ragents.watch/server/contract.ts

@@ -0,0 +1,4 @@
+import { serviceToken, type ServiceToken } from "@aicontainer/ragents";
+import type { WatchServiceApi } from "../contract.js";
+
+export const watchServiceToken: ServiceToken<WatchServiceApi> = serviceToken("ragents.watch.service");

package/plugins/ragents.watch/server/functions.ts

@@ -0,0 +1,62 @@
+import { Type } from "typebox";
+import { defineRunFunction, defineToolAvailability, type ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import type { WatchServiceApi } from "../contract.js";
+
+const available = defineToolAvailability({ availability: "always", availabilityDetail: "In jedem Run verfügbar." }, () => true);
+
+const verdictSchema = Type.Object({
+  at: Type.String({ description: "Zeitpunkt der Bewertung" }),
+  wake: Type.Boolean({ description: "Ob der Wächter geweckt hat" }),
+  reason: Type.String({ description: "Grund, den die Bedingung geliefert hat, oder 'Bedingung nicht erfüllt'" }),
+  changes: Type.Array(Type.String(), { description: "Änderungen seit der letzten Weckung, die der Bewertung vorlagen" }),
+}, { additionalProperties: false });
+
+const summarySchema = Type.Object({
+  id: Type.String({ description: "Kennung des Wächters für watch_remove" }),
+  source: Type.String({ description: "Beobachteter Actor als @handle" }),
+  target: Type.String({ description: "Geweckter Actor als @handle" }),
+  condition: Type.String({ description: "Weckbedingung als TypeScript-Funktionsrumpf" }),
+  observe: Type.Optional(Type.String({ description: "Benannte Operation, deren Ergebnis zum beobachteten Stand gehört" })),
+  stallAfterSeconds: Type.Optional(Type.Integer({ description: "Sekunden ohne Ereignis des beobachteten Actors, ab denen der Stand einen Stillstand nennt" })),
+  wakes: Type.Integer({ description: "Anzahl der bisherigen Weckungen" }),
+  lastEvaluatedAt: Type.Optional(Type.String({ description: "Zeitpunkt der letzten Bewertung" })),
+  lastVerdict: Type.Optional(verdictSchema),
+}, { additionalProperties: false });
+
+const createSchema = Type.Object({
+  source: Type.String({ minLength: 1, description: "Beobachteter Actor als @handle oder Kennung" }),
+  condition: Type.String({ minLength: 1, maxLength: 4_000, description: "Weckbedingung als TypeScript-Funktionsrumpf von (now: WatchState, before: WatchState) => string | undefined; liefert den Weckgrund als Text oder undefined. WatchState: source { lifecycle idle|running|stopped, completedTurns, lastTurn { status, reason? }, pendingInputs, openQuestions, lastOutput? }, observed (Ergebnis der observe-Operation als Record<string, unknown>), stalledForSeconds (nur bei Stillstand). before ist der Stand bei der letzten Weckung. Beispiel: return now.source.completedTurns > before.source.completedTurns && now.observed?.phase !== \"ready\" ? \"Turn beendet, Auftrag nicht fertig\" : undefined;" }),
+  target: Type.Optional(Type.String({ minLength: 1, description: "Zu weckender Actor als @handle oder Kennung; ohne Angabe der Aufrufer" })),
+  observe: Type.Optional(Type.String({ minLength: 1, description: "Benannte Operation ohne Eingabe, deren Ergebnis den beobachteten Stand ergänzt und per Differenz verglichen wird" })),
+  instruction: Type.Optional(Type.String({ minLength: 1, maxLength: 2_000, description: "Text, der jeder Weckung angehängt wird, etwa wie der Geweckte reagieren soll" })),
+  stallAfterSeconds: Type.Optional(Type.Integer({ minimum: 1, description: "Sekunden ohne Ereignis des beobachteten Actors, ab denen der Stand stalledForSeconds nennt" })),
+}, { additionalProperties: false });
+
+export const watchFunctions = (service: WatchServiceApi): ToolContributor => {
+  const functions = [
+    defineRunFunction({
+      name: "watch_create", label: "Wächter anlegen",
+      description: "Beobachtet einen Actor dieses Runs und weckt einen anderen mit einer Hintergrundnachricht, sobald die als TypeScript-Funktionsrumpf formulierte Bedingung im geänderten Stand einen Grund liefert. Kein Modell: Die Bedingung wird beim Anlegen typgeprüft und danach deterministisch bei jeder Änderung des beobachteten Stands ausgeführt, sobald der beobachtete Actor zur Ruhe gekommen ist; stalledForSeconds erscheint nach stallAfterSeconds ohne Aktivität und danach je weitere Periode erneut. Ein gleicher Wächter wird nicht doppelt angelegt.",
+      schema: createSchema, resultSchema: summarySchema, available,
+      run: (scope, _toolCallId, input) => service.create(scope.caller.runId, scope.caller.actorId, input),
+    }),
+    defineRunFunction({
+      name: "watch_list", label: "Wächter auflisten",
+      description: "Listet die Wächter dieses Runs mit Bedingung, Anzahl der Weckungen und letztem Urteil.",
+      schema: Type.Object({}, { additionalProperties: false }), resultSchema: Type.Array(summarySchema), available,
+      run: (scope) => service.list(scope.caller.runId),
+    }),
+    defineRunFunction({
+      name: "watch_remove", label: "Wächter entfernen",
+      description: "Entfernt einen Wächter dieses Runs; danach weckt er nicht mehr.",
+      schema: Type.Object({
+        id: Type.String({ minLength: 1, description: "Kennung aus watch_create oder watch_list" }),
+        reason: Type.String({ minLength: 1, description: "Grund der Entfernung" }),
+      }, { additionalProperties: false }),
+      resultSchema: Type.Object({ removed: Type.Literal(true) }, { additionalProperties: false }), available,
+      run: (scope, _toolCallId, input) => { service.remove(scope.caller.runId, input.id, input.reason); return { removed: true as const }; },
+    }),
+  ];
+  return { name: "ragents.watch", descriptors: functions.map((fn) => toolDescriptorFrom(fn, available)), tools: () => functions };
+};

package/plugins/ragents.watch/server/index.ts

@@ -0,0 +1,39 @@
+import type { JsonValue, RAgentsPlugin } from "@aicontainer/ragents";
+import { randomUUID } from "node:crypto";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { runtimeProviderToken } from "@aicontainer/server/ragents/host-services.js";
+import { WATCH_PLUGIN_ID } from "../contract.js";
+import { watchServiceToken } from "./contract.js";
+import { compileWatchCondition } from "./condition.js";
+import { watchFunctions } from "./functions.js";
+import { WatchService } from "./service.js";
+
+const watchPlugin: RAgentsPlugin = {
+  manifest: { id: WATCH_PLUGIN_ID },
+  register: (host) => {
+    const runtime = host.service(runtimeProviderToken);
+    const service = new WatchService({
+      runtime,
+      compile: (condition, signal) => compileWatchCondition(condition, signal),
+      operationExists: (id) => host.operation(id) !== undefined,
+      observe: (runId, id, signal) => host.invokeOperation(id, {
+        runId, invocationId: `ragents.watch:${randomUUID()}`, signal,
+        principal: { kind: "operator", actorId: runtime().view(runId).ownerId },
+      }, {}) as Promise<JsonValue>,
+    });
+    host.provide(watchServiceToken, service);
+    host.functions(watchFunctions(service));
+    host.lifecycle({
+      id: "ragents.watch.lifecycle",
+      prepareSession: ({ runId }) => service.prepare(runId),
+      stopSession: ({ runId }) => service.stop(runId),
+      deleteSession: ({ runId }) => service.stop(runId),
+      shutdown: () => service.shutdown(),
+    });
+  },
+};
+
+export const plugin: PluginModule = {
+  requires: ["ragents.orchestration"],
+  create: () => watchPlugin,
+};