@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/web/FunctionForm.tsx

@@ -0,0 +1,102 @@
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { useAccess } from "@aicontainer/web/AccessContext";
+import { Button, cn, Input, Textarea } from "@aicontainer/web/ui";
+import type { SessionContext } from "@aicontainer/web/PluginRegistry";
+import type { RunAppInvocation, RunScriptTool } from "./api";
+import { HostConfirmation, pendingConfirmationFor, useActorPrograms } from "./AppsPanel";
+import { invokeActorFunction } from "./function-call";
+import { actorFunctionInput } from "./function-input";
+
+const selectClass = "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base font-normal md:text-sm";
+
+export function FunctionForm({ session, tool, detail = false }: {
+  session: SessionContext;
+  tool: RunScriptTool;
+  detail?: boolean;
+}) {
+  const writable = useAccess().can("runs.write");
+  const { api, refresh, runId } = useActorPrograms();
+  const [error, setError] = useState<string>();
+  const [busy, setBusy] = useState(false);
+  const [invocation, setInvocation] = useState<RunAppInvocation>();
+  const controllerRef = useRef<AbortController | undefined>(undefined);
+  useEffect(() => () => controllerRef.current?.abort(), []);
+  const confirmation = invocation ? pendingConfirmationFor(session, { invocations: [invocation] }) : undefined;
+
+  const submit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (controllerRef.current || !writable) return;
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    setError(undefined);
+    setInvocation(undefined);
+    try {
+      const input = actorFunctionInput(tool.parameters, new FormData(event.currentTarget));
+      setBusy(true);
+      await invokeActorFunction(api, runId, tool, input, controller.signal, (current) => {
+        if (!controller.signal.aborted) setInvocation(current);
+      });
+      if (!controller.signal.aborted) await refresh();
+    } catch (caught) {
+      if (!controller.signal.aborted) setError(caught instanceof Error ? caught.message : String(caught));
+    } finally {
+      if (!controller.signal.aborted) setBusy(false);
+      if (controllerRef.current === controller) controllerRef.current = undefined;
+    }
+  };
+
+  const status = confirmation ? "Bestätigung erforderlich"
+    : invocation?.status === "queued" ? "Wartet auf Ausführung"
+      : invocation?.status === "running" ? "Funktion läuft"
+        : invocation?.status === "succeeded" ? "Ausgeführt"
+          : invocation?.status === "cancelled" ? "Abgebrochen"
+            : invocation?.status === "failed" ? "Fehlgeschlagen"
+              : busy ? "Aufruf wird gesendet" : undefined;
+  const failure = error ?? (invocation?.status === "failed" || invocation?.status === "cancelled" ? invocation.error : undefined);
+
+  return (
+    <div className="grid min-w-0 gap-2.5">
+      <form aria-label={`${tool.name} aufrufen`} className={cn("grid", detail ? "gap-3.5" : "gap-2")} onSubmit={(event) => void submit(event)}>
+        {tool.parameters.length === 0 && detail && <p>Diese Funktion benötigt keine Parameter.</p>}
+        {tool.parameters.map((parameter) => (
+          <label className={cn("grid gap-[3px] font-[650] text-foreground [&_small]:text-[0.61rem] [&_small]:font-normal [&_small]:text-muted-foreground",
+            detail ? "text-[0.8rem]" : "text-[0.68rem]",
+            parameter.type === "boolean" && parameter.required && "grid-cols-[auto_minmax(0,1fr)] items-center gap-x-1.5 [&_small]:col-start-2")} key={parameter.name}>
+            {parameter.type === "boolean" && parameter.required && <input aria-description={parameter.description} className="m-0 accent-primary" disabled={!writable || busy} name={parameter.name} type="checkbox" />}
+            <span>{parameter.name}{parameter.required ? " *" : ""}{detail && <small className="ml-2">{parameter.type}{parameter.required ? "" : " (optional)"}</small>}</span>
+            {parameter.type === "boolean"
+              ? !parameter.required && <select className={selectClass} disabled={!writable || busy} name={parameter.name} defaultValue=""><option value="">Nicht übergeben</option><option value="true">Ja</option><option value="false">Nein</option></select>
+              : parameter.type === "json" || parameter.type === "string[]" || parameter.type === "number[]" || detail && parameter.type === "string"
+                ? <Textarea aria-description={parameter.description} className="min-h-8 resize-y font-normal" disabled={!writable || busy} name={parameter.name} placeholder={parameter.description} required={parameter.required} rows={2} />
+                : <Input
+                    aria-description={parameter.description}
+                    className="font-normal"
+                    disabled={!writable || busy}
+                    name={parameter.name}
+                    placeholder={parameter.description}
+                    required={parameter.required}
+                    step={parameter.type === "integer" ? "1" : parameter.type === "number" ? "any" : undefined}
+                    type={parameter.type === "integer" || parameter.type === "number" ? "number" : "text"}
+                  />}
+            {(detail || parameter.type === "boolean") && <small>{parameter.description}</small>}
+            {parameter.type === "json" && <small>Als JSON eingeben.</small>}
+            {parameter.type === "number[]" && <small>Als JSON-Liste eingeben, z. B. [1, 2, 3].</small>}
+            {parameter.type === "string[]" && <small>Ein Eintrag pro Zeile oder als JSON-Liste.</small>}
+          </label>
+        ))}
+        <div className="flex flex-wrap items-center gap-2">
+          <Button disabled={!writable || busy} type="submit">{busy ? "Wird ausgeführt ..." : "Ausführen"}</Button>
+          {status && <span className="text-[0.63rem] text-muted-foreground" role="status">{status}</span>}
+        </div>
+      </form>
+      {confirmation && <HostConfirmation action={confirmation} key={confirmation.id} session={session} />}
+      {failure && <p className="text-destructive [overflow-wrap:anywhere]" role="alert">{failure}</p>}
+      {invocation?.status === "succeeded" && !error && (
+        <section aria-label="Ergebnis" className="grid min-w-0 gap-2">
+          <h3>Ergebnis</h3>
+          <pre className="max-h-[320px] overflow-auto rounded-md border border-border-soft bg-card p-2.5 text-[0.75rem] whitespace-pre-wrap text-foreground [overflow-wrap:anywhere]">{typeof invocation.result === "string" ? invocation.result : JSON.stringify(invocation.result, null, 2)}</pre>
+        </section>
+      )}
+    </div>
+  );
+}

package/plugins/ragents.actor-programs/web/ProgramSource.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useState } from "react";
+import { SourceCode } from "@aicontainer/web/SourceCode";
+import { Alert, Button, cn, Spinner } from "@aicontainer/web/ui";
+import type { ActorProgramSourceFile, ActorProgramsApi } from "./api";
+
+type SourceState =
+  | { kind: "loading" }
+  | { kind: "ready"; files: ActorProgramSourceFile[] }
+  | { kind: "error"; message: string };
+
+export function ProgramSource({ api, moduleId, runId, revision, expandedByDefault = false }: {
+  api: ActorProgramsApi;
+  moduleId: string;
+  runId: string;
+  revision?: string;
+  expandedByDefault?: boolean;
+}) {
+  const [expanded, setExpanded] = useState(expandedByDefault);
+  const [state, setState] = useState<SourceState>({ kind: "loading" });
+  const [activePath, setActivePath] = useState<string>();
+
+  useEffect(() => {
+    if (!expanded) return undefined;
+    const controller = new AbortController();
+    setState({ kind: "loading" });
+    api.source(runId, moduleId, controller.signal).then(
+      (files) => {
+        if (controller.signal.aborted) return;
+        setState({ kind: "ready", files });
+        setActivePath(files.find((file) => file.path === "src/server.ts")?.path ?? files.find((file) => /\.tsx?$/.test(file.path))?.path ?? files[0]?.path);
+      },
+      (caught: unknown) => {
+        if (controller.signal.aborted) return;
+        setState({ kind: "error", message: caught instanceof Error ? caught.message : String(caught) });
+      },
+    );
+    return () => controller.abort();
+  }, [api, expanded, moduleId, runId, revision]);
+
+  const active = state.kind === "ready"
+    ? state.files.find((file) => file.path === activePath) ?? state.files[0]
+    : undefined;
+
+  return (
+    <section className="grid w-full min-w-0 grid-cols-[minmax(0,1fr)] justify-items-start gap-2">
+      <h3 className="text-xs font-semibold text-muted-foreground">Quellcode</h3>
+      {!expanded && (
+        <Button onClick={() => setExpanded(true)} size="sm" variant="outline">Quellcode anzeigen</Button>
+      )}
+      {expanded && (
+        <>
+          <p className="text-[0.67rem] text-muted-foreground">Quelle des installierten Builds</p>
+          {state.kind === "loading" && (
+            <p className="flex items-center gap-2 text-[0.72rem] text-muted-foreground">
+              <Spinner aria-hidden aria-label={undefined} role={undefined} />
+              <span>Quellcode wird geladen</span>
+            </p>
+          )}
+          {state.kind === "error" && <Alert className="w-full" variant="destructive">{state.message}</Alert>}
+          {state.kind === "ready" && (
+            <div className="flex flex-wrap gap-1.5">
+              {state.files.map((file) => (
+                <button
+                  className={cn("max-w-full cursor-pointer rounded-lg border border-border-soft bg-background/70 px-[9px] py-1 text-left font-mono text-[0.66rem] text-muted-foreground [overflow-wrap:anywhere]",
+                    file.path === active?.path && "border-[color-mix(in_srgb,var(--primary)_48%,var(--border))] bg-primary/9 text-foreground")}
+                  key={file.path}
+                  onClick={() => setActivePath(file.path)}
+                  type="button"
+                >
+                  {file.path}
+                </button>
+              ))}
+            </div>
+          )}
+          {active && <SourceCode className="h-full max-h-[340px] w-full min-h-0 min-w-0 overflow-auto rounded-lg border border-border-soft bg-background/70" content={active.content} path={active.path} />}
+          {!expandedByDefault && <Button onClick={() => setExpanded(false)} size="sm" variant="outline">Quellcode ausblenden</Button>}
+        </>
+      )}
+    </section>
+  );
+}

package/plugins/ragents.actor-programs/web/api.ts

@@ -0,0 +1,353 @@
+import { isRecord } from "@aicontainer/web/lib/guards";
+import { rpc } from "@aicontainer/web/rpc";
+import { withAccessToken } from "@aicontainer/web/access-token";
+import { actorProgramContracts } from "../contract";
+import {
+  actorFunctionParameterTypes,
+  type ActorFunctionParameterType,
+} from "../parameter-types";
+import { isJsonValue, type JsonValue } from "./bridge";
+
+export type RunAppInvocationStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+
+export interface RunAppAction {
+  id: string;
+  label: string;
+  description?: string;
+  confirmation: string | null;
+}
+
+export type RunAppPlacement = { kind: "canvas"; anchorActorId: string; width: number; height: number };
+
+export type RunAppInvocation = {
+  id: string;
+  actorId: string;
+  actorHandle: string;
+  appId: string;
+  actionId: string;
+  revision: string;
+  output: string[];
+  createdAt: string;
+  requestId: string;
+} & (
+  | { status: "queued" }
+  | { status: "running"; startedAt: string }
+  | { status: "succeeded"; startedAt: string; finishedAt: string; result: JsonValue }
+  | { status: "failed" | "cancelled"; startedAt?: string; finishedAt: string; error: string }
+);
+
+export interface RunApp {
+  id: string;
+  actorId: string;
+  actorHandle: string;
+  visible?: boolean;
+  title: string;
+  description?: string;
+  revision: string;
+  actions: RunAppAction[];
+  placements: RunAppPlacement[];
+  state: { version: 1; revision: number; values: JsonValue };
+  invocations: RunAppInvocation[];
+}
+
+export interface RunToolParameter {
+  name: string;
+  description: string;
+  type: ActorFunctionParameterType;
+  required: boolean;
+}
+
+export interface RunToolTarget {
+  actorId: string;
+  handle: string | null;
+}
+
+export interface RunScriptTool {
+  actorId: string;
+  actorHandle: string;
+  functionId: string;
+  revision: string;
+  moduleId: string;
+  name: string;
+  description: string;
+  parameters: RunToolParameter[];
+  card: boolean;
+  sourceHash: string;
+  targets: RunToolTarget[];
+  installedBy: string;
+}
+
+export interface ActorProgramSourceFile {
+  path: string;
+  content: string;
+}
+
+export interface ActorProgramsListing {
+  apps: RunApp[];
+  tools: RunScriptTool[];
+}
+
+export interface ActorProgramsApi {
+  list: (runId: string, signal?: AbortSignal) => Promise<ActorProgramsListing>;
+  source: (runId: string, moduleId: string, signal?: AbortSignal) => Promise<ActorProgramSourceFile[]>;
+  frameUrl: (runId: string, appId: string, revision: string) => string;
+  invoke: (
+    runId: string,
+    appId: string,
+    revision: string,
+    actionId: string,
+    requestId: string,
+    input: JsonValue,
+    signal?: AbortSignal,
+  ) => Promise<RunAppInvocation>;
+  invocation: (runId: string, appId: string, invocationId: string, signal?: AbortSignal) => Promise<RunAppInvocation>;
+  invokeFunction: (runId: string, actorHandle: string, revision: string, functionId: string, requestId: string, input: JsonValue, signal?: AbortSignal) => Promise<RunAppInvocation>;
+  functionInvocation: (runId: string, actorHandle: string, invocationId: string, signal?: AbortSignal) => Promise<RunAppInvocation>;
+}
+
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,100}$/;
+const VIEW_ID_PATTERN = /^[A-Za-z0-9_-]{1,130}$/;
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+const PARAMETER_TYPES = new Set<RunToolParameter["type"]>(actorFunctionParameterTypes);
+
+const requiredString = (value: unknown, field: string): string => {
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${field} fehlt oder ist leer`);
+  return value;
+};
+
+const optionalString = (value: unknown, field: string): string | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") throw new Error(`${field} ist kein Text`);
+  return value;
+};
+
+const idFrom = (value: unknown, field: string): string => {
+  const id = requiredString(value, field);
+  if (!ID_PATTERN.test(id)) throw new Error(`${field} ist keine gültige Kennung`);
+  return id;
+};
+
+const unique = <T,>(values: T[], keyOf: (value: T) => string, label: string): T[] => {
+  const ids = values.map(keyOf);
+  if (new Set(ids).size !== ids.length) throw new Error(`${label} enthält doppelte Kennungen`);
+  return values;
+};
+
+export const runAppActionFrom = (value: unknown): RunAppAction => {
+  if (!isRecord(value)) throw new Error("Eine App-Aktion ist kein Objekt");
+  if (value.confirmation !== null && typeof value.confirmation !== "string") {
+    throw new Error("confirmation einer App-Aktion muss Text oder null sein");
+  }
+  if (typeof value.confirmation === "string" && !value.confirmation.trim()) {
+    throw new Error("confirmation einer App-Aktion darf nicht leer sein");
+  }
+  return {
+    id: idFrom(value.id, "action.id"),
+    label: requiredString(value.label, "action.label"),
+    ...(value.description !== undefined
+      ? { description: optionalString(value.description, "action.description") as string }
+      : {}),
+    confirmation: value.confirmation,
+  };
+};
+
+export const runAppInvocationFrom = (value: unknown): RunAppInvocation => {
+  if (!isRecord(value)) throw new Error("Eine App-Ausführung ist kein Objekt");
+  if (!Array.isArray(value.output) || value.output.some((line) => typeof line !== "string")) {
+    throw new Error("output einer App-Ausführung ist keine Textliste");
+  }
+  const base = {
+    id: idFrom(value.id, "invocation.id"),
+    actorId: requiredString(value.actorId, "invocation.actorId"),
+    actorHandle: requiredString(value.actorHandle, "invocation.actorHandle"),
+    appId: requiredString(value.appId, "invocation.appId"),
+    actionId: idFrom(value.actionId, "invocation.actionId"),
+    revision: requiredString(value.revision, "invocation.revision"),
+    output: value.output as string[],
+    createdAt: requiredString(value.createdAt, "invocation.createdAt"),
+    requestId: idFrom(value.requestId, "invocation.requestId"),
+  };
+  switch (value.status) {
+    case "queued":
+      return { ...base, status: "queued" };
+    case "running":
+      return { ...base, status: "running", startedAt: requiredString(value.startedAt, "invocation.startedAt") };
+    case "succeeded": {
+      if (!isJsonValue(value.result)) throw new Error("result einer App-Ausführung ist kein JSON-Wert");
+      return {
+        ...base,
+        status: "succeeded",
+        startedAt: requiredString(value.startedAt, "invocation.startedAt"),
+        finishedAt: requiredString(value.finishedAt, "invocation.finishedAt"),
+        result: value.result,
+      };
+    }
+    case "failed":
+    case "cancelled":
+      return {
+        ...base,
+        status: value.status,
+        ...(value.startedAt !== undefined
+          ? { startedAt: requiredString(value.startedAt, "invocation.startedAt") }
+          : {}),
+        finishedAt: requiredString(value.finishedAt, "invocation.finishedAt"),
+        error: requiredString(value.error, "invocation.error"),
+      };
+    default:
+      throw new Error("status einer App-Ausführung ist ungültig");
+  }
+};
+
+const boundedInteger = (value: unknown, field: string, minimum: number, maximum: number): number => {
+  if (!Number.isInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new Error(`${field} liegt außerhalb des gültigen Bereichs`);
+  }
+  return value as number;
+};
+
+const runAppPlacementFrom = (value: unknown): RunAppPlacement => {
+  if (!isRecord(value)) throw new Error("Eine App-Platzierung ist kein Objekt");
+  if (value.kind === "canvas") {
+    return {
+      kind: "canvas",
+      anchorActorId: requiredString(value.anchorActorId, "placement.anchorActorId"),
+      width: boundedInteger(value.width, "placement.width", 280, 960),
+      height: boundedInteger(value.height, "placement.height", 180, 720),
+    };
+  }
+  throw new Error("kind einer App-Platzierung muss canvas sein");
+};
+
+export const runAppFrom = (value: unknown): RunApp => {
+  if (!isRecord(value)) throw new Error("Eine App ist kein Objekt");
+  if (!Array.isArray(value.actions)) throw new Error("actions einer App ist keine Liste");
+  if (!Array.isArray(value.invocations)) throw new Error("invocations einer App ist keine Liste");
+  const rawPlacements = value.placements ?? [];
+  if (!Array.isArray(rawPlacements)) throw new Error("placements einer App ist keine Liste");
+  if (!isRecord(value.state) || value.state.version !== 1 || !Number.isSafeInteger(value.state.revision) || !isJsonValue(value.state.values)) throw new Error("state einer Ansicht entspricht nicht dem Zustandvertrag");
+  const actions = unique(value.actions.map(runAppActionFrom), (action) => action.id, "actions");
+  const invocations = unique(
+    value.invocations.map(runAppInvocationFrom),
+    (invocation) => invocation.id,
+    "invocations",
+  );
+  const actionIds = new Set(actions.map((action) => action.id));
+  if (invocations.some((invocation) => !actionIds.has(invocation.actionId))) {
+    throw new Error("Eine App-Ausführung verweist auf eine unbekannte Aktion");
+  }
+  if (value.visible !== undefined && typeof value.visible !== "boolean") throw new Error("visible einer App ist kein Wahrheitswert");
+  if (rawPlacements.length > 1) throw new Error("placements einer App enthält mehr als eine Platzierung");
+  const placements = rawPlacements.map(runAppPlacementFrom);
+  const id = requiredString(value.id, "view.id");
+  if (!VIEW_ID_PATTERN.test(id)) throw new Error("view.id ist keine gültige Kennung");
+  const actorId = requiredString(value.actorId, "view.actorId");
+  if (placements.some((placement) => placement.anchorActorId !== actorId)) throw new Error("Die Ansicht muss bei ihrem eigenen Actor platziert sein");
+  return {
+    id,
+    actorId,
+    actorHandle: requiredString(value.actorHandle, "view.actorHandle"),
+    visible: value.visible !== false,
+    title: requiredString(value.title, "app.title"),
+    ...(value.description !== undefined
+      ? { description: optionalString(value.description, "app.description") as string }
+      : {}),
+    revision: requiredString(value.revision, "app.revision"),
+    actions,
+    placements,
+    state: { version: 1, revision: value.state.revision as number, values: value.state.values },
+    invocations,
+  };
+};
+
+const runToolParameterFrom = (value: unknown): RunToolParameter => {
+  if (!isRecord(value)) throw new Error("Ein Werkzeugparameter ist kein Objekt");
+  if (typeof value.type !== "string" || !PARAMETER_TYPES.has(value.type as RunToolParameter["type"])) {
+    throw new Error("type eines Werkzeugparameters ist ungültig");
+  }
+  if (typeof value.required !== "boolean") throw new Error("required eines Werkzeugparameters ist kein Wahrheitswert");
+  return {
+    name: idFrom(value.name, "parameter.name"),
+    description: requiredString(value.description, "parameter.description"),
+    type: value.type as RunToolParameter["type"],
+    required: value.required,
+  };
+};
+
+const runToolTargetFrom = (value: unknown): RunToolTarget => {
+  if (!isRecord(value)) throw new Error("Ein Werkzeugziel ist kein Objekt");
+  if (value.handle !== null && typeof value.handle !== "string") {
+    throw new Error("handle eines Werkzeugziels muss Text oder null sein");
+  }
+  return {
+    actorId: requiredString(value.actorId, "target.actorId"),
+    handle: value.handle,
+  };
+};
+
+export const runScriptToolFrom = (value: unknown): RunScriptTool => {
+  if (!isRecord(value)) throw new Error("Ein Script-Werkzeug ist kein Objekt");
+  if (!Array.isArray(value.parameters)) throw new Error("parameters eines Script-Werkzeugs ist keine Liste");
+  if (!Array.isArray(value.targets)) throw new Error("targets eines Script-Werkzeugs ist keine Liste");
+  const sourceHash = requiredString(value.sourceHash, "tool.sourceHash");
+  if (!HASH_PATTERN.test(sourceHash)) throw new Error("sourceHash eines Script-Werkzeugs ist ungültig");
+  return {
+    actorId: requiredString(value.actorId, "tool.actorId"),
+    actorHandle: requiredString(value.actorHandle, "tool.actorHandle"),
+    functionId: idFrom(value.functionId, "tool.functionId"),
+    revision: requiredString(value.revision, "tool.revision"),
+    moduleId: idFrom(value.moduleId, "tool.moduleId"),
+    name: idFrom(value.name, "tool.name"),
+    description: requiredString(value.description, "tool.description"),
+    parameters: unique(value.parameters.map(runToolParameterFrom), (parameter) => parameter.name, "parameters"),
+    card: value.card === true,
+    sourceHash,
+    targets: unique(value.targets.map(runToolTargetFrom), (target) => target.actorId, "targets"),
+    installedBy: requiredString(value.installedBy, "tool.installedBy"),
+  };
+};
+
+const actorProgramSourceFileFrom = (value: unknown): ActorProgramSourceFile => {
+  if (!isRecord(value)) throw new Error("Eine Quelldatei ist kein Objekt");
+  if (typeof value.content !== "string") throw new Error("content einer Quelldatei ist kein Text");
+  return {
+    path: requiredString(value.path, "source.path"),
+    content: value.content,
+  };
+};
+
+export const actorProgramSourceFrom = (value: unknown): ActorProgramSourceFile[] => {
+  if (!isRecord(value) || !Array.isArray(value.files)) throw new Error("Die Quellenliste entspricht nicht dem Vertrag");
+  return unique(value.files.map(actorProgramSourceFileFrom), (file) => file.path, "files");
+};
+
+export const actorProgramsListingFrom = (value: unknown): ActorProgramsListing => {
+  if (!isRecord(value) || !Array.isArray(value.apps) || !Array.isArray(value.tools)) {
+    throw new Error("Die Run-Modul-Liste entspricht nicht dem Vertrag");
+  }
+  return {
+    apps: unique(value.apps.map(runAppFrom), (app) => app.id, "apps"),
+    tools: unique(value.tools.map(runScriptToolFrom), (tool) => tool.name, "tools"),
+  };
+};
+
+const segment = (value: string): string => encodeURIComponent(value);
+
+const frameBase = (routePrefix: string, runId: string): string =>
+  `${routePrefix}/runs/${segment(runId)}/apps`;
+
+export const createActorProgramsApi = (routePrefix: string): ActorProgramsApi => ({
+  list: async (runId, signal) =>
+    actorProgramsListingFrom(await rpc.call(actorProgramContracts.apps, { runId }, { signal })),
+  source: async (runId, moduleId, signal) =>
+    actorProgramSourceFrom(await rpc.call(actorProgramContracts.source, { runId, moduleId }, { signal })),
+  frameUrl: (runId, appId, revision) =>
+    withAccessToken(`${frameBase(routePrefix, runId)}/${segment(appId)}/frame?revision=${segment(revision)}`),
+  invoke: async (runId, appId, revision, actionId, requestId, input, signal) =>
+    runAppInvocationFrom(await rpc.call(actorProgramContracts.action, { runId, appId, revision, actionId, requestId, input }, { signal })),
+  invocation: async (runId, appId, invocationId, signal) =>
+    runAppInvocationFrom(await rpc.call(actorProgramContracts.invocation, { runId, appId, invocationId }, { signal })),
+  invokeFunction: async (runId, actorHandle, revision, functionId, requestId, input, signal) =>
+    runAppInvocationFrom(await rpc.call(actorProgramContracts.function, { runId, actorHandle, revision, functionId, requestId, input }, { signal })),
+  functionInvocation: async (runId, actorHandle, invocationId, signal) =>
+    runAppInvocationFrom(await rpc.call(actorProgramContracts.functionInvocation, { runId, actorHandle, invocationId }, { signal })),
+});

package/plugins/ragents.actor-programs/web/bridge.ts

@@ -0,0 +1,122 @@
+import { isRecord } from "@aicontainer/web/lib/guards";
+import type { ChatAttachmentInput } from "@aicontainer/server/chat-events";
+import { parseChatAttachments } from "@aicontainer/server/chat-attachments";
+
+export const RUN_APP_BRIDGE_VERSION = 1;
+
+export const RUN_APP_FRAME_READY = "ragents.app.frame-ready";
+export const RUN_APP_CONNECTED = "ragents.app.connected";
+export const RUN_APP_READY = "ragents.app.ready";
+export const RUN_APP_THEME = "ragents.app.theme";
+export const RUN_APP_INVOKE = "ragents.app.invoke";
+export const RUN_APP_GET_STATE = "ragents.app.get-state";
+export const RUN_APP_STATE = "ragents.app.state";
+export const RUN_APP_INVOCATION = "ragents.app.invocation";
+export const RUN_APP_ERROR = "ragents.app.error";
+export const RUN_APP_CHAT_WATCH = "ragents.app.chat-watch";
+export const RUN_APP_CHAT_UNWATCH = "ragents.app.chat-unwatch";
+export const RUN_APP_CHAT_SEND = "ragents.app.chat-send";
+export const RUN_APP_CHAT_STATE = "ragents.app.chat-state";
+export const RUN_APP_CHAT_ACK = "ragents.app.chat-ack";
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+export interface RunAppInvokeRequest {
+  type: typeof RUN_APP_INVOKE;
+  version: typeof RUN_APP_BRIDGE_VERSION;
+  requestId: string;
+  actionId: string;
+  input: JsonValue;
+}
+
+export interface RunAppGetStateRequest {
+  type: typeof RUN_APP_GET_STATE;
+  version: typeof RUN_APP_BRIDGE_VERSION;
+  requestId: string;
+}
+
+export type RunAppChatRequest = {
+  version: typeof RUN_APP_BRIDGE_VERSION;
+  requestId: string;
+  actor: string;
+} & (
+  | { type: typeof RUN_APP_CHAT_WATCH }
+  | { type: typeof RUN_APP_CHAT_UNWATCH }
+  | { type: typeof RUN_APP_CHAT_SEND; text: string; attachments?: ChatAttachmentInput[] }
+);
+
+export type RunAppBridgeRequest = RunAppInvokeRequest | RunAppGetStateRequest | RunAppChatRequest;
+
+export type RunAppBridgeValidation =
+  | { ok: true; request: RunAppBridgeRequest }
+  | { ok: false; requestId?: string; error: string };
+
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_INPUT_LENGTH = 64 * 1024;
+const MAX_DEPTH = 24;
+
+export const isJsonValue = (value: unknown, depth = 0): value is JsonValue => {
+  if (depth > MAX_DEPTH) return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((entry) => isJsonValue(entry, depth + 1));
+  if (!isRecord(value)) return false;
+  return Object.entries(value).every(([key, entry]) => key.length <= 256 && isJsonValue(entry, depth + 1));
+};
+
+const requestIdFrom = (value: unknown): string | undefined =>
+  typeof value === "string" && ID_PATTERN.test(value) ? value : undefined;
+
+const inputWithinLimit = (value: JsonValue): boolean => {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength <= MAX_INPUT_LENGTH;
+  } catch {
+    return false;
+  }
+};
+
+export const validateRunAppBridgeRequest = (value: unknown): RunAppBridgeValidation => {
+  if (!isRecord(value)) return { ok: false, error: "Die App-Nachricht ist kein Objekt" };
+  const requestId = requestIdFrom(value.requestId);
+  if (!requestId) return { ok: false, error: "Die App-Nachricht enthält keine gültige requestId" };
+  if (value.version !== RUN_APP_BRIDGE_VERSION) {
+    return { ok: false, requestId, error: "Die App verwendet eine nicht unterstützte Bridge-Version" };
+  }
+  if (value.type === RUN_APP_GET_STATE) {
+    return { ok: true, request: { type: RUN_APP_GET_STATE, version: RUN_APP_BRIDGE_VERSION, requestId } };
+  }
+  if (value.type === RUN_APP_CHAT_WATCH || value.type === RUN_APP_CHAT_UNWATCH || value.type === RUN_APP_CHAT_SEND) {
+    if (typeof value.actor !== "string" || !/^@?[\p{L}\p{N}_-]{1,64}$/u.test(value.actor)) {
+      return { ok: false, requestId, error: "Das Chat-Ziel muss primary oder ein Actor-Handle wie @reviewer sein" };
+    }
+    const common = { version: RUN_APP_BRIDGE_VERSION, requestId, actor: value.actor } as const;
+    if (value.type !== RUN_APP_CHAT_SEND) return { ok: true, request: { ...common, type: value.type } };
+    let attachments: ChatAttachmentInput[];
+    try { attachments = parseChatAttachments(value.attachments); } catch (cause) {
+      return { ok: false, requestId, error: cause instanceof Error ? cause.message : String(cause) };
+    }
+    if (typeof value.text !== "string" || (!value.text.trim() && !attachments.length) || !inputWithinLimit(value.text)) {
+      return { ok: false, requestId, error: "Die Chat-Nachricht ist leer oder zu groß" };
+    }
+    return { ok: true, request: { ...common, type: RUN_APP_CHAT_SEND, text: value.text.trim(), ...(attachments.length ? { attachments } : {}) } };
+  }
+  if (value.type !== RUN_APP_INVOKE) {
+    return { ok: false, requestId, error: "Die App-Nachricht hat einen unbekannten Typ" };
+  }
+  if (typeof value.actionId !== "string" || !ID_PATTERN.test(value.actionId)) {
+    return { ok: false, requestId, error: "Die App-Nachricht enthält keine gültige actionId" };
+  }
+  if (!isJsonValue(value.input) || !inputWithinLimit(value.input)) {
+    return { ok: false, requestId, error: "Die Eingabe der App-Aktion ist kein gültiger JSON-Wert oder zu groß" };
+  }
+  return {
+    ok: true,
+    request: {
+      type: RUN_APP_INVOKE,
+      version: RUN_APP_BRIDGE_VERSION,
+      requestId,
+      actionId: value.actionId,
+      input: value.input,
+    },
+  };
+};