@schlenkr/ragents 0.1.0

package/plugins/ragents.orchestration/contract.ts

@@ -0,0 +1,322 @@
+import { canvasTileNodeOf } from "./tiled-layout.js";
+
+export const ORCHESTRATION_PLUGIN_ID = "ragents.orchestration";
+
+export const CANVAS_GROUP_KINDS = ["h", "v", "wrap-h", "wrap-v", "grid", "circle", "tree"] as const;
+export type CanvasGroupKind = typeof CANVAS_GROUP_KINDS[number];
+
+export const CANVAS_TREE_DIRECTIONS = ["right", "down"] as const;
+export type CanvasTreeDirection = typeof CANVAS_TREE_DIRECTIONS[number];
+
+export const CANVAS_SHAPE_KINDS = ["circle", "diamond"] as const;
+export type CanvasShapeKind = typeof CANVAS_SHAPE_KINDS[number];
+
+export const CANVAS_ARROWS = ["none", "end", "both"] as const;
+export type CanvasArrow = typeof CANVAS_ARROWS[number];
+
+export const CANVAS_LINE_STYLES = ["solid", "dashed"] as const;
+export type CanvasLineStyle = typeof CANVAS_LINE_STYLES[number];
+
+/** Default sizes of the shapes in px; a circle is measured by its diameter, a diamond by its width. */
+export const CANVAS_SHAPE_DEFAULT_SIZE: Record<CanvasShapeKind, number> = { circle: 120, diamond: 150 };
+const DIAMOND_ASPECT = 0.62;
+
+export type CanvasEntity =
+  | { kind: "actor"; handle: string }
+  | { kind: "shape"; id: string }
+  | { kind: "app"; id: string };
+
+type CanvasGroupBase = {
+  id: string;
+  parent?: string;
+  label?: string;
+  gap?: number;
+  frame: boolean;
+};
+
+/** The model sends one flat object per node; internally each group kind carries exactly its own parameters. */
+export type CanvasGroupNode =
+  | (CanvasGroupBase & { group: "h" | "v" | "circle" })
+  | (CanvasGroupBase & { group: "wrap-h"; width: number })
+  | (CanvasGroupBase & { group: "wrap-v"; height: number })
+  | (CanvasGroupBase & { group: "grid"; columns: number })
+  | (CanvasGroupBase & { group: "tree"; root: string; direction: CanvasTreeDirection });
+
+export type CanvasItemNode = {
+  entity: string;
+  parent?: string;
+  chatInput?: boolean;
+};
+
+export type CanvasLayoutNode = CanvasGroupNode | CanvasItemNode;
+
+export type CanvasShape = {
+  id: string;
+  kind: CanvasShapeKind;
+  text: string;
+  size: number;
+};
+
+export type CanvasLine = {
+  from: string;
+  to: string;
+  label?: string;
+  arrow: CanvasArrow;
+  style: CanvasLineStyle;
+};
+
+export type CanvasTileNode =
+  | { entity: string }
+  | { direction: "horizontal" | "vertical"; weights: [number, number]; children: [CanvasTileNode, CanvasTileNode] };
+
+export type CanvasLayout = {
+  mode?: "free" | "tiled";
+  root?: CanvasTileNode | null;
+  nodes: CanvasLayoutNode[];
+  shapes: CanvasShape[];
+  lines: CanvasLine[];
+};
+
+export const isCanvasGroupNode = (node: CanvasLayoutNode): node is CanvasGroupNode => "group" in node;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isAbsent = (value: unknown) => value === undefined || value === null;
+
+const normalizedHandle = (value: string) => value.trim().replace(/^@/, "").toLowerCase();
+
+export const canvasEntityOf = (text: string): CanvasEntity => {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("@")) {
+    const handle = normalizedHandle(trimmed);
+    if (!handle || /\s/.test(handle)) throw new Error(`Entität ${JSON.stringify(text)}: nach dem @ fehlt ein Handle`);
+    return { kind: "actor", handle };
+  }
+  const match = /^(shape|app):(.+)$/s.exec(trimmed);
+  if (!match) {
+    throw new Error(`Entität ${JSON.stringify(text)}: erwartet @handle, shape:<id> oder app:<id>`);
+  }
+  const id = match[2].trim();
+  if (!id) throw new Error(`Entität ${JSON.stringify(text)}: die ID nach dem Doppelpunkt ist leer`);
+  return match[1] === "shape" ? { kind: "shape", id } : { kind: "app", id };
+};
+
+export const canvasEntityKey = (entity: CanvasEntity): string =>
+  entity.kind === "actor" ? `@${entity.handle}` : `${entity.kind}:${entity.id}`;
+
+export const canvasShapeSize = (shape: CanvasShape): { width: number; height: number } =>
+  shape.kind === "circle"
+    ? { width: shape.size, height: shape.size }
+    : { width: shape.size, height: Math.round(shape.size * DIAMOND_ASPECT) };
+
+const oneOf = <T extends string>(allowed: readonly T[], value: unknown, where: string): T => {
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    throw new Error(`${where}: ${JSON.stringify(value)} ist unbekannt, erlaubt sind ${allowed.join(", ")}`);
+  }
+  return value as T;
+};
+
+const optionalText = (value: unknown, where: string): string | undefined => {
+  if (isAbsent(value)) return undefined;
+  if (typeof value !== "string") throw new Error(`${where} muss ein Text sein`);
+  return value.trim() || undefined;
+};
+
+const requiredText = (value: unknown, where: string): string => {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${where} fehlt oder ist leer`);
+  return value.trim();
+};
+
+const positiveNumber = (value: unknown, where: string): number => {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) throw new Error(`${where} muss eine positive Zahl sein`);
+  return value;
+};
+
+const optionalGap = (value: unknown, where: string): number | undefined => {
+  if (isAbsent(value)) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${where} darf nicht negativ sein`);
+  return value;
+};
+
+const withoutUndefined = <T extends object>(value: T): T =>
+  Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+
+const GROUP_PARAMETERS: Record<CanvasGroupKind, readonly string[]> = {
+  "h": [],
+  "v": [],
+  "circle": [],
+  "wrap-h": ["width"],
+  "wrap-v": ["height"],
+  "grid": ["columns"],
+  "tree": ["direction", "root"],
+};
+
+const groupNodeOf = (value: Record<string, unknown>, index: number): CanvasGroupNode => {
+  const where = `nodes[${index}]`;
+  const group = oneOf(CANVAS_GROUP_KINDS, value.group, `${where}.group`);
+  const id = requiredText(value.id, `${where}.id (jede Gruppe braucht eine ID)`);
+  if (!isAbsent(value.entity)) {
+    throw new Error(`${where}: Gruppe ${id} darf kein entity tragen; Elemente sind eigene Knoten mit parent ${JSON.stringify(id)}`);
+  }
+  for (const parameter of ["width", "height", "columns", "direction", "root"]) {
+    if (!isAbsent(value[parameter]) && !GROUP_PARAMETERS[group].includes(parameter)) {
+      throw new Error(`${where}: Gruppe ${id} (${group}) kennt keinen Parameter ${parameter}`
+        + (parameter === "width" ? "; für Umbruch wrap-h nehmen" : parameter === "height" ? "; für Umbruch wrap-v nehmen" : ""));
+    }
+  }
+  if (!isAbsent(value.frame) && typeof value.frame !== "boolean") throw new Error(`${where}.frame muss true oder false sein`);
+  const base: CanvasGroupBase = withoutUndefined({
+    id,
+    parent: optionalText(value.parent, `${where}.parent`),
+    label: optionalText(value.label, `${where}.label`),
+    gap: optionalGap(value.gap, `${where}.gap`),
+    frame: value.frame === true,
+  });
+  switch (group) {
+    case "h":
+    case "v":
+    case "circle":
+      return { ...base, group };
+    case "wrap-h":
+      return { ...base, group, width: positiveNumber(value.width, `${where}.width (wrap-h braucht die Zeilenbreite)`) };
+    case "wrap-v":
+      return { ...base, group, height: positiveNumber(value.height, `${where}.height (wrap-v braucht die Spaltenhöhe)`) };
+    case "grid": {
+      const columns = value.columns;
+      if (typeof columns !== "number" || !Number.isInteger(columns) || columns < 1) {
+        throw new Error(`${where}.columns (grid braucht eine ganze Spaltenzahl ab 1)`);
+      }
+      return { ...base, group, columns };
+    }
+    case "tree": {
+      const entity = canvasEntityOf(requiredText(value.root, `${where}.root (tree braucht den @handle des Wurzel-Actors)`));
+      if (entity.kind !== "actor") throw new Error(`${where}.root: die Wurzel eines Baums ist ein Actor (@handle)`);
+      return {
+        ...base,
+        group,
+        root: canvasEntityKey(entity),
+        direction: isAbsent(value.direction) ? "right" : oneOf(CANVAS_TREE_DIRECTIONS, value.direction, `${where}.direction`),
+      };
+    }
+  }
+};
+
+const itemNodeOf = (value: Record<string, unknown>, index: number): CanvasItemNode => {
+  const where = `nodes[${index}]`;
+  if (typeof value.entity !== "string") {
+    throw new Error(`${where}: ein Knoten ist entweder eine Gruppe (group + id) oder ein Element (entity)`);
+  }
+  const entity = canvasEntityOf(value.entity);
+  if (value.chatInput !== undefined && (entity.kind !== "actor" || typeof value.chatInput !== "boolean")) {
+    throw new Error(`${where}.chatInput ist nur für Actors als Wahrheitswert erlaubt`);
+  }
+  return withoutUndefined({
+    entity: canvasEntityKey(entity),
+    parent: optionalText(value.parent, `${where}.parent`),
+    chatInput: value.chatInput as boolean | undefined,
+  });
+};
+
+const shapeOf = (value: unknown, index: number): CanvasShape => {
+  const where = `shapes[${index}]`;
+  if (!isRecord(value)) throw new Error(`${where} muss ein Objekt sein`);
+  const kind = oneOf(CANVAS_SHAPE_KINDS, value.kind, `${where}.kind`);
+  return {
+    id: requiredText(value.id, `${where}.id`),
+    kind,
+    text: requiredText(value.text, `${where}.text (jede Form trägt einen Text)`),
+    size: isAbsent(value.size) ? CANVAS_SHAPE_DEFAULT_SIZE[kind] : positiveNumber(value.size, `${where}.size`),
+  };
+};
+
+const lineOf = (value: unknown, index: number): CanvasLine => {
+  const where = `lines[${index}]`;
+  if (!isRecord(value)) throw new Error(`${where} muss ein Objekt sein`);
+  const from = canvasEntityKey(canvasEntityOf(requiredText(value.from, `${where}.from`)));
+  const to = canvasEntityKey(canvasEntityOf(requiredText(value.to, `${where}.to`)));
+  if (from === to) throw new Error(`${where}: eine Linie führt von einer Entität zu einer ANDEREN, nicht von ${from} zu sich selbst`);
+  return withoutUndefined({
+    from,
+    to,
+    label: optionalText(value.label, `${where}.label`),
+    arrow: isAbsent(value.arrow) ? "none" : oneOf(CANVAS_ARROWS, value.arrow, `${where}.arrow`),
+    style: isAbsent(value.style) ? "solid" : oneOf(CANVAS_LINE_STYLES, value.style, `${where}.style`),
+  });
+};
+
+const assertNoCycle = (groups: Map<string, CanvasGroupNode>) => {
+  for (const start of groups.values()) {
+    const seen = new Set<string>([start.id]);
+    let current = start;
+    while (current.parent) {
+      const next = groups.get(current.parent);
+      if (!next) throw new Error(`Gruppe ${current.id}: parent ${JSON.stringify(current.parent)} ist keine bekannte Gruppe`);
+      if (seen.has(next.id)) throw new Error(`Gruppe ${start.id} liegt über parent in sich selbst`);
+      seen.add(next.id);
+      current = next;
+    }
+  }
+};
+
+/** Parses and validates a canvas layout; throws a German error naming the first violation. */
+export const canvasLayoutOf = (value: unknown): CanvasLayout => {
+  if (!isRecord(value)) throw new Error("Das Layout muss ein Objekt mit nodes, shapes und lines sein");
+  if (!Array.isArray(value.nodes)) throw new Error("nodes fehlt oder ist keine Liste");
+  const rawShapes = value.shapes ?? [];
+  const rawLines = value.lines ?? [];
+  if (!Array.isArray(rawShapes)) throw new Error("shapes muss eine Liste sein");
+  if (!Array.isArray(rawLines)) throw new Error("lines muss eine Liste sein");
+
+  const nodes = value.nodes.map((entry, index): CanvasLayoutNode => {
+    if (!isRecord(entry)) throw new Error(`nodes[${index}] muss ein Objekt sein`);
+    if (!isAbsent(entry.group) && entry.chatInput !== undefined) throw new Error(`nodes[${index}].chatInput ist nur für Actors erlaubt`);
+    return isAbsent(entry.group) ? itemNodeOf(entry, index) : groupNodeOf(entry, index);
+  });
+  const shapes = rawShapes.map(shapeOf);
+  const lines = rawLines.map(lineOf);
+
+  const groups = new Map<string, CanvasGroupNode>();
+  for (const node of nodes.filter(isCanvasGroupNode)) {
+    if (groups.has(node.id)) throw new Error(`Gruppen-ID ${JSON.stringify(node.id)} kommt mehrfach vor`);
+    groups.set(node.id, node);
+  }
+  assertNoCycle(groups);
+  for (const node of nodes) {
+    if (!node.parent) continue;
+    const parent = groups.get(node.parent);
+    if (!parent) throw new Error(`parent ${JSON.stringify(node.parent)} ist keine bekannte Gruppe`);
+    if (parent.group === "tree") {
+      throw new Error(`Gruppe ${parent.id} ist ein Baum und füllt sich aus der Abstammung von ${parent.root}; sie nimmt keine eigenen Kinder auf`);
+    }
+  }
+
+  const shapeIds = new Set<string>();
+  for (const shape of shapes) {
+    if (shapeIds.has(shape.id)) throw new Error(`Form-ID ${JSON.stringify(shape.id)} kommt mehrfach vor`);
+    shapeIds.add(shape.id);
+  }
+  const placed = new Set<string>();
+  for (const node of nodes) {
+    if (isCanvasGroupNode(node)) continue;
+    if (placed.has(node.entity)) throw new Error(`${node.entity} ist mehr als einmal platziert`);
+    placed.add(node.entity);
+  }
+  const assertKnownShape = (reference: string, where: string) => {
+    const entity = canvasEntityOf(reference);
+    if (entity.kind === "shape" && !shapeIds.has(entity.id)) {
+      throw new Error(`${where}: Form ${JSON.stringify(entity.id)} ist nicht in shapes definiert`);
+    }
+  };
+  for (const reference of placed) assertKnownShape(reference, "nodes");
+  for (const shape of shapes) {
+    if (!placed.has(`shape:${shape.id}`)) throw new Error(`Form ${JSON.stringify(shape.id)} ist nirgends platziert; jede Form braucht einen Knoten mit entity shape:${shape.id}`);
+  }
+  lines.forEach((line, index) => {
+    assertKnownShape(line.from, `lines[${index}].from`);
+    assertKnownShape(line.to, `lines[${index}].to`);
+  });
+
+  const mode = value.mode === undefined ? undefined : oneOf(["free", "tiled"] as const, value.mode, "mode");
+  const root = value.root === undefined ? undefined : value.root === null ? null : canvasTileNodeOf(value.root);
+  return withoutUndefined({ nodes, shapes, lines, mode, root });
+};

