@schlenkr/ragents 0.1.10 → 0.1.11

package/apps/server/src/api/reference.ts

@@ -3,40 +3,40 @@ import { RPC_METHODS, type ChannelDescriptor, type MethodDescriptor, type Plugin
 
 export type ApiAuthentication = { kind: "open" } | { kind: "token" } | { kind: "users"; cookieName: string };
 
-export const RPC_API_TITLE = "RAgents JSON-RPC-API";
+export const RPC_API_TITLE = "RAgents JSON-RPC API";
 
 const schemaJson = (schema: TSchema): Record<string, unknown> => JSON.parse(JSON.stringify(schema)) as Record<string, unknown>;
 
 const byId = <T extends { id: string }>(entries: readonly T[]): T[] =>
   [...entries].sort((left, right) => left.id.localeCompare(right.id, "en"));
 
-const rights = (entry: { rights: readonly string[] }): string => entry.rights.length > 0 ? entry.rights.join(", ") : "keine festen Rechte";
+const rights = (entry: { rights: readonly string[] }): string => entry.rights.length > 0 ? entry.rights.join(", ") : "no fixed rights";
 
 export const authenticationDescription = (authentication: ApiAuthentication): string => authentication.kind === "users"
-  ? "Benutzeranmeldung: POST /api/access/login mit id und password. Das erhaltene Sitzungscookie bei weiteren Anfragen mitsenden. ACCESS_TOKEN ersetzt keine Benutzeranmeldung."
-  : authentication.kind === "token" ? "Dieses Profil verlangt den konfigurierten ACCESS_TOKEN als Bearer-Token oder das bestehende Zugangscookie."
-    : "Dieses Profil verlangt keine Anmeldung. Profile mit users verwenden Sitzungscookies; ohne users kann ACCESS_TOKEN den bisherigen Zugang schützen.";
+  ? "User sign-in: POST /api/access/login with id and password. Send the received session cookie with further requests. ACCESS_TOKEN does not replace user sign-in."
+  : authentication.kind === "token" ? "This profile requires the configured ACCESS_TOKEN as a bearer token or the existing access cookie."
+    : "This profile requires no sign-in. Profiles with users use session cookies; without users, ACCESS_TOKEN can protect the existing access.";
 
 const transportLines = (authentication: ApiAuthentication, example: string): string[] => [
-  "Die API ist JSON-RPC 2.0. Eine Anfrage ist ein Objekt mit jsonrpc, id, method und params; params ist immer das Eingabeobjekt der Methode. Die Antwort enthält result oder error; error.data nennt code und status des Fehlers.",
+  "The API is JSON-RPC 2.0. A request is an object with jsonrpc, id, method and params; params is always the method's input object. The response contains result or error; error.data names the error's code and status.",
   "",
-  "Transporte:",
+  "Transports:",
   "",
-  "- HTTP: `POST /rpc` mit genau einer Nachricht je Anfrage. `GET /rpc/stream` liefert als Server-Sent-Events die Benachrichtigungen und Anfragen des Servers; das erste Ereignis `hello` nennt die Verbindungskennung, die weitere Anfragen im Header `x-ragents-connection` mitsenden.",
-  "- stdio: der Server startet mit `--stdio` und tauscht eine JSON-Nachricht je Zeile über stdin und stdout aus.",
+  "- HTTP: `POST /rpc` with exactly one message per request. `GET /rpc/stream` delivers the server's notifications and requests as server-sent events; the first event `hello` names the connection id, which further requests send in the header `x-ragents-connection`.",
+  "- stdio: the server starts with `--stdio` and exchanges one JSON message per line over stdin and stdout.",
   "",
-  `Feste Methoden der Nachrichtenschicht: ${RPC_METHODS.subscribe}, ${RPC_METHODS.unsubscribe}, ${RPC_METHODS.event}, ${RPC_METHODS.cancel} und ${RPC_METHODS.progress}. Ein Abonnement nennt channel und params und erhält eine Abonnementkennung; jede Nachricht des Kanals kommt als ${RPC_METHODS.event}.`,
+  `Fixed methods of the message layer: ${RPC_METHODS.subscribe}, ${RPC_METHODS.unsubscribe}, ${RPC_METHODS.event}, ${RPC_METHODS.cancel} and ${RPC_METHODS.progress}. A subscription names channel and params and receives a subscription id; every message of the channel arrives as ${RPC_METHODS.event}.`,
   "",
   authenticationDescription(authentication),
   "",
-  "Die Shellvariable RAGENTS_API_BASE_URL enthält die Serveradresse. Falls RAGENTS_API_TOKEN gesetzt ist, bei Anfragen den Header Authorization: Bearer <Token> senden. Der Token gehört nicht in Ausgaben oder Dokumente.",
+  "The shell variable RAGENTS_API_BASE_URL contains the server address. If RAGENTS_API_TOKEN is set, send the header Authorization: Bearer <token> with requests. The token does not belong in output or documents.",
   "",
   "```sh",
   `curl -s "$RAGENTS_API_BASE_URL/rpc" -H 'content-type: application/json' \\`,
   `  -d '{"jsonrpc":"2.0","id":1,"method":"${example}","params":{}}'`,
   "```",
   "",
-  "Kennungen aus Ergebnissen werden programmgesteuert weiterverwendet, nicht abgeschrieben.",
+  "Ids from results are reused programmatically, not copied by hand.",
 ];
 
 const methodSection = (method: MethodDescriptor): string[] => [
@@ -44,15 +44,15 @@ const methodSection = (method: MethodDescriptor): string[] => [
   "",
   method.description,
   "",
-  `Eigentümer: ${method.owner}. Rechte: ${rights(method)}. Ausführung: ${method.implementedBy === "client" ? "der verbundene Client" : "der Server"}.`,
+  `Owner: ${method.owner}. Rights: ${rights(method)}. Execution: ${method.implementedBy === "client" ? "the connected client" : "the server"}.`,
   "",
-  "### Eingabe",
+  "### Input",
   "",
   "```json",
   JSON.stringify(schemaJson(method.input), null, 2),
   "```",
   "",
-  "### Ergebnis",
+  "### Result",
   "",
   "```json",
   JSON.stringify(schemaJson(method.result), null, 2),
@@ -61,11 +61,11 @@ const methodSection = (method: MethodDescriptor): string[] => [
 ];
 
 const channelSection = (channel: ChannelDescriptor): string[] => [
-  `## Kanal ${channel.id}`,
+  `## Channel ${channel.id}`,
   "",
   channel.description,
   "",
-  `Eigentümer: ${channel.owner}. Rechte: ${rights(channel)}.`,
+  `Owner: ${channel.owner}. Rights: ${rights(channel)}.`,
   "",
   "### Parameter",
   "",
@@ -73,7 +73,7 @@ const channelSection = (channel: ChannelDescriptor): string[] => [
   JSON.stringify(schemaJson(channel.params), null, 2),
   "```",
   "",
-  "### Nachricht",
+  "### Message",
   "",
   "```json",
   JSON.stringify(schemaJson(channel.message), null, 2),
@@ -81,35 +81,35 @@ const channelSection = (channel: ChannelDescriptor): string[] => [
   "",
 ];
 
-/** Für das Beispiel eine Methode ohne Pflichtfelder, damit der gezeigte Aufruf tatsächlich funktioniert. */
+/** For the example, a method without required fields, so that the call shown actually works. */
 const exampleMethod = (methods: readonly MethodDescriptor[]): string => {
   const empty = methods.find((method) => {
     const schema = schemaJson(method.input);
     return schema.type === "object" && schema.required === undefined && method.implementedBy === "server";
   });
-  return empty?.id ?? methods[0]?.id ?? "<methoden-id>";
+  return empty?.id ?? methods[0]?.id ?? "<method-id>";
 };
 
-/** Lesbare Referenz aller registrierten Methoden und Kanäle, direkt aus ihren Verträgen. */
+/** Readable reference of all registered methods and channels, directly from their contracts. */
 export function methodReference(host: PluginHost, authentication: ApiAuthentication = { kind: "open" }): string {
   const methods = byId(host.methods.describe());
   const channels = byId(host.channels.describe());
   return [
     `# ${RPC_API_TITLE}`,
     "",
-    "Diese Referenz entsteht aus den registrierten Verträgen. Interne und externe Clients verwenden dieselben Methoden.",
+    "This reference is generated from the registered contracts. Internal and external clients use the same methods.",
     "",
     ...transportLines(authentication, exampleMethod(methods)),
     "",
-    "## Methodenübersicht",
+    "## Method overview",
     "",
-    "| Methode | Eigentümer | Rechte |",
+    "| Method | Owner | Rights |",
     "| --- | --- | --- |",
     ...methods.map((method) => `| ${method.id} | ${method.owner} | ${rights(method)} |`),
     "",
-    "## Kanalübersicht",
+    "## Channel overview",
     "",
-    "| Kanal | Eigentümer | Rechte |",
+    "| Channel | Owner | Rights |",
     "| --- | --- | --- |",
     ...channels.map((channel) => `| ${channel.id} | ${channel.owner} | ${rights(channel)} |`),
     "",
@@ -118,7 +118,7 @@ export function methodReference(host: PluginHost, authentication: ApiAuthenticat
   ].join("\n");
 }
 
-/** OpenRPC 1.3 aus denselben Verträgen; Kanäle stehen als x-channels daneben. */
+/** OpenRPC 1.3 from the same contracts; channels sit alongside as x-channels. */
 export function openRpcDocument(host: PluginHost, authentication: ApiAuthentication = { kind: "open" }): Record<string, unknown> {
   return {
     openrpc: "1.3.0",

package/apps/server/src/api/rights.ts

@@ -4,30 +4,30 @@ import type { RunRightsKind } from "@ragents/engine/src/http/methods";
 import type { RunListScope } from "../chat-handler.js";
 
 export interface GlobalRunPolicy {
-  /** Jede Kennung, die einem globalen Koordinator vorbehalten ist. */
+  /** Every id reserved for a global coordinator. */
   isCoordinator: (runId: string) => boolean;
-  /** Der Koordinator eines Benutzers; ohne Anmeldung (null) gibt es genau einen. */
+  /** A user's coordinator; without sign-in (null) there is exactly one. */
   runIdFor: (userId: string | null) => string;
   read: string;
   write: string;
 }
 
-/** Der Koordinator eines Zugangs: ohne Anmeldung der eine, angemeldet der des Benutzers, ohne Benutzer keiner. */
+/** The coordinator of an access: without sign-in the one, signed in that of the user, without a user none. */
 export const coordinatorRunIdOf = (access: AccessContext, global: GlobalRunPolicy): string | undefined =>
   !access.enabled ? global.runIdFor(null) : access.user ? global.runIdFor(access.user.id) : undefined;
 
-/** Das Recht, die Runs aller Benutzer zu sehen; ohne es bleibt ein Zugang bei seinen eigenen. */
+/** The right to see the runs of all users; without it, an access stays with its own. */
 export const RUNS_READ_ALL = "runs.read.all";
 
 export interface RunAccessPolicy {
   global: GlobalRunPolicy | undefined;
-  /** Der Benutzer des Runs: null für einen Run ohne Eigentümer, undefined für einen Run, den es noch nicht gibt. */
+  /** The user of the run: null for a run without an owner, undefined for a run that does not exist yet. */
   ownerOf: (runId: string) => string | null | undefined;
-  /** Ob nur der Eigentümer den Run bedient, weil ein Plugin ihn so erklärt hat. */
+  /** Whether only the owner operates the run, because a plugin declared it so. */
   ownerOnly: (runId: string) => boolean;
 }
 
-/** Rechte je Run: gewöhnliche Runs über runs.*, die Koordinatoren über die Rechte ihres Plugins. */
+/** Rights per run: ordinary runs through runs.*, the coordinators through the rights of their plugin. */
 export const runRights = (runId: string, kind: RunRightsKind, global: GlobalRunPolicy | undefined): readonly string[] => {
   if (global?.isCoordinator(runId)) {
     const technical = kind === "inspect" || kind === "write-inspect" ? ["runs.inspect"] : [];
@@ -42,25 +42,25 @@ export const runRights = (runId: string, kind: RunRightsKind, global: GlobalRunP
   }
 };
 
-/** Ein Run gehört dem Zugang: ohne Anmeldung gibt es nur einen, runs.read.all sieht alle; ein Koordinator gehört nur seinem Benutzer. */
+/** A run belongs to the access: without sign-in there is only one, runs.read.all sees all; a coordinator belongs only to its user. */
 export const runOwned = (access: AccessContext, runId: string, policy: RunAccessPolicy): boolean =>
   policy.global?.isCoordinator(runId)
     ? runId === coordinatorRunIdOf(access, policy.global)
     : !access.enabled || access.can(RUNS_READ_ALL) || policy.ownerOf(runId) === access.user?.id;
 
-/** Erreichbar ist zusätzlich eine Kennung ohne Run: sie gehört erst dem, der den Run unter ihr anlegt; eine Koordinatorkennung nie einem anderen. */
+/** Also reachable is an id without a run: it belongs only to whoever creates the run under it; a coordinator id never to anyone else. */
 export const runReachable = (access: AccessContext, runId: string, policy: RunAccessPolicy): boolean =>
   runOwned(access, runId, policy) || (!policy.global?.isCoordinator(runId) && policy.ownerOf(runId) === undefined);
 
-/** Bedienen heißt schreiben, starten und antworten; einen Run, den nur sein Eigentümer bedient, bedient auch runs.read.all nicht. */
+/** Operating means writing, starting and answering; a run operated only by its owner is not operated by runs.read.all either. */
 export const runOperable = (access: AccessContext, runId: string, policy: RunAccessPolicy): boolean =>
   !access.enabled || !policy.ownerOnly(runId) || policy.ownerOf(runId) === access.user?.id;
 
-/** Der Arbeitsbereich eines Runs, den nur sein Eigentümer bedient, liegt bei ihm; auch lesend erreicht ihn nur er, das Journal lesen weiter alle, die den Run sehen. */
+/** The workspace of a run operated only by its owner stays with the owner; only the owner reaches it, even for reading, while everyone who sees the run can still read the journal. */
 export const runWorkspaceAccessible = (access: AccessContext, runId: string, policy: RunAccessPolicy): boolean =>
   runOperable(access, runId, policy);
 
-/** Die Run-Liste eines Zugangs: sichtbar, was ihm gehört, erreichbar nur der Arbeitsbereich, den er auch lesen darf. */
+/** The run list of an access: visible is what belongs to it, reachable only the workspace it may also read. */
 export const runListScope = (access: AccessContext, policy: RunAccessPolicy): RunListScope => ({
   visible: (runId) => runOwned(access, runId, policy),
   workspaceAccessible: (runId) => runWorkspaceAccessible(access, runId, policy),
@@ -70,29 +70,29 @@ export const assertRunWorkspaceAccess = (access: AccessContext, runId: string, p
   if (!runWorkspaceAccessible(access, runId, policy)) {
     throw new DomainError(
       "run-workspace-owner-only",
-      `Den Arbeitsbereich des Runs ${runId} sieht nur sein Eigentümer; Journal lesen und den Run stoppen darfst du.`,
+      `Only its owner sees the workspace of run ${runId}; you may read the journal and stop the run.`,
       403,
     );
   }
 };
 
-/** Auslieferungsadressen nennen ihren Run als eigenen Pfadabschnitt: /files/runs/<id>/..., /api/plugins/<plugin>/runs/<id>/... */
+/** Delivery addresses name their run as a separate path segment: /files/runs/<id>/..., /api/plugins/<plugin>/runs/<id>/... */
 export const runIdInPath = (pathname: string): string | undefined =>
   /(?:^|\/)runs\/([A-Za-z0-9_-]{1,64})(?:\/|$)/.exec(pathname)?.[1];
 
-/** Ein fremder Run verhält sich wie ein nicht vorhandener: gleicher Code, gleiche Meldung, gleicher Status. */
+/** A foreign run behaves like a nonexistent one: same code, same message, same status. */
 export const assertRunReachable = (access: AccessContext, runId: string, policy: RunAccessPolicy): void => {
   if (!runReachable(access, runId, policy)) throw new DomainError("run-not-found", `Run ${runId} does not exist.`, 404);
 };
 
-/** Wer den Run sehen darf, erfährt auch, warum er ihn nicht bedienen darf. */
+/** Whoever may see the run also learns why they may not operate it. */
 export const assertRunOperable = (access: AccessContext, runId: string, policy: RunAccessPolicy): void => {
   if (!runOperable(access, runId, policy)) {
-    throw new DomainError("run-owner-only", `Den Run ${runId} bedient nur sein Eigentümer; lesen und stoppen darfst du ihn.`, 403);
+    throw new DomainError("run-owner-only", `Only its owner operates run ${runId}; you may read and stop it.`, 403);
   }
 };
 
-/** Die Prüfung der Nachrichtenschicht: jeder Beitrag mit runId muss den Run erreichen, einer mit runs.write ihn auch bedienen. */
+/** The message layer's check: every contribution with runId must reach the run, one with runs.write must also operate it. */
 export const assertRunAccess = (access: AccessContext, runId: string, operates: boolean, policy: RunAccessPolicy): void => {
   assertRunReachable(access, runId, policy);
   if (operates) assertRunOperable(access, runId, policy);

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

@@ -1,4 +1,4 @@
-/** Die Verträge der Runs, gegen die Kernmethoden und Auslieferung arbeiten. */
+/** The contracts of the runs that core methods and delivery work against. */
 import type { ChatAttachment, ChatAttachmentInput, ChatEvent } from "quassel/events";
 import type { ActorConversations } from "./ragents/actor-chat-history.js";
 
@@ -8,7 +8,7 @@ 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. */
+  /** Why the run is locked; it stays visible and deletable, everything else reports journal-unavailable. */
   locked?: string;
 }
 
@@ -17,7 +17,7 @@ export interface ChatUser {
   label: string;
 }
 
-/** Was der HTTP-Adapter von einem Run braucht. */
+/** What the HTTP adapter needs from a run. */
 export interface ChatSessionLike {
   readonly running: boolean;
   subscribe(listener: (event: ChatEvent) => void): () => void;
@@ -30,7 +30,7 @@ export interface ChatSessionLike {
   stop(): void | Promise<void>;
 }
 
-/** Was der Aufrufer der Run-Liste sieht und welchen Arbeitsbereich er erreicht. */
+/** What the caller of the run list sees and which workspace it reaches. */
 export interface RunListScope {
   visible: (runId: string) => boolean;
   workspaceAccessible: (runId: string) => boolean;
@@ -39,7 +39,7 @@ export interface RunListScope {
 export interface ChatSessionProvider {
   get(id: string): Promise<ChatSessionLike>;
   hasRun?(id: string): boolean;
-  /** Ohne Bereich alle Runs, aber kein Arbeitsbereich, den nur sein Eigentümer bedient. */
+  /** Without a scope all runs, but no workspace that only its owner operates. */
   list(scope?: RunListScope): Promise<SessionInfo[]>;
   subscribeList?(listener: () => void): () => void;
   delete(id: string): Promise<void>;

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

@@ -11,7 +11,7 @@ const ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 export const env = (name: string): EnvironmentReference => {
   if (!ENVIRONMENT_NAME.test(name)) {
-    throw new Error(`env("${name}") nennt keinen gültigen Namen einer Umgebungsvariablen`);
+    throw new Error(`env("${name}") does not name a valid environment variable`);
   }
   return { kind: "environment", name };
 };
@@ -27,13 +27,13 @@ export interface ProvisionedReference {
 
 const PLUGIN_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 
-/** Eine Datei im Werkzeugordner eines Plugins; beim Laden der Profildatei wird daraus ein absoluter Pfad. */
+/** A file in a plugin's tool folder; loading the profile file turns it into an absolute path. */
 export const provisioned = (plugin: string, file: string): ProvisionedReference => {
   if (!PLUGIN_ID.test(plugin)) {
-    throw new Error(`provisioned("${plugin}", ...) nennt keine gültige Plugin-Kennung`);
+    throw new Error(`provisioned("${plugin}", ...) does not name a valid plugin id`);
   }
   if (!file || file.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
-    throw new Error(`provisioned("${plugin}", "${file}") braucht einen relativen Pfad im Werkzeugordner`);
+    throw new Error(`provisioned("${plugin}", "${file}") needs a relative path in the tool folder`);
   }
   return { kind: "provisioned", plugin, path: file };
 };
@@ -50,25 +50,51 @@ export interface ProfileAnonymousUser {
 
 export interface ProfileUser extends ProfileAnonymousUser {
   readonly password: string | EnvironmentReference;
-  /** Dauerhafter Bearer-Token für Clients ohne Anmeldedialog; nur als env(...), nie im Klartext. */
+  /** Permanent bearer token for clients without a sign-in dialog; only as env(...), never in plain text. */
   readonly token?: EnvironmentReference;
 }
 
-/** Ein Eintrag von MODEL_ALIASES: ein Modell unter eigenem Namen mit den Kompaktierungswerten, die für dieses Modell gelten. */
+/** An entry of MODEL_ALIASES: a model under its own name with the compaction values that apply to this model. */
 export interface ProfileModelAlias {
   readonly alias: string;
-  /** Das Ziel als anbieter/modell aus dem eingebauten Katalog des Anbieters. */
+  /** The target as provider/model from a provider of MODEL_PROVIDERS or a built-in catalog. */
   readonly model: string;
   readonly thinking?: ThinkingLevel;
+  /** The levels the alias offers, each mapped to a level of the target; without them it offers the target's levels. */
+  readonly thinkingLevels?: Readonly<Partial<Record<ThinkingLevel, ThinkingLevel>>>;
   readonly compaction: Readonly<ModelCompaction>;
 }
 
+/** An entry of MODEL_PROVIDERS: an OpenAI-compatible server, for instance a self-hosted one, whose models aliases can name as provider/model. */
+export interface ProfileModelProvider {
+  readonly id: string;
+  /** The address up to /v1, without a trailing slash; requests go to baseUrl/chat/completions. */
+  readonly baseUrl: string;
+  /** Only as env(...), never in plain text. */
+  readonly apiKey: EnvironmentReference;
+  readonly compat?: Readonly<{
+    /** "qwen-chat-template" switches thinking with chat_template_kwargs.enable_thinking and sends the effort as reasoning_effort. */
+    thinkingFormat?: "qwen-chat-template";
+    requiresReasoningContentOnAssistantMessages?: boolean;
+  }>;
+  readonly models: readonly Readonly<{
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+    reasoning: boolean;
+    input: readonly ("text" | "image" | "video" | "file" | "audio")[];
+    /** What the server gets per level; null removes a level, xhigh and max exist only when named here. */
+    thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
+  }>[];
+}
+
 export type ConfigValue =
   | string
   | number
   | boolean
   | readonly string[]
   | readonly ProfileModelAlias[]
+  | readonly ProfileModelProvider[]
   | EnvironmentReference
   | ProvisionedReference;
 
@@ -82,12 +108,13 @@ type Section<T extends Descriptors> = {
   readonly [Key in T[number]["key"]]?: Key extends SecretKeyOf<T> ? EnvironmentReference : ConfigValue;
 };
 
-type HostSection = Omit<Section<typeof hostConfigDescriptors>, "MODEL_ALIASES"> & {
+type HostSection = Omit<Section<typeof hostConfigDescriptors>, "MODEL_ALIASES" | "MODEL_PROVIDERS"> & {
   readonly MODEL_ALIASES?: readonly ProfileModelAlias[];
+  readonly MODEL_PROVIDERS?: readonly ProfileModelProvider[];
 };
 
-// Der Kern kennt keine Plugin-IDs: welche Sektion und welcher Schlüssel gültig ist, entscheidet die
-// Laufzeitprüfung gegen die Deklarationen der geladenen Plugins.
+// The core knows no plugin ids: which section and which key is valid is decided by the
+// runtime check against the declarations of the loaded plugins.
 export type PluginSection = {
   readonly [key: `${string}_PAT`]: EnvironmentReference | undefined;
   readonly [key: `${string}_KEY`]: EnvironmentReference | undefined;