@schlenkr/ragents 0.1.4 → 0.1.6

package/{plugins/ragents.product/server/relay.ts → apps/server/src/plugin-support/product-relay.ts}

@@ -1,5 +1,5 @@
-import type { Api, Model } from "@aicontainer/ai";
-import type { ModelProviderRegistration } from "@aicontainer/ragents";
+import type { Api, Model } from "@ragents/ai";
+import type { ModelProviderRegistration } from "@ragents/engine";
 
 export const RELAY_PROVIDER = "relay";
 export const RELAY_API_PATH = "/relay/v1";

package/apps/server/src/plugin-support/product-start-options.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
-import { DomainError, isThinkingLevel, type StartOptionContribution, type ThinkingLevel } from "@aicontainer/ragents";
+import { DomainError, isThinkingLevel, type StartOptionContribution, type ThinkingLevel } from "@ragents/engine";
+import { displayProvider } from "./model-aliases.js";
 import type { ModelChoice } from "./model-choice.js";
 import type { SystemPromptCatalog } from "./system-prompts.js";
 import { modelStartOptionId, systemPromptStartOptionId } from "../ragents/start-option-state.js";
@@ -40,13 +41,16 @@ export const modelStartOption = (choice: ModelChoice, preferredThinking: Thinkin
       }
       return { model, thinking: wanted };
     }
-    const preferred = typeof preferredThinking === "function" ? preferredThinking() : preferredThinking;
+    const coordinatorThinking = typeof preferredThinking === "function" ? preferredThinking() : preferredThinking;
+    const preferred = model === choice.defaultModel ? coordinatorThinking : choice.defaultThinkingFor?.(model) ?? coordinatorThinking;
     const thinking = allowed.includes(preferred) ? preferred : allowed[0];
     return thinking ? { model, thinking } : { model };
   };
   return {
     id: modelStartOptionId,
     schema: modelSchema,
+    rights: ["runs.inspect"],
+    changeable: true,
     selectable: () => choice.selectable,
     defaultValue: () => ({ ...resolved(choice.defaultModel, undefined) }),
     accept: (value) => {
@@ -57,7 +61,7 @@ export const modelStartOption = (choice: ModelChoice, preferredThinking: Thinkin
       const { model } = value as unknown as ModelStartOptionValue;
       return {
         kind: "model",
-        provider: choice.provider,
+        provider: displayProvider(choice.provider),
         options: [...choice.options],
         thinkingOptions: [...choice.thinkingOptionsFor(model)],
       };
@@ -68,6 +72,7 @@ export const modelStartOption = (choice: ModelChoice, preferredThinking: Thinkin
 export const systemPromptStartOption = (catalog: () => SystemPromptCatalog): StartOptionContribution => ({
   id: systemPromptStartOptionId,
   schema: systemPromptSchema,
+  rights: ["runs.inspect"],
   selectable: () => catalog().mode === "selectable" && catalog().options.length > 0,
   defaultValue: () => ({ promptIds: [...catalog().defaultIds], shareWithAgents: catalog().shareDefault }),
   accept: (value) => {

package/apps/server/src/plugin-support/prompt.ts

@@ -4,7 +4,7 @@ import {
   PromptContributionRegistry,
   type PromptContribution,
   type PromptRenderContext,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
 import { selectedSystemPrompts, type SystemPromptCatalog } from "./system-prompts.js";
 
 export const handlebarsPrompt = (

package/apps/server/src/plugin-support/provision.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { promisify } from "node:util";
 import { readZipEntries, readZipNames } from "./zip.js";
@@ -18,6 +19,11 @@ export interface PluginProvision {
 
 export const provisionReady: ProvisionState = { kind: "ready" };
 
+const hostRequire = createRequire(import.meta.url);
+
+/** The folder of a package the host provides, for tools a plugin starts as a separate process. */
+export const hostPackageFolder = (name: string): string => path.dirname(hostRequire.resolve(`${name}/package.json`));
+
 export const provisionGap = (name: string, instruction: string, installable: boolean): ProvisionState =>
   ({ kind: "gap", name, instruction, installable });
 

package/apps/server/src/plugin-support/run-scripts.ts

@@ -1,12 +1,12 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
-import type { ActorProgramFile, StartEntryContribution } from "@aicontainer/ragents";
+import type { ActorProgramFile, JsonValue, StartEntryContribution } from "@ragents/engine";
 import { flag, frontMatterOf, numberOf, tagsOf } from "./front-matter.js";
 
 export type ScriptStartEntry = Extract<StartEntryContribution, { action: "script" }>;
 
 const PACKAGE_NAME = /^[a-z0-9][a-z0-9-]*$/;
-const RUN_FIELDS = ["title", "description", "order", "guide", "tags", "coordinator", "category"];
+const RUN_FIELDS = ["title", "description", "order", "guide", "tags", "coordinator", "category", "fixed-start-options"];
 
 const requiredFile = (directory: string, name: string): string => {
   const file = path.join(directory, name);
@@ -14,6 +14,18 @@ const requiredFile = (directory: string, name: string): string => {
   return file;
 };
 
+/** Die Kopfzeile fixed-start-options ist ein JSON-Objekt in einer Zeile: Startoption-Id auf festen Wert. */
+const fixedStartOptionsOf = (file: string, value: string | undefined): Readonly<Record<string, JsonValue>> | undefined => {
+  if (value === undefined) return undefined;
+  let parsed: unknown;
+  try { parsed = JSON.parse(value); }
+  catch (error) { throw new Error(`${file}: fixed-start-options ist kein JSON (${error instanceof Error ? error.message : String(error)})`); }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${file}: fixed-start-options muss ein JSON-Objekt aus Startoption-Id und Wert sein`);
+  }
+  return parsed as Record<string, JsonValue>;
+};
+
 const packageFiles = (directory: string, relative = ""): ActorProgramFile[] =>
   readdirSync(path.join(directory, relative), {withFileTypes: true})
     .sort((left, right) => left.name.localeCompare(right.name))
@@ -47,6 +59,7 @@ const runScriptFrom = (directory: string, name: string, id: string): ScriptStart
   const tags = tagsOf(runFile, fields.get("tags"));
   const category = fields.get("category");
   if (category !== undefined && !category.trim()) throw new Error(`${runFile}: category ist leer`);
+  const fixedStartOptions = fixedStartOptionsOf(runFile, fields.get("fixed-start-options"));
   const programsDirectory = path.join(directory, "actors");
   const programsStats = statSync(programsDirectory, {throwIfNoEntry: false});
   if (programsStats && !programsStats.isDirectory()) throw new Error(`${programsDirectory} muss ein Verzeichnis sein`);
@@ -63,6 +76,7 @@ const runScriptFrom = (directory: string, name: string, id: string): ScriptStart
     ...(guide ? {guide} : {}),
     ...(tags !== undefined ? {tags} : {}),
     ...(category ? {category} : {}),
+    ...(fixedStartOptions !== undefined ? {fixedStartOptions} : {}),
     script: {
       handle: name,
       coordinator: flag(runFile, "coordinator", fields.get("coordinator"), true),

package/apps/server/src/plugin-support/skills.ts

@@ -1,7 +1,7 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
-import { parseFrontmatter } from "@aicontainer/agent";
-import type { StartEntryContribution } from "@aicontainer/ragents";
+import { parseFrontmatter, type Skill } from "@ragents/agent";
+import type { StartEntryContribution } from "@ragents/engine";
 import { flag, FRONT_MATTER, numberOf, tagsOf } from "./front-matter.js";
 import type { DeclaredEnvironment } from "./plugin-config.js";
 
@@ -16,9 +16,16 @@ export const skillEnvDescriptors = [
   { key: "SKILLS_DIR", source: "environment" },
 ] as const;
 
+/** The alias under which every skill folder is readable, whichever machine a run works on. */
+export const SKILLS_ALIAS = "@skills";
+
+/** A skill is reached as `@skills/<name>`; its name is its folder name and unique in the profile. */
+export const skillRootAlias = (name: string): string => `${SKILLS_ALIAS}/${name}`;
+
 type SkillEnvironment = DeclaredEnvironment<(typeof skillEnvDescriptors)[number]["key"]>;
 
-const skillStartFrom = (directory: string, idPrefix: string): SkillStartEntry | undefined => {
+/** Reads and checks the SKILL.md of a skill folder; the one parser for templates and the skills of agents. */
+const readSkill = (directory: string): { skill: Skill; start: (idPrefix: string) => SkillStartEntry | undefined } => {
   const file = path.join(directory, "SKILL.md");
   if (!statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`Dem Skill ${directory} fehlt die SKILL.md`);
   const raw = readFileSync(file, "utf8");
@@ -45,11 +52,14 @@ const skillStartFrom = (directory: string, idPrefix: string): SkillStartEntry |
   const description = fields.get("description");
   if (!description) throw new Error(`${file}: description fehlt`);
   if (!body.trim()) throw new Error(`${file}: Skill-Anleitung ist leer`);
-  flag(file, "disable-model-invocation", fields.get("disable-model-invocation"));
+  const disableModelInvocation = flag(file, "disable-model-invocation", fields.get("disable-model-invocation"));
   flag(file, "user-invokable", fields.get("user-invokable"));
   const order = numberOf(file, "order", fields.get("order"));
   const tags = tagsOf(file, fields.get("tags"));
-  if (!flag(file, "start", fields.get("start"))) return undefined;
+  const skill: Skill = {
+    name, description, filePath: path.resolve(file), baseDir: path.resolve(directory), location: `${skillRootAlias(name)}/SKILL.md`, disableModelInvocation,
+  };
+  if (!flag(file, "start", fields.get("start"))) return { skill, start: () => undefined };
   const title = fields.get("title");
   if (!title) throw new Error(`${file}: title fehlt`);
   const category = fields.get("category");
@@ -59,19 +69,25 @@ const skillStartFrom = (directory: string, idPrefix: string): SkillStartEntry |
   const guide = fields.get("guide");
   if (guide !== undefined && !guide) throw new Error(`${file}: guide ist leer`);
   return {
-    id: `${idPrefix}.${name}`,
-    action: "skill",
-    skill: name,
-    title,
-    description,
-    category,
-    prompt,
-    ...(order !== undefined ? { order } : {}),
-    ...(tags !== undefined ? { tags } : {}),
-    ...(guide !== undefined ? { guide } : {}),
+    skill,
+    start: (idPrefix) => ({
+      id: `${idPrefix}.${name}`,
+      action: "skill",
+      skill: name,
+      title,
+      description,
+      category,
+      prompt,
+      ...(order !== undefined ? { order } : {}),
+      ...(tags !== undefined ? { tags } : {}),
+      ...(guide !== undefined ? { guide } : {}),
+    }),
   };
 };
 
+/** The skill of a skill folder as an agent sees it. */
+export const skillOfDirectory = (directory: string): Skill => readSkill(directory).skill;
+
 export const skillsFromDirectory = (directory: string, idPrefix: string): FolderSkills => {
   const resolved = path.resolve(directory);
   let entries;
@@ -85,7 +101,7 @@ export const skillsFromDirectory = (directory: string, idPrefix: string): Folder
   const paths = entries.map((entry) => path.join(resolved, entry.name)).sort();
   if (paths.length === 0) throw new Error(`${resolved} enthält keinen Skill-Ordner`);
   const startEntries = paths.flatMap((skillPath) => {
-    const entry = skillStartFrom(skillPath, idPrefix);
+    const entry = readSkill(skillPath).start(idPrefix);
     return entry ? [entry] : [];
   });
   return { startEntries, paths };

package/apps/server/src/plugin-support/start-entries-contract.ts

@@ -1,5 +1,8 @@
 export type StartEntryAction = "skill" | "script";
 
+/** Dieselbe JSON-Form wie im Kern; der Vertrag bleibt importfrei. */
+export type JsonValue = null | string | number | boolean | JsonValue[] | { [key: string]: JsonValue | undefined };
+
 export interface StartEntryBase {
   id: string;
   owner: string;
@@ -8,9 +11,11 @@ export interface StartEntryBase {
   order?: number;
   guide?: string;
   tags?: readonly string[];
+  /** Startoptionen, die die Vorlage festlegt: ein Run über sie läuft genau mit diesen Werten. */
+  fixedStartOptions?: Readonly<Record<string, JsonValue>>;
 }
 
-/** One entry of the start surface as GET /api/plugins publishes it; a script entry never carries its source. */
+/** One template of the start page as ragents.plugins.bootstrap publishes it; a script template never carries its source. */
 export type StartEntry = StartEntryBase & (
   | { action: "skill"; skill: string; category: string; prompt: string }
   | { action: "script"; coordinator: boolean; category?: string }
@@ -24,9 +29,9 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 
 const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
 
-const BASE_FIELDS = ["id", "owner", "title", "description", "order", "guide", "tags", "action"];
+const BASE_FIELDS = ["id", "owner", "title", "description", "order", "guide", "tags", "fixedStartOptions", "action"];
 
-const invalid = (detail: string): Error => new Error(`Die Plugin-Konfiguration enthält einen ungültigen Einstieg: ${detail}`);
+const invalid = (detail: string): Error => new Error(`Die Plugin-Konfiguration enthält eine ungültige Vorlage: ${detail}`);
 
 export const startEntryFrom = (value: unknown): StartEntry => {
   if (!isRecord(value)) throw invalid("kein Objekt");
@@ -40,6 +45,9 @@ export const startEntryFrom = (value: unknown): StartEntry => {
     || new Set(value.tags).size !== value.tags.length)) {
     throw invalid(`${id}: tags müssen eindeutige, nicht leere Schlagworte sein`);
   }
+  if (value.fixedStartOptions !== undefined && (!isRecord(value.fixedStartOptions) || Object.keys(value.fixedStartOptions).length === 0)) {
+    throw invalid(`${id}: fixedStartOptions muss mindestens eine Startoption festlegen`);
+  }
   const base: StartEntryBase = {
     id,
     owner: value.owner,
@@ -48,6 +56,7 @@ export const startEntryFrom = (value: unknown): StartEntry => {
     ...(value.order !== undefined ? { order: value.order } : {}),
     ...(value.guide !== undefined ? { guide: value.guide } : {}),
     ...(value.tags !== undefined ? { tags: [...value.tags] as string[] } : {}),
+    ...(value.fixedStartOptions !== undefined ? { fixedStartOptions: { ...value.fixedStartOptions as Record<string, JsonValue> } } : {}),
   };
   const allowed = (extra: readonly string[]) => {
     const unknown = Object.keys(value).filter((field) => !BASE_FIELDS.includes(field) && !extra.includes(field));

package/apps/server/src/plugin-support/start-options-contract.ts

@@ -9,6 +9,8 @@ export interface StartOptionState {
   presentation: unknown;
   selectable: boolean;
   locked: boolean;
+  /** Ob jemand den Wert vor dem Start gewählt hat; eine Vorlage, die etwas anderes festlegt, lehnt den Start dann ab. */
+  chosen: boolean;
 }
 
 export interface ChoicePresentationOption {
@@ -51,7 +53,8 @@ export const startOptionStateFrom = (value: unknown): StartOptionState => {
     || !("value" in value)
     || !("presentation" in value)
     || typeof value.selectable !== "boolean"
-    || typeof value.locked !== "boolean") {
+    || typeof value.locked !== "boolean"
+    || typeof value.chosen !== "boolean") {
     throw new Error("Die Startoption entspricht nicht dem erwarteten Format");
   }
   return {
@@ -61,5 +64,6 @@ export const startOptionStateFrom = (value: unknown): StartOptionState => {
     presentation: value.presentation,
     selectable: value.selectable,
     locked: value.locked,
+    chosen: value.chosen,
   };
 };

package/apps/server/src/plugin-support/thinking-level.ts

@@ -1,4 +1,5 @@
-import { isThinkingLevel, thinkingLevels, type ThinkingLevel } from "@aicontainer/ragents";
+import { isThinkingLevel, thinkingLevels, type ThinkingLevel } from "@ragents/engine";
+import { modelDefaultThinking } from "./model-aliases.js";
 
 export const checkedThinkingLevel = (value: string, label: string): ThinkingLevel => {
   if (!isThinkingLevel(value)) {
@@ -6,3 +7,7 @@ export const checkedThinkingLevel = (value: string, label: string): ThinkingLeve
   }
   return value;
 };
+
+/** Die Denktiefe einer Rolle: ihr Schlüssel, sonst die Denktiefe, die der Alias ihres Modells mitbringt, sonst high. */
+export const roleThinkingLevel = (configured: string | undefined, label: string, provider: string, model: string): ThinkingLevel =>
+  checkedThinkingLevel(configured || modelDefaultThinking(provider, model) || "high", label);

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

@@ -1,19 +1,13 @@
 import {
   defineToolAvailability,
-  holdsUsable,
   type ToolAvailability,
-} from "@aicontainer/ragents";
+} from "@ragents/engine";
 
 export const alwaysAvailable = defineToolAvailability({
   availability: "always",
   availabilityDetail: "In jedem Modell-Turn verfügbar.",
 }, () => true);
 
-export const canUseWorkspace = defineToolAvailability({
-  availability: "conditional",
-  availabilityDetail: "Nur mit der Capability workspace.use.",
-}, (actor) => holdsUsable(actor, "workspace.use"));
-
 export const facesOperator: ToolAvailability = defineToolAvailability({
   availability: "always",
   availabilityDetail: "In jedem Turn verfügbar; die Frage geht immer an den Benutzer des Runs.",

package/apps/server/src/plugin-support/workspace-ownership.ts

@@ -1,6 +1,6 @@
 import { chmod, chown, lstat, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
-import { containsWorkspacePath } from "@aicontainer/workspace-executor";
+import { containsWorkspacePath } from "@ragents/workspace-executor";
 
 export interface WorkspaceIdentity {
   uid?: number;
@@ -8,6 +8,12 @@ export interface WorkspaceIdentity {
   storageRoot?: string;
 }
 
+/** Was während des Abgleichs verschwindet, etwa ein umbenanntes Paket aus dem Staging, braucht keine Rechte mehr. */
+const unlessVanished = (error: NodeJS.ErrnoException): undefined => {
+  if (error.code === "ENOENT") return undefined;
+  throw error;
+};
+
 export const syncWorkspaceOwnership = async (directory: string, identity: WorkspaceIdentity): Promise<void> => {
   if (identity.uid === undefined && identity.gid === undefined) return;
   if (identity.uid === undefined || identity.gid === undefined || !identity.storageRoot) {
@@ -18,12 +24,12 @@ export const syncWorkspaceOwnership = async (directory: string, identity: Worksp
   if (!containsWorkspacePath(root, target) || target === root) throw new Error("Das private Arbeitsverzeichnis liegt außerhalb seiner Run-Speichergrenze.");
   const { uid, gid } = identity;
   const visit = async (file: string): Promise<void> => {
-    const info = await lstat(file);
-    if (info.isSymbolicLink() || !info.isDirectory() && !info.isFile()) return;
-    if (info.uid !== uid || info.gid !== gid) await chown(file, uid, gid);
+    const info = await lstat(file).catch(unlessVanished);
+    if (!info || info.isSymbolicLink() || !info.isDirectory() && !info.isFile()) return;
+    if (info.uid !== uid || info.gid !== gid) await chown(file, uid, gid).catch(unlessVanished);
     const mode = info.isDirectory() ? 0o700 : (info.mode & 0o100) | 0o600;
-    if ((info.mode & 0o7777) !== mode) await chmod(file, mode);
-    if (info.isDirectory()) for (const entry of await readdir(file)) await visit(path.join(file, entry));
+    if ((info.mode & 0o7777) !== mode) await chmod(file, mode).catch(unlessVanished);
+    if (info.isDirectory()) for (const entry of await readdir(file).catch(unlessVanished) ?? []) await visit(path.join(file, entry));
   };
   await visit(target);
   for (let ancestor = path.dirname(target); containsWorkspacePath(root, ancestor); ancestor = path.dirname(ancestor)) {