package/plugins/ragents.orchestration/orchestration.hbs

@@ -0,0 +1,105 @@
+# Orchestration through TypeScript
+
+You coordinate this conversation and carry out the user's requested work. The user describes
+an outcome; discover the available functions and choose the implementation yourself. A task
+or skill start prompt need not prescribe actors, subscriptions, packages or a technical workflow.
+
+## The shared API
+
+Use `typescript_api` to discover the available functions and obtain their exact input and
+result types. Use `typescript_eval` to run a small TypeScript snippet: `code` is the body of an
+async function with `context` and an optional `return`; `path` executes an existing source file
+through the same path. Call registered functions as `context.functions.<name>(input)`.
+Keep dependent calls and returned references together in code. Do not retype IDs or infer
+result shapes from event names. Type errors identify a disagreement with the contract; fix
+the assumption instead of hiding it with `any` or a double assertion.
+
+A snippet can inspect data, call extension functions, create participants and arrange a run.
+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.
+
+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
+actor's function does not become that actor. In particular, `event_subscribe` subscribes the
+acting caller. To let a persistent actor receive later events, arrange its subscription in
+its own `onInput`; send it an ordinary input to begin that work.
+
+Already completed function calls are not rolled back if a later call fails. Before retrying,
+inspect the existing actors, programs and subscriptions and resume the missing work. A failed
+snippet is not evidence that its earlier operations had no effect.
+
+## Actors and messages
+
+A run contains actors, inputs, turns, events, subscriptions and artifacts. Actors are the user,
+LLM agents or TypeScript actors. `actor_input` delivers ordinary text and explicitly attached
+artifacts. The recipient does not receive your context.
+Only LLM agents interpret arbitrary natural-language tasks. A TypeScript actor executes its
+programmed input protocol; inspect its program or documented functions before addressing it.
+Prefer its published functions for actions. A primary actor can be a TypeScript program;
+primary does not mean conversational. Enqueueing confirms delivery to the queue, not processing
+or task completion. Unknown program commands must fail explicitly instead of returning silently.
+
+Use `actor_list` before creating participants. A prepared run or another actor may already
+have created the required roles. Reuse suitable active actors even when they are not your
+children. Reusing a name in `agent_spawn` creates another actor with a suffix; it does not
+select the existing one. Inspect an unclear role before deciding to create another.
+
+Do the work yourself unless a separate role, context or independent task has a concrete
+benefit, or the user requests participants. Multiple files, languages or steps alone do not
+require more actors. Pure deterministic forwarding and persistent bookkeeping belong in
+TypeScript; `context.std.mediators.route` supports existing routing patterns. Use model
+judgment where the task needs it, not for unchanged message forwarding.
+
+Read `model_list` before the first spawn and select an actual profile or model from its
+result. A new agent does not inherit your model. Pass its profile or model explicitly and
+choose `tools` explicitly: `[]` for plain conversation, a named function selection for a
+bounded task, or `null` for the full available function inventory. Tools are not a role label:
+a critic who must inspect files needs the corresponding access; a plain advisor may need none.
+Agents inherit the engine capabilities you may pass on. Use `withoutCapabilities` only when
+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
+and subscriptions before sending the first assignments. Subscribe to a needed reply before
+requesting it. Never assume a failed creation produced an actor.
+
+## Events and turn boundaries
+
+Ordinary model output, reasoning and function calls are journaled automatically. A subscription
+observes matching new events and delivers each as a later ActorInput to its subscriber.
+Inputs arriving during a turn wait for the next turn. A consumed input is not automatically
+repeated after interruption. An actor program receives the structured source in `input.event`;
+the event's `type` belongs to the event itself, not its payload.
+
+Once subscriptions and assignments are in place, end the turn. Do not poll `event_query`, run
+sleep loops or keep a snippet alive waiting for future model answers. A new matching input
+starts the next turn. Use `event_query` for intentional history inspection or recovery, with
+focused filters and a small limit. `event_subscription_list` lists subscriptions;
+`event_unsubscribe` removes those no longer needed.
+
+Subscribe to `model.output.completed` for answer text, or `turn.finished` when completion
+status is sufficient. Subscribe to failures, interruption and stops only where the flow
+needs an independent reaction. Combining answer and finish events routinely produces two
+inputs for one result; when both are necessary, correlate by turn and act only once.
+Keep `includeSelf` off unless an intentional self-trigger requires it.
+
+LLM event inputs show a readable header and text, plus active subscription information.
+TypeScript programs receive structured events. An actor remains addressable after a turn;
+`actor_stop` stops it and the actors it spawned.
+The primary actor can use `run_stop` to stop all work in its own run, including tools and plugin services. Use it immediately when the user requests a complete stop. It also interrupts the calling turn; no final reply is required. The conversation and files remain available.
+
+## Results for the user
+
+Verify the actual outcome against the user's requirements. A successful typecheck or tests
+written alongside the implementation do not prove the requested behavior. Keep meaningful
+checks of output, state and effects; fix implementation errors rather than changing an
+expectation merely to obtain a passing test.
+
+Your model answer is already the user chat. Report concrete results and meaningful phase
+changes; do not add a filler waiting message after assigning work. State only what happened,
+never describe an unperformed step as done. Respect prescribed output formats. Use meaningful
+actor names and keep the run's task list current when useful. Technical IDs and environment
+variables belong in code, not in explanations to the user.

