@schlenkr/ragents 0.1.5 → 0.1.6

package/plugins/ragents.lsp-roslyn/server/solution-on-start.ts

@@ -0,0 +1,145 @@
+import type { Orchestration, SessionLifecycleContribution } from "@ragents/engine";
+import {
+  languageServerOpenOperation,
+  languageServerSolutionsOperation,
+  type LanguageServerSolutions,
+} from "@ragents/workspace-executor";
+import type { SandboxServices } from "@ragents/host/plugin-support/workspace-sandbox-host.js";
+import { DISMISSED_ANSWER, type AskService } from "@ragents/plugins/ragents.ask/server/contract.js";
+
+export const SOLUTION_ON_START_VARIABLE = "ROSLYN_SOLUTION_ON_START";
+export const NO_SOLUTION = "Keine laden";
+export const SOLUTION_QUESTION = "Welche Solution soll Roslyn für die Diagnostik laden?";
+
+export type SolutionStartStep =
+  | { kind: "none" }
+  | { kind: "open"; path: string }
+  | { kind: "ask"; options: readonly string[] };
+
+export type SolutionAnswer =
+  | { kind: "none" }
+  | { kind: "open"; path: string }
+  | { kind: "forward" };
+
+/** Was jemand schon geöffnet hat oder gerade öffnet, bleibt ohne Frage und ohne zweites Laden. */
+export const solutionStartStep = (listing: LanguageServerSolutions): SolutionStartStep => {
+  if (listing.opened || listing.solutions.length === 0) return { kind: "none" };
+  if (listing.solutions.length === 1) return { kind: "open", path: listing.solutions[0].path };
+  return { kind: "ask", options: [...listing.solutions.map((solution) => solution.path), NO_SOLUTION] };
+};
+
+/** Eine frei formulierte Antwort bekommt der Koordinator, damit sie nicht verloren geht. */
+export const solutionAnswer = (options: readonly string[], answer: string): SolutionAnswer => {
+  const chosen = answer.trim().replaceAll("\\", "/");
+  if (chosen === NO_SOLUTION || answer === DISMISSED_ANSWER) return { kind: "none" };
+  return options.includes(chosen) ? { kind: "open", path: chosen } : { kind: "forward" };
+};
+
+export interface SolutionOnStartOptions {
+  pluginId: string;
+  adapterId: string;
+  sandbox: () => SandboxServices;
+  runtime: () => Orchestration;
+  ask: () => AskService;
+}
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+/** Lädt beim Start ohne Run-Script die einzige Solution oder fragt bei mehreren; der Merker im Journal lässt das je Run höchstens einmal zu. */
+export interface SolutionOnStart {
+  lifecycle: SessionLifecycleContribution;
+  /** Jemand hat eine Instanz geöffnet; eine noch offene Startfrage erledigt sich damit ohne Laden und ohne Input. */
+  opened: (runId: string) => void;
+}
+
+export const createSolutionOnStart = (options: SolutionOnStartOptions): SolutionOnStart => {
+  const running = new Map<string, AbortController>();
+  const openTool = languageServerOpenOperation(options.adapterId);
+  const questionCommand = (runId: string): string => `${options.pluginId}.solution-question:${runId}`;
+
+  const marked = (runId: string): boolean => options.runtime().view(runId).pluginStates
+    .some((entry) => entry.pluginId === options.pluginId && entry.scope.kind === "run");
+
+  const load = async (runId: string, path: string, ifNoneOpen: boolean, signal: AbortSignal): Promise<void> => {
+    await options.sandbox().execute(runId, openTool, { root: path, ifNoneOpen }, { signal });
+  };
+
+  const answered = async (runId: string, coordinatorId: string, choices: readonly string[], answer: string, signal: AbortSignal) => {
+    const outcome = solutionAnswer(choices, answer);
+    if (outcome.kind === "open") return load(runId, outcome.path, false, signal);
+    if (outcome.kind === "none") return;
+    const runtime = options.runtime();
+    runtime.enqueueInput(
+      { actorId: runtime.state(runId).ownerId, commandId: `${options.pluginId}.solution-answer:${runId}` },
+      runId,
+      { actorId: coordinatorId, content: `Antwort auf die Frage: ${SOLUTION_QUESTION}\nAntwort: ${answer}\n${openTool} lädt eine Solution.` },
+    );
+  };
+
+  const begin = async (runId: string, ownerId: string, coordinatorId: string, signal: AbortSignal): Promise<{ rest: Promise<void> }> => {
+    const listing = await options.sandbox().execute(runId, languageServerSolutionsOperation(options.adapterId), null, { signal }) as LanguageServerSolutions;
+    const step = solutionStartStep(listing);
+    if (step.kind === "none") return { rest: Promise.resolve() };
+    if (step.kind === "open") return { rest: load(runId, step.path, true, signal) };
+    const answer = options.ask().ask(
+      { runId, agentId: ownerId, turnId: null, commandId: questionCommand(runId) },
+      {
+        question: SOLUTION_QUESTION,
+        description: "Im Arbeitsbereich liegen mehrere Solutions; die gewählte lädt Roslyn für die Diagnostik ohne Build.",
+        options: [...step.options],
+        recipient: coordinatorId,
+      },
+      signal,
+    );
+    return { rest: answer.then((text) => answered(runId, coordinatorId, step.options, text, signal)) };
+  };
+
+  const finish = (runId: string, controller: AbortController, error?: unknown): void => {
+    if (error !== undefined && !controller.signal.aborted) {
+      console.error(`${options.pluginId}: Solution beim Start von ${runId} nicht geladen: ${messageOf(error)}`);
+    }
+    if (running.get(runId) === controller) running.delete(runId);
+  };
+
+  const stop = ({ runId }: { runId: string }): void => {
+    running.get(runId)?.abort(new Error("Der Run wurde gestoppt"));
+    running.delete(runId);
+  };
+
+  const opened = (runId: string): void => {
+    try {
+      const proposed = options.runtime().events(runId).find((event) =>
+        event.type === "action.proposed" && event.commandId === questionCommand(runId));
+      if (proposed?.type === "action.proposed") options.ask().withdraw(runId, proposed.payload.actionId);
+    } catch (error) {
+      console.error(`${options.pluginId}: Startfrage von ${runId} nicht verworfen: ${messageOf(error)}`);
+    }
+  };
+
+  const lifecycle: SessionLifecycleContribution = {
+    id: `${options.pluginId}.solution-on-start`,
+    sessionStarted: async ({ runId, startEntry }) => {
+      if (marked(runId)) return;
+      const runtime = options.runtime();
+      const { ownerId, primaryActorId } = runtime.state(runId);
+      runtime.replacePluginState(
+        { actorId: ownerId, commandId: `${options.pluginId}.solution-on-start:${runId}` },
+        runId,
+        { pluginId: options.pluginId, scope: { kind: "run" }, state: { version: 1, startEntry: startEntry?.id ?? null } },
+      );
+      if (startEntry?.action === "script") return;
+      if (!primaryActorId) throw new Error(`Der Run ${runId} hat beim Start keinen Koordinator, dem eine Antwort zugehen könnte`);
+      const controller = new AbortController();
+      running.set(runId, controller);
+      try {
+        const { rest } = await begin(runId, ownerId, primaryActorId, controller.signal);
+        void rest.then(() => finish(runId, controller), (error: unknown) => finish(runId, controller, error));
+      } catch (error) {
+        finish(runId, controller, error);
+      }
+    },
+    stopSession: stop,
+    deleteSession: stop,
+  };
+  return { lifecycle, opened };
+};

package/plugins/ragents.lsp-roslyn/web/index.tsx

@@ -1,4 +1,4 @@
-import { languageServerWebPlugin } from "./language-server-plugin";
+import { languageServerWebPlugin } from "@ragents/web/language-server/language-server-plugin";
 
 export const webPlugin = languageServerWebPlugin("ragents.lsp-roslyn", LanguageIcon);
 

package/plugins/ragents.lsp-typescript/ragents-plugin.json

@@ -0,0 +1,3 @@
+{
+  "id": "ragents.lsp-typescript"
+}

package/plugins/ragents.lsp-typescript/server/index.ts

@@ -1,6 +1,6 @@
-import { typescriptAdapter } from "@aicontainer/workspace-executor";
-import { createLanguageServerPlugin } from "@aicontainer/server/plugin-support/language-server/plugin.js";
-import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
+import { typescriptAdapter } from "@ragents/workspace-executor";
+import { createLanguageServerPlugin } from "@ragents/host/plugin-support/language-server/plugin.js";
+import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
 
 export const plugin: PluginModule = {
   create: () => createLanguageServerPlugin({ id: "ragents.lsp-typescript", adapter: typescriptAdapter }),

package/plugins/ragents.lsp-typescript/web/index.tsx

@@ -1,4 +1,4 @@
-import { languageServerWebPlugin } from "@aicontainer/plugins/ragents.lsp-roslyn/web/language-server-plugin";
+import { languageServerWebPlugin } from "@ragents/web/language-server/language-server-plugin";
 
 export const webPlugin = languageServerWebPlugin("ragents.lsp-typescript", LanguageIcon);
 

package/plugins/ragents.model-relay/ragents-plugin.json

@@ -0,0 +1,3 @@
+{
+  "id": "ragents.model-relay"
+}

package/plugins/ragents.model-relay/server/config.ts

@@ -1,37 +1,11 @@
-import { declaredEnvironment } from "@aicontainer/server/plugin-support/plugin-config.js";
+import { configuredModelAliases, type ModelAlias } from "@ragents/host/plugin-support/model-aliases.js";
 
-export const modelRelayConfigDescriptors = [
-  { key: "RELAY_MODELS", source: "environment" },
-] as const;
-
-const env = declaredEnvironment(modelRelayConfigDescriptors);
-
-export interface RelayAlias {
-  readonly alias: string;
-  readonly upstream: string;
-  readonly model: string;
-}
-
-const ALIAS = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-
-/** RELAY_MODELS: eine Liste "alias=anbieter/modell"; der Alias ist der einzige Name, den ein Client sieht. */
-export const parseRelayAliases = (entries: readonly string[]): readonly RelayAlias[] => {
-  if (entries.length === 0) throw new Error("RELAY_MODELS nennt kein Modell; erwartet wird eine Liste \"alias=anbieter/modell\"");
-  const aliases = entries.map((entry) => {
-    const separator = entry.indexOf("=");
-    const alias = separator > 0 ? entry.slice(0, separator).trim() : "";
-    const target = separator > 0 ? entry.slice(separator + 1).trim() : "";
-    const slash = target.indexOf("/");
-    if (!ALIAS.test(alias) || slash <= 0 || slash === target.length - 1) {
-      throw new Error(`RELAY_MODELS: "${entry}" hat nicht das Format "alias=anbieter/modell"`);
-    }
-    return { alias, upstream: target.slice(0, slash), model: target.slice(slash + 1) };
-  });
-  const duplicate = aliases.find((entry, index) => aliases.findIndex((other) => other.alias === entry.alias) !== index);
-  if (duplicate) throw new Error(`RELAY_MODELS nennt den Alias ${duplicate.alias} mehrfach`);
+/** Das Relay bietet die Aliasse des Profils an (MODEL_ALIASES im Abschnitt host), dieselben wie für die eigenen Runs. */
+export const relayAliases = (aliases: readonly ModelAlias[]): readonly ModelAlias[] => {
+  if (aliases.length === 0) throw new Error("ragents.model-relay braucht MODEL_ALIASES im Abschnitt host; erwartet wird eine Liste \"alias=anbieter/modell\"");
   return aliases;
 };
 
 export const modelRelayConfig = Object.freeze({
-  aliases: () => parseRelayAliases(env.list("RELAY_MODELS")),
+  aliases: () => relayAliases(configuredModelAliases()),
 });

package/plugins/ragents.model-relay/server/index.ts

@@ -1,14 +1,13 @@
-import type { RAgentsPlugin } from "@aicontainer/ragents";
-import { modelUpstreamsToken } from "@aicontainer/server/plugin-support/model-upstreams.js";
-import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
-import { Protocol } from "@aicontainer/server/protocol.js";
-import { modelRelayConfig, modelRelayConfigDescriptors } from "./config.js";
+import type { RAgentsPlugin } from "@ragents/engine";
+import { modelUpstreamsToken } from "@ragents/host/plugin-support/model-upstreams.js";
+import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
+import { Protocol } from "@ragents/host/protocol.js";
+import { modelRelayConfig } from "./config.js";
 import { createRelayRoutes, resolveAliases, type ResolvedAlias } from "./relay.js";
 
 const modelRelayPlugin: RAgentsPlugin = {
   manifest: { id: "ragents.model-relay" },
   register: (host) => {
-    host.config(...modelRelayConfigDescriptors);
     const upstreams = host.service(modelUpstreamsToken);
     let resolved: readonly ResolvedAlias[] | undefined;
     const aliases = (): readonly ResolvedAlias[] => resolved ??= resolveAliases(modelRelayConfig.aliases(), upstreams());

package/plugins/ragents.model-relay/server/relay.ts

@@ -2,11 +2,10 @@ import type { IncomingMessage } from "node:http";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import type { ReadableStream } from "node:stream/web";
-import type { Api, Model } from "@aicontainer/ai";
-import type { HttpRouteContribution } from "@aicontainer/ragents";
-import { PayloadTooLargeError, readBody, writeJson } from "@aicontainer/server/plugin-support/http.js";
-import type { ModelUpstream } from "@aicontainer/server/plugin-support/model-upstreams.js";
-import type { RelayAlias } from "./config.js";
+import type { HttpRouteContribution } from "@ragents/engine";
+import { PayloadTooLargeError, readBody, writeJson } from "@ragents/host/plugin-support/http.js";
+import type { ModelAlias } from "@ragents/host/plugin-support/model-aliases.js";
+import type { ModelUpstream } from "@ragents/host/plugin-support/model-upstreams.js";
 
 export const RELAY_PATH_PREFIX = "/relay/v1";
 export const RELAY_RIGHT = "models.use";
@@ -18,19 +17,19 @@ const DROPPED_HEADERS = new Set(["host", "authorization", "cookie", "content-len
 export interface ResolvedAlias {
   readonly alias: string;
   readonly upstream: ModelUpstream;
-  readonly model: Model<Api>;
+  readonly model: ModelUpstream["models"][number];
 }
 
 /** Jeder Alias muss auf einen konfigurierten Anbieter und ein Modell aus dessen Katalog zeigen. */
-export const resolveAliases = (aliases: readonly RelayAlias[], upstreams: readonly ModelUpstream[]): readonly ResolvedAlias[] =>
+export const resolveAliases = (aliases: readonly ModelAlias[], upstreams: readonly ModelUpstream[]): readonly ResolvedAlias[] =>
   aliases.map((entry) => {
     const upstream = upstreams.find((candidate) => candidate.id === entry.upstream);
     if (!upstream) {
       const available = upstreams.map((candidate) => candidate.id).join(", ") || "keiner";
-      throw new Error(`RELAY_MODELS: der Anbieter ${entry.upstream} hinter ${entry.alias} ist auf diesem Server nicht konfiguriert (verfügbar: ${available})`);
+      throw new Error(`MODEL_ALIASES: der Anbieter ${entry.upstream} hinter ${entry.alias} ist auf diesem Server nicht konfiguriert (verfügbar: ${available})`);
     }
     const model = upstream.models.find((candidate) => candidate.id === entry.model);
-    if (!model) throw new Error(`RELAY_MODELS: das Modell ${entry.model} hinter ${entry.alias} fehlt im Katalog von ${entry.upstream}`);
+    if (!model) throw new Error(`MODEL_ALIASES: das Modell ${entry.model} hinter ${entry.alias} fehlt im Katalog von ${entry.upstream}`);
     return { alias: entry.alias, upstream, model };
   });
 

package/plugins/ragents.orchestration/contract.ts

@@ -1,27 +1,26 @@
-import { canvasTileNodeOf } from "./tiled-layout.js";
+import { handleKey } from "@ragents/engine/src/http/contracts";
+import { surfaceTileNodeOf } from "./tiled-layout.js";
 
 export const ORCHESTRATION_PLUGIN_ID = "ragents.orchestration";
 
-export type CanvasEntity =
+export type SurfaceEntity =
   | { kind: "actor"; handle: string }
   | { kind: "app"; id: string };
 
-export type CanvasTileNode =
+export type SurfaceTileNode =
   | { entity: string; chatInput?: boolean }
-  | { direction: "horizontal" | "vertical"; weights: [number, number]; children: [CanvasTileNode, CanvasTileNode] };
+  | { direction: "horizontal" | "vertical"; weights: [number, number]; children: [SurfaceTileNode, SurfaceTileNode] };
 
-export type CanvasLayout = {
-  root: CanvasTileNode | null;
+export type SurfaceLayout = {
+  root: SurfaceTileNode | null;
 };
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
-const normalizedHandle = (value: string) => value.trim().replace(/^@/, "").toLowerCase();
-
-export const canvasEntityOf = (text: string): CanvasEntity => {
+export const surfaceEntityOf = (text: string): SurfaceEntity => {
   const trimmed = text.trim();
   if (trimmed.startsWith("@")) {
-    const handle = normalizedHandle(trimmed);
+    const handle = handleKey(trimmed);
     if (!handle || /\s/.test(handle)) throw new Error(`Entität ${JSON.stringify(text)}: nach dem @ fehlt ein Handle`);
     return { kind: "actor", handle };
   }
@@ -34,19 +33,19 @@ export const canvasEntityOf = (text: string): CanvasEntity => {
   return { kind: "app", id };
 };
 
-export const canvasEntityKey = (entity: CanvasEntity): string =>
+export const surfaceEntityKey = (entity: SurfaceEntity): string =>
   entity.kind === "actor" ? `@${entity.handle}` : `app:${entity.id}`;
 
 const LEGACY_KEYS = ["nodes", "shapes", "lines", "mode"] as const;
 
 /** Parses and validates a tile layout; throws a German error naming the first violation. */
-export const canvasLayoutOf = (value: unknown): CanvasLayout => {
+export const surfaceLayoutOf = (value: unknown): SurfaceLayout => {
   if (!isRecord(value)) throw new Error("Die Anordnung muss ein Objekt mit root sein");
   const legacy = LEGACY_KEYS.filter((key) => key in value);
   if (legacy.length > 0) {
-    throw new Error(`Die Programmanordnung stammt aus dem entfernten freien Canvas (${legacy.join(", ")}); `
+    throw new Error(`Die Programmanordnung stammt aus der entfernten freien Fläche (${legacy.join(", ")}); `
       + "canvas_layout_replace mit root setzt sie als Kachelaufteilung neu");
   }
   if (!("root" in value)) throw new Error("root fehlt; erwartet wird eine Kachel, eine Teilung oder null");
-  return { root: value.root === null ? null : canvasTileNodeOf(value.root) };
+  return { root: value.root === null ? null : surfaceTileNodeOf(value.root) };
 };

package/plugins/ragents.orchestration/orchestration.hbs

@@ -18,8 +18,8 @@ A snippet can inspect data, call extension functions, create participants and ar
 It needs no actor package, persistent setup actor or invented tests. Local variables end with
 that execution. Use an actor program when later messages, events, persistent state or a view
 are needed. Snippets and actor programs use the same registered functions and contracts.
-Use the registered file functions for editing sources; Bash uses `$RAGENTS_ACTORS_DIR` instead
-of copied physical paths.
+Use the registered file functions for editing sources, with a root alias such as `@actors/`
+instead of copied physical paths; `bash` takes such an alias path as `cwd`.
 
 A snippet acts as its caller. A TypeScript actor's `onInput` acts as that actor. An actor
 function owns its actor's state but invokes run functions as its caller: calling another
@@ -62,7 +62,8 @@ Agents inherit the engine capabilities you may pass on. Use `withoutCapabilities
 an ability must deliberately be absent from a whole subtree.
 
 `agent_spawn` creates an idle actor. Its prompt describes the lasting role and output rules;
-its concrete assignment is an `actor_input`. Prepare participants, required programs, views
+its concrete assignment is an `actor_input`. Give it a `description` of a few words, such as
+"checks the comment rule"; people pick addressees by it in a tree of who created whom. Prepare participants, required programs, views
 and subscriptions before sending the first assignments. Subscribe to a needed reply before
 requesting it. Never assume a failed creation produced an actor.
 

package/plugins/ragents.orchestration/ragents-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "ragents.orchestration",
+  "exports": {
+    "web": ["web/surface-entities", "web/program-slot", "web/tile-docking"]
+  }
+}

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

@@ -2,28 +2,25 @@ import {
   actorInputSchema,
   agentTools,
   enqueueActorInput,
-  eventResultSchema,
+  eventResultSchemaOf,
   ScriptDriver,
   type ActorInputRequest,
   type RAgentsPlugin,
-} from "@aicontainer/ragents";
-import { runtimeProviderToken } from "@aicontainer/server/ragents/host-services.js";
-import { pluginAssetPath } from "@aicontainer/server/plugin-support/asset-path.js";
-import type { PluginModule } from "@aicontainer/server/plugin-support/plugin-module.js";
-import { boundToTools, handlebarsPrompt } from "@aicontainer/server/plugin-support/prompt.js";
-import { createCanvasToolContributor } from "./canvas-tool.js";
+} from "@ragents/engine";
+import { runtimeProviderToken } from "@ragents/host/ragents/host-services.js";
+import { pluginAsset } from "@ragents/host/plugin-support/plugin-folder.js";
+import type { PluginModule } from "@ragents/host/plugin-support/plugin-module.js";
+import { boundToTools, handlebarsPrompt } from "@ragents/host/plugin-support/prompt.js";
+import { createSurfaceToolContributor } from "./surface-tool.js";
 import { createRunStopContributor } from "./run-stop-tool.js";
-import { sessionManagementToken } from "@aicontainer/server/ragents/global-chat.js";
-
-const orchestrationPromptFile = pluginAssetPath(import.meta.url, "../orchestration.hbs");
-const canvasPromptFile = pluginAssetPath(import.meta.url, "../canvas.hbs");
+import { runManagementToken } from "@ragents/host/ragents/global-chat.js";
 
 const orchestrationPlugin: RAgentsPlugin = {
   manifest: { id: "ragents.orchestration" },
   register: (host) => {
-    host.functions(createCanvasToolContributor());
+    host.functions(createSurfaceToolContributor());
     host.functions(createRunStopContributor(
-      (runId) => host.service(sessionManagementToken)().stop(runId),
+      (runId) => host.service(runManagementToken)().stop(runId),
       (error) => console.error("Run-Stopp durch den Koordinator fehlgeschlagen", error),
     ));
     host.operations({
@@ -32,7 +29,7 @@ const orchestrationPlugin: RAgentsPlugin = {
       description: "Reiht für einen Actor einen normalen Texteingang unter der gebundenen Identität ein - "
         + "als Agent oder, aus einer App-Aktion, als Besitzer des Runs. Bestätigt nur das Einreihen. TypeScript-Actors verstehen ausschließlich ihr programmiertes Eingabeprotokoll, keine freien Aufträge.",
       schema: actorInputSchema,
-      resultSchema: eventResultSchema,
+      resultSchema: eventResultSchemaOf("actor.input.enqueued"),
       operator: "direct",
       execute: (context, input) =>
         enqueueActorInput(host.service(runtimeProviderToken)(), {
@@ -52,9 +49,9 @@ const orchestrationPlugin: RAgentsPlugin = {
       }),
     });
     host.prompts(
-      handlebarsPrompt("ragents.orchestration.prompt", 600, orchestrationPromptFile),
+      handlebarsPrompt("ragents.orchestration.prompt", 600, pluginAsset("ragents.orchestration", "orchestration.hbs")),
       boundToTools(
-        handlebarsPrompt("ragents.orchestration.canvas", 650, canvasPromptFile),
+        handlebarsPrompt("ragents.orchestration.surface", 650, pluginAsset("ragents.orchestration", "surface.hbs")),
         "canvas_layout_replace",
       ),
     );

package/plugins/ragents.orchestration/server/run-stop-tool.ts

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
-import { defineRunFunction, defineToolAvailability, holdsUsable, type ToolContributor } from "@aicontainer/ragents";
-import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
+import { defineRunFunction, defineToolAvailability, holdsUsable, type ToolContributor } from "@ragents/engine";
+import { toolDescriptorFrom } from "@ragents/host/plugin-support/agent-tool.js";
 
 const available = defineToolAvailability({
   availability: "conditional",
@@ -11,8 +11,8 @@ const available = defineToolAvailability({
 export const createRunStopContributor = (stop: (runId: string) => Promise<void>, onError: (error: unknown) => void): ToolContributor => {
   const definition = defineRunFunction({
     name: "run_stop",
-    label: "Lauf stoppen",
-    description: "Leitet den vollständigen Stopp des eigenen Runs ein: laufende Turns, Werkzeuge, Unteragenten und Plugin-Dienste. Unterhaltung und Dateien bleiben erhalten. Bricht auch den eigenen Turn ab; die Annahme ist keine Bestätigung abgeschlossener Bereinigung. Bei Benutzerwunsch nach vollständigem Abbruch sofort verwenden, keine Abbruchnachricht an beschäftigte Agenten senden.",
+    label: "Run stoppen",
+    description: "Leitet den vollständigen Stopp des eigenen Runs ein: laufende Turns, Werkzeuge, Unteragenten und Plugin-Dienste. Gespräch und Dateien bleiben erhalten. Bricht auch den eigenen Turn ab; die Annahme ist keine Bestätigung abgeschlossener Bereinigung. Bei Benutzerwunsch nach vollständigem Abbruch sofort verwenden, keine Abbruchnachricht an beschäftigte Agenten senden.",
     schema: Type.Object({}, { additionalProperties: false }),
     resultSchema: Type.Object({ requested: Type.Literal(true) }, { additionalProperties: false }),
     available,

package/plugins/ragents.orchestration/server/{canvas-tool.ts → surface-tool.ts}

@@ -1,27 +1,27 @@
 import { Type } from "typebox";
 import {
   DomainError,
+  actorByHandle,
   defineRunFunction,
   defineToolAvailability,
-  eventResultSchema,
   holdsUsable,
   type RunFunction,
   type RunView,
   type ToolContributor,
-} from "@aicontainer/ragents";
-import { toolDescriptorFrom } from "@aicontainer/server/plugin-support/agent-tool.js";
-import { ACTOR_PROGRAMS_STATE_ID, resolveActorView, type ActorProgramState } from "@aicontainer/plugins/ragents.actor-programs/contract.js";
+} from "@ragents/engine";
+import { toolDescriptorFrom } from "@ragents/host/plugin-support/agent-tool.js";
+import { ACTOR_PROGRAMS_STATE_ID, resolveActorView, type ActorProgramState } from "@ragents/host/plugin-support/actor-programs/contract.js";
 import {
   ORCHESTRATION_PLUGIN_ID,
-  canvasEntityOf,
-  canvasLayoutOf,
-  type CanvasLayout,
+  surfaceEntityOf,
+  surfaceLayoutOf,
+  type SurfaceLayout,
 } from "../contract.js";
-import { canvasTileEntities, mapCanvasTileEntities } from "../tiled-layout.js";
+import { surfaceTileEntities, mapSurfaceTileEntities } from "../tiled-layout.js";
 
-export const canvasToolMetadata = {
+export const surfaceToolMetadata = {
   name: "canvas_layout_replace",
-  label: "Replace Canvas Layout",
+  label: "Replace Surface Layout",
   description: "Arrange actors and mini-apps as tiles on the viewport-filling work surface, using a binary tree of weighted splits.",
   longDescription: "root is the whole arrangement and replaces the stored one. A tile is {entity:'@helper'} or "
     + "{entity:'app:@workspace/main'}; a split is {direction:'horizontal',weights:[1,1],children:[tile,tile]}. "
@@ -34,14 +34,14 @@ export const canvasToolMetadata = {
     + "Participants you do not place stay reachable through the run header.",
 } as const;
 
-export const canDesignCanvas = defineToolAvailability({
+export const canDesignSurface = defineToolAvailability({
   availability: "conditional",
-  availabilityDetail: "Nur für Agenten und Script-Actors mit der Capability plugin.state.write.",
+  availabilityDetail: "Nur für Agenten und TypeScript-Actors mit der Capability plugin.state.write.",
   requiredCapabilities: ["plugin.state.write"],
 }, (actor) => actor.kind !== "human" && holdsUsable(actor, "plugin.state.write"));
 
 const tileSchema = Type.Cyclic({
-  CanvasTile: Type.Union([
+  SurfaceTile: Type.Union([
     Type.Object({
       entity: Type.String({ minLength: 1, description: "Actor @handle or activated mini-app app:@handle/view-key or app:program-name/view-key; the server resolves the view ID" }),
       chatInput: Type.Optional(Type.Boolean({ description: "Actor tiles only: false hides the chat composer in the tile; default true. Does not change permissions or the inspector" })),
@@ -49,20 +49,20 @@ const tileSchema = Type.Cyclic({
     Type.Object({
       direction: Type.Union([Type.Literal("horizontal"), Type.Literal("vertical")]),
       weights: Type.Tuple([Type.Number({ exclusiveMinimum: 0 }), Type.Number({ exclusiveMinimum: 0 })]),
-      children: Type.Tuple([Type.Ref("CanvasTile"), Type.Ref("CanvasTile")]),
+      children: Type.Tuple([Type.Ref("SurfaceTile"), Type.Ref("SurfaceTile")]),
     }, { additionalProperties: false }),
   ]),
-}, "CanvasTile");
+}, "SurfaceTile");
 
-const canvasLayoutSchema = Type.Object({
+const surfaceLayoutSchema = Type.Object({
   root: Type.Union([tileSchema, Type.Null()], { description: "The whole arrangement: a tile or a binary split. Maximum 64 unique tiles and 16 nested splits. null clears the surface" }),
 });
 
-const invalid = (message: string) => new DomainError("invalid-canvas-layout", message, 400);
+const invalid = (message: string) => new DomainError("invalid-surface-layout", message, 400);
 
-const parsedLayout = (input: unknown): CanvasLayout => {
+const parsedLayout = (input: unknown): SurfaceLayout => {
   try {
-    return canvasLayoutOf(input);
+    return surfaceLayoutOf(input);
   } catch (caught) {
     throw invalid(caught instanceof Error ? caught.message : String(caught));
   }
@@ -70,15 +70,14 @@ const parsedLayout = (input: unknown): CanvasLayout => {
 
 const isStopped = (actor: RunView["actors"][number]) => actor.kind !== "human" && actor.lifecycle.kind === "stopped";
 
-const actorByHandle = (view: RunView, reference: string, where: string) => {
-  const entity = canvasEntityOf(reference);
+const surfaceActorOf = (view: RunView, reference: string, where: string) => {
+  const entity = surfaceEntityOf(reference);
   if (entity.kind !== "actor") throw invalid(`${where}: ${reference} ist kein Actor`);
   const handle = entity.handle;
-  const sharing = view.actors.filter((actor) => actor.handle === handle);
-  const found = sharing.find((actor) => actor.kind === "human" || !isStopped(actor)) ?? sharing.at(-1);
+  const found = actorByHandle(view.actors, handle);
   if (!found) {
     const known = view.actors.filter((actor) => actor.kind !== "human").map((actor) => `@${actor.handle}`);
-    throw invalid(`${where}: @${handle} ist kein Actor dieses Laufs. Vorhanden: ${known.join(", ") || "keine"}`);
+    throw invalid(`${where}: @${handle} ist kein Actor dieses Runs. Vorhanden: ${known.join(", ") || "keine"}`);
   }
   if (found.kind === "human") {
     throw invalid(`${where}: @${handle} ist der Mensch im Chat; der Chat liegt fest links neben der Fläche`);
@@ -86,9 +85,9 @@ const actorByHandle = (view: RunView, reference: string, where: string) => {
   return found;
 };
 
-const isActorReference = (reference: string) => canvasEntityOf(reference).kind === "actor";
+const isActorReference = (reference: string) => surfaceEntityOf(reference).kind === "actor";
 
-const resolveAppReferences = (view: RunView, layout: CanvasLayout): CanvasLayout => {
+const resolveAppReferences = (view: RunView, layout: SurfaceLayout): SurfaceLayout => {
   const programs = view.pluginStates.flatMap((entry) => {
     if (entry.pluginId !== ACTOR_PROGRAMS_STATE_ID || entry.scope.kind !== "actor") return [];
     const actorId = entry.scope.actorId;
@@ -98,33 +97,33 @@ const resolveAppReferences = (view: RunView, layout: CanvasLayout): CanvasLayout
     return program ? [program] : [];
   });
   const resolve = (reference: string, where: string): string => {
-    const entity = canvasEntityOf(reference);
+    const entity = surfaceEntityOf(reference);
     if (entity.kind !== "app") return reference;
     try {
       return `app:${resolveActorView(programs, entity.id).view.id}`;
     } catch (error) {
-      throw invalid(`${where}: ${reference}: ${error instanceof Error ? error.message : String(error)} Canvas-Entitäten erhalten das Präfix app:.`);
+      throw invalid(`${where}: ${reference}: ${error instanceof Error ? error.message : String(error)} Flächenentitäten erhalten das Präfix app:.`);
     }
   };
-  return parsedLayout({ root: layout.root ? mapCanvasTileEntities(layout.root, (entity) => resolve(entity, "root")) : null });
+  return parsedLayout({ root: layout.root ? mapSurfaceTileEntities(layout.root, (entity) => resolve(entity, "root")) : null });
 };
 
 /** Resolve app names and validate the placed actors before any layout is stored. */
-export const checkLayoutAgainstRun = (view: RunView, input: CanvasLayout): CanvasLayout => {
+export const checkLayoutAgainstRun = (view: RunView, input: SurfaceLayout): SurfaceLayout => {
   const layout = resolveAppReferences(view, input);
-  for (const reference of canvasTileEntities(layout.root)) {
-    if (isActorReference(reference)) actorByHandle(view, reference, "root");
+  for (const reference of surfaceTileEntities(layout.root)) {
+    if (isActorReference(reference)) surfaceActorOf(view, reference, "root");
   }
   return layout;
 };
 
-export const createCanvasTool = (): RunFunction =>
+export const createSurfaceTool = (): RunFunction =>
   defineRunFunction({
-    ...canvasToolMetadata,
-    schema: canvasLayoutSchema,
-    resultSchema: eventResultSchema,
-    available: canDesignCanvas,
-    run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
+    ...surfaceToolMetadata,
+    schema: surfaceLayoutSchema,
+    resultSchema: Type.Null(),
+    available: canDesignSurface,
+    run: ({ runtime, caller, context }, toolCallId, input) => {
       const view = runtime.view(caller.runId);
       const layout = checkLayoutAgainstRun(view, parsedLayout(input));
       runtime.replacePluginState(context(toolCallId), caller.runId, {
@@ -132,12 +131,12 @@ export const createCanvasTool = (): RunFunction =>
         scope: { kind: "run" },
         state: layout,
       });
-      return eventsFor(toolCallId);
+      return null;
     },
   });
 
-export const createCanvasToolContributor = (): ToolContributor => ({
-  name: "ragents.orchestration.canvas",
-  descriptors: [toolDescriptorFrom(canvasToolMetadata, canDesignCanvas)],
-  tools: () => [createCanvasTool()],
+export const createSurfaceToolContributor = (): ToolContributor => ({
+  name: "ragents.orchestration.surface",
+  descriptors: [toolDescriptorFrom(surfaceToolMetadata, canDesignSurface)],
+  tools: () => [createSurfaceTool()],
 });