@schlenkr/ragents 0.1.0

package/plugins/ragents.orchestration/web/executions.ts

@@ -0,0 +1,124 @@
+import type { JournalEvent } from "../../../packages/ragents/src/domain/events";
+import type { JsonValue } from "../../../packages/ragents/src/domain/json";
+import type { RunView } from "./run-view";
+
+export type ExecutionStatus = "running" | "completed" | "failed" | "interrupted";
+
+export interface TypeScriptExecution {
+  key: string;
+  actorId: string;
+  actorHandle: string;
+  actorName: string;
+  turnId: string;
+  toolCallId: string;
+  sequence: number;
+  startedAt: string;
+  finishedAt: string | null;
+  status: ExecutionStatus;
+  code: string | null;
+  path: string | null;
+  result: JsonValue | undefined;
+  logs: readonly string[];
+  error: string | null;
+}
+
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const executionKey = (actorId: string, turnId: string, toolCallId: string) => JSON.stringify([actorId, turnId, toolCallId]);
+
+export const executionEventsFrom = (value: unknown, runId: string): readonly JournalEvent[] => {
+  if (!Array.isArray(value) || value.some((entry: unknown) => {
+    if (!record(entry) || entry.runId !== runId || typeof entry.eventId !== "string" || typeof entry.actorId !== "string"
+      || !Number.isSafeInteger(entry.sequence) || typeof entry.occurredAt !== "string" || !Number.isFinite(Date.parse(entry.occurredAt))
+      || typeof entry.type !== "string" || !record(entry.payload)) return true;
+    const payload = entry.payload;
+    if (entry.type.startsWith("tool.call.") && (typeof payload.turnId !== "string" || typeof payload.toolCallId !== "string")) return true;
+    if (entry.type === "tool.call.source") return typeof payload.code !== "string" || (payload.path !== null && typeof payload.path !== "string");
+    if (entry.type === "tool.call.started") return typeof payload.name !== "string" || !("input" in payload);
+    if (entry.type === "tool.call.completed") return typeof payload.name !== "string" || !("output" in payload);
+    if (entry.type === "tool.call.failed") return typeof payload.name !== "string" || typeof payload.error !== "string";
+    if (entry.type === "turn.finished") return typeof payload.turnId !== "string" || !["completed", "failed"].includes(String(payload.outcome));
+    if (entry.type === "turn.interrupted") return typeof payload.turnId !== "string" || typeof payload.reason !== "string";
+    return false;
+  })) throw new Error("Der Server hat kein gültiges Journal für diesen Run geliefert.");
+  return value as JournalEvent[];
+};
+
+export const projectExecutions = (events: readonly JournalEvent[], view?: Pick<RunView, "id" | "actors" | "turns">): TypeScriptExecution[] => {
+  const executions = new Map<string, TypeScriptExecution>();
+  const actors = new Map(view?.actors.map((actor) => [actor.id, actor]));
+  const ends = new Map<string, { at: string; reason: string | null }>();
+  for (const event of [...events].sort((left, right) => left.sequence - right.sequence)) {
+    if (view && event.runId !== view.id) continue;
+    if (event.type === "turn.finished" || event.type === "turn.interrupted") {
+      ends.set(JSON.stringify([event.actorId, event.payload.turnId]), { at: event.occurredAt, reason: "reason" in event.payload ? event.payload.reason : null });
+      continue;
+    }
+    if (event.type !== "tool.call.started" && event.type !== "tool.call.completed" && event.type !== "tool.call.failed" && event.type !== "tool.call.source") continue;
+    const key = executionKey(event.actorId, event.payload.turnId, event.payload.toolCallId);
+    if (event.type === "tool.call.started") {
+      if (event.payload.name !== "typescript_eval" || executions.has(key)) continue;
+      const actor = actors.get(event.actorId);
+      const input = record(event.payload.input) ? event.payload.input : {};
+      executions.set(key, {
+        key, actorId: event.actorId, actorHandle: actor?.handle ?? event.actorId, actorName: actor?.displayName ?? event.actorId,
+        turnId: event.payload.turnId, toolCallId: event.payload.toolCallId, sequence: event.sequence,
+        startedAt: event.occurredAt, finishedAt: null, status: "running",
+        code: typeof input.code === "string" ? input.code : null, path: typeof input.path === "string" ? input.path : null,
+        result: undefined, logs: [], error: null,
+      });
+      continue;
+    }
+    const execution = executions.get(key);
+    if (!execution) continue;
+    if (event.type === "tool.call.source") {
+      execution.code = event.payload.code;
+      execution.path = event.payload.path;
+    } else if (event.type === "tool.call.completed") {
+      execution.status = "completed";
+      execution.finishedAt = event.occurredAt;
+      const output = event.payload.output;
+      const envelope = record(output) && "result" in output && Array.isArray(output.logs) && output.logs.every((line) => typeof line === "string");
+      execution.result = envelope ? output.result as JsonValue : output;
+      execution.logs = envelope ? output.logs as string[] : [];
+    } else {
+      execution.status = "failed";
+      execution.finishedAt = event.occurredAt;
+      execution.error = event.payload.error;
+    }
+  }
+  const turns = new Map(view?.turns.map((turn) => [JSON.stringify([turn.actorId, turn.id]), turn]));
+  for (const execution of executions.values()) {
+    if (execution.status !== "running") continue;
+    const turnKey = JSON.stringify([execution.actorId, execution.turnId]);
+    const turn = turns.get(turnKey);
+    const call = turn?.toolCalls?.find((entry) => entry.id === execution.toolCallId && entry.name === "typescript_eval");
+    const ended = ends.get(turnKey);
+    if (call && call.status !== "running") {
+      execution.status = call.status;
+      execution.finishedAt = call.finishedAt ?? turn?.finishedAt ?? ended?.at ?? null;
+    } else if (ended || (turn && turn.status !== "running")) {
+      execution.status = "interrupted";
+      execution.finishedAt = ended?.at ?? turn?.finishedAt ?? null;
+    }
+    if (execution.status === "interrupted") execution.error = ended?.reason ?? turn?.reason ?? "Der Aufruf wurde unterbrochen.";
+  }
+  return [...executions.values()].sort((left, right) => right.sequence - left.sequence);
+};
+
+export const executionStatusLabel = (status: ExecutionStatus): string => ({ running: "Läuft", completed: "Fertig", failed: "Fehlgeschlagen", interrupted: "Unterbrochen" })[status];
+
+export const filterExecutions = (executions: readonly TypeScriptExecution[], query: string, status: ExecutionStatus | "all"): TypeScriptExecution[] => {
+  const search = query.trim().toLocaleLowerCase("de-DE");
+  return executions.filter((execution) => (status === "all" || execution.status === status) && (!search || [
+    execution.actorId, execution.actorHandle, execution.actorName, execution.code, execution.path,
+    JSON.stringify(execution.result), ...execution.logs, execution.error, executionStatusLabel(execution.status),
+  ].join("\n").toLocaleLowerCase("de-DE").includes(search)));
+};
+
+export const executionDuration = (execution: Pick<TypeScriptExecution, "startedAt" | "finishedAt">, now: number): string => {
+  const milliseconds = Math.max(0, (execution.finishedAt ? Date.parse(execution.finishedAt) : now) - Date.parse(execution.startedAt));
+  if (!Number.isFinite(milliseconds)) return "Dauer unbekannt";
+  if (milliseconds < 1_000) return `${milliseconds} ms`;
+  const seconds = Math.floor(milliseconds / 1_000);
+  return seconds < 60 ? `${seconds} s` : `${Math.floor(seconds / 60)} min ${seconds % 60} s`;
+};

