@schlenkr/ragents 0.1.9 → 0.1.11

package/apps/server/src/ragents/engine.ts

@@ -32,6 +32,7 @@ import {
   type PublicPromptSnapshot,
   type RunStopBoundary,
   type RunStopOperation,
+  type RunView,
   type StartOptionContributionRegistry,
   type Workspaces,
 } from "@ragents/engine";
@@ -65,7 +66,7 @@ export class SessionWorkspaces implements Workspaces {
   readonly #roots = new Map<string, RememberedWorkspace>();
   readonly #sandbox: () => Pick<SandboxServices, "execute" | "serverProcessContextFor">;
 
-  /** Der Zugang zum Arbeitsbereich der Runs; über ihn liegen Anhänge dort, wo die Werkzeuge arbeiten, und die Laufzeit bekommt ihren Serverordner. */
+  /** The access to the runs' workspace; through it, attachments lie where the tools work, and the runtime gets its server folder. */
   constructor(sandbox: () => Pick<SandboxServices, "execute" | "serverProcessContextFor">) {
     this.#sandbox = sandbox;
   }
@@ -80,7 +81,7 @@ export class SessionWorkspaces implements Workspaces {
 
   ensure(runId: string): string {
     const root = this.#roots.get(runId);
-    if (!root) throw new Error(`Für den Run ${runId} ist kein Arbeitsverzeichnis bekannt`);
+    if (!root) throw new Error(`No working directory is known for run ${runId}`);
     return root.cwd;
   }
 
@@ -91,7 +92,7 @@ export class SessionWorkspaces implements Workspaces {
   async storeAttachment(runId: string, name: string, content: Uint8Array): Promise<string> {
     const stored = await this.#sandbox().execute(runId, FILE_OPERATIONS.attach, { name, content: Buffer.from(content).toString("base64") });
     const storedName = (stored as { name?: unknown } | null)?.name;
-    if (typeof storedName !== "string") throw new Error(`Der Executor meldet für den Anhang ${name} keinen Namen`);
+    if (typeof storedName !== "string") throw new Error(`The executor reports no name for the attachment ${name}`);
     return storedName;
   }
 }
@@ -151,30 +152,30 @@ const hasTool = (actor: ExecutableActor, name: string, capability: string): bool
   && actor.grants.some((grant) => grant.capability === capability && grant.usable !== false);
 
 const outputContractFor = (role: ActorRole): string => role === "primary"
-  ? "Dein Modelltext wird im Chat mit dem Benutzer angezeigt. Antworte natürlich als Text."
-  : "Antworte natürlich im Modelltext.";
+  ? "Your model text is shown in the chat with the user. Respond naturally as text."
+  : "Respond naturally in the model text.";
 
 const coreContractFor = (actor: ExecutableActor): string => {
   if (actor.toolNames?.length === 0) return "";
 
   const lines = [
-    "Alles, was du im Modelltext schreibst, wird automatisch als Ereignis erfasst.",
-    "Dein Turn endet, sobald du kein Werkzeug mehr aufrufst. Danach ruhst du bis zum nächsten ActorInput.",
+    "Everything you write in the model text is automatically recorded as an event.",
+    "Your turn ends as soon as you no longer call a tool. After that you are idle until the next ActorInput.",
   ];
   if (hasTool(actor, "actor_input", "actor.input")) {
-    lines.push("Mit context.functions.actor_input gibst du einem anderen Actor einen Auftrag oder eine Rückfrage.");
+    lines.push("With context.functions.actor_input you give another actor a task or a question.");
   }
   if (hasTool(actor, "event_subscribe", "event.subscribe")) {
-    lines.push("Mit context.functions.event_subscribe abonnierst du die Ereignisse der Actors, deren Arbeit du verfolgen willst.");
+    lines.push("With context.functions.event_subscribe you subscribe to the events of the actors whose work you want to follow.");
   }
   if (hasTool(actor, "event_subscription_list", "event.subscribe")) {
-    lines.push("context.functions.event_subscription_list zeigt deine aktiven Ereignisabonnements.");
+    lines.push("context.functions.event_subscription_list shows your active event subscriptions.");
   }
   if (hasTool(actor, "event_unsubscribe", "event.subscribe")) {
-    lines.push("Nicht mehr benötigte Abonnements beendest du mit context.functions.event_unsubscribe.");
+    lines.push("You end subscriptions you no longer need with context.functions.event_unsubscribe.");
   }
   if (hasTool(actor, "agent_spawn", "agent.spawn") && hasTool(actor, "actor_input", "actor.input")) {
-    lines.push("context.functions.agent_spawn erzeugt nur den Actor. Gib ihm seinen ersten Auftrag anschließend mit context.functions.actor_input.");
+    lines.push("context.functions.agent_spawn only creates the actor. Give it its first task afterwards with context.functions.actor_input.");
   }
   return lines.join("\n");
 };
@@ -211,7 +212,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     if (model.driver !== "agent") return model;
     const supported = await agentRuntime.thinkingCapabilities(model.provider, model.model);
     const invalid = model.thinking.filter((level) => !supported.includes(level));
-    if (invalid.length) throw new Error(`Die Denktiefen ${invalid.join(", ")} gibt es für ${model.provider}/${model.model} nicht; gültig: ${supported.join(", ")}.`);
+    if (invalid.length) throw new Error(`The thinking levels ${invalid.join(", ")} do not exist for ${model.provider}/${model.model}; valid: ${supported.join(", ")}.`);
     return model;
   }));
   const catalog = new ProductCatalog(configuredModels, () => options.plugins.profiles.profiles());
@@ -240,7 +241,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
   const live = new LiveBus({
     onListenerError: (error, context) => {
       const detail = error instanceof Error ? error.stack ?? error.message : String(error);
-      console.error(`Live-Listener für ${context.runId}/${context.agentId}/${context.event.kind} fehlgeschlagen: ${detail}`);
+      console.error(`Live listener for ${context.runId}/${context.agentId}/${context.event.kind} failed: ${detail}`);
     },
   });
   const workspaceToolNaming = options.plugins.service(workspaceRuntimeToken).toolNaming;
@@ -264,13 +265,13 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     selectedSystemPrompts(promptCatalog, promptIdsFor(runId)).map((option) => {
       const text = optionTexts.get(option.id);
       if (text === undefined) {
-        throw new Error(`Der Systemprompt ${option.id} des Runs ${runId} ist nicht mehr konfiguriert`);
+        throw new Error(`The system prompt ${option.id} of run ${runId} is no longer configured`);
       }
       return text;
     });
   const boundToTools = (entry: PublicPromptContribution, toolNames: readonly string[]): boolean =>
     entry.requiresTools.some((name) => toolNames.includes(name));
-  /** Ein Beitrag darf je Run anders lauten oder fehlen, etwa die Shell-Plattform des Executors oder ein Plugin, dessen Laufbedingung nicht zutrifft; das gilt auch für die gewählten Systemprompts. */
+  /** A contribution may read differently per run or be missing, e.g. the executor's shell platform or a plugin whose run condition does not apply; this also holds for the chosen system prompts. */
   const contentFor = (runId: string | null, texts: () => readonly string[]): ((entry: PublicPromptContribution) => string) => {
     const overrides = runId === null ? undefined : options.plugins.prompts.runOverrides(runId);
     return (entry) => overrides?.get(entry.id)
@@ -328,7 +329,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     registry,
     live,
     modelSelection: (turn, actor) => {
-      if (actor.execution.driver.kind !== "agent") throw new Error("Modellwahl benötigt einen Modell-Actor");
+      if (actor.execution.driver.kind !== "agent") throw new Error("Model choice requires a model actor");
       if (globalChat?.isCoordinator(turn.runId) && globalChat.model) return globalChat.model.forTurn(runtime, turn.runId, actor.id, turn.turnId);
       return isRunCoordinator(runtime, turn.runId, actor.id)
         ? coordinatorSelection(catalog, productRuntime.coordinator, storedModelChoice(journal.stateOf(turn.runId)), actor.execution.driver.config)
@@ -338,7 +339,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     basePrompt: basePromptFor,
     contract: (actor) => coreContractFor(actor),
     toolChapters: (runId, _actor, toolNames) => chaptersFor(runId, toolNames),
-    onError: (error) => console.error(`Turn fehlgeschlagen: ${error instanceof Error ? error.stack ?? error.message : String(error)}`),
+    onError: (error) => console.error(`Turn failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}`),
   });
   const stopExternal: RunStopBoundary = (runId, stopJournal) => scheduler.haltRun(runId, async (
     runtimeStopped,
@@ -350,7 +351,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     const boundedStop = settleRunStop(runId, [journalStopped, pluginStop.bounded]);
     let followFinalStop!: (bounded: Promise<void>) => void;
     const finalBounded = new Promise<void>((resolve) => { followFinalStop = resolve; });
-    void finalBounded.catch((error: unknown) => console.error("Abschließender Plugin-Stopp fehlgeschlagen", error));
+    void finalBounded.catch((error: unknown) => console.error("Final plugin stop failed", error));
     const quarantine = (async () => {
       await Promise.allSettled([runtimeSettled, pluginStop.settled, journalStopped]);
       const afterStop = options.plugins.lifecycle.beginAfterStopSession(runId);
@@ -360,7 +361,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
       afterStop.release();
       pluginStop.release();
 
-      throwRejected([...finalCleanup, ...finalJournal], `Plugin-Nachlauf für Run ${runId} konnte nicht sicher bereinigt werden`);
+      throwRejected([...finalCleanup, ...finalJournal], `Plugin follow-up for run ${runId} could not be cleaned up safely`);
     })();
     scheduler.quarantineRun(runId, quarantine);
     await boundedStop;
@@ -370,7 +371,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
         Promise.all([quarantine, finalBounded]),
         new Promise<never>((_, reject) => {
           timeout = setTimeout(() => reject(new Error(
-            `Der abschließende Stopp von Run ${runId} hat die Zeitgrenze von ${FINAL_RUN_STOP_TIMEOUT_MS} ms überschritten; der Run bleibt bis zur Bereinigung gesperrt.`,
+            `The final stop of run ${runId} exceeded the time limit of ${FINAL_RUN_STOP_TIMEOUT_MS} ms; the run stays locked until cleanup.`,
           )), FINAL_RUN_STOP_TIMEOUT_MS);
         }),
       ]);
@@ -380,7 +381,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
   });
   const settleRunStop = async (runId: string, operations: readonly Promise<void>[]): Promise<void> => {
     const results = await Promise.allSettled(operations);
-    throwRejected(results, `Run ${runId} konnte nicht vollständig gestoppt werden`);
+    throwRejected(results, `Run ${runId} could not be stopped completely`);
   };
   const runStopper = new RunStopper({
     runtime,
@@ -397,7 +398,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
     assertAvailable: options.assertAvailable,
     assertRunUsable: options.assertRunUsable,
     assertRunRights: (access: AccessContext, runId: string, kind: RunRightsKind) => assertRunRights(access, runId, kind, runAccess),
-    projectView: accessibleRunView,
+    projectView: (view: RunView, access: AccessContext) => accessibleRunView(view, access, options.plugins.accessProjections),
     hasRun: (runId: string) => journal.stateOf(runId) !== null,
   };
   const methods = runtimeMethods({
@@ -442,7 +443,7 @@ export const createEngine = async (options: EngineOptions): Promise<Engine> => {
         nativeTypeScriptExecutor.shutdown(),
       ]);
       journal.close();
-      throwRejected(results, "RAgents-Shutdown fehlgeschlagen");
+      throwRejected(results, "RAgents shutdown failed");
     },
   };
 };

package/apps/server/src/ragents/global-chat.ts

@@ -3,9 +3,9 @@ import type { GlobalRunPolicy } from "../api/rights.js";
 import type { ChatUser, SessionInfo } from "../chat-handler.js";
 
 export interface GlobalChatPolicy {
-  /** 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;
-  /** Jede Kennung, die einem Koordinator vorbehalten ist, auch eine, die keinem Zugang mehr gehört. */
+  /** Every id reserved for a coordinator, including one that no longer belongs to any access. */
   isCoordinator: (runId: string) => boolean;
   access?: { read: string; write: string };
   title: string;
@@ -14,7 +14,7 @@ export interface GlobalChatPolicy {
   toolNames: readonly string[];
   workspaceDirectory: (runId: string) => string;
   prepareWorkspace?: (directory: string) => Promise<void>;
-  /** Je Koordinator eine Datei <runId>.json, solange sein Gesprächsreset nicht abgeschlossen ist. */
+  /** One file <runId>.json per coordinator, as long as its conversation reset is not complete. */
   resetIntentDirectory?: string;
   inputContext?: (runtime: Orchestration, runId: string, value: unknown) => Promise<readonly string[]>;
   contextPrompt?: (runtime: Orchestration, runId: string, actor: ExecutableActor) => string;
@@ -28,18 +28,24 @@ export interface GlobalChatPolicy {
 export type ManagedRunStart = {
   title: string;
   options?: Readonly<Record<string, JsonValue>>;
-  /** Wer die Startoptionen wählt und den Run besitzt: der Benutzer der Anfrage, null ohne Anmeldung. */
+  /** Who chooses the start options and owns the run: the user of the request, null without sign-in. */
   user: ChatUser | null;
 } & ({ kind: "message"; message: string } | { kind: "script"; entryId: string; input: JsonValue }
-  | { kind: "package"; directory: string; input: JsonValue });
+  | {
+    kind: "package";
+    directory: string;
+    input: JsonValue;
+    /** The plugin that starts the package; it stands as the owner of this start's template. */
+    owner: string;
+  });
 
 export interface RunManagement {
-  /** Mit einem Zugang bleiben nur dessen eigene Runs übrig; ohne ihn ist es die Liste des Servers. */
+  /** With an access, only its own runs remain; without one it is the server's list. */
   list: (access?: AccessContext) => Promise<SessionInfo[]>;
   view: (runId: string) => RunView;
   events: (runId: string) => readonly JournalEvent[];
   create: (start: ManagedRunStart) => Promise<string>;
-  /** Eine Nachricht bedient den Run; der Host prüft dafür denselben Zugang wie beim Chat. */
+  /** A message operates the run; the host checks the same access for it as for the chat. */
   send: (runId: string, message: string, access: AccessContext) => Promise<void>;
   stop: (runId: string) => Promise<void>;
   resetGlobal: (runId: string) => Promise<void>;
@@ -47,7 +53,7 @@ export interface RunManagement {
 
 export const globalChatToken = serviceToken<GlobalChatPolicy>("host.global-chat");
 
-/** Die Rechte der Koordinatoren für die Nachrichtenschicht; ohne Rechte des Plugins gilt keiner als eigener Run. */
+/** The coordinators' rights for the message layer; without rights from the plugin, none counts as an own run. */
 export const globalRunPolicyOf = (policy: GlobalChatPolicy | undefined): GlobalRunPolicy | undefined =>
   policy?.access ? { isCoordinator: policy.isCoordinator, runIdFor: policy.runIdFor, ...policy.access } : undefined;
 export const runManagementToken = serviceToken<() => RunManagement>("host.run-management");

package/apps/server/src/ragents/host-services.ts

@@ -5,13 +5,14 @@ import {
   type PluginHost,
   type ServiceToken,
 } from "@ragents/engine";
+import type { ModelRuntime } from "@ragents/agent";
 import type { PreparedExecutorContribution } from "@ragents/workspace-executor";
 import type { SessionWorkspace } from "./workspace-runtime.js";
 import type { RunManagement } from "./global-chat.js";
 
 export const runGuardToken: ServiceToken<(runId: string) => void> = serviceToken("host.run-guard");
 
-/** Jeder Weg von außen zum Arbeitsbereich eines Runs (Dateien, Prozesse, Sprachserver) prüft damit Run und Zugang: ein Run, den nur sein Eigentümer bedient, zeigt seinen Arbeitsbereich nur ihm. */
+/** Every path from outside into a run's workspace (files, processes, language servers) checks run and access with this: a run that only its owner operates shows its workspace only to that owner. */
 export const workspaceGuardToken: ServiceToken<(access: AccessContext, runId: string) => void> = serviceToken("host.workspace-guard");
 
 export const runWorkspaceProviderToken: ServiceToken<(runId: string) => Promise<SessionWorkspace>> =
@@ -21,10 +22,10 @@ export const secretEnvNamesToken: ServiceToken<() => readonly string[]> = servic
 
 export const runtimeProviderToken: ServiceToken<() => Orchestration> = serviceToken("host.runtime-provider");
 
-/** Die Adresse, unter der dieser Server seine API anbietet, etwa http://127.0.0.1:4710; ohne HTTP (nur stdio) keine. */
+/** The address at which this server offers its API, e.g. http://127.0.0.1:4710; none without HTTP (stdio only). */
 export const hostAddressToken: ServiceToken<() => string | undefined> = serviceToken("host.address");
 
-/** Die Beiträge der Bundles dieses Profils zum Executor, gebaut für den Server; jeder Executor des Servers trägt sie, jeder Arbeitsplatz dieselben. */
+/** The executor contributions of this profile's bundles, built for the server; every executor of the server carries them, every workstation the same ones. */
 export const executorContributionsToken: ServiceToken<readonly PreparedExecutorContribution[]> = serviceToken("host.executor-contributions");
 
 export interface HostBridges {
@@ -33,6 +34,8 @@ export interface HostBridges {
   runtime: () => Orchestration;
   sessionWorkspaceFor: (runId: string) => Promise<SessionWorkspace>;
   sessions?: () => RunManagement;
+  /** The server's one model runtime with the profile's providers and aliases. */
+  modelRuntime?: () => Promise<ModelRuntime>;
   apiBaseUrl?: string;
 }
 

package/apps/server/src/ragents/journal-chat-events.ts

@@ -35,7 +35,7 @@ export const journalChatEventsOf = (
   switch (event.type) {
     case "model.output.completed":
     case "model.output.interrupted":
-      if (!cursor) throw new Error("Die Journalposition des Antworttexts fehlt.");
+      if (!cursor) throw new Error("The journal position of the response text is missing.");
       return [{ kind: "text", delta: event.payload.text, at, cursor }];
     case "model.reasoning.completed":
       return [{ kind: "thinking", delta: event.payload.text, at }];

package/apps/server/src/ragents/run-owner.ts

@@ -1,14 +1,14 @@
 import type { Journal, StartOptionContributionRegistry } from "@ragents/engine";
 import { storedStartOption } from "./start-option-state.js";
 
-/** Der Benutzer eines Runs aus seinem Journal: null ohne Eigentümer und für ein gesperrtes Journal ohne Zustand, undefined für eine Kennung ohne Run. */
+/** A run's user from its journal: null without owner and for a locked journal without state, undefined for an id without a run. */
 export const runOwnerOf = (journal: Journal, runId: string): string | null | undefined => {
   const state = journal.stateOf(runId);
   if (state) return state.ownerUserId;
   return journal.failureOf(runId) ? null : undefined;
 };
 
-/** Nur der Eigentümer bedient einen Run, dessen gespeicherte Startoption das für ihren Wert erklärt. */
+/** Only the owner operates a run whose stored start option declares this for its value. */
 export const runOwnerOnly = (journal: Journal, startOptions: StartOptionContributionRegistry, runId: string): boolean => {
   const state = journal.stateOf(runId);
   return startOptions.entries().some(({ option }) => {