@schlenkr/ragents 0.1.0

package/apps/server/src/data-directory.ts

@@ -0,0 +1,42 @@
+import { lstat, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { ragentsDataRoot } from "@aicontainer/workspace-executor/src/tools.ts";
+
+export { ragentsDataRoot };
+
+export function defaultDataDirectory(profile: string, home = homedir()): string {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(profile)) throw new Error("PRODUCT_PROFILE muss ein einfacher Profilname sein.");
+  return path.join(ragentsDataRoot(home), profile);
+}
+
+async function physicalDirectory(directory: string): Promise<string> {
+  try {
+    return await realpath(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const entry = await lstat(directory).catch((cause: NodeJS.ErrnoException) => {
+      if (cause.code === "ENOENT") return undefined;
+      throw cause;
+    });
+    if (entry) throw error;
+    const parent = path.dirname(directory);
+    if (parent === directory) throw error;
+    return path.join(await physicalDirectory(parent), path.basename(directory));
+  }
+}
+
+export async function assertDataDirectoryIsolated(directory: string): Promise<void> {
+  const physical = await physicalDirectory(path.resolve(directory));
+  for (let current = physical; ; current = path.dirname(current)) {
+    for (const marker of [".git", "pnpm-workspace.yaml", "package.json"]) {
+      const filename = path.join(current, marker);
+      const entry = await lstat(filename).catch((error: NodeJS.ErrnoException) => {
+        if (error.code === "ENOENT") return undefined;
+        throw error;
+      });
+      if (entry) throw new Error(`DATA_DIR liegt innerhalb eines Projekts (${filename}). Wähle einen externen Datenordner, zum Beispiel ~/.local/share/ragents/<profil>.`);
+    }
+    if (path.dirname(current) === current) return;
+  }
+}

package/apps/server/src/external-access.ts

@@ -0,0 +1,40 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { config } from "./config.js";
+
+const stateFile = path.join(config.dataDir, "external-access.json");
+const LOCAL_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+let open = true;
+
+const hostOf = (req: IncomingMessage): string => {
+  const header = req.headers.host ?? "";
+  const bracketed = /^\[(.+)\]/.exec(header);
+  return (bracketed ? bracketed[1] : header.split(":")[0] ?? "").toLowerCase();
+};
+
+export const isLocalRequest = (req: IncomingMessage): boolean => LOCAL_HOSTS.has(hostOf(req));
+
+export const externalAccessOpen = (): boolean => open;
+
+export const loadExternalAccess = async (): Promise<void> => {
+  const raw = await readFile(stateFile, "utf8").catch(() => "");
+  if (!raw) return;
+  const parsed: unknown = JSON.parse(raw);
+  if (parsed && typeof parsed === "object" && typeof (parsed as { open?: unknown }).open === "boolean") {
+    open = (parsed as { open: boolean }).open;
+  }
+};
+
+export const setExternalAccess = async (value: boolean): Promise<void> => {
+  open = value;
+  await writeFile(stateFile, `${JSON.stringify({ open })}\n`, "utf8");
+};
+
+export const externalGate = (req: IncomingMessage, res: ServerResponse): boolean => {
+  if (open || isLocalRequest(req)) return false;
+  res.writeHead(503, { "Content-Type": "text/plain; charset=utf-8" });
+  res.end("Der Zugang von außen ist ausgeschaltet.\n");
+  return true;
+};

package/apps/server/src/help-files.ts

@@ -0,0 +1,63 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const contentTypes: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/plain; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".ts": "text/plain; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+};
+
+interface HelpResponse {
+  status: number;
+  headers: Record<string, string>;
+  body?: Buffer | string;
+}
+
+export async function readHelpResponse(url: URL, webDistDir: string, method = "GET"): Promise<HelpResponse | undefined> {
+  if (url.pathname !== "/help" && !url.pathname.startsWith("/help/")) return undefined;
+  if (method !== "GET" && method !== "HEAD") {
+    return { status: 405, headers: { Allow: "GET, HEAD" } };
+  }
+  if (url.pathname === "/help") {
+    return { status: 302, headers: { Location: `/help/${url.search}` } };
+  }
+
+  const notFound = (): HelpResponse => ({
+    status: 404,
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+    body: method === "HEAD" ? undefined : "Nicht gefunden",
+  });
+  let requested: string;
+  try {
+    requested = decodeURIComponent(url.pathname.slice("/help/".length)) || "index.html";
+  } catch {
+    return { status: 400, headers: {} };
+  }
+  const root = path.resolve(webDistDir, "help");
+  const file = path.resolve(root, requested);
+  if (!file.startsWith(`${root}${path.sep}`) || requested.includes("\0")) return notFound();
+
+  try {
+    const body = await readFile(file);
+    return {
+      status: 200,
+      headers: { "Content-Type": contentTypes[path.extname(file)] ?? "application/octet-stream" },
+      body: method === "HEAD" ? undefined : body,
+    };
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR", "EISDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) return notFound();
+    throw error;
+  }
+}