package/plugins/ragents.orchestration/server/canvas-tool.ts

@@ -0,0 +1,248 @@
+import { Type } from "typebox";
+import {
+  DomainError,
+  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";
+import {
+  CANVAS_ARROWS,
+  CANVAS_GROUP_KINDS,
+  CANVAS_LINE_STYLES,
+  CANVAS_SHAPE_KINDS,
+  CANVAS_TREE_DIRECTIONS,
+  ORCHESTRATION_PLUGIN_ID,
+  canvasEntityOf,
+  canvasLayoutOf,
+  isCanvasGroupNode,
+  type CanvasLayout,
+} from "../contract.js";
+import { canvasTileEntities, mapCanvasTileEntities } from "../tiled-layout.js";
+
+const ENTITY = "@handle names an actor, shape:<id> one of the shapes of this call, "
+  + "app:@handle/view-key or app:program-name/view-key an activated actor view. "
+  + "Use the actor handle or program name and view key you chose; the server resolves the view ID";
+
+export const canvasToolMetadata = {
+  name: "canvas_layout_replace",
+  label: "Replace Canvas Layout",
+  description: "Arrange actors and mini-apps on the free canvas or in a viewport-filling tiled layout with nested, weighted splits.",
+  longDescription: "Free mode is the default. Set mode: 'tiled' and root to a recursive tree: "
+    + "{entity:'@helper'} or {direction:'horizontal',weights:[2,1],children:[{entity:'app:@workspace/main'},{entity:'@helper'}]}. "
+    + "horizontal means left/right; vertical means top/bottom. Weights [1,1] split equally. "
+    + "Every split has two children, which may themselves be splits. Tiled mode has draggable dividers and no canvas pan or zoom. "
+    + "Mode/root-only calls preserve the free layout; mode:'free' restores it. Personal user arrangements take precedence until reset. "
+    + "In free mode the canvas draws NO lines by itself; "
+    + "a relation is visible only when you add a line here. Actors you do not place appear below your "
+    + "layout as lineage trees. Approximate sizes in px for planning wrap widths: an actor card is 150 to "
+    + "320 wide and 44 high without card sections, with sections (documents, to-dos, tools) 360 to 640 wide "
+    + "and 100 to 300 high; an actor view uses its declared canvas placement (280 to 960 by 180 to 720); "
+    + "a circle shape is 120 wide, a diamond 150 by 94 by default.",
+} as const;
+
+export const canDesignCanvas = defineToolAvailability({
+  availability: "conditional",
+  availabilityDetail: "Nur für Agenten und Script-Actors mit der Capability plugin.state.write.",
+  requiredCapabilities: ["plugin.state.write"],
+}, (actor) => actor.kind !== "human" && holdsUsable(actor, "plugin.state.write"));
+
+const literals = <T extends string>(values: readonly T[]) => values.map((value) => Type.Literal(value));
+
+const tileSchema = Type.Cyclic({
+  CanvasTile: Type.Union([
+    Type.Object({ entity: Type.String({ minLength: 1, description: "Actor @handle or activated mini-app app:@handle/view-key; no shapes" }) }, { additionalProperties: false }),
+    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")]),
+    }, { additionalProperties: false }),
+  ]),
+}, "CanvasTile");
+
+const canvasLayoutSchema = Type.Object({
+  mode: Type.Optional(Type.Union([Type.Literal("free"), Type.Literal("tiled")], { description: "free is the default; tiled fills the viewport, disables pan/zoom and uses root" })),
+  root: Type.Optional(Type.Union([tileSchema, Type.Null()], { description: "Tiled layout: an actor/app leaf or a binary split. Maximum 64 unique leaves and 16 nested splits. null clears the tiles; omitted preserves them" })),
+  nodes: Type.Optional(Type.Array(Type.Object({
+    id: Type.Optional(Type.String({ minLength: 1, description: "Groups only: an id you choose; member nodes name it in parent" })),
+    group: Type.Optional(Type.Union(literals(CANVAS_GROUP_KINDS), {
+      description: "Makes the node a group. h = row, v = column, wrap-h = row wrapping at width, "
+        + "wrap-v = column wrapping at height, grid = columns by rows, circle = members on a ring "
+        + "(actors talking to each other), tree = the root actor and everything it spawned",
+    })),
+    entity: Type.Optional(Type.String({ minLength: 1, description: `Items only: ${ENTITY}` })),
+    chatInput: Type.Optional(Type.Boolean({ description: "Actor items only: false hides the chat composer on free canvas and tiles; default true. Does not change permissions or the inspector" })),
+    parent: Type.Optional(Type.String({ minLength: 1, description: "Id of the enclosing group; omitted = top level (top-level nodes stack vertically)" })),
+    label: Type.Optional(Type.String({ description: "Groups: caption above the members, shown with or without frame" })),
+    frame: Type.Optional(Type.Boolean({ description: "Groups: true draws a dashed outline around the members; default false, no outline" })),
+    gap: Type.Optional(Type.Number({ minimum: 0, description: "Groups: minimum distance between members in px, default 44; labelled connections may increase it to leave room for their text" })),
+    width: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: "wrap-h only and required there: row width in px before wrapping" })),
+    height: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: "wrap-v only and required there: column height in px before wrapping" })),
+    columns: Type.Optional(Type.Integer({ minimum: 1, description: "grid only and required there" })),
+    direction: Type.Optional(Type.Union(literals(CANVAS_TREE_DIRECTIONS), { description: "tree only: where the children go, default right" })),
+    root: Type.Optional(Type.String({ minLength: 1, description: "tree only and required there: @handle of the root actor" })),
+  }))),
+  shapes: Type.Optional(Type.Array(Type.Object({
+    id: Type.String({ minLength: 1, description: "Your id; place the shape as an item with entity shape:<id>" }),
+    kind: Type.Union(literals(CANVAS_SHAPE_KINDS)),
+    text: Type.String({ minLength: 1, description: "Text inside the shape; keep it to a few words" }),
+    size: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: "Diameter of a circle or width of a diamond in px; default 120 and 150" })),
+  }))),
+  lines: Type.Optional(Type.Array(Type.Object({
+    from: Type.String({ minLength: 1, description: ENTITY }),
+    to: Type.String({ minLength: 1, description: `${ENTITY}; must differ from from` }),
+    label: Type.Optional(Type.String({ description: "Short caption on the line" })),
+    arrow: Type.Optional(Type.Union(literals(CANVAS_ARROWS), { description: "none = plain line (default), end = arrow at to, both = arrows at both ends" })),
+    style: Type.Optional(Type.Union(literals(CANVAS_LINE_STYLES), { description: "solid (default) or dashed" })),
+  }))),
+});
+
+const invalid = (message: string) => new DomainError("invalid-canvas-layout", message, 400);
+
+const parsedLayout = (input: unknown): CanvasLayout => {
+  try {
+    return canvasLayoutOf(input);
+  } catch (caught) {
+    throw invalid(caught instanceof Error ? caught.message : String(caught));
+  }
+};
+
+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);
+  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);
+  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"}`);
+  }
+  if (found.kind === "human") {
+    throw invalid(`${where}: @${handle} ist der Mensch im Chat; der Chat liegt fest links neben der Fläche`);
+  }
+  return found;
+};
+
+const descendantsOf = (view: RunView, actorId: string): string[] => {
+  const result: string[] = [];
+  const queue = [actorId];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const actor of view.actors) {
+      if (actor.kind !== "human" && actor.createdBy === current && !result.includes(actor.id)) {
+        result.push(actor.id);
+        queue.push(actor.id);
+      }
+    }
+  }
+  return result;
+};
+
+const isActorReference = (reference: string) => canvasEntityOf(reference).kind === "actor";
+
+const resolveAppReferences = (view: RunView, layout: CanvasLayout): CanvasLayout => {
+  const programs = view.pluginStates.flatMap((entry) => {
+    if (entry.pluginId !== ACTOR_PROGRAMS_STATE_ID || entry.scope.kind !== "actor") return [];
+    const actorId = entry.scope.actorId;
+    const actor = view.actors.find((candidate) => candidate.id === actorId);
+    if (!actor || actor.kind === "human" || isStopped(actor)) return [];
+    const { program } = entry.state as unknown as ActorProgramState;
+    return program ? [program] : [];
+  });
+  const resolve = (reference: string, where: string): string => {
+    const entity = canvasEntityOf(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:.`);
+    }
+  };
+  return parsedLayout({
+    ...layout,
+    ...(layout.root ? { root: mapCanvasTileEntities(layout.root, (entity) => resolve(entity, "root")) } : {}),
+    nodes: layout.nodes.map((node, index) => isCanvasGroupNode(node)
+      ? node : { ...node, entity: resolve(node.entity, `nodes[${index}].entity`) }),
+    lines: layout.lines.map((line, index) => ({
+      ...line,
+      from: resolve(line.from, `lines[${index}].from`),
+      to: resolve(line.to, `lines[${index}].to`),
+    })),
+  });
+};
+
+/** Resolve app names and validate entities and actor ancestry before any layout is stored. */
+export const checkLayoutAgainstRun = (view: RunView, input: CanvasLayout): CanvasLayout => {
+  const layout = resolveAppReferences(view, input);
+  for (const reference of canvasTileEntities(layout.root)) {
+    if (isActorReference(reference)) actorByHandle(view, reference, "root");
+  }
+  const placed = new Map<string, string>();
+  layout.nodes.forEach((node, index) => {
+    if (isCanvasGroupNode(node) || !isActorReference(node.entity)) return;
+    const actor = actorByHandle(view, node.entity, `nodes[${index}]`);
+    placed.set(actor.id, node.entity);
+  });
+  const trees = layout.nodes.flatMap((node, index) =>
+    isCanvasGroupNode(node) && node.group === "tree"
+      ? [{ node, root: actorByHandle(view, node.root, `nodes[${index}].root`) }]
+      : []);
+  for (const { node, root } of trees) {
+    if (placed.has(root.id)) {
+      throw invalid(`Baum ${node.id}: die Wurzel ${node.root} ist zusätzlich einzeln platziert`);
+    }
+    for (const id of descendantsOf(view, root.id)) {
+      const reference = placed.get(id);
+      if (reference) throw invalid(`Baum ${node.id}: ${reference} gehört zur Abstammung von ${node.root} und ist zusätzlich einzeln platziert`);
+      const other = trees.find((tree) => tree.root.id === id);
+      if (other) throw invalid(`Baum ${other.node.id}: ${other.node.root} liegt schon im Baum ${node.id} von ${node.root}`);
+    }
+  }
+  layout.lines.forEach((line, index) => {
+    if (isActorReference(line.from)) actorByHandle(view, line.from, `lines[${index}].from`);
+    if (isActorReference(line.to)) actorByHandle(view, line.to, `lines[${index}].to`);
+  });
+  return layout;
+};
+
+export const createCanvasTool = (): RunFunction =>
+  defineRunFunction({
+    ...canvasToolMetadata,
+    schema: canvasLayoutSchema,
+    resultSchema: eventResultSchema,
+    available: canDesignCanvas,
+    run: ({ runtime, caller, context, eventsFor }, toolCallId, input) => {
+      const view = runtime.view(caller.runId);
+      if (input.nodes === undefined && input.mode === undefined && input.root === undefined) throw invalid("nodes oder mode/root muss angegeben werden");
+      if (input.nodes === undefined && (input.shapes !== undefined || input.lines !== undefined)) throw invalid("shapes und lines ersetzen den freien Canvas zusammen mit nodes");
+      const currentState = view.pluginStates.find((entry) => entry.pluginId === ORCHESTRATION_PLUGIN_ID && entry.scope.kind === "run");
+      const current = currentState ? parsedLayout(currentState.state) : { nodes: [], shapes: [], lines: [] };
+      const checked = checkLayoutAgainstRun(view, parsedLayout({ ...input, nodes: input.nodes ?? [] }));
+      const layout: CanvasLayout = {
+        ...current,
+        ...checked,
+        ...(input.nodes === undefined ? { nodes: current.nodes, shapes: current.shapes, lines: current.lines } : {}),
+        ...(input.mode !== undefined || input.root !== undefined || current.mode !== undefined
+          ? { mode: input.mode ?? (input.root !== undefined ? "tiled" : "free") } : {}),
+      };
+      runtime.replacePluginState(context(toolCallId), caller.runId, {
+        pluginId: ORCHESTRATION_PLUGIN_ID,
+        scope: { kind: "run" },
+        state: layout,
+      });
+      return eventsFor(toolCallId);
+    },
+  });
+
+export const createCanvasToolContributor = (): ToolContributor => ({
+  name: "ragents.orchestration.canvas",
+  descriptors: [toolDescriptorFrom(canvasToolMetadata, canDesignCanvas)],
+  tools: () => [createCanvasTool()],
+});