@schlenkr/ragents 0.1.0

package/plugins/ragents.ask/server/ask-service.ts

@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import {
+  DomainError,
+  type Action,
+  type CommandContext,
+  type JournalEvent,
+  type Orchestration,
+} from "@aicontainer/ragents";
+import type { AskCall, AskRequest, AskService } from "./contract.js";
+
+export const DISMISSED_ANSWER = "Der Benutzer hat die Frage verworfen.";
+
+const answerOf = (decision: "approved" | "dismissed", response: string | null): string =>
+  decision === "approved" ? response ?? "" : DISMISSED_ANSWER;
+
+const resolvedAnswerOf = (action: Action): string | null =>
+  action.status === "pending" ? null : answerOf(action.status, action.response);
+
+export class RuntimeAskService implements AskService {
+  #runtime: Orchestration | undefined;
+  readonly #waiters = new Map<string, (answer: string) => void>();
+  readonly #aborting = new Set<string>();
+
+  bind(runtime: Orchestration): void {
+    if (this.#runtime) throw new Error("Der Ask-Service wurde bereits an eine Runtime gebunden");
+    this.#runtime = runtime;
+    runtime.subscribe((events) => this.#onJournal(events));
+  }
+
+  ask(call: AskCall, request: AskRequest, signal: AbortSignal | undefined): Promise<string> {
+    const runtime = this.#requireRuntime();
+    const context: CommandContext = {
+      actorId: call.agentId,
+      commandId: call.commandId,
+      ...(call.turnId ? { turnId: call.turnId, correlationId: call.turnId, causationId: call.turnId } : {}),
+    };
+    runtime.proposeAction(context, call.runId, {
+      kind: "question",
+      question: { options: request.options, multi: request.multi === true },
+      title: request.question,
+      description: request.description,
+      parameters: request.parameters,
+      input: { label: "Antwort", placeholder: null, required: true },
+    });
+    const proposed = runtime.events(call.runId).find((event) =>
+      event.type === "action.proposed" && event.commandId === call.commandId);
+    if (proposed?.type !== "action.proposed") {
+      throw new Error(`Die Frage von ${call.agentId} wurde nicht im Journal von ${call.runId} angelegt`);
+    }
+    return this.#awaitAnswer(call.runId, proposed.payload.actionId, signal);
+  }
+
+  answer(runId: string, actionId: string, input: { answer?: string; dismiss?: boolean }): void {
+    const runtime = this.#requireRuntime();
+    const state = runtime.state(runId);
+    const action = state.actions.get(actionId);
+    if (!action || action.kind !== "question") {
+      throw new DomainError("question-not-found", `Frage ${actionId} existiert nicht in Run ${runId}.`, 404);
+    }
+    runtime.resolveAction(
+      { actorId: state.ownerId, commandId: `ask-answer:${actionId}:${randomUUID()}` },
+      runId,
+      actionId,
+      input.dismiss === true
+        ? { decision: "dismissed", response: null }
+        : { decision: "approved", response: input.answer ?? null },
+    );
+  }
+
+  #awaitAnswer(runId: string, actionId: string, signal: AbortSignal | undefined): Promise<string> {
+    const runtime = this.#requireRuntime();
+    const action = runtime.state(runId).actions.get(actionId);
+    if (!action) throw new Error(`Frage ${actionId} existiert nicht in Run ${runId}`);
+    const settled = resolvedAnswerOf(action);
+    if (settled !== null) return Promise.resolve(settled);
+    return new Promise<string>((resolve, reject) => {
+      const abort = () => {
+        this.#waiters.delete(actionId);
+        this.#aborting.add(actionId);
+        try {
+          const state = runtime.state(runId);
+          const pending = state.actions.get(actionId);
+          if (pending?.status === "pending") {
+            runtime.resolveAction(
+              { actorId: state.ownerId, commandId: `ask-abort:${actionId}:${randomUUID()}` },
+              runId,
+              actionId,
+              { decision: "dismissed", response: null },
+            );
+          }
+          reject(new Error("Das Warten auf die Antwort wurde abgebrochen."));
+        } catch (error) {
+          reject(error);
+        } finally {
+          this.#aborting.delete(actionId);
+        }
+      };
+      if (signal?.aborted) {
+        abort();
+        return;
+      }
+      signal?.addEventListener("abort", abort, { once: true });
+      this.#waiters.set(actionId, (answer) => {
+        signal?.removeEventListener("abort", abort);
+        this.#waiters.delete(actionId);
+        resolve(answer);
+      });
+    });
+  }
+
+  #onJournal(events: JournalEvent[]): void {
+    for (const event of events) {
+      if (event.type !== "action.resolved") continue;
+      if (this.#aborting.has(event.payload.actionId)) continue;
+      const resolved = this.#requireRuntime().state(event.runId).actions.get(event.payload.actionId);
+      if (resolved?.kind !== "question") continue;
+      const answer = answerOf(event.payload.decision, event.payload.response);
+      const waiter = this.#waiters.get(event.payload.actionId);
+      if (waiter) {
+        waiter(answer);
+        continue;
+      }
+      queueMicrotask(() => this.#enqueueAnswer(event.runId, event.payload.actionId, answer));
+    }
+  }
+
+  #enqueueAnswer(runId: string, actionId: string, answer: string): void {
+    try {
+      const runtime = this.#requireRuntime();
+      const state = runtime.state(runId);
+      const action = state.actions.get(actionId);
+      if (!action) return;
+      const asker = state.actors.get(action.askedBy);
+      if (!asker || asker.kind === "human" || asker.lifecycle.kind === "stopped") return;
+      runtime.enqueueInput(
+        { actorId: state.ownerId, commandId: `ask-input:${actionId}` },
+        runId,
+        {
+          actorId: action.askedBy,
+          content: `Antwort auf deine Frage: ${action.title}\nAntwort: ${answer}`,
+        },
+      );
+    } catch (error) {
+      console.error(`Antwort auf Frage ${actionId} konnte nicht als Input eingereiht werden: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  #requireRuntime(): Orchestration {
+    if (!this.#runtime) throw new Error("Der Ask-Service ist noch nicht an die Runtime gebunden");
+    return this.#runtime;
+  }
+}

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

@@ -0,0 +1,39 @@
+import { Type } from "typebox";
+import { defineRunFunction, type RunFunction } from "@aicontainer/ragents";
+import { facesOperator } from "@aicontainer/server/plugin-support/tool-availability.js";
+import type { AskService } from "./contract.js";
+
+export const askToolMetadata = {
+  name: "ask_user",
+  label: "Rückfrage",
+  description: "Holt eine nötige Benutzerentscheidung mit Antwortoptionen ein und wartet auf die Antwort.",
+  longDescription: "Nutze dieses Werkzeug immer, wenn du eine Entscheidung des Benutzers brauchst "
+    + "(z.B. Auswahl eines Branches oder eines Zeitraums), statt die Frage nur als Text zu stellen. "
+    + "Mit multi=true darf der Benutzer mehrere Optionen wählen; die Antwort ist dann mit '; ' verbunden. "
+    + "Der Benutzer kann statt einer Option auch immer frei antworten - rechne also damit, "
+    + "dass die Antwort beliebiger Text sein kann.",
+} as const;
+
+export const createAskTool = (service: AskService): RunFunction =>
+  defineRunFunction({
+    ...askToolMetadata,
+    schema: Type.Object({
+      question: Type.String({ description: "Die Frage an den Benutzer, kurz und konkret" }),
+      options: Type.Array(Type.String(), { description: "Antwortoptionen (2 bis 6 Stück)" }),
+      multi: Type.Optional(Type.Boolean({ description: "true = Mehrfachauswahl erlaubt" })),
+    }),
+    resultSchema: Type.String(),
+    available: facesOperator,
+    executionMode: "sequential",
+    run: (scope, toolCallId, input) =>
+      service.ask(
+        {
+          runId: scope.caller.runId,
+          agentId: scope.caller.actorId,
+          turnId: scope.caller.turnId,
+          commandId: scope.context(toolCallId).commandId,
+        },
+        { question: input.question, options: input.options, multi: input.multi === true },
+        scope.signal,
+      ),
+  });

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

@@ -0,0 +1,22 @@
+import { serviceToken, type ServiceToken } from "@aicontainer/ragents";
+
+export interface AskCall {
+  runId: string;
+  agentId: string;
+  turnId: string | null;
+  commandId: string;
+}
+
+export interface AskRequest {
+  question: string;
+  options: string[];
+  multi?: boolean;
+  description?: string;
+  parameters?: Record<string, string>;
+}
+
+export interface AskService {
+  ask: (call: AskCall, request: AskRequest, signal: AbortSignal | undefined) => Promise<string>;
+}
+
+export const askServiceToken: ServiceToken<AskService> = serviceToken("ragents.ask.service");

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

@@ -0,0 +1,26 @@
+import type { RAgentsPlugin } from "@aicontainer/ragents";
+import { pluginAssetPath } from "@aicontainer/server/plugin-support/asset-path.js";
+import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { handlebarsPrompt } from "@aicontainer/server/plugin-support/prompt.js";
+import { sessionGuardToken } from "@aicontainer/server/ragents/host-services.js";
+import { runtimeBridgeToken } from "@aicontainer/server/ragents/runtime-bridge.js";
+import { createAnswerMethod } from "./answer-method.js";
+import { RuntimeAskService } from "./ask-service.js";
+import { askServiceToken } from "./contract.js";
+import { createAskToolContributor } from "./tool-contributor.js";
+
+const askPromptPath = pluginAssetPath(import.meta.url, "../ask.hbs");
+
+const askPlugin: RAgentsPlugin = {
+  manifest: { id: "ragents.ask" },
+  register: (host) => {
+    const service = new RuntimeAskService();
+    host.provide(askServiceToken, service);
+    host.provide(runtimeBridgeToken, { bind: (runtime) => service.bind(runtime) });
+    host.prompts(handlebarsPrompt("ragents.ask.prompt", 480, askPromptPath));
+    host.functions(createAskToolContributor(service));
+    host.methods(createAnswerMethod(service, host.service(sessionGuardToken)));
+  },
+};
+
+export const plugin: PluginModule = { create: () => askPlugin };

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

@@ -0,0 +1,11 @@
+import type { ToolContributor } from "@aicontainer/ragents";
+import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { facesOperator } from "@aicontainer/server/plugin-support/tool-availability.js";
+import { askToolMetadata, createAskTool } from "./ask-tool.js";
+import type { AskService } from "./contract.js";
+
+export const createAskToolContributor = (service: AskService): ToolContributor => ({
+  name: "ragents.ask",
+  descriptors: [toolDescriptorFrom(askToolMetadata, facesOperator)],
+  tools: () => [createAskTool(service)],
+});

package/plugins/ragents.ask/web/QuestionSection.tsx

@@ -0,0 +1,47 @@
+import { useAccess } from "@aicontainer/web/AccessContext";
+import { useState } from "react";
+import { QuestionCard } from "@aicontainer/web/chat/QuestionCard";
+import { runActorFrom, runViewFrom } from "@aicontainer/plugins/ragents.orchestration/web/contract";
+import type { CardSectionContext } from "@aicontainer/web/PluginRegistry";
+import { SectionLabel } from "@aicontainer/web/ui";
+
+export function QuestionSection({ actor, session }: CardSectionContext) {
+  const access = useAccess();
+  const [error, setError] = useState<string>();
+  const view = runViewFrom(session.runView);
+  if (!view) return null;
+  const actorId = runActorFrom(actor).id;
+  const pending = view.actions.filter((action) =>
+    action.kind === "question" && action.askedBy === actorId && action.status === "pending");
+  if (pending.length === 0) return null;
+
+  const answer = (actionId: string, text: string) => {
+    setError(undefined);
+    session.respond(actionId, text)
+      .catch((caught: unknown) => setError(caught instanceof Error ? caught.message : String(caught)));
+  };
+
+  return (
+    <section className="grid gap-1.5">
+      <SectionLabel>
+        <span>Rückfrage</span>
+        <small>{pending.length}</small>
+      </SectionLabel>
+      {pending.map((action) => (
+        <div className="rounded-lg animate-ring-pulse motion-reduce:animate-none" key={action.id}>
+          {action.description && <p className="mb-1.5 text-[0.7rem] leading-[1.35] text-muted-foreground">{action.description}</p>}
+          <QuestionCard
+            onAnswer={access.can("runs.write") ? (text) => answer(action.id, text) : undefined}
+            question={{
+              callId: action.id,
+              options: action.question?.options ?? [],
+              multi: action.question?.multi ?? false,
+            }}
+            text={action.title}
+          />
+        </div>
+      ))}
+      {error && <p className="text-[0.7rem] text-destructive" role="alert">{error}</p>}
+    </section>
+  );
+}

package/plugins/ragents.ask/web/api.ts

@@ -0,0 +1,6 @@
+import { rpc } from "@aicontainer/web/rpc";
+import { askContracts } from "../contract";
+
+export const answerQuestion = async (runId: string, actionId: string, answer: string): Promise<void> => {
+  await rpc.call(askContracts.answer, { runId, actionId, answer });
+};

package/plugins/ragents.ask/web/constants.ts

@@ -0,0 +1 @@
+export const ASK_PLUGIN_ID = "ragents.ask";

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

@@ -0,0 +1,50 @@
+import {
+  type SessionContext,
+  type WebPlugin,
+  type WebPluginDescriptor,
+} from "@aicontainer/web/PluginRegistry";
+import { runViewFrom, type RunView } from "@aicontainer/plugins/ragents.orchestration/web/contract";
+import { answerQuestion } from "./api";
+import { QuestionSection } from "./QuestionSection";
+
+const pendingQuestions = (view: RunView) =>
+  view.actions.filter((action) => action.kind === "question" && action.status === "pending");
+
+const askerHandle = (view: RunView, askedBy: string): string =>
+  view.actors.find((actor) => actor.id === askedBy)?.handle ?? askedBy;
+
+const attentionFor = (session: SessionContext) => {
+  const view = runViewFrom(session.runView);
+  if (!view) return undefined;
+  const [first, ...rest] = pendingQuestions(view);
+  if (!first) return undefined;
+  return {
+    active: true as const,
+    label: rest.length === 0
+      ? `@${askerHandle(view, first.askedBy)} fragt`
+      : `${rest.length + 1} Rückfragen offen`,
+  };
+};
+
+const configuredPlugin = (descriptor: WebPluginDescriptor): WebPlugin => ({
+  ...descriptor,
+  needsRunView: true,
+  questionResponder: (session, callId, payload) =>
+    answerQuestion(session.id, callId, typeof payload === "string" ? payload : JSON.stringify(payload)),
+  cardSections: [{
+    id: "ragents.ask.questions",
+    order: 100,
+    Section: QuestionSection,
+  }],
+  attention: [{
+    id: "ragents.ask.pending-questions",
+    assess: attentionFor,
+  }],
+});
+
+const descriptor: WebPluginDescriptor = { id: "ragents.ask" };
+
+export const webPlugin: WebPlugin = {
+  ...descriptor,
+  activate: () => configuredPlugin(descriptor),
+};

package/plugins/ragents.browser/provision.ts

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { chromium } from "playwright-core";
+import {
+  provisionGap,
+  provisionReady,
+  type PluginProvision,
+} from "@aicontainer/server/plugin-support/provision.js";
+
+const executable = async (file: string): Promise<boolean> => access(file, constants.X_OK).then(() => true, () => false);
+
+const playwrightCli = (): string =>
+  path.join(path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json")), "cli.js");
+
+const install = (log: (line: string) => void): Promise<void> => new Promise((resolve, reject) => {
+  const child = spawn(process.execPath, [playwrightCli(), "install", ...(process.platform === "linux" ? ["--with-deps"] : []), "chromium"], { stdio: ["ignore", "pipe", "pipe"] });
+  for (const stream of [child.stdout, child.stderr]) stream.on("data", (chunk: Buffer) => log(chunk.toString().trimEnd()));
+  child.once("error", reject);
+  child.once("exit", (code) => code === 0 ? resolve() : reject(new Error(`playwright-core install chromium endete mit Code ${code}`)));
+});
+
+// Playwright verwaltet seinen Browsercache selbst; der Werkzeugordner des Plugins bleibt leer.
+export const createBrowserProvision = (): PluginProvision => ({
+  check: async () => {
+    const configured = process.env.BROWSER_EXECUTABLE_PATH;
+    if (configured) {
+      return await executable(configured)
+        ? provisionReady
+        : provisionGap("browser", `BROWSER_EXECUTABLE_PATH nennt ${configured}; dort gibt es keinen ausführbaren Browser`, false);
+    }
+    const bundled = chromium.executablePath();
+    return await executable(bundled)
+      ? provisionReady
+      : provisionGap("chromium", `Chromium fehlt unter ${bundled}; entweder BROWSER_EXECUTABLE_PATH in der Profilsektion ragents.browser `
+        + "auf einen vorhandenen Chrome setzen oder die Provisionierung den Browser laden lassen", true);
+  },
+  apply: async (_target, log) => {
+    const state = await createBrowserProvision().check("");
+    if (state.kind === "ready") return;
+    if (!state.installable) throw new Error(state.instruction);
+    log("Chromium für playwright-core laden");
+    await install(log);
+  },
+});
+
+export const provision = createBrowserProvision();