package/apps/server/src/host-resolution-hooks.mjs

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+const hostEntries = ["apps/server/src/main.ts", "apps/web/src/main.tsx"]
+  .map((entry) => pathToFileURL(path.join(repositoryRoot, entry)).href);
+
+const isBareSpecifier = (specifier) => !/^(\.{1,2}\/|\/|[a-z][a-z0-9+.-]*:)/i.test(specifier);
+
+const isResolutionFailure = (error) =>
+  typeof error === "object" && error !== null
+  && ["ERR_MODULE_NOT_FOUND", "ERR_PACKAGE_PATH_NOT_EXPORTED"].includes(String(error.code));
+
+// Reines JavaScript, weil Node diese Datei im Loader-Thread lädt und dort unter node_modules keine Typen entfernt.
+/** Bare imports of files outside the repository resolve through the host, so plugins need no own node_modules. */
+export const resolve = async (specifier, context, next) => {
+  try {
+    return await next(specifier, context);
+  } catch (error) {
+    if (!isBareSpecifier(specifier) || !isResolutionFailure(error) || hostEntries.includes(context.parentURL ?? "")) throw error;
+    for (const [index, parentURL] of hostEntries.entries()) {
+      try {
+        return await next(specifier, { ...context, parentURL });
+      } catch (retryError) {
+        if (index === hostEntries.length - 1 || !isResolutionFailure(retryError)) throw retryError;
+      }
+    }
+    throw error;
+  }
+};

package/apps/server/src/host-resolution.ts

@@ -0,0 +1,3 @@
+import { register } from "node:module";
+
+register("./host-resolution-hooks.mjs", import.meta.url);

package/apps/server/src/host-version.ts

