@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/client-ui/contracts.d.ts

@@ -0,0 +1,84 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ChatAttachment, ChatAttachmentCapabilities, ChatAttachmentInput, Message } from "../../../apps/server/src/chat-events";
+
+export * from "../../../apps/web/src/ui";
+export * from "./file-contracts";
+export * from "./form-contracts";
+export * from "./layout-contracts";
+export * from "./table-contracts";
+export * from "./viewer-contracts";
+export * from "./message-list-contracts";
+export * from "./flow-diagram-contracts";
+export * from "./workflow-diagram-contracts";
+
+export type { ChatAttachment, ChatAttachmentCapabilities, ChatAttachmentInput, Message };
+
+export interface ChatSnapshot {
+  /** Resolved sender identity of the bound actor, used as the default presentation owner. */
+  owner?: string;
+  readOnly?: boolean;
+  attachmentCapabilities?: ChatAttachmentCapabilities;
+  attachmentCapabilitiesError?: string;
+  messages: Message[];
+  running: boolean;
+  error?: string;
+}
+
+export interface ChatConnection {
+  read(actor: string): ChatSnapshot | undefined;
+  subscribe(actor: string, listener: () => void): () => void;
+  send(actor: string, text: string, attachments?: ChatAttachmentInput[]): Promise<void>;
+}
+
+export interface ChatMessagesProps {
+  messages: Message[];
+  /** Matching Message.sender renders without bubbles; null uses message defaults, actor chats default to their bound actor. */
+  owner?: string | null;
+  running?: boolean;
+  detailMode?: "off" | "current" | "icons" | "chips" | "grouped" | "compact" | "full";
+  showTimestamps?: boolean;
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+export interface ChatInputProps {
+  attachmentCapabilities?: ChatAttachmentCapabilities;
+  attachmentCapabilitiesError?: string;
+  onSend: (text: string, attachments?: ChatAttachmentInput[]) => void | Promise<void>;
+  placeholder?: string;
+  rows?: number;
+  maxRows?: number;
+  running?: boolean;
+  disabled?: boolean;
+}
+
+interface ChatBaseProps extends Omit<ChatMessagesProps, "messages" | "running"> {
+  attachmentCapabilities?: ChatAttachmentCapabilities;
+  attachmentCapabilitiesError?: string;
+  title?: string;
+  showInput?: boolean;
+  placeholder?: string;
+  rows?: number;
+  maxRows?: number;
+}
+
+export interface ActorChatProps extends ChatBaseProps {
+  actor: string;
+  messages?: never;
+  onSend?: never;
+  running?: never;
+}
+
+export interface ControlledChatProps extends ChatBaseProps {
+  actor?: never;
+  messages: Message[];
+  onSend?: (text: string, attachments?: ChatAttachmentInput[]) => void | Promise<void>;
+  running?: boolean;
+}
+
+export type ChatProps = ActorChatProps | ControlledChatProps;
+
+export declare function Chat(props: ChatProps): ReactElement;
+export declare function ChatMessages(props: ChatMessagesProps): ReactElement;
+export declare function ChatInput(props: ChatInputProps): ReactElement;
+export declare function Markdown(props: { text: string }): ReactElement;

package/plugins/ragents.actor-programs/client-ui/file-contracts.d.ts

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+
+export interface FilePickerProps {
+  label: string;
+  files: readonly File[];
+  /** Auswahl bleibt lokal; die Ansicht entscheidet über Lesen und Übertragen. */
+  onChange: (files: File[]) => void | Promise<void>;
+  /** Dateiendungen oder MIME-Typen, z. B. .csv,image/*; wird auch für Drop und Paste geprüft. */
+  accept?: string;
+  multiple?: boolean;
+  /** Höchstzahl der gesamten Auswahl; Standard 10, bei multiple=false genau eine Datei. */
+  maxFiles?: number;
+  /** Maximale Gesamtgröße in Bytes; Standard 20 MiB. */
+  maxBytes?: number;
+  disabled?: boolean;
+  showPreview?: boolean;
+}
+
+export declare function FilePicker(props: FilePickerProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/file-selection.ts

@@ -0,0 +1,24 @@
+import type { FilePickerProps } from "./file-contracts";
+
+export const fileSelection = (current: readonly File[], incoming: readonly File[], options: Pick<FilePickerProps, "accept" | "multiple" | "maxFiles" | "maxBytes">): File[] => {
+  const maximum = options.multiple === false ? 1 : options.maxFiles ?? 10;
+  const bytes = options.maxBytes ?? 20 * 1024 * 1024;
+  if (!Number.isInteger(maximum) || maximum < 1 || !Number.isFinite(bytes) || bytes < 1) throw new Error("Dateigrenzen müssen positive Zahlen sein.");
+  if (!incoming.length) throw new Error("Die Auswahl enthält keine lesbaren Dateien.");
+  if (options.multiple === false && incoming.length > 1) throw new Error("Bitte genau eine Datei auswählen.");
+  const accepted = options.accept?.toLowerCase().split(",").map((part) => part.trim()).filter(Boolean) ?? [];
+  for (const file of incoming) {
+    if (accepted.length && !accepted.some((type) => type.startsWith(".")
+      ? file.name.toLowerCase().endsWith(type)
+      : type.endsWith("/*") ? file.type.toLowerCase().startsWith(type.slice(0, -1)) : file.type.toLowerCase() === type)) {
+      throw new Error(`Dateityp von ${file.name} nicht erlaubt. Erlaubt: ${options.accept}`);
+    }
+  }
+  const result = options.multiple === false ? [...incoming] : [...current];
+  if (options.multiple !== false) for (const file of incoming) {
+    if (!result.some((entry) => entry.name === file.name && entry.size === file.size && entry.lastModified === file.lastModified && entry.type === file.type)) result.push(file);
+  }
+  if (result.length > maximum) throw new Error(`Höchstens ${maximum} Dateien auswählen.`);
+  if (result.reduce((sum, file) => sum + file.size, 0) > bytes) throw new Error(`Die Auswahl überschreitet ${bytes} Bytes.`);
+  return result;
+};

package/plugins/ragents.actor-programs/client-ui/flow-diagram-contracts.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+
+export interface FlowDiagramProps {
+  nodes: readonly {
+    id: string;
+    label: string;
+    detail?: string;
+    status?: "pending" | "active" | "done" | "blocked";
+    running?: boolean;
+    items?: readonly { label: string; status?: "pending" | "active" | "done" | "blocked" | "skipped"; detail?: string }[];
+    kind?: "actor" | "agent" | "service";
+    actions?: readonly { id: string; label: string; disabled?: boolean; primary?: boolean }[];
+  }[];
+  edges: readonly { id?: string; source: string; target: string; label?: string; kind?: "return"; status?: "pending" | "active" | "done" | "blocked" }[];
+  label: string;
+  /** "star" places the first node in the middle and the others around it. */
+  layout?: "layered" | "star";
+  direction?: "right" | "down";
+  className?: string;
+  height?: number;
+  detailLevel?: "full" | "summary";
+  /** "fit" scales the diagram into the available width and height. */
+  viewport?: "interactive" | "fit-width" | "fit";
+  onAction?: (nodeId: string, actionId: string) => void;
+}
+
+export declare function FlowDiagram(props: FlowDiagramProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/flow-diagram.css

@@ -0,0 +1,23 @@
+/* The only hand-written CSS of the mini-app library: the xyflow stylesheet and overrides of its generated classes. */
+@import "@xyflow/react/dist/style.css";
+
+.react-flow {
+    --xy-background-color: transparent;
+    --xy-edge-stroke: var(--muted-foreground);
+    --xy-edge-stroke-width: 1.5;
+    --xy-edge-label-color: var(--foreground);
+    --xy-edge-label-background-color: var(--background);
+    --xy-controls-button-background-color: var(--card);
+    --xy-controls-button-background-color-hover: var(--accent);
+    --xy-controls-button-color: var(--foreground);
+    --xy-controls-button-border-color: var(--border);
+}
+
+.react-flow__edge-text {
+    font: 16px var(--font-sans);
+}
+
+.react-flow__handle {
+    opacity: 0;
+    pointer-events: none;
+}

package/plugins/ragents.actor-programs/client-ui/form-contracts.d.ts

@@ -0,0 +1,38 @@
+import type { ReactElement } from "react";
+
+export type FormValue = string | number | boolean | null;
+export type FormValues = Readonly<Record<string, FormValue>>;
+export type FormErrors = Readonly<Record<string, string>>;
+
+interface FormFieldBase {
+  id: string;
+  label: string;
+  hint?: string;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+}
+
+export type FormField = FormFieldBase & (
+  | { type: "text"; placeholder?: string }
+  | { type: "textarea"; placeholder?: string; rows?: number }
+  | { type: "number"; min?: number; max?: number; step?: number; placeholder?: string }
+  | { type: "checkbox" }
+  | { type: "select"; options: readonly { value: string; label: string; hint?: string }[] }
+);
+
+export interface FormProps {
+  title?: string;
+  fields: readonly FormField[];
+  values: FormValues;
+  onChange: (values: FormValues, fieldId: string) => void;
+  /** Values stay controlled and are never reset after submission. */
+  onSubmit?: (values: FormValues) => void | Promise<void>;
+  /** Additional synchronous field errors, keyed by field ID. */
+  validate?: (values: FormValues) => FormErrors | undefined;
+  submitLabel?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+}
+
+export declare function Form(props: FormProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/frame-layout.ts

@@ -0,0 +1,4 @@
+/** Utilities of the mini-app frame document; they live here so the Tailwind scan of client-ui finds them. */
+export const FRAME_DOCUMENT_CLASS = "h-full overflow-hidden";
+export const FRAME_BODY_CLASS = "h-full overflow-hidden text-[13px]";
+export const FRAME_ROOT_CLASS = "relative block h-full w-full min-w-0 overflow-auto overscroll-contain p-workspace-inset";

package/plugins/ragents.actor-programs/client-ui/index.tsx

@@ -0,0 +1,81 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { cn } from "../../../apps/web/src/ui";
+import { ChatPanel } from "../../../apps/web/src/chat/ChatPanel";
+import { ChatMessages } from "../../../apps/web/src/chat/ChatMessages";
+import { ChatInputToolbar } from "../../../apps/web/src/chat/ChatInputToolbar";
+import { Markdown } from "../../../apps/web/src/chat/Markdown";
+import type { ActorChatProps, ChatAttachmentInput, ChatConnection, ChatInputProps, ChatProps, ControlledChatProps } from "./contracts";
+
+export * from "../../../apps/web/src/ui";
+export { FilePicker } from "./FilePicker";
+export { Form } from "./Form";
+export { AppLayout, Stack, Grid } from "./Layout";
+export { DataTable } from "./DataTable";
+export { TaskProgress, DocumentViewer, DiffViewer } from "./Viewers";
+export { MessageList } from "./MessageList";
+export { FlowDiagram } from "./FlowDiagram";
+export { WorkflowDiagram } from "./WorkflowDiagram";
+
+const appChat = (): ChatConnection => {
+  const bridge = (globalThis as typeof globalThis & { __ragentsAppContext?: { chat: ChatConnection } }).__ragentsAppContext;
+  if (!bridge) throw new Error("Die Host-Bridge der Actor-Ansicht fehlt.");
+  return bridge.chat;
+};
+
+const emptyMessages: never[] = [];
+
+const chatSurface = "flex h-full min-h-0 w-full min-w-0 flex-col text-foreground";
+
+function ChatInput({ onSend, placeholder, ...props }: ChatInputProps) {
+  return <ChatInputToolbar {...props} onSend={onSend} texts={placeholder === undefined ? undefined : {
+    placeholder,
+    steeringPlaceholder: placeholder,
+  }} />;
+}
+
+function ChatView({ title, showInput = true, onSend, placeholder, rows = 2, maxRows = 6,
+  className, error, disabled, attachmentCapabilities, attachmentCapabilitiesError, ...messages }: ControlledChatProps & { error?: string; disabled?: boolean }) {
+  return (
+    <section aria-label={title ?? "Chat"} className={cn(chatSurface, "[&_[data-chat=composer]]:px-3 [&_[data-chat=composer]]:pb-3", className)}>
+      {title && <h2 className="px-4 pt-3 pb-1 text-[14px] font-semibold">{title}</h2>}
+      {error && <p className="px-4 py-3 text-[13px] text-destructive" role="alert">{error}</p>}
+      <ChatPanel className="flex-1" composer={showInput && onSend ? <ChatInput
+        attachmentCapabilities={attachmentCapabilities}
+        attachmentCapabilitiesError={attachmentCapabilitiesError}
+        disabled={disabled}
+        maxRows={maxRows}
+        onSend={onSend}
+        placeholder={placeholder}
+        rows={rows}
+        running={messages.running}
+      /> : undefined}>
+        <ChatMessages {...messages} />
+      </ChatPanel>
+    </section>
+  );
+}
+
+function ActorChat({ actor, ...props }: ActorChatProps) {
+  const subscribe = useCallback((listener: () => void) => appChat().subscribe(actor, listener), [actor]);
+  const read = useCallback(() => appChat().read(actor), [actor]);
+  const snapshot = useSyncExternalStore(subscribe, read, read);
+  const send = useCallback((text: string, attachments?: ChatAttachmentInput[]) => appChat().send(actor, text, attachments), [actor]);
+  return <ChatView {...props}
+    showInput={props.showInput !== false && snapshot?.readOnly !== true}
+    attachmentCapabilities={snapshot?.attachmentCapabilities}
+    attachmentCapabilitiesError={snapshot?.attachmentCapabilitiesError}
+    disabled={snapshot === undefined || snapshot.error !== undefined || snapshot.readOnly === true}
+    emptyState={props.emptyState ?? (snapshot === undefined ? <p className="px-4 py-3 text-[13px] text-muted-foreground">Gespräch wird geladen ...</p> : undefined)}
+    error={snapshot?.error}
+    messages={snapshot?.messages ?? emptyMessages}
+    owner={props.owner === undefined ? snapshot?.owner : props.owner}
+    onSend={send}
+    running={snapshot?.running ?? false}
+  />;
+}
+
+function Chat(props: ChatProps) {
+  return props.actor !== undefined ? <ActorChat {...props} key={props.actor} /> : <ChatView {...props} />;
+}
+
+export { Chat, ChatMessages, ChatInput, Markdown };

package/plugins/ragents.actor-programs/client-ui/layout-contracts.d.ts

@@ -0,0 +1,33 @@
+import type { ReactElement, ReactNode } from "react";
+
+export type LayoutGap = "small" | "normal" | "large";
+
+export interface AppLayoutProps {
+  title?: string;
+  description?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+  /** Fill a height-constrained parent; only the content scrolls, header and actions stay visible. */
+  fill?: boolean;
+}
+
+export interface StackProps {
+  children: ReactNode;
+  gap?: LayoutGap;
+  /** Rows wrap automatically when their children no longer fit. */
+  direction?: "column" | "row";
+}
+
+export interface GridProps {
+  children: ReactNode;
+  /** Maximum columns; the available container width reduces them to two or one. */
+  columns?: 2 | 3;
+  gap?: LayoutGap;
+}
+
+/** App frame with shared typography, spacing, header, content and optional actions. */
+export declare function AppLayout(props: AppLayoutProps): ReactElement;
+/** Vertical content or a wrapping row with consistent spacing. */
+export declare function Stack(props: StackProps): ReactElement;
+/** Equal responsive columns based on the container width, including inside a canvas frame. */
+export declare function Grid(props: GridProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/message-list-contracts.d.ts

@@ -0,0 +1,33 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ChatAttachment } from "../../../apps/server/src/chat-events";
+
+export interface MessageListItem {
+  /** Stable key within this list. */
+  key: string;
+  /** Visible sender name; also determines the default bubble color. */
+  sender: string;
+  /** Message content as Markdown. */
+  text: string;
+  /** Optional ISO timestamp, shown when showTimestamps is enabled. */
+  at?: string;
+  attachments?: ChatAttachment[];
+  /** Optional CSS color overriding the stable sender color. */
+  color?: string;
+  /** Bubble alignment, default start. */
+  side?: "start" | "end";
+}
+
+export interface MessageListProps {
+  /** Displayed in the supplied order; new props update the view. */
+  messages: readonly MessageListItem[];
+  /** Sender name whose messages render without bubbles; omitted or null shows all sender bubbles. */
+  owner?: string | null;
+  showTimestamps?: boolean;
+  emptyState?: ReactNode;
+  className?: string;
+  /** Accessible name of the display, default Nachrichten. */
+  label?: string;
+}
+
+/** Read-only messages from named senders, with the shared chat renderer and automatic scrolling. */
+export declare function MessageList(props: MessageListProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/table-contracts.d.ts

@@ -0,0 +1,35 @@
+import type { ReactElement, ReactNode } from "react";
+
+export type TableValue = string | number | boolean | null | undefined;
+export interface TableColumn<Row> {
+  id: string;
+  label: string;
+  /** Primitive value used for sorting, filtering and default display. */
+  value: (row: Row) => TableValue;
+  render?: (row: Row) => ReactNode;
+  sortable?: boolean;
+  /** Searched when table filtering is enabled; defaults to true. */
+  filterable?: boolean;
+}
+export interface TableAction<Row> {
+  id: string;
+  label: string;
+  onClick: (row: Row) => void | Promise<void>;
+  disabled?: (row: Row) => boolean;
+}
+interface DataTableBaseProps<Row> {
+  title?: string;
+  rows: readonly Row[];
+  columns: readonly TableColumn<Row>[];
+  rowKey: (row: Row) => string;
+  filterable?: boolean;
+  actions?: readonly TableAction<Row>[];
+  loading?: boolean;
+  emptyText?: string;
+}
+export type DataTableProps<Row> = DataTableBaseProps<Row> & (
+  | { selectedKeys: readonly string[]; onSelectionChange: (keys: string[]) => void }
+  | { selectedKeys?: never; onSelectionChange?: never }
+);
+
+export declare function DataTable<Row>(props: DataTableProps<Row>): ReactElement;

package/plugins/ragents.actor-programs/client-ui/viewer-contracts.d.ts

@@ -0,0 +1,37 @@
+import type { ReactElement } from "react";
+
+export interface TaskItem {
+  id: string;
+  label: string;
+  status: "pending" | "running" | "done" | "error" | "skipped";
+  description?: string;
+}
+
+export interface TaskProgressProps {
+  title?: string;
+  tasks: readonly TaskItem[];
+  showProgress?: boolean;
+}
+
+export interface DocumentViewerProps {
+  title?: string;
+  content: string;
+  format?: "text" | "markdown" | "code";
+  /** Sprache für Code-Hervorhebung; alternativ bestimmt filename die Sprache. */
+  language?: string;
+  filename?: string;
+}
+
+export interface DiffViewerProps {
+  title?: string;
+  /** Bereits vorliegender Unified-Diff; das Control vergleicht keine Dateien und schreibt nichts. */
+  patch: string;
+  emptyText?: string;
+  /** Sprache für Code-Hervorhebung; alternativ bestimmt filename oder der Pfad im Diff die Sprache. */
+  language?: string;
+  filename?: string;
+}
+
+export declare function TaskProgress(props: TaskProgressProps): ReactElement;
+export declare function DocumentViewer(props: DocumentViewerProps): ReactElement;
+export declare function DiffViewer(props: DiffViewerProps): ReactElement;

package/plugins/ragents.actor-programs/client-ui/workflow-diagram-contracts.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from "react";
+import type { WorkflowDefinition, WorkflowState } from "../workflow/index";
+import type { FlowDiagramProps } from "./flow-diagram-contracts";
+
+export interface WorkflowDiagramProps extends Omit<FlowDiagramProps, "nodes" | "edges"> {
+  definition: WorkflowDefinition;
+  state: WorkflowState;
+}
+
+export declare function WorkflowDiagram(props: WorkflowDiagramProps): ReactElement;

package/plugins/ragents.actor-programs/contract.ts

@@ -0,0 +1,180 @@
+import { Type } from "typebox";
+import { defineOperation } from "@aicontainer/ragents/src/rpc/contract";
+import { openJson } from "@aicontainer/ragents/src/http/contracts";
+
+export const ACTOR_PROGRAMS_STATE_ID = "ragents.actor-programs";
+export const ACTOR_INVOCATIONS_STATE_ID = "ragents.actor-programs.invocations";
+export const ACTOR_SCRIPT_STATE_ID = "ragents.actor-programs.script";
+export const ACTOR_STATE_ID = "ragents.actor-state";
+
+export interface ActorViewPlacement { kind: "canvas"; anchorActorId: string; width: number; height: number; }
+export interface ActorViewDefinition {
+  id: string;
+  key: string;
+  title: string;
+  visible: boolean;
+  placements: ActorViewPlacement[];
+  html: string;
+  styles: string;
+  clientFile: string;
+}
+export interface ActorFunctionDefinition {
+  id: string;
+  label: string;
+  description: string;
+  inputSchema: object;
+  resultSchema: object;
+  capabilityIds: string[];
+  capabilityContractHash: string;
+  confirmation: string | null;
+  tool?: { name: string; targets: string[] | null; card: boolean };
+}
+export interface ActorProgramDefinition {
+  name: string;
+  title: string;
+  description: string;
+  actorId: string;
+  actorHandle: string;
+  revision: string;
+  installedBy: string;
+  directory: string;
+  sourceDirectory: string;
+  backendFile?: string;
+  stateSchema: object;
+  stylesFile: string;
+  functions: ActorFunctionDefinition[];
+  input?: { capabilityIds: string[]; capabilityContractHash: string };
+  views: ActorViewDefinition[];
+}
+export interface ActorProgramState { version: 1; program: ActorProgramDefinition | null; }
+export interface ActorScriptState { version: 1; entryId: string; }
+
+export const resolveActorView = (programs: readonly ActorProgramDefinition[], reference: string) => {
+  const normalized = reference.trim().toLowerCase();
+  const views = programs.flatMap((program) => program.views.map((view) => ({ program, view })));
+  const named = views.filter(({ program, view }) => [view.id, `${program.name}/${view.key}`, `@${program.actorHandle}/${view.key}`]
+    .some((name) => name.toLowerCase() === normalized));
+  const matches = named.length > 0 ? named : views.filter(({ view }) => view.title.toLowerCase() === normalized);
+  const names = (entries: typeof views) => entries.map(({ program, view }) => `${program.name}/${view.key} (@${program.actorHandle}/${view.key})`).join(", ") || "keine";
+  if (matches.length === 0) {
+    throw new Error(`${reference} ist keine aktive Actor-Ansicht dieses Laufs. Zuerst das Programm aktivieren. Vorhanden: ${names(views)}`);
+  }
+  if (matches.length > 1) throw new Error(`${reference} ist mehrdeutig. Verwende einen eindeutigen Namen: ${names(matches)}`);
+  return matches[0]!;
+};
+
+export interface ActorDataState { version: 1; revision: number; values: Record<string, unknown>; }
+interface InvocationBase {
+  id: string;
+  requestId: string;
+  actorId: string;
+  actorHandle: string;
+  appId: string;
+  revision: string;
+  actionId: string;
+  input: unknown;
+  output: string[];
+  createdAt: string;
+}
+export type ActorFunctionInvocation = InvocationBase & (
+  | { status: "queued" }
+  | { status: "running"; startedAt: string }
+  | { status: "succeeded"; startedAt: string; finishedAt: string; result: unknown }
+  | { status: "failed" | "cancelled"; startedAt?: string; finishedAt: string; error: string }
+);
+export interface ActorViewListing {
+  id: string;
+  actorId: string;
+  actorHandle: string;
+  title: string;
+  description: string;
+  revision: string;
+  actions: { id: string; label: string; description: string; confirmation: string | null }[];
+  placements: ActorViewPlacement[];
+  visible: boolean;
+  state: ActorDataState;
+  invocations: ActorFunctionInvocation[];
+}
+
+export interface ActorLocalToolParameter {
+  name: string;
+  type: string;
+  description: string;
+  required: boolean;
+}
+
+export interface ActorLocalTool {
+  moduleId: string;
+  name: string;
+  description: string;
+  card: boolean;
+  actorId: string;
+  actorHandle: string;
+  functionId: string;
+  revision: string;
+  sourceHash: string;
+  installedBy: string;
+  parameters: ActorLocalToolParameter[];
+  targets: { actorId: string; handle: string | null }[];
+}
+
+const runId = Type.String({ pattern: "^[A-Za-z0-9_-]{1,64}$", description: "Kennung des Runs" });
+const viewId = Type.String({ pattern: "^[a-z][a-z0-9_-]{0,129}$", description: "Kennung der Actor-Ansicht oder des Programms" });
+const actorHandle = Type.String({ pattern: "^[a-z][a-z0-9-]{0,63}$", description: "Handle des Actors ohne @" });
+const functionId = Type.String({ pattern: "^[a-zA-Z][a-zA-Z0-9_-]{0,63}$", description: "Kennung der Funktion" });
+const invocationId = Type.String({ pattern: "^[A-Za-z0-9_-]{1,100}$", description: "Kennung des Funktionsaufrufs" });
+const revision = Type.String({ pattern: "^[a-f0-9]{64}$", description: "Revision des aktiven Actor-Pakets" });
+const requestId = Type.String({ minLength: 1, maxLength: 200, description: "Eigene Kennung des Aufrufers; wiederholte Aufrufe liefern denselben Aufruf" });
+const functionInput = Type.Unknown({ description: "Eingabe der Funktion nach ihrem eigenen Schema" });
+
+const invocationSchema = openJson<ActorFunctionInvocation>("ActorFunctionInvocation");
+
+export const actorProgramContracts = {
+  apps: defineOperation({
+    id: "ragents.actor-programs.apps",
+    description: "Die Actor-Ansichten eines Runs mit Zustand und Aufrufen; die Werkzeugliste bleibt ohne runs.inspect leer.",
+    rights: ["runs.read"],
+    input: Type.Object({ runId }, { additionalProperties: false }),
+    result: Type.Object({
+      apps: Type.Array(openJson<ActorViewListing>("ActorViewListing")),
+      tools: Type.Array(openJson<ActorLocalTool>("ActorLocalTool")),
+    }, { additionalProperties: false }),
+  }),
+  source: defineOperation({
+    id: "ragents.actor-programs.source",
+    description: "Den Quellcode eines Actor-Programms lesen.",
+    rights: ["runs.read", "runs.inspect"],
+    input: Type.Object({ runId, moduleId: viewId }, { additionalProperties: false }),
+    result: Type.Object({
+      files: Type.Array(Type.Object({ path: Type.String({ minLength: 1 }), content: Type.String() }, { additionalProperties: false })),
+    }, { additionalProperties: false }),
+  }),
+  action: defineOperation({
+    id: "ragents.actor-programs.action",
+    description: "Eine Funktion einer Actor-Ansicht starten; die Antwort ist der eingereihte Aufruf.",
+    rights: ["runs.read", "runs.write"],
+    input: Type.Object({ runId, appId: viewId, revision, actionId: functionId, requestId, input: functionInput }, { additionalProperties: false }),
+    result: invocationSchema,
+  }),
+  invocation: defineOperation({
+    id: "ragents.actor-programs.invocation",
+    description: "Den Stand eines Aufrufs einer Actor-Ansicht lesen.",
+    rights: ["runs.read"],
+    input: Type.Object({ runId, appId: viewId, invocationId }, { additionalProperties: false }),
+    result: invocationSchema,
+  }),
+  function: defineOperation({
+    id: "ragents.actor-programs.function",
+    description: "Eine Funktion eines Actors unabhängig von seinen Ansichten starten.",
+    rights: ["runs.read", "runs.write", "runs.inspect"],
+    input: Type.Object({ runId, actorHandle, revision, functionId, requestId, input: functionInput }, { additionalProperties: false }),
+    result: invocationSchema,
+  }),
+  functionInvocation: defineOperation({
+    id: "ragents.actor-programs.function-invocation",
+    description: "Den Stand eines Aufrufs einer Actor-Funktion lesen.",
+    rights: ["runs.read", "runs.inspect"],
+    input: Type.Object({ runId, actorHandle, invocationId }, { additionalProperties: false }),
+    result: invocationSchema,
+  }),
+} as const;

package/plugins/ragents.actor-programs/parameter-types.ts

@@ -0,0 +1,3 @@
+export const actorFunctionParameterTypes = ["string", "number", "integer", "boolean", "string[]", "number[]", "json"] as const;
+
+export type ActorFunctionParameterType = typeof actorFunctionParameterTypes[number];