@schlenkr/ragents 0.1.5 → 0.1.7

package/apps/server/src/chat-handler.ts

@@ -1,5 +1,5 @@
-/** Die Verträge der Unterhaltungen, gegen die Kernmethoden und Auslieferung arbeiten. */
-import type { ChatAttachment, ChatAttachmentInput, ChatEvent } from "./chat-events.js";
+/** Die Verträge der Runs, gegen die Kernmethoden und Auslieferung arbeiten. */
+import type { ChatAttachment, ChatAttachmentInput, ChatEvent } from "quassel/events";
 import type { ActorConversations } from "./ragents/actor-chat-history.js";
 
 export interface SessionInfo {
@@ -8,6 +8,8 @@ export interface SessionInfo {
   createdAt?: number;
   updatedAt: number;
   revision?: number;
+  /** Warum der Run gesperrt ist; er bleibt sichtbar und löschbar, alles andere meldet journal-unavailable. */
+  locked?: string;
 }
 
 export interface ChatUser {
@@ -15,23 +17,30 @@ export interface ChatUser {
   label: string;
 }
 
-/** Was der HTTP-Adapter von einer Unterhaltung braucht. */
+/** Was der HTTP-Adapter von einem Run braucht. */
 export interface ChatSessionLike {
   readonly running: boolean;
   subscribe(listener: (event: ChatEvent) => void): () => void;
-  send(text: string, attachments?: ChatAttachmentInput[], userLocation?: unknown, user?: ChatUser): void | Promise<void>;
-  sendToActor?(actorId: string, text: string, attachments?: ChatAttachmentInput[]): Promise<void>;
+  send(text: string, attachments?: ChatAttachmentInput[], userLocation?: unknown, user?: ChatUser, entryId?: string): void | Promise<void>;
+  sendToActor?(actorId: string, text: string, attachments?: ChatAttachmentInput[], user?: ChatUser): Promise<void>;
   actorConversations?(): ActorConversations;
-  capabilities?(actor?: string): Promise<{ input: string[]; model: string }>;
+  capabilities?(actor: string, userId: string | null): Promise<{ input: string[]; model: string }>;
   attachment?(artifactId: string): { attachment: ChatAttachment; content: Uint8Array };
   start(entryId: string, input: unknown, user?: ChatUser): void;
   stop(): void | Promise<void>;
 }
 
+/** Was der Aufrufer der Run-Liste sieht und welchen Arbeitsbereich er erreicht. */
+export interface RunListScope {
+  visible: (runId: string) => boolean;
+  workspaceAccessible: (runId: string) => boolean;
+}
+
 export interface ChatSessionProvider {
   get(id: string): Promise<ChatSessionLike>;
   hasRun?(id: string): boolean;
-  list(): Promise<SessionInfo[]>;
+  /** Ohne Bereich alle Runs, aber kein Arbeitsbereich, den nur sein Eigentümer bedient. */
+  list(scope?: RunListScope): Promise<SessionInfo[]>;
   subscribeList?(listener: () => void): () => void;
   delete(id: string): Promise<void>;
 }

package/apps/server/src/config-file.ts

@@ -1,7 +1,7 @@
 import { statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { pluginToolsDirectory } from "@aicontainer/workspace-executor/src/tools.ts";
+import { pluginToolsDirectory } from "@ragents/workspace-executor/src/tools.ts";
 import { isAccessRight, type AccessUser } from "../../../packages/ragents/src/access.js";
 import {
   isEnvironmentReference,
@@ -12,12 +12,17 @@ import {
   type RAgentsConfig,
 } from "./config-definition.js";
 import { defaultDataDirectory } from "./data-directory.js";
+import { MissingEnvironmentError } from "./missing-environment.js";
 import { isPluginPath, pluginFolderFor } from "./plugin-support/plugins-root.js";
 
+// Der Befund über eine fehlende Umgebungsvariable gehört zum Laden der Konfiguration; main.ts holt ihn darum von hier.
+export { missingEnvironmentOf, reportMissingEnvironment } from "./missing-environment.js";
+
 const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 
 export const SECRET_KEY_PATTERN = /(_PAT|_KEY|_TOKEN|_SECRET|_PASSWORD)$/;
 const ENVIRONMENT_PLACEHOLDER = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+const START_ENTRY_ID = /^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/;
 
 interface ConfigFileEntry {
   section: string;
@@ -32,6 +37,7 @@ interface LoadedConfigFile {
   entries: readonly ConfigFileEntry[];
   users: readonly ResolvedProfileUser[] | undefined;
   anonymousUser: AccessUser | undefined;
+  defaultStartEntry: string | undefined;
 }
 
 export interface ResolvedProfileUser extends AccessUser {
@@ -73,9 +79,9 @@ const resolveIdentity = (location: string, entry: Record<string, unknown>): Acce
   }
   if (new Set(entry.rights).size !== entry.rights.length) throw new Error(`${location}.rights enthält doppelte Rechte`);
   if (entry.startEntries !== undefined && (!Array.isArray(entry.startEntries)
-    || !entry.startEntries.every((id) => typeof id === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/.test(id))
+    || !entry.startEntries.every((id) => typeof id === "string" && START_ENTRY_ID.test(id))
     || new Set(entry.startEntries).size !== entry.startEntries.length)) {
-    throw new Error(`${location}.startEntries braucht eindeutige Einstiegkennungen als Strings`);
+    throw new Error(`${location}.startEntries braucht eindeutige Vorlagenkennungen als Strings`);
   }
   return Object.freeze({
     id: entry.id,
@@ -96,6 +102,15 @@ export const resolveAnonymousUser = (source: string, raw: unknown): AccessUser |
   return resolveIdentity(location, entry);
 };
 
+/** Die Vorlage, die ein neuer Run ohne Auswahl nimmt; ob sie registriert ist, prüft der PluginHost beim Start. */
+export const resolveDefaultStartEntry = (source: string, raw: unknown): string | undefined => {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "string" || !START_ENTRY_ID.test(raw)) {
+    throw new Error(`${source}: defaultStartEntry braucht eine Vorlagenkennung als String, etwa "ragents.reference.word-game"`);
+  }
+  return raw;
+};
+
 export const resolveProfileUsers = (
   source: string,
   raw: unknown,
@@ -153,7 +168,8 @@ const materialize = (value: Exclude<ConfigValue, EnvironmentReference | Provisio
 const dataDirectoryOf = (source: string, raw: RAgentsConfig): string => {
   const configured = raw.host?.DATA_DIR;
   if (isEnvironmentReference(configured) && process.env[configured.name] === undefined) {
-    throw new Error(`${source}: host.DATA_DIR verweist auf die nicht gesetzte Umgebungsvariable ${configured.name}`);
+    throw new MissingEnvironmentError({ variable: configured.name, section: "host", key: "DATA_DIR" },
+      `${source}: host.DATA_DIR verweist auf die nicht gesetzte Umgebungsvariable ${configured.name}`);
   }
   const fromFile = isEnvironmentReference(configured) ? process.env[configured.name] : typeof configured === "string" ? configured : undefined;
   const profile = process.env.PRODUCT_PROFILE;
@@ -170,7 +186,7 @@ const entryFor = (source: string, section: string, key: string, value: ConfigVal
   if (isEnvironmentReference(value)) {
     const resolved = process.env[value.name];
     if (resolved === undefined) {
-      throw new Error(
+      throw new MissingEnvironmentError({ variable: value.name, section, key },
         `${source}: ${section}.${key} verweist mit env("${value.name}") auf eine Umgebungsvariable, `
         + `die in dieser Shell nicht gesetzt ist. Setze sie vor dem Start (export ${value.name}=...) oder `
         + "hinterlege sie in der Startdatei Deiner Shell; Secrets stehen nie in der Konfigurationsdatei.");
@@ -250,7 +266,8 @@ const readProfileConfiguration = async (root: string): Promise<LoadedConfigFile
   const users = resolveProfileUsers(source, module.users);
   const anonymousUser = resolveAnonymousUser(source, module.anonymousUser);
   if (users && anonymousUser) throw new Error(`${source}: users und anonymousUser schließen einander aus`);
-  return { path: source, entries: parseEntries(source, raw), users, anonymousUser };
+  const defaultStartEntry = resolveDefaultStartEntry(source, module.defaultStartEntry);
+  return { path: source, entries: parseEntries(source, raw), users, anonymousUser, defaultStartEntry };
 };
 
 let loadedConfigFile: LoadedConfigFile | undefined;
@@ -278,6 +295,8 @@ export const configuredUsers = (): readonly ResolvedProfileUser[] | undefined =>
 
 export const configuredAnonymousUser = (): AccessUser | undefined => loadedConfigFile?.anonymousUser;
 
+export const configuredDefaultStartEntry = (): string | undefined => loadedConfigFile?.defaultStartEntry;
+
 export interface ConfigFileValidationContext {
   hostKeys: readonly string[];
   knownPluginIds: readonly string[];

package/apps/server/src/config.ts

@@ -1,18 +1,21 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { modelAliasEnvDescriptors } from "./plugin-support/model-aliases.js";
 import { declaredEnvironment } from "./plugin-support/plugin-config.js";
 import { defaultDataDirectory } from "./data-directory.js";
+import { hostWebDirectory } from "./host-web.js";
 
 const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 
 export const hostConfigDescriptors = [
   { key: "PORT", source: "environment" },
   { key: "DATA_DIR", source: "environment" },
-  { key: "WEB_DIST_DIR", source: "environment" },
   { key: "AGENT_THINKING", source: "environment" },
-  { key: "AGENT_HOME_DIR", source: "environment" },
+  { key: "AGENT_COMPACTION_RESERVE_TOKENS", source: "environment" },
+  { key: "AGENT_COMPACTION_KEEP_RECENT_TOKENS", source: "environment" },
   { key: "COMPACTION_PROVIDER", source: "environment" },
   { key: "COMPACTION_MODEL", source: "environment" },
+  ...modelAliasEnvDescriptors,
   { key: "PRODUCT_PROFILE", source: "environment" },
   { key: "PLUGINS", source: "environment" },
   { key: "PRODUCT_ID", source: "environment" },
@@ -32,9 +35,12 @@ const env = declaredEnvironment(hostConfigDescriptors);
 export const config = Object.freeze({
   port: Number(env.value("PORT", "4710")),
   dataDir: path.resolve(env.value("DATA_DIR", defaultDataDirectory(env.required("PRODUCT_PROFILE")))),
-  webDistDir: path.resolve(env.value("WEB_DIST_DIR", path.join(rootDir, "apps/web/dist", env.required("PRODUCT_PROFILE")))),
+  webDistDir: hostWebDirectory(rootDir),
   agentThinking: env.value("AGENT_THINKING", "high"),
-  agentHomeDir: path.resolve(env.value("AGENT_HOME_DIR", path.join(rootDir, "apps/server/agent-home"))),
+  agentCompaction: {
+    ...(env.optional("AGENT_COMPACTION_RESERVE_TOKENS") ? { reserveTokens: env.positiveNumber("AGENT_COMPACTION_RESERVE_TOKENS", "") } : {}),
+    ...(env.optional("AGENT_COMPACTION_KEEP_RECENT_TOKENS") ? { keepRecentTokens: env.positiveNumber("AGENT_COMPACTION_KEEP_RECENT_TOKENS", "") } : {}),
+  },
   compactionProvider: env.value("COMPACTION_PROVIDER", "openrouter"),
   compactionModel: env.value("COMPACTION_MODEL", ""),
   productProfile: env.required("PRODUCT_PROFILE"),

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

@@ -1,7 +1,7 @@
 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";
+import { ragentsDataRoot } from "@ragents/workspace-executor/src/tools.ts";
 
 export { ragentsDataRoot };
 

package/apps/server/src/folder-install.ts

@@ -0,0 +1,115 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readFile, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const LOCK_POLL_MS = 100;
+const LOCK_TIMEOUT_MS = 10 * 60_000;
+/** A lock file without a process number is being written right now; only an old one is a leftover. */
+const EMPTY_LOCK_LEFTOVER_MS = 10_000;
+
+/** Every file below a folder as a relative path with forward slashes, sorted; directories only through their files. */
+export const filesBelow = (folder: string, prefix = ""): readonly string[] =>
+  readdirSync(folder, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name, "en")).flatMap((entry) => {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    return entry.isDirectory() ? filesBelow(path.join(folder, entry.name), relative) : [relative];
+  });
+
+const isAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const isLeftover = (file: string, owner: string): boolean => {
+  const pid = Number(owner);
+  if (owner !== "" && Number.isInteger(pid) && pid > 0) return !isAlive(pid);
+  const stats = statSync(file, { throwIfNoEntry: false });
+  return stats !== undefined && Date.now() - stats.mtimeMs > EMPTY_LOCK_LEFTOVER_MS;
+};
+
+/** Takes the lock file for this process, waiting while another live process holds it; a lock of a dead process is taken over. Returns the release. */
+export const acquireLock = async (file: string): Promise<() => Promise<void>> => {
+  await mkdir(path.dirname(file), { recursive: true });
+  const started = Date.now();
+  for (;;) {
+    try {
+      await writeFile(file, `${process.pid}\n`, { flag: "wx" });
+      return () => rm(file, { force: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const owner = (await readFile(file, "utf8").catch(() => "")).trim();
+      if (isLeftover(file, owner)) {
+        await rm(file, { force: true });
+        continue;
+      }
+      if (Date.now() - started > LOCK_TIMEOUT_MS) {
+        throw new Error(`${file} ist seit ${Math.round(LOCK_TIMEOUT_MS / 60_000)} Minuten von Prozess ${owner || "?"} belegt; läuft dort noch ein Bau?`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+  }
+};
+
+/** Runs an action while this process holds the lock file, so that parallel builds into the same place take turns. */
+export const withLock = async <T>(file: string, action: () => Promise<T>): Promise<T> => {
+  const release = await acquireLock(file);
+  try {
+    return await action();
+  } finally {
+    await release();
+  }
+};
+
+const sameContent = (left: string, right: string): boolean => {
+  const target = statSync(right, { throwIfNoEntry: false });
+  if (!target?.isFile() || target.size !== statSync(left).size) return false;
+  return readFileSync(left).equals(readFileSync(right));
+};
+
+/** Removes whatever blocks a path: a file where a folder must go, or a folder where a file must go. */
+const clearWay = async (target: string, relative: string): Promise<void> => {
+  const parts = relative.split("/");
+  for (let length = 1; length < parts.length; length += 1) {
+    const folder = path.join(target, ...parts.slice(0, length));
+    const stats = statSync(folder, { throwIfNoEntry: false });
+    if (stats && !stats.isDirectory()) await rm(folder, { force: true });
+  }
+  const file = path.join(target, ...parts);
+  if (statSync(file, { throwIfNoEntry: false })?.isDirectory()) await rm(file, { recursive: true, force: true });
+  await mkdir(path.dirname(file), { recursive: true });
+};
+
+const removeEmptyFolders = async (folder: string, root: string): Promise<void> => {
+  for (const entry of readdirSync(folder, { withFileTypes: true })) {
+    if (entry.isDirectory()) await removeEmptyFolders(path.join(folder, entry.name), root);
+  }
+  if (folder !== root && readdirSync(folder).length === 0) await rmdir(folder);
+};
+
+/** Moves a finished folder into place file by file with atomic renames: the target never disappears, unchanged files stay, the given ones come last. */
+export const installFolder = async (staging: string, target: string, last: readonly string[]): Promise<void> => {
+  if (!statSync(target, { throwIfNoEntry: false })?.isDirectory()) {
+    await rm(target, { force: true });
+    await mkdir(path.dirname(target), { recursive: true });
+    await rename(staging, target);
+    return;
+  }
+  const incoming = filesBelow(staging);
+  const ordered = [...incoming.filter((file) => !last.includes(file)), ...last.filter((file) => incoming.includes(file))];
+  for (const relative of ordered) {
+    const from = path.join(staging, ...relative.split("/"));
+    const to = path.join(target, ...relative.split("/"));
+    if (sameContent(from, to)) continue;
+    await clearWay(target, relative);
+    await rename(from, to);
+  }
+  const kept = new Set(incoming);
+  for (const relative of filesBelow(target)) {
+    if (!kept.has(relative)) await rm(path.join(target, ...relative.split("/")), { force: true });
+  }
+  await removeEmptyFolders(target, target);
+  await rm(staging, { recursive: true, force: true });
+};