@@ -0,0 +1,74 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const hostRoot = (): string => path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+export interface HostPackage {
+  readonly name: string;
+  readonly version: string;
+  readonly hostVersion: string;
+}
+
+/** Das npm-Paket @schlenkr/ragents trägt den Commit, aus dem es gebaut wurde; ein Checkout hat diese Datei nicht. */
+export const readHostPackage = (root: string = hostRoot()): HostPackage | undefined => {
+  const file = path.join(root, "package.json");
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) return undefined;
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as { name?: unknown; version?: unknown; ragents?: { hostVersion?: unknown } };
+  const hostVersion = parsed.ragents?.hostVersion;
+  if (hostVersion === undefined) return undefined;
+  if (typeof hostVersion !== "string" || !/^[0-9a-f]{40}$/.test(hostVersion)) {
+    throw new Error(`${file}: ragents.hostVersion muss ein vollständiger Git-Commit sein, nicht ${JSON.stringify(hostVersion)}`);
+  }
+  if (typeof parsed.name !== "string" || typeof parsed.version !== "string") throw new Error(`${file}: name und version fehlen`);
+  return { name: parsed.name, version: parsed.version, hostVersion };
+};
+
+/** Die Fassung des npm-Pakets: im Paket seine eigene, im Checkout die der Wurzel; eine Quelle für beide. */
+export const readPackageVersion = (root: string = hostRoot()): string => {
+  const file = path.join(root, "package.json");
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Paketfassung ist unbekannt: ${file} fehlt`);
+  const version = (JSON.parse(readFileSync(file, "utf8")) as { version?: unknown }).version;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+/.test(version)) {
+    throw new Error(`${file}: version ist die Fassung des Pakets und muss x.y.z sein, nicht ${JSON.stringify(version)}`);
+  }
+  return version;
+};
+
+const gitDirectoryOf = (root: string): string => {
+  const entry = path.join(root, ".git");
+  const stats = statSync(entry, { throwIfNoEntry: false });
+  if (!stats) throw new Error(`Die Host-Version ist unbekannt: ${entry} fehlt; der Host braucht einen Git-Checkout oder das Paket @schlenkr/ragents`);
+  if (stats.isDirectory()) return entry;
+  const pointer = /^gitdir:\s*(.+)\s*$/.exec(readFileSync(entry, "utf8"));
+  if (!pointer) throw new Error(`Die Host-Version ist unbekannt: ${entry} nennt kein gitdir`);
+  return path.resolve(root, pointer[1]!.trim());
+};
+
+const refFrom = (gitDirectory: string, ref: string): string | undefined => {
+  const direct = statSync(path.join(gitDirectory, ref), { throwIfNoEntry: false })?.isFile()
+    ? readFileSync(path.join(gitDirectory, ref), "utf8").trim() : undefined;
+  if (direct) return direct;
+  const packed = path.join(gitDirectory, "packed-refs");
+  if (!statSync(packed, { throwIfNoEntry: false })?.isFile()) return undefined;
+  const line = readFileSync(packed, "utf8").split("\n").find((entry) => entry.endsWith(` ${ref}`));
+  return line?.split(" ")[0];
+};
+
+/** Der Commit des laufenden Hosts: aus dem Paket @schlenkr/ragents, sonst aus dem Git-Checkout mit Worktrees und gepackten Refs. */
+export const readHostVersion = (root: string = hostRoot()): string => {
+  const packaged = readHostPackage(root);
+  if (packaged) return packaged.hostVersion;
+  const gitDirectory = gitDirectoryOf(root);
+  const head = readFileSync(path.join(gitDirectory, "HEAD"), "utf8").trim();
+  const ref = /^ref:\s*(.+)$/.exec(head)?.[1]?.trim();
+  if (!ref) {
+    if (/^[0-9a-f]{40}$/.test(head)) return head;
+    throw new Error(`Die Host-Version ist unbekannt: HEAD in ${gitDirectory} ist weder Ref noch Commit`);
+  }
+  const commonDirectory = statSync(path.join(gitDirectory, "commondir"), { throwIfNoEntry: false })?.isFile()
+    ? path.resolve(gitDirectory, readFileSync(path.join(gitDirectory, "commondir"), "utf8").trim()) : undefined;
+  const commit = refFrom(gitDirectory, ref) ?? (commonDirectory ? refFrom(commonDirectory, ref) : undefined);
+  if (!commit || !/^[0-9a-f]{40}$/.test(commit)) throw new Error(`Die Host-Version ist unbekannt: ${ref} in ${gitDirectory} zeigt auf keinen Commit`);
+  return commit;
+};

package/apps/server/src/layout.ts

@@ -0,0 +1,36 @@
+import path from "node:path";
+import { isPortableId } from "@aicontainer/ragents";
+import { config } from "./config.js";
+
+const portableId = (value: string, name: string) => {
+  if (!isPortableId(value)) throw new Error(`${name} must be a lowercase portable ID.`);
+
+  return value;
+};
+
+export const layout = {
+  runsDir: path.join(config.dataDir, "runs"),
+  artifactsDir: path.join(config.dataDir, "artifacts"),
+  sessionsDir: path.join(config.dataDir, "sessions"),
+  deleteIntentsDir: path.join(config.dataDir, "delete-intents"),
+  archiveDir: path.join(config.dataDir, "archive"),
+  recoveryDir: path.join(config.dataDir, "recovery"),
+  serverLog: path.join(config.dataDir, "logs/server.log"),
+
+  sessionDir: (id: string) => path.join(config.dataDir, "sessions", id),
+  chatDir: (id: string) => path.join(config.dataDir, "sessions", id, "chat"),
+  agentChatDir: (id: string, agentId: string) => path.join(
+    config.dataDir,
+    "sessions",
+    portableId(id, "Run ID"),
+    "chat",
+    portableId(agentId, "Actor ID"),
+  ),
+  deleteIntentFile: (id: string) => path.join(config.dataDir, "delete-intents", `${id}.json`),
+  archiveSessionDir: (id: string) => path.join(config.dataDir, "archive", id),
+  recoverySessionDir: (id: string) => path.join(config.dataDir, "recovery", id),
+} as const;
+
+export const SESSIONS_MODE = 0o711;
+export const SESSION_MODE = 0o711;
+export const ROOT_ONLY_MODE = 0o700;

package/apps/server/src/main.ts

@@ -0,0 +1,54 @@
+import "./host-resolution.js";
+import { configuredAnonymousUser, configuredUsers, loadConfigFile } from "./config-file.js";
+
+const startupFailure = (error: unknown): never => {
+  const message = error instanceof Error ? error.message : String(error);
+  if (error instanceof Error && error.constructor !== Error) console.error(error.stack ?? message);
+  console.error(`\nRAgents startet nicht: ${message}`);
+  process.exit(1);
+};
+
+/** Startmodi: --stdio (JSON-RPC über stdin und stdout, ohne --port kein HTTP), --port 0 (privater Port mit Ansage auf stdout), --port N. */
+const parseArguments = (argv: readonly string[]): { stdio: boolean; port: number | undefined } => {
+  let stdio = false;
+  let port: number | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--stdio") { stdio = true; continue; }
+    if (argument === "--port") {
+      const value = Number(argv[index + 1]);
+      if (!Number.isInteger(value) || value < 0 || value > 65535) throw new Error(`--port braucht eine ganze Zahl von 0 bis 65535, nicht ${argv[index + 1]}`);
+      port = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unbekanntes Argument: ${argument} (erlaubt: --stdio, --port <n>)`);
+  }
+  return { stdio, port };
+};
+
+try {
+  if (!process.env.PRODUCT_PROFILE) {
+    throw new Error(
+      "PRODUCT_PROFILE ist nicht gesetzt. scripts/start.sh <profil> setzt das Profil; "
+      + "für pnpm start vorher export PRODUCT_PROFILE=<profil>.",
+    );
+  }
+  const arguments_ = parseArguments(process.argv.slice(2));
+  if (arguments_.port !== undefined) process.env.PORT = String(arguments_.port);
+  if (arguments_.stdio) process.env.RAGENTS_STDIO = "1";
+  if (arguments_.stdio && arguments_.port === undefined) process.env.RAGENTS_NO_HTTP = "1";
+  await loadConfigFile();
+  const { assertServerPortAvailable, assertDataDirectoryIsolated } = await import("./startup.js");
+  const { config } = await import("./config.js");
+  if (config.port === 0) {
+    process.env.RAGENTS_ANNOUNCE = "1";
+    if (!process.env.ACCESS_TOKEN && !configuredUsers() && !configuredAnonymousUser()) process.env.ACCESS_TOKEN = globalThis.crypto.randomUUID().replaceAll("-", "");
+  } else if (process.env.RAGENTS_NO_HTTP !== "1") {
+    await assertServerPortAvailable(config.port);
+  }
+  await assertDataDirectoryIsolated(config.dataDir);
+  await import("./server.js");
+} catch (error) {
+  startupFailure(error);
+}