package/plugins/ragents.orchestration/web/format.ts

@@ -0,0 +1,4 @@
+export const formatTime = (iso: string) => {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString("de-DE");
+};

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

@@ -0,0 +1,182 @@
+import { useAccess } from "@aicontainer/web/AccessContext";
+import { createContext, useContext, useEffect, useState } from "react";
+import { FlowInspector as NetworkInspector, type FlowSelection as NetworkSelection } from "./FlowInspector";
+import { OrchestrationCenter } from "./Center";
+import { OrchestrationColumn } from "./column/RunColumn";
+import { DocumentsSection } from "./DocumentsSection";
+import { CardSizeSettings } from "./CardSizeSettings";
+import { ZoomSettings } from "./ZoomSettings";
+import { ColumnSettings } from "./column/ColumnSettings";
+import { ActorShortcuts } from "./ActorCanvasControls";
+import { MaterialSettings } from "@aicontainer/web/MaterialSettings";
+import { JournalStatus } from "./JournalStatus";
+import { StopRunHeader } from "./StopRunButton";
+import { EXECUTIONS_TAB_ID, ExecutionsPanel, IconExecutions } from "./ExecutionsPanel";
+import { ORCHESTRATION_PLUGIN_ID, ORCHESTRATION_TAB_ID } from "./constants";
+import { runViewFrom } from "./run-view";
+import {
+  CanvasControllerProvider,
+  type EntityReference,
+  type SessionProviderProps,
+  type WebPlugin,
+  type WorkspaceTabContext,
+} from "@aicontainer/web/PluginRegistry";
+
+export { ORCHESTRATION_PLUGIN_ID, ORCHESTRATION_TAB_ID } from "./constants";
+
+interface OrchestrationController {
+  canGoBack: boolean;
+  selection: NetworkSelection | undefined;
+  selectionRevision: number;
+  acceptCanvasSelection: (selection: EntityReference | undefined) => void;
+  navigateBack: () => void;
+  navigateFromPanel: (selection: NetworkSelection) => void;
+}
+
+const OrchestrationContext = createContext<OrchestrationController | undefined>(undefined);
+
+const isNetworkSelection = (selection: EntityReference): selection is NetworkSelection =>
+  selection.type === "actor"
+  || selection.type === "input"
+  || selection.type === "turn"
+  || selection.type === "subscription"
+  || selection.type === "action"
+  || selection.type === "artifact";
+
+function OrchestrationSessionProvider({ children, navigation, session }: SessionProviderProps) {
+  const inspect = useAccess().can("runs.inspect");
+  const runView = runViewFrom(session.runView);
+  const [selection, setSelection] = useState<NetworkSelection>();
+  const [history, setHistory] = useState<NetworkSelection[]>([]);
+  const [selectionRevision, setSelectionRevision] = useState(0);
+
+  useEffect(() => {
+    if (runView) return;
+    setSelection(undefined);
+    setHistory([]);
+    setSelectionRevision((revision) => revision + 1);
+  }, [runView]);
+
+  const publishSelection = (next: NetworkSelection | undefined) => {
+    setSelection(next);
+    setSelectionRevision((revision) => revision + 1);
+  };
+
+  const acceptCanvasSelection = (nextEntity: EntityReference | undefined) => {
+    if (nextEntity && !isNetworkSelection(nextEntity)) return;
+    const next = nextEntity;
+    if (next?.type === "artifact" && navigation.revealEntity(next)) {
+      setSelectionRevision((revision) => revision + 1);
+      return;
+    }
+    setHistory([]);
+    publishSelection(next);
+    if (next && inspect) navigation.openTab(ORCHESTRATION_TAB_ID);
+  };
+
+  const navigateFromPanel = (next: NetworkSelection) => {
+    if (next.type === "artifact" && navigation.revealEntity(next)) return;
+    const current = selection
+      ?? (runView ? { type: "actor" as const, id: runView.primaryActorId ?? runView.ownerId } : undefined);
+    if (current) setHistory((entries) => [...entries.slice(-31), current]);
+    publishSelection(next);
+  };
+
+  const navigateBack = () => {
+    const previous = history.at(-1);
+    setHistory((entries) => entries.slice(0, -1));
+    publishSelection(previous);
+  };
+
+  return (
+    <CanvasControllerProvider value={{
+      acceptSelection: acceptCanvasSelection,
+      selection,
+      selectionRevision,
+      tabId: ORCHESTRATION_TAB_ID,
+    }}>
+      <OrchestrationContext.Provider value={{
+        acceptCanvasSelection,
+        canGoBack: history.length > 0,
+        navigateBack,
+        navigateFromPanel,
+        selection,
+        selectionRevision,
+      }}>
+        {children}
+      </OrchestrationContext.Provider>
+    </CanvasControllerProvider>
+  );
+}
+
+export const useOrchestrationController = () => useContext(OrchestrationContext);
+
+function OrchestrationInspectorPanel({ session }: WorkspaceTabContext) {
+  const controller = useOrchestrationController();
+  if (!controller) throw new Error("Orchestrierungs-Plugin ist nicht aktiv");
+  return (
+    <NetworkInspector
+      canGoBack={controller.canGoBack}
+      composerVisible={session.centerMode === "workflow"}
+      primaryMessages={session.messages}
+      actorConversations={session.actorConversations}
+      conversationError={session.conversationError}
+      primaryRunning={session.running}
+      onBack={controller.navigateBack}
+      onNavigate={controller.navigateFromPanel}
+      selection={controller.selection}
+      view={runViewFrom(session.runView)}
+    />
+  );
+}
+
+function IconOrchestration() {
+  return (
+    <svg aria-hidden fill="none" height="15" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.7" viewBox="0 0 24 24" width="15">
+      <rect height="6" rx="1.5" width="8" x="3" y="3" />
+      <rect height="6" rx="1.5" width="8" x="13" y="15" />
+      <path d="M7 9v4a2 2 0 0 0 2 2h4" />
+    </svg>
+  );
+}
+
+export const webPlugin: WebPlugin = {
+  id: ORCHESTRATION_PLUGIN_ID,
+  needsRunView: true,
+  sessionStatus: [{ id: "ragents.orchestration.journal", readRight: "runs.inspect", order: 20, Status: JournalStatus }],
+  sessionHeaders: [
+    { id: "ragents.orchestration.stop", readRight: "runs.write", order: 100, Header: StopRunHeader },
+    { id: "ragents.orchestration.actors", order: 300, placement: "canvas", Header: ActorShortcuts },
+  ],
+  settings: [
+    { id: "ragents.orchestration.material", category: "appearance", label: "Schichtwerk-Material", Settings: MaterialSettings },
+    { id: "ragents.orchestration.card-size", category: "appearance", label: "LLM-Karten", Settings: CardSizeSettings },
+    { id: "ragents.orchestration.zoom", category: "appearance", label: "Canvas-Zoom", Settings: ZoomSettings },
+    { id: "ragents.orchestration.column", category: "appearance", label: "Arbeitsspalte", Settings: ColumnSettings },
+  ],
+  canvas: { Center: OrchestrationCenter, Column: OrchestrationColumn, tabId: ORCHESTRATION_TAB_ID },
+  cardSections: [{
+    id: "ragents.orchestration.documents",
+    order: 300,
+    Section: DocumentsSection,
+  }],
+  SessionProvider: OrchestrationSessionProvider,
+  workspaceTabs: [{
+    readRight: "runs.inspect",
+    id: ORCHESTRATION_TAB_ID,
+    label: "Netz",
+    order: 100,
+    Icon: IconOrchestration,
+    Panel: OrchestrationInspectorPanel,
+    available: (session) => (runViewFrom(session.runView)?.actors.length ?? 0) > 0,
+  }, {
+    id: EXECUTIONS_TAB_ID,
+    readRight: "runs.inspect",
+    label: "Executions",
+    order: 110,
+    Icon: IconExecutions,
+    Panel: ExecutionsPanel,
+    keepMounted: true,
+    available: (session) => runViewFrom(session.runView) !== undefined,
+  }],
+};

package/plugins/ragents.orchestration/web/keyboard-navigation.ts

@@ -0,0 +1,55 @@
+import type { CanvasCamera } from "./canvas-layout-storage";
+
+const DURATION = 300;
+
+export interface CanvasNavigationBox { id: string; left: number; top: number; right: number; bottom: number }
+
+export const nextCanvasElement = (
+  elements: readonly CanvasNavigationBox[],
+  origin: Omit<CanvasNavigationBox, "id">,
+  key: string,
+  currentId?: string,
+): CanvasNavigationBox | undefined => {
+  if (!["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(key)) return undefined;
+  const horizontal = key === "ArrowLeft" || key === "ArrowRight";
+  const direction = key === "ArrowLeft" || key === "ArrowUp" ? -1 : 1;
+  const x = (origin.left + origin.right) / 2;
+  const y = (origin.top + origin.bottom) / 2;
+  return elements.filter((box) => box.id !== currentId).map((box) => {
+    const dx = (box.left + box.right) / 2 - x;
+    const dy = (box.top + box.bottom) / 2 - y;
+    const forward = (horizontal ? dx : dy) * direction;
+    const across = horizontal ? dy : dx;
+    const aligned = horizontal ? box.bottom >= origin.top && box.top <= origin.bottom
+      : box.right >= origin.left && box.left <= origin.right;
+    return { box, forward, aligned, distance: Math.hypot(forward, across * 2) };
+  }).filter((entry) => entry.forward > 1)
+    .sort((a, b) => Number(b.aligned) - Number(a.aligned) || a.distance - b.distance || a.box.id.localeCompare(b.box.id))[0]?.box;
+};
+
+export const createKeyboardNavigation = (read: () => CanvasCamera, apply: (camera: CanvasCamera) => void) => {
+  let frame: number | undefined;
+  let startedAt = -Infinity;
+  const cancel = () => {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    frame = undefined;
+  };
+  const moveTo = (to: CanvasCamera, repeat: boolean, reducedMotion: boolean): boolean => {
+    const now = performance.now();
+    if (repeat && (frame !== undefined || now - startedAt < DURATION)) return false;
+    const from = read();
+    cancel();
+    startedAt = now;
+    if (reducedMotion) { apply(to); return true; }
+    const step = (time: number) => {
+      const progress = Math.min(1, Math.max(0, (time - startedAt) / DURATION));
+      const eased = progress * progress * (3 - 2 * progress);
+      apply({ x: from.x + (to.x - from.x) * eased, y: from.y + (to.y - from.y) * eased, zoom: from.zoom });
+      if (progress < 1) frame = requestAnimationFrame(step);
+      else frame = undefined;
+    };
+    frame = requestAnimationFrame(step);
+    return true;
+  };
+  return { moveTo, cancel };
+};

package/plugins/ragents.orchestration/web/material-layout.ts

@@ -0,0 +1,14 @@
+import type { SceneNode } from "./canvas-layout";
+
+export function withMaterialSpacing(node: SceneNode, depth: number): SceneNode {
+  if (node.kind === "leaf") return node;
+  const horizontal = depth * .5 + 32, vertical = depth * .7 + 32;
+  const layout = node.layout;
+  const next = layout.type === "tree" ? {
+    ...layout,
+    rankGap: Math.max(layout.rankGap, layout.direction === "right" ? horizontal : vertical),
+    siblingGap: Math.max(layout.siblingGap, layout.direction === "right" ? vertical : horizontal),
+  } : { ...layout, gap: Math.max(layout.gap,
+    layout.type === "stack" ? layout.axis === "h" ? horizontal : vertical : Math.max(horizontal, vertical)) };
+  return { ...node, layout: next, children: node.children.map((child) => withMaterialSpacing(child, depth)) };
+}

package/plugins/ragents.orchestration/web/run-view.ts

@@ -0,0 +1,199 @@
+import { artifactContentPath } from "@aicontainer/ragents/src/http/contracts";
+
+export interface RunCapabilityGrant {
+  capability: string;
+  scope: { kind: "run" } | { kind: "workspace"; path: string };
+  delegable: boolean;
+  usable?: boolean;
+}
+
+export interface RunUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+}
+
+export interface RunExecution {
+  driver: {
+    kind: string;
+    config: {
+      provider?: string | null;
+      model?: string | null;
+      thinking?: string | null;
+    };
+  };
+  workspacePath: string | null;
+  turnTimeoutMs: number | null;
+}
+
+export interface RunActor {
+  id: string;
+  kind: "human" | "agent" | "script";
+  handle: string;
+  displayName: string;
+  grants: RunCapabilityGrant[];
+  createdAt: string;
+  createdBy?: string;
+  prompt?: string;
+  source?: string;
+  sourceHash?: string;
+  platformVersion?: 2;
+  compilationHash?: string;
+  capabilityIds?: string[];
+  capabilityContractHash?: string;
+  inputs?: Record<string, string>;
+  execution?: RunExecution;
+  lifecycle?:
+    | { kind: "idle"; since: string }
+    | { kind: "running"; turnId: string; inputId: string; startedAt: string }
+    | { kind: "stopped"; stoppedAt: string; reason: string };
+  usage?: RunUsage;
+  toolNames?: string[] | null;
+}
+
+export type RunActorInputLifecycle =
+  | { kind: "pending" }
+  | { kind: "claimed"; turnId: string }
+  | { kind: "discarded"; at: string; reason: string };
+
+export interface RunActorInput {
+  presentation?: "background";
+  id: string;
+  actorId: string;
+  content: string;
+  artifactIds: string[];
+  sourceEventIds: string[];
+  subscriptionId: string | null;
+  enqueuedBy: string;
+  enqueuedAt: string;
+  sequence: number;
+  lifecycle: RunActorInputLifecycle;
+}
+
+export const isPendingRunActorInput = (input: RunActorInput) =>
+  input.lifecycle.kind === "pending";
+
+export interface RunTurnOutput {
+  text: string;
+  sequence: number;
+  occurredAt: string;
+}
+
+export interface RunTurn {
+  id: string;
+  actorId: string;
+  inputId: string;
+  status: "running" | "completed" | "failed" | "interrupted";
+  startedAt: string;
+  finishedAt: string | null;
+  reason: string | null;
+  usage: RunUsage;
+  outputs?: RunTurnOutput[];
+  toolCalls?: readonly { id: string; name: string; status: "running" | "completed" | "failed" | "interrupted"; startedAt: string; finishedAt: string | null }[];
+}
+
+const isRunTurnOutput = (value: unknown): value is RunTurnOutput => {
+  if (typeof value !== "object" || value === null) return false;
+  const output = value as RunTurnOutput;
+  return typeof output.text === "string"
+    && typeof output.sequence === "number"
+    && typeof output.occurredAt === "string";
+};
+
+/** Die Modellantworten eines Turns in Journal-Reihenfolge; eine Ansicht ohne das Feld liefert nichts. */
+export const runTurnOutputs = (turn: RunTurn): RunTurnOutput[] =>
+  (Array.isArray(turn.outputs) ? turn.outputs.filter(isRunTurnOutput) : [])
+    .sort((left, right) => left.sequence - right.sequence);
+
+export type RunSubscription = {
+  id: string;
+  subscriberId: string;
+  sourceActorIds: string[] | null;
+  sourceActorKinds: Array<RunActor["kind"]> | null;
+  eventTypes: string[];
+  includeSelf: boolean;
+  createdBy: string;
+  createdAt: string;
+  createdSequence: number;
+} & (
+  | { status: "active" }
+  | { status: "removed"; endedAt: string; reason: string }
+  | { status: "failed"; endedAt: string; reason: string; sourceEventId: string }
+);
+
+export interface RunPluginState {
+  pluginId: string;
+  scope: { kind: "run" } | { kind: "actor"; actorId: string };
+  state: unknown;
+  updatedAt: string;
+}
+
+export interface RunAction {
+  id: string;
+  askedBy: string;
+  kind: "action" | "question";
+  question: { options: string[]; multi: boolean } | null;
+  title: string;
+  description: string | null;
+  parameters: Record<string, string>;
+  input: { label: string; placeholder: string | null; required: boolean } | null;
+  status: "pending" | "approved" | "dismissed";
+  proposedAt: string;
+  resolvedAt: string | null;
+  resolvedBy: string | null;
+  response: string | null;
+}
+
+export interface RunArtifact {
+  id: string;
+  title: string;
+  mediaType: string;
+  hash: string;
+  size: number;
+  previousVersionId: string | null;
+  createdBy: string;
+  createdAt: string;
+}
+
+export interface RunView {
+  id: string;
+  revision: number;
+  title: string;
+  ownerId: string;
+  primaryActorId: string | null;
+  createdAt: string;
+  forkedFrom: { runId: string; sequence: number } | null;
+  actors: RunActor[];
+  inputs: RunActorInput[];
+  turns: RunTurn[];
+  subscriptions: RunSubscription[];
+  pluginStates: RunPluginState[];
+  actions: RunAction[];
+  artifacts: RunArtifact[];
+}
+
+export type ActorSurface = "agent" | "primary" | "script";
+
+export const actorSurface = (view: RunView, actor: RunActor): ActorSurface =>
+  actor.kind === "script" ? "script" : actor.id === view.primaryActorId ? "primary" : "agent";
+
+export const runViewFrom = (value: unknown): RunView | undefined => {
+  if (typeof value !== "object" || value === null) return undefined;
+  const view = value as RunView;
+  return typeof view.id === "string"
+    && typeof view.ownerId === "string"
+    && (typeof view.primaryActorId === "string" || view.primaryActorId === null)
+    && Array.isArray(view.actors)
+    && Array.isArray(view.inputs)
+    && Array.isArray(view.turns)
+    && Array.isArray(view.subscriptions)
+    && Array.isArray(view.pluginStates)
+    && Array.isArray(view.actions)
+    && Array.isArray(view.artifacts)
+    ? view
+    : undefined;
+};
+
+export const runArtifactContentUrl = (runId: string, artifactId: string) => artifactContentPath(runId, artifactId);

package/plugins/ragents.orchestration/web/tile-docking.ts

@@ -0,0 +1,99 @@
+import type { CanvasTileNode } from "../tiled-layout";
+
+export const CANVAS_TILE_DRAG_TYPE = "application/x-ragents-canvas-tile";
+export const TILE_DIVIDER_SIZE = 8;
+export const TILE_MIN_WIDTH = 220;
+export const TILE_MIN_HEIGHT = 160;
+export type TileDockSide = "left" | "right" | "top" | "bottom";
+export interface TileRect { left: number; top: number; width: number; height: number }
+export interface TileDivider extends TileRect {
+  path: readonly number[];
+  direction: "horizontal" | "vertical";
+  ratio: number;
+  minimum: number;
+  maximum: number;
+  span: number;
+}
+
+export function tileEntities(root: CanvasTileNode | null): string[] {
+  return root === null ? [] : "entity" in root ? [root.entity] : root.children.flatMap(tileEntities);
+}
+
+export function removeTile(root: CanvasTileNode | null, entity: string): CanvasTileNode | null {
+  if (root === null || "entity" in root) return root?.entity === entity ? null : root;
+  const first = removeTile(root.children[0], entity);
+  const second = removeTile(root.children[1], entity);
+  if (!first) return second;
+  if (!second) return first;
+  return first === root.children[0] && second === root.children[1] ? root : { ...root, children: [first, second] };
+}
+
+export function dockTile(root: CanvasTileNode | null, entity: string, target: string | null, side: TileDockSide): CanvasTileNode | null {
+  if ((root && "entity" in root && root.entity === entity && target === null) || entity === target || (target !== null && !tileEntities(root).includes(target))) return root;
+  const remaining = removeTile(root, entity);
+  const leaf: CanvasTileNode = { entity };
+  if (!remaining) return leaf;
+  const wrap = (node: CanvasTileNode): CanvasTileNode => ({
+    direction: side === "left" || side === "right" ? "horizontal" : "vertical",
+    weights: [1, 1],
+    children: side === "left" || side === "top" ? [leaf, node] : [node, leaf],
+  });
+  if (target === null) return wrap(remaining);
+  const insert = (node: CanvasTileNode): CanvasTileNode => "entity" in node
+    ? node.entity === target ? wrap(node) : node
+    : { ...node, children: [insert(node.children[0]), insert(node.children[1])] };
+  return insert(remaining);
+}
+
+export function tileMinimum(root: CanvasTileNode): { width: number; height: number } {
+  if ("entity" in root) return { width: TILE_MIN_WIDTH, height: TILE_MIN_HEIGHT };
+  const first = tileMinimum(root.children[0]);
+  const second = tileMinimum(root.children[1]);
+  return root.direction === "horizontal"
+    ? { width: first.width + second.width + TILE_DIVIDER_SIZE, height: Math.max(first.height, second.height) }
+    : { width: Math.max(first.width, second.width), height: first.height + second.height + TILE_DIVIDER_SIZE };
+}
+
+export function resizeTile(root: CanvasTileNode, path: readonly number[], ratio: number): CanvasTileNode {
+  if ("entity" in root) return root;
+  if (path.length === 0) {
+    const bounded = Math.max(0.001, Math.min(0.999, ratio));
+    return { ...root, weights: [bounded, 1 - bounded] };
+  }
+  const branch = path[0];
+  if (branch !== 0 && branch !== 1) return root;
+  const children: [CanvasTileNode, CanvasTileNode] = [...root.children];
+  children[branch] = resizeTile(children[branch], path.slice(1), ratio);
+  return { ...root, children };
+}
+
+export function tileGeometry(root: CanvasTileNode, bounds: TileRect): { leaves: Map<string, TileRect>; dividers: TileDivider[] } {
+  const leaves = new Map<string, TileRect>();
+  const dividers: TileDivider[] = [];
+  const visit = (node: CanvasTileNode, rect: TileRect, path: readonly number[]) => {
+    if ("entity" in node) { leaves.set(node.entity, rect); return; }
+    const horizontal = node.direction === "horizontal";
+    const span = Math.max(0, (horizontal ? rect.width : rect.height) - TILE_DIVIDER_SIZE);
+    const firstMinimum = tileMinimum(node.children[0]);
+    const secondMinimum = tileMinimum(node.children[1]);
+    const minimum = span > 0 ? (horizontal ? firstMinimum.width : firstMinimum.height) / span : 0.5;
+    const maximum = span > 0 ? 1 - (horizontal ? secondMinimum.width : secondMinimum.height) / span : 0.5;
+    const scale = Math.max(...node.weights);
+    const firstWeight = node.weights[0] / scale;
+    const requested = firstWeight / (firstWeight + node.weights[1] / scale);
+    const ratio = minimum <= maximum ? Math.max(minimum, Math.min(maximum, requested)) : requested;
+    const first = span * ratio;
+    dividers.push({
+      left: rect.left + (horizontal ? first : 0), top: rect.top + (horizontal ? 0 : first),
+      width: horizontal ? TILE_DIVIDER_SIZE : rect.width, height: horizontal ? rect.height : TILE_DIVIDER_SIZE,
+      path, direction: node.direction, ratio, minimum, maximum, span,
+    });
+    visit(node.children[0], { ...rect, width: horizontal ? first : rect.width, height: horizontal ? rect.height : first }, [...path, 0]);
+    visit(node.children[1], {
+      left: rect.left + (horizontal ? first + TILE_DIVIDER_SIZE : 0), top: rect.top + (horizontal ? 0 : first + TILE_DIVIDER_SIZE),
+      width: horizontal ? span - first : rect.width, height: horizontal ? rect.height : span - first,
+    }, [...path, 1]);
+  };
+  visit(root, bounds, []);
+  return { leaves, dividers };
+}