@schlenkr/ragents 0.1.5 → 0.1.7

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()],
 });

package/plugins/ragents.orchestration/surface.hbs

@@ -0,0 +1,34 @@
+## Arranging the tiled work surface
+
+The work surface of a run is a grid of tiles that fills the viewport. Each tile shows one actor or
+one activated mini-app. There is no other arrangement and no pan, zoom or free placement. Use
+`context.functions.canvas_layout_replace` from TypeScript to set the arrangement, and read its exact
+input type with `typescript_api` before the first call.
+
+`root` is the whole arrangement and replaces the stored one; it is the only parameter. A tile is
+{entity:"@helper"} or {entity:"app:@workspace/main"}. A split is {direction, weights, children} with
+direction "horizontal" (left/right) or "vertical" (top/bottom), two positive weights and exactly two
+children, each of which may be a split again. `root:null` clears the surface.
+
+App left, chat right at 50:50:
+{root:{direction:"horizontal",weights:[1,1],children:[
+  {entity:"app:@workspace/main"},{entity:"@helper"}
+]}}. One tile above two tiles at 2:1:
+{root:{direction:"vertical",weights:[2,1],children:[{entity:"@lead"},
+  {direction:"horizontal",weights:[1,1],children:[{entity:"@first"},{entity:"@second"}]}
+]}}. Resolve the actual actor and app names before calling; the example names are not existing
+participants.
+
+An actor tile carries {entity:"@helper",chatInput:false} when its chat composer should stay hidden.
+That changes neither permissions nor the inspector. Mini-app tiles have no chatInput.
+
+Activate actor programs before placing their views. Reference a view as `app:@handle/view-key` or
+`app:program-name/view-key`, using the handle, program name and view key you chose. The server
+resolves the actual view ID and rejects unknown views before storing the layout. Do not invent or
+copy generated view IDs. `actor_view_set_visibility` uses the same names without the `app:` prefix.
+
+Place what the user needs to see side by side and update the arrangement when the work changes.
+Participants you do not place stay reachable through the run header and can be dragged onto a tile
+there. Users can move, resize and remove tiles themselves; their personal arrangement takes
+precedence until they reset it, so do not resend a layout to fight it. The user takes part through
+the chat and needs no tile of their own.

package/plugins/ragents.orchestration/tiled-layout.ts

@@ -1,27 +1,27 @@
-import { canvasEntityKey, canvasEntityOf, type CanvasTileNode } from "./contract.js";
+import { surfaceEntityKey, surfaceEntityOf, type SurfaceTileNode } from "./contract.js";
 
-export type { CanvasTileNode } from "./contract.js";
+export type { SurfaceTileNode } from "./contract.js";
 
-export const MAX_CANVAS_TILE_DEPTH = 16;
-export const MAX_CANVAS_TILES = 64;
+export const MAX_SURFACE_TILE_DEPTH = 16;
+export const MAX_SURFACE_TILES = 64;
 
-export const canvasTileNodeOf = (input: unknown): CanvasTileNode => {
+export const surfaceTileNodeOf = (input: unknown): SurfaceTileNode => {
   const entities = new Set<string>();
-  const parse = (value: unknown, where: string, depth: number): CanvasTileNode => {
-    if (depth > MAX_CANVAS_TILE_DEPTH) throw new Error(`${where}: höchstens ${MAX_CANVAS_TILE_DEPTH} verschachtelte Teilungen sind erlaubt`);
+  const parse = (value: unknown, where: string, depth: number): SurfaceTileNode => {
+    if (depth > MAX_SURFACE_TILE_DEPTH) throw new Error(`${where}: höchstens ${MAX_SURFACE_TILE_DEPTH} verschachtelte Teilungen sind erlaubt`);
     if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${where} muss eine Kachel oder Teilung sein`);
     const node = value as Record<string, unknown>;
     if (Object.hasOwn(node, "entity")) {
       if (Object.keys(node).some((key) => key !== "entity" && key !== "chatInput")) throw new Error(`${where}: eine Kachel trägt nur entity und chatInput; eine Teilung direction, weights und children`);
       if (typeof node.entity !== "string") throw new Error(`${where}.entity muss @handle oder app:<name>/<view> sein`);
-      const entity = canvasEntityOf(node.entity);
-      const key = canvasEntityKey(entity);
+      const entity = surfaceEntityOf(node.entity);
+      const key = surfaceEntityKey(entity);
       if (node.chatInput !== undefined && (entity.kind !== "actor" || typeof node.chatInput !== "boolean")) {
         throw new Error(`${where}.chatInput ist nur für Actors als Wahrheitswert erlaubt`);
       }
       if (entities.has(key)) throw new Error(`${where}: ${key} ist mehr als einmal als Kachel platziert`);
       entities.add(key);
-      if (entities.size > MAX_CANVAS_TILES) throw new Error(`Höchstens ${MAX_CANVAS_TILES} Kacheln sind erlaubt`);
+      if (entities.size > MAX_SURFACE_TILES) throw new Error(`Höchstens ${MAX_SURFACE_TILES} Kacheln sind erlaubt`);
       return node.chatInput === undefined ? { entity: key } : { entity: key, chatInput: node.chatInput as boolean };
     }
     if (Object.keys(node).some((key) => !["direction", "weights", "children"].includes(key))) throw new Error(`${where}: eine Teilung trägt nur direction, weights und children`);
@@ -40,16 +40,16 @@ export const canvasTileNodeOf = (input: unknown): CanvasTileNode => {
 };
 
 /** A tile hides the chat composer of its actor only when its leaf says chatInput: false. */
-export const canvasTileChatInput = (root: CanvasTileNode | null | undefined, entity: string): boolean =>
+export const surfaceTileChatInput = (root: SurfaceTileNode | null | undefined, entity: string): boolean =>
   !root ? true : "entity" in root
     ? root.entity !== entity || root.chatInput !== false
-    : canvasTileChatInput(root.children[0], entity) && canvasTileChatInput(root.children[1], entity);
+    : surfaceTileChatInput(root.children[0], entity) && surfaceTileChatInput(root.children[1], entity);
 
-export const canvasTileEntities = (root: CanvasTileNode | null | undefined): string[] =>
-  !root ? [] : "entity" in root ? [root.entity] : root.children.flatMap(canvasTileEntities);
+export const surfaceTileEntities = (root: SurfaceTileNode | null | undefined): string[] =>
+  !root ? [] : "entity" in root ? [root.entity] : root.children.flatMap(surfaceTileEntities);
 
-export const mapCanvasTileEntities = (root: CanvasTileNode, resolve: (entity: string) => string): CanvasTileNode =>
+export const mapSurfaceTileEntities = (root: SurfaceTileNode, resolve: (entity: string) => string): SurfaceTileNode =>
   "entity" in root ? { ...root, entity: resolve(root.entity) } : {
     ...root,
-    children: [mapCanvasTileEntities(root.children[0], resolve), mapCanvasTileEntities(root.children[1], resolve)],
+    children: [mapSurfaceTileEntities(root.children[0], resolve), mapSurfaceTileEntities(root.children[1], resolve)],
   };