package/apps/server/src/plugin-support/actor-programs/capability-resolver.ts

@@ -0,0 +1,107 @@
+import {
+  runCapabilityBindingHash,
+  runCapabilityContractHash,
+  type Actor,
+  type RunFunction,
+  type RunCapabilityDescriptor,
+} from "@aicontainer/ragents";
+
+import type { OperationDescriptorPort } from "./operations.js";
+
+export interface ResolvedCapabilityBinding {
+  descriptors: readonly RunCapabilityDescriptor[];
+  descriptorContractHash: string;
+  bindingContractHash: string;
+}
+
+const descriptorOf = (capability: {
+  id: string;
+  label: string;
+  description: string;
+  schema: RunCapabilityDescriptor["schema"];
+  resultSchema: RunCapabilityDescriptor["resultSchema"];
+}): RunCapabilityDescriptor => ({
+  id: capability.id,
+  label: capability.label,
+  description: capability.description,
+  schema: capability.schema,
+  resultSchema: capability.resultSchema,
+});
+
+const selected = <T>(
+  available: readonly T[],
+  capabilityIds: readonly string[],
+  idOf: (value: T) => string,
+  unavailable: (id: string, names: string) => Error,
+): T[] => {
+  const byId = new Map(available.map((value) => [idOf(value), value]));
+  return capabilityIds.map((id) => {
+    const value = byId.get(id);
+    if (!value) throw unavailable(id, [...byId.keys()].sort().join(", ") || "keine");
+    return value;
+  });
+};
+
+export const operatorCapabilityBinding = (
+  actorId: string,
+  operations: readonly OperationDescriptorPort[],
+  capabilityIds: readonly string[],
+): ResolvedCapabilityBinding => {
+  const resolved = selected(
+    operations.filter((operation) => operation.operator !== "unavailable"),
+    capabilityIds,
+    (operation) => operation.id,
+    (id, names) => new Error(`Capability ${id} ist für den Bediener nicht verfügbar. Verfügbar sind: ${names}.`),
+  );
+  const descriptors = resolved.map(descriptorOf);
+  return {
+    descriptors,
+    descriptorContractHash: runCapabilityContractHash(descriptors),
+    bindingContractHash: runCapabilityBindingHash({
+      principal: { id: actorId, kind: "operator" },
+      capabilities: descriptors,
+      policies: resolved.map((operation) => ({ id: operation.id, policy: operation.operator })),
+    }),
+  };
+};
+
+export const agentCapabilityBinding = (
+  actor: Actor,
+  tools: readonly RunFunction[],
+  capabilityIds: readonly string[],
+  blockedNames: ReadonlySet<string>,
+): ResolvedCapabilityBinding => {
+  const resolved = selected(
+    tools.filter((tool) => !blockedNames.has(tool.name)),
+    capabilityIds,
+    (tool) => tool.name,
+    (id, names) => new Error(
+      `Capability ${id} ist für @${actor.handle} nicht verfügbar. Verfügbar sind: ${names}.`,
+    ),
+  );
+  const descriptors = resolved.map((tool) => descriptorOf({ ...tool, id: tool.name }));
+  return {
+    descriptors,
+    descriptorContractHash: runCapabilityContractHash(descriptors),
+    bindingContractHash: runCapabilityBindingHash({
+      principal: { id: actor.id, kind: actor.kind === "script" ? "script" : "agent", grants: actor.grants },
+      capabilities: descriptors,
+      policies: descriptors.map((descriptor) => ({ id: descriptor.id, policy: "agent" })),
+    }),
+  };
+};
+
+export const assertSharedDescriptorContract = (
+  handlerId: string,
+  bindings: readonly ResolvedCapabilityBinding[],
+): string => {
+  const hashes = new Set(bindings.map((binding) => binding.descriptorContractHash));
+  if (hashes.size !== 1) {
+    throw new Error(
+      `Handler ${handlerId} wird unter Identitäten mit unterschiedlichen Capability-Verträgen verwendet.`,
+    );
+  }
+  const hash = hashes.values().next().value;
+  if (!hash) throw new Error(`Handler ${handlerId} besitzt keine gebundene Oberfläche.`);
+  return hash;
+};

package/apps/server/src/plugin-support/actor-programs/limits.ts

@@ -0,0 +1,33 @@
+import { assertJsonValue, type JsonValue } from "@aicontainer/ragents";
+
+export const MAX_JSON_BYTES = 250_000;
+export const MAX_JSON_DEPTH = 24;
+export const MAX_JSON_KEY_LENGTH = 256;
+export const MAX_INVOCATIONS_STATE_BYTES = 8 * 1024 * 1024;
+
+export const jsonBytes = (value: unknown): number => Buffer.byteLength(JSON.stringify(value), "utf8");
+
+export const jsonValue = <T>(value: T, label: string): T & JsonValue => {
+  assertJsonValue(value, label);
+  const text = JSON.stringify(value);
+  if (Buffer.byteLength(text, "utf8") > MAX_JSON_BYTES)
+    throw new Error(`${label} ist größer als ${MAX_JSON_BYTES} Byte.`);
+  const pending: Array<{ value: unknown; depth: number }> = [{ value, depth: 0 }];
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    if (current.depth > MAX_JSON_DEPTH)
+      throw new Error(`${label} ist tiefer als ${MAX_JSON_DEPTH} Ebenen verschachtelt.`);
+    if (Array.isArray(current.value)) {
+      current.value.forEach((entry) => pending.push({ value: entry, depth: current.depth + 1 }));
+      continue;
+    }
+    if (current.value && typeof current.value === "object") {
+      Object.entries(current.value).forEach(([key, entry]) => {
+        if (key.length > MAX_JSON_KEY_LENGTH)
+          throw new Error(`${label} enthält einen Schlüssel mit mehr als ${MAX_JSON_KEY_LENGTH} Zeichen.`);
+        pending.push({ value: entry, depth: current.depth + 1 });
+      });
+    }
+  }
+  return value;
+};

package/apps/server/src/plugin-support/actor-programs/operations.ts

@@ -0,0 +1,19 @@
+import type { TSchema } from "typebox";
+import type { JsonValue, OperationContext } from "@aicontainer/ragents";
+
+export interface OperationDescriptorPort {
+  id: string;
+  label: string;
+  description: string;
+  schema: TSchema;
+  resultSchema: TSchema;
+  operator: "unavailable" | "direct" | "confirm";
+}
+
+export type OperationInvocationPort = OperationContext;
+
+export interface ActorOperationPort {
+  operation: (id: string) => OperationDescriptorPort | undefined;
+  invoke: (id: string, context: OperationInvocationPort, input: JsonValue) => Promise<JsonValue>;
+  list: () => readonly OperationDescriptorPort[];
+}

package/apps/server/src/plugin-support/actor-programs/service.ts

@@ -0,0 +1,16 @@
+import { serviceToken, type ActorProgramExecutor, type CommandContext } from "@aicontainer/ragents";
+export interface ActorProgramSource {
+    path: string;
+    content: string;
+}
+export interface ActivatedActorProgram {
+    name: string;
+    actorId: string;
+    actorHandle: string;
+    views: number;
+}
+export interface ActorProgramsService extends ActorProgramExecutor {
+    workspaceDirectory(runId: string): Promise<string>;
+    importPackage(context: CommandContext, runId: string, name: string, files: readonly ActorProgramSource[], signal?: AbortSignal, scriptEntryId?: string): Promise<ActivatedActorProgram>;
+}
+export const actorProgramsToken = serviceToken<ActorProgramsService>("ragents.actor-programs.runtime");

package/apps/server/src/plugin-support/agent-tool.ts

@@ -0,0 +1,60 @@
+import type { ToolDefinition } from "@aicontainer/agent";
+import { Type } from "typebox";
+import {
+  describeToolAvailability,
+  defineRunFunction,
+  type RunFunction,
+  type ToolAvailability,
+  type ToolDescriptor,
+  type ToolExecutionMode,
+} from "@aicontainer/ragents";
+
+export type AgentToolDefinition = ToolDefinition<any, any, any> & { longDescription?: string; nativeTool?: boolean };
+export type AgentToolMetadata = Pick<AgentToolDefinition, "name" | "description"> & { nativeTool?: boolean };
+
+type ToolOutput = { content?: ReadonlyArray<{ type: string; text?: string }> };
+
+type BoundExecute = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: unknown,
+  ctx: unknown,
+) => Promise<ToolOutput>;
+
+const textOf = (result: ToolOutput): string =>
+  (result.content ?? [])
+    .filter((part) => part.type === "text" && typeof part.text === "string")
+    .map((part) => part.text)
+    .join("\n");
+
+export const agentToolFrom = (
+  definition: AgentToolDefinition,
+  available: ToolAvailability,
+  executionMode?: ToolExecutionMode,
+): RunFunction =>
+  defineRunFunction({
+    name: definition.name,
+    label: definition.label ?? definition.name,
+    description: definition.description,
+    ...(definition.longDescription === undefined ? {} : { longDescription: definition.longDescription }),
+    ...(definition.nativeTool === undefined ? {} : { nativeTool: definition.nativeTool }),
+    schema: definition.parameters,
+    resultSchema: Type.String(),
+    available,
+    ...(executionMode ? { executionMode } : {}),
+    run: async (scope, toolCallId, input) =>
+      textOf(await (definition.execute as BoundExecute)(toolCallId, input, scope.signal, undefined, undefined)),
+  });
+
+export const toolDescriptorFrom = (
+  definition: AgentToolMetadata,
+  available: ToolAvailability,
+  scope: ToolDescriptor["scope"] = "per-turn",
+): ToolDescriptor => ({
+  name: definition.name,
+  description: definition.description,
+  scope,
+  ...(definition.nativeTool === undefined ? {} : { nativeTool: definition.nativeTool }),
+  ...describeToolAvailability(available),
+});

package/apps/server/src/plugin-support/asset-path.ts

@@ -0,0 +1,4 @@
+import { fileURLToPath } from "node:url";
+
+export const pluginAssetPath = (moduleUrl: string, relativePath: string): string =>
+  fileURLToPath(new URL(relativePath, moduleUrl));

package/apps/server/src/plugin-support/await-with-signal.ts

@@ -0,0 +1,18 @@
+export const awaitWithSignal = <T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> => {
+  if (!signal) return operation;
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    void operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+};

package/apps/server/src/plugin-support/chat-display-contract.ts

@@ -0,0 +1,7 @@
+export const CHAT_DETAIL_MODES = ["off", "current", "icons", "chips", "grouped", "compact", "full"] as const;
+
+export type ChatDetailMode = (typeof CHAT_DETAIL_MODES)[number];
+
+export const CHAT_STEP_SCOPES = ["coordinator", "agents"] as const;
+
+export type ChatStepScope = (typeof CHAT_STEP_SCOPES)[number];