@schlenkr/ragents 0.1.3 → 0.1.5

package/README.md

@@ -22,7 +22,8 @@ npm install -g @schlenkr/ragents
   RAGENTS_TOKEN=<token> ragents connect https://ragents.example.com
   ```
 
-- `start <profile|path>` - start a profile shipped with the package (`core`, `developer`), your
+- `start <profile|path>` - start a profile shipped with the package (`core`, `developer`,
+  `showcase`), your
   own `ragents.config.<name>.ts` anywhere on disk, or a stand that `connect` already fetched,
   without asking the server. The web interface is built for that set of plugins when it is
   missing or was last built for another profile or host version; the result goes to

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

@@ -51,8 +51,9 @@ const resolveUserToken = (
   if (!isEnvironmentReference(raw) || typeof raw.name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(raw.name)) {
     throw new Error(`${location}.token braucht env("ENV_NAME"); ein Token steht nie im Klartext in der Profildatei`);
   }
+  // Ein Benutzer meldet sich weiter mit seinem Passwort an; ohne gesetzte Variable hat er nur keinen persönlichen Token.
   const token = environment[raw.name];
-  if (!token) throw new Error(`${location}.token verweist auf die nicht gesetzte oder leere Umgebungsvariable ${raw.name}`);
+  if (!token) return undefined;
   // $ und ! sind tabu, weil der Verbraucher den Token als API-Schlüssel mit Vorlagen- und Befehlssyntax auswertet.
   if (token.length < MIN_TOKEN_LENGTH || token.length > MAX_TOKEN_LENGTH || !/^[\x21-\x7e]+$/.test(token) || /[$!]/.test(token)) {
     throw new Error(`${location}.token (${raw.name}) braucht ${MIN_TOKEN_LENGTH} bis ${MAX_TOKEN_LENGTH} druckbare ASCII-Zeichen ohne Leerzeichen, $ und !`);

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

@@ -0,0 +1,31 @@
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export interface HostRecord {
+  readonly profile: string;
+  readonly url: string;
+  readonly pid: number;
+  readonly log: string;
+  readonly startedAt: string;
+}
+
+/** Der gemerkte Host eines Profils; ragents run und ragents start schreiben dieselbe Datei, stop --host liest sie. */
+export const hostRecordFile = (dataDirectory: string): string => path.join(dataDirectory, "host.json");
+
+export const readHostRecord = (dataDirectory: string): HostRecord | undefined => {
+  const file = hostRecordFile(dataDirectory);
+  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) return undefined;
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<HostRecord>;
+  // Eine PID unter 1 wäre für process.kill die ganze Prozessgruppe; sie darf nie aus dieser Datei kommen.
+  if (typeof parsed.url !== "string" || !Number.isInteger(parsed.pid) || (parsed.pid ?? 0) < 1) throw new Error(`${file} nennt keine Adresse oder keine PID des Hosts`);
+  return parsed as HostRecord;
+};
+
+export const writeHostRecord = (dataDirectory: string, record: HostRecord): void => {
+  mkdirSync(dataDirectory, { recursive: true });
+  writeFileSync(hostRecordFile(dataDirectory), `${JSON.stringify(record, null, 2)}\n`);
+};
+
+export const removeHostRecord = (dataDirectory: string): void => {
+  rmSync(hostRecordFile(dataDirectory), { force: true });
+};

package/apps/server/src/profile-target.ts

@@ -2,7 +2,9 @@ import { statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { isEnvironmentReference } from "./config-definition.js";
+import { profileFileName } from "./config-file.js";
 import { defaultDataDirectory } from "./data-directory.js";
+import { hostRoot } from "./host-version.js";
 
 export interface ProfileTarget {
   readonly profile: string;
@@ -12,6 +14,29 @@ export interface ProfileTarget {
   readonly baseUrl: string;
 }
 
+export interface LocalProfile {
+  readonly profile: string;
+  readonly profileFile: string;
+}
+
+const PROFILE_FILE = /^ragents\.config\.([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
+
+/** pnpm und der bin-Befehl führen die Skripte mit dem Arbeitsverzeichnis apps/server aus; ein relativer Pfad gilt trotzdem ab dem Aufrufer. */
+export const callerDirectory = (): string => process.env.RAGENTS_CWD ?? process.env.INIT_CWD ?? process.cwd();
+
+/** Ein Profil ist ein Name neben dem Host (Checkout wie Paket) oder ein Pfad zu einer ragents.config.<profil>.ts an beliebiger Stelle. */
+export const localProfile = (selection: string, root = hostRoot(), caller = callerDirectory()): LocalProfile | undefined => {
+  if (!selection.includes("/") && !selection.endsWith(".ts")) {
+    const file = path.join(root, profileFileName(selection));
+    return statSync(file, { throwIfNoEntry: false })?.isFile() ? { profile: selection, profileFile: file } : undefined;
+  }
+  const profileFile = path.resolve(caller, selection);
+  const match = PROFILE_FILE.exec(path.basename(profileFile));
+  if (!match) throw new Error(`Eine Profildatei heißt ragents.config.<profil>.ts, nicht ${path.basename(profileFile)}`);
+  if (!statSync(profileFile, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Profildatei fehlt: ${profileFile}`);
+  return { profile: match[1]!, profileFile };
+};
+
 /** Port und Datenordner eines Profils, wie der Server sie später selbst bestimmt: Umgebung vor Profildatei vor Vorgabe. */
 export const readProfileTarget = async (profile: string, profileFile: string, environment = process.env): Promise<ProfileTarget> => {
   if (!statSync(profileFile, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Profildatei fehlt: ${profileFile}`);
@@ -23,3 +48,10 @@ export const readProfileTarget = async (profile: string, profileFile: string, en
   const dataDirectory = path.resolve(environment.DATA_DIR ?? fromFile ?? defaultDataDirectory(profile));
   return { profile, profileFile, port, dataDirectory, baseUrl: `http://localhost:${port}` };
 };
+
+/** Die eine Auflösung für alle Befehle: Name oder Pfad zum Profil, danach Port und Datenordner wie beim Server. */
+export const selectProfileTarget = async (selection: string, root = hostRoot(), environment = process.env): Promise<ProfileTarget> => {
+  const own = localProfile(selection, root);
+  if (!own) throw new Error(`Die Profildatei fehlt: ${path.join(root, profileFileName(selection))}`);
+  return readProfileTarget(own.profile, own.profileFile, environment);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schlenkr/ragents",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "RAgents-Host: Server, Engine, Plugins und Werkzeuge ohne Quell-Checkout",
   "keywords": [
     "agents",
@@ -11,7 +11,7 @@
     "fsharp",
     "vscode"
   ],
-  "homepage": "https://github.com/SchlenkR/RAgents#readme",
+  "homepage": "https://schlenkr.github.io/RAgents/",
   "bugs": {
     "url": "https://github.com/SchlenkR/RAgents/issues"
   },

package/plugins/ragents.reference/walkthroughs.ts

@@ -5,7 +5,7 @@ export const referenceWalkthroughs = [
     description: "Die Mini-App bleibt als Kachel sichtbar; ihr Besitzer ist auch ohne eigene Kachel erreichbar.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Kachelfläche"],
     steps: [
-      "Im Profil core Sammelboard einrichten öffnen und den Leitfaden abschließen. Erwartung: Die Liste steht als Kachel auf der Fläche; ihr Besitzer hat keine eigene Kachel.",
+      "Im Profil showcase Sammelboard einrichten öffnen und den Leitfaden abschließen. Erwartung: Die Liste steht als Kachel auf der Fläche; ihr Besitzer hat keine eigene Kachel.",
       "In der Kopfzeile Actors öffnen und den Namen des Listenbesitzers wählen. Erwartung: Rechts öffnen sich dessen Chat und Details, ohne die Kachelaufteilung zu ändern.",
       "Den Besitzer aus der Kopfzeile auf die Kachel der Liste ziehen und rechts andocken. Erwartung: Seine Kachel erscheint neben der Liste; die Mini-App bleibt bedienbar und behält ihre Einträge.",
       "Die neue Kachel über das Kreuz in ihrer Kopfzeile wieder entfernen und die App erneut bedienen. Erwartung: Actor und Funktionen arbeiten weiter; sein Name bleibt in der Kopfzeile erreichbar.",
@@ -17,7 +17,7 @@ export const referenceWalkthroughs = [
     description: "Kacheln lassen sich persönlich umstellen und wieder auf die Programmvorgabe zurücksetzen.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Kachelfläche"],
     steps: [
-      "Im Profil core den Einstieg Gesprächsrunde einrichten ausführen und den Aufbau abwarten. Die vom Run gesetzte Aufteilung ansehen.",
+      "Im Profil showcase den Einstieg Gesprächsrunde einrichten ausführen und den Aufbau abwarten. Die vom Run gesetzte Aufteilung ansehen.",
       "Eine Kachel an ihrer Kopfzeile fassen und am oberen Rand einer anderen Kachel andocken. Erwartung: Die Aufteilung ändert sich sofort; alle Gesprächspartner arbeiten weiter.",
       "Die Trennlinie zwischen zwei Kacheln verschieben und denselben Run im selben Browser neu laden. Erwartung: Die persönliche Aufteilung bleibt erhalten; die Actors und die Programmanordnung sind unverändert.",
       "In der Statusleiste Programmvorgabe übernehmen wählen. Erwartung: Die Fläche zeigt wieder die Aufteilung des Runs; der Knopf verschwindet, bis wieder eine eigene Änderung vorliegt.",
@@ -29,7 +29,7 @@ export const referenceWalkthroughs = [
     description: "Der übergeordnete Koordinator liest vorhandene Runs, während die aktuelle Arbeitsfläche geöffnet bleibt.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Globaler Koordinator"],
     steps: [
-      "Im Profil core zwei kurze Unterhaltungen zu einer Leseliste und einem Wochenplan anlegen und ihre Antworten abwarten.",
+      "Im Profil showcase zwei kurze Unterhaltungen zu einer Leseliste und einem Wochenplan anlegen und ihre Antworten abwarten.",
       "In die Eingabe Globaler Koordinator in der Kopfzeile klicken und damit seinen Verlauf öffnen. Um eine knappe Übersicht der beiden Unterhaltungen mit ihrem jeweiligen Arbeitsstand bitten.",
       "Die Run-Liste über die Übersichtsecke oder Cmd+I auf macOS beziehungsweise Ctrl+I öffnen, beide Runs auswählen und die Antwort mit ihren tatsächlichen Unterhaltungen vergleichen. Erwartung: Der globale Chat kann beide Journale berücksichtigen; ein Run-Wechsel erhält seinen eigenen Verlauf.",
       "Einen ungesendeten Entwurf oben eingeben, Escape drücken und den Verlauf wieder öffnen. Erwartung: Das Dropdown schließt ohne Stopp; Entwurf, aktueller Run und globales Gespräch bleiben erhalten.",
@@ -126,7 +126,7 @@ export const referenceWalkthroughs = [
     description: "Eine TypeScript-Prüfung macht den zugehörigen Sprachserver in der Prozessanzeige sichtbar.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Prozessanzeige"],
     steps: [
-      "Im Profil core den Skill-Einstieg Fehler in einer Terminliste finden ausführen. Voraussetzung ist ein verfügbarer TypeScript-Sprachserver; eine fehlende Voraussetzung muss als Fehler gemeldet werden.",
+      "Im Profil showcase den Skill-Einstieg Fehler in einer Terminliste finden ausführen. Voraussetzung ist ein verfügbarer TypeScript-Sprachserver; eine fehlende Voraussetzung muss als Fehler gemeldet werden.",
       "Nach dem Öffnen des Sprachservers die gemeinsame Kopfzeile des Runs ansehen. Erwartung: Der verwaltete Sprachserver erscheint als zu diesem Run gehörender Prozess.",
       "Einen anderen Run öffnen und zurückwechseln. Erwartung: Die Prozessanzeige folgt dem ausgewählten Run und ist kein gemeinsames Verzeichnis aller Rechnerprozesse.",
       "Die Prozessanzeige dient der Beobachtung. Sie bietet keinen Beenden-Knopf; fehlende Betriebssystemrechte oder Werkzeuge werden als sichtbarer Fehler gemeldet.",
@@ -138,7 +138,7 @@ export const referenceWalkthroughs = [
     description: "Ein zeitlich begrenzter Demo-Webprozess erscheint mit seinem erkannten Port in der Kopfzeile.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Prozessanzeige"],
     steps: [
-      "In einem eigenen core-Run den Koordinator bitten, einen kleinen Node-Demoprozess im Run-Arbeitsverzeichnis vorzubereiten: Er liefert nur einen neutralen Begrüßungstext, bindet ausschließlich 127.0.0.1 auf einem freien Port und beendet sich nach zwei Minuten selbst. Keine zusätzlichen Pakete installieren und keinen Produktserver ersetzen.",
+      "In einem eigenen showcase-Run den Koordinator bitten, einen kleinen Node-Demoprozess im Run-Arbeitsverzeichnis vorzubereiten: Er liefert nur einen neutralen Begrüßungstext, bindet ausschließlich 127.0.0.1 auf einem freien Port und beendet sich nach zwei Minuten selbst. Keine zusätzlichen Pakete installieren und keinen Produktserver ersetzen.",
       "Den vorbereiteten Demoprozess starten lassen und bei laufender Ausführung die Kopfzeile ansehen. Erwartung: Der Prozess erscheint mit einem Link auf seinen erkannten offenen Port.",
       "Den Port-Link nur auf demselben Rechner öffnen. Erwartung: Die lokale Demoantwort erscheint; bei einem entfernten Server ist dessen Loopback-Adresse nicht die Adresse des Browsers.",
       "Das vorgesehene automatische Ende abwarten. Erwartung: Der Eintrag verschwindet nach der nächsten Prozessaktualisierung. Run-Stopp oder das Schließen eines Tabs werden hier nicht als Beenden eines abgesetzten Dienstes versprochen.",
@@ -150,7 +150,7 @@ export const referenceWalkthroughs = [
     description: "Ein Run schreibt einen kleinen Text; der Dateireiter zeigt Inhalt und spätere Änderung ohne eigenen Editor.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Dateien und Arbeitsverzeichnis"],
     steps: [
-      "In einem neuen core-Run den Koordinator bitten, im Run-Arbeitsverzeichnis die Datei reading-list.md mit drei neutralen Lesethemen anzulegen.",
+      "In einem neuen showcase-Run den Koordinator bitten, im Run-Arbeitsverzeichnis die Datei reading-list.md mit drei neutralen Lesethemen anzulegen.",
       "Den Reiter Dateien öffnen, das Arbeitsverzeichnis aufklappen und reading-list.md auswählen. Erwartung: Der geschriebene Text erscheint als Vorschau.",
       "Im Chat ein viertes Thema ergänzen lassen und zur weiterhin geöffneten Vorschau zurückkehren. Erwartung: Die Dateiänderung wird im Dateibrowser sichtbar.",
       "Erwartung: Der Dateireiter bleibt eine Leseansicht. Änderungen erfolgen durch den beauftragten Actor und dessen Dateiwerkzeuge, nicht durch einen eingebauten Editor oder Löschknopf.",
@@ -162,8 +162,8 @@ export const referenceWalkthroughs = [
     description: "Zwei unabhängige Arbeitsverzeichnisse enthalten eigene Dateien mit demselben Namen.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Dateien und Arbeitsverzeichnis"],
     steps: [
-      "Einen core-Run Leseliste anlegen und darin notes.md mit dem Inhalt Lesen vorbereiten schreiben lassen.",
-      "Einen zweiten core-Run Wochenplan anlegen und dort ebenfalls notes.md schreiben lassen, diesmal mit dem Inhalt Woche planen. Keine Datei zwischen Runs kopieren.",
+      "Einen showcase-Run Leseliste anlegen und darin notes.md mit dem Inhalt Lesen vorbereiten schreiben lassen.",
+      "Einen zweiten showcase-Run Wochenplan anlegen und dort ebenfalls notes.md schreiben lassen, diesmal mit dem Inhalt Woche planen. Keine Datei zwischen Runs kopieren.",
       "In beiden Runs nacheinander den Reiter Dateien öffnen und notes.md lesen. Erwartung: Der gleiche Dateiname zeigt den jeweils eigenen Inhalt des Run-Arbeitsverzeichnisses.",
       "Nur im Wochenplan eine Zeile ergänzen lassen und beide Vorschauen erneut prüfen. Erwartung: Die Datei des Leselisten-Runs ist unverändert.",
     ],
@@ -174,7 +174,7 @@ export const referenceWalkthroughs = [
     description: "Eine abgeschlossene Actor-Funktion bleibt beim regulären Neustart desselben Profils erhalten.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Wiederherstellung nach Neustart"],
     steps: [
-      "Im Profil core Sammelboard einrichten öffnen und den Leitfaden abschließen. Einen eindeutig erkennbaren Eintrag hinzufügen und die bestätigte Aktualisierung der Liste abwarten.",
+      "Im Profil showcase Sammelboard einrichten öffnen und den Leitfaden abschließen. Einen eindeutig erkennbaren Eintrag hinzufügen und die bestätigte Aktualisierung der Liste abwarten.",
       "Alle laufenden Arbeiten abschließen lassen. Den lokalen Server selbst über den für diese Installation verwendeten Startweg beenden und mit demselben Profil und Datenverzeichnis neu starten. Keine Daten löschen und keine zweite Serverinstanz parallel starten.",
       "Die Anwendung erneut öffnen und denselben Run auswählen. Erwartung: Gespräch, Mini-App und bestätigter Listeneintrag sind wieder vorhanden.",
       "Die Liste auf doppelte Einträge prüfen. Erwartung: Der Neustart stellt gespeicherten Zustand wieder her, führt die bereits abgeschlossene Hinzufügeaktion aber nicht erneut aus. Das Journal allein ersetzt keine vollständige Sicherung der übrigen Run-Dateien.",
@@ -186,7 +186,7 @@ export const referenceWalkthroughs = [
     description: "Normale Unterhaltung und globaler Koordinator behalten ihre jeweils eigene Geschichte.",
     tags: ["Anwendungsfall", "Konzeptdemo", "Wiederherstellung nach Neustart"],
     steps: [
-      "In einem normalen core-Run drei Lernziele besprechen und im globalen Chat eine knappe Übersicht dieses Runs anfordern. Beide Antworten vollständig abwarten und die globale Modellwahl merken.",
+      "In einem normalen showcase-Run drei Lernziele besprechen und im globalen Chat eine knappe Übersicht dieses Runs anfordern. Beide Antworten vollständig abwarten und die globale Modellwahl merken.",
       "Den lokalen Server selbst über den vorhandenen Startweg neu starten, mit demselben Profil und Datenverzeichnis. Keine Dateien entfernen oder zwischen Installationen übertragen.",
       "Den normalen Run und anschließend den globalen Chat öffnen. Erwartung: Beide bisherigen Verläufe und die globale Modellwahl sind erhalten.",
       "Im normalen Run um den nächsten Schritt zu den Lernzielen bitten. Die neue Antwort als neue Arbeit behandeln; der Neustart hat alte Modellaufrufe nicht wiederholt. Ein beim Neustart noch offener Turn wäre unterbrochen abgeschlossen worden und wird nicht automatisch erneut ausgeführt.",

package/ragents.config.core.ts

@@ -21,7 +21,6 @@ export const config = {
       "ragents.watch",
       "ragents.transcript",
       "ragents.actor-programs",
-      "ragents.reference",
       "ragents.lsp-roslyn",
       "ragents.lsp-fsharp",
       "ragents.lsp-typescript",

package/ragents.config.showcase.ts

@@ -0,0 +1,64 @@
+// Schaufenster: das Profil core und zusätzlich die mitgelieferten Beispiele aus ragents.reference.
+import { env, provisioned, type RAgentsConfig } from "./apps/server/src/config-definition.js";
+
+export const config = {
+  host: {
+    PORT: 4713,
+    PRODUCT_PROFILE: "showcase",
+    COMPACTION_MODEL: "google/gemma-4-26b-a4b-it",
+    PRODUCT_ID: "ragents-showcase",
+    PRODUCT_TITLE: "RAgents Showcase",
+    PLUGINS: [
+      "ragents.orchestration",
+      "ragents.workspace",
+      "ragents.product",
+      "ragents.overseer",
+      "ragents.activity",
+      "ragents.processes",
+      "ragents.documents",
+      "ragents.browser",
+      "ragents.ask",
+      "ragents.todo",
+      "ragents.watch",
+      "ragents.transcript",
+      "ragents.actor-programs",
+      "ragents.reference",
+      "ragents.lsp-roslyn",
+      "ragents.lsp-fsharp",
+      "ragents.lsp-typescript",
+      "ragents.model-relay",
+      "ragents.profile-distribution",
+    ],
+  },
+
+  "ragents.product": {
+    OPENROUTER_API_KEY: env("OPENROUTER_API_KEY"),
+    AGENT_MODEL: "z-ai/glm-5.3-flash",
+    AGENT_MODELS: [
+      "deepseek/deepseek-v4-flash-0731",
+      "deepseek/deepseek-v4-pro-0813",
+      "qwen/qwen3.8-max",
+      "z-ai/glm-5.3",
+      "z-ai/glm-5.3-flash",
+      "qwen/qwen3.8-flash",
+      "moonshotai/kimi-k3",
+      "minimax/minimax-m3",
+      "qwen/qwen3.8-27b",
+      "moonshotai/kimi-k2.7-code",
+    ],
+    AGENT_COORDINATOR_MODEL: "z-ai/glm-5.3-flash",
+    AGENT_COORDINATOR_THINKING: "high",
+  },
+
+  // Modell-Relay: Aliasse für andere RAgents-Server, die ihre Modelle von hier beziehen.
+  "ragents.model-relay": {
+    RELAY_MODELS: ["showcase-standard=openrouter/z-ai/glm-5.3-flash", "showcase-coordinator=openrouter/deepseek/deepseek-v4-flash-0731"],
+  },
+
+  "ragents.lsp-roslyn": {
+    ROSLYN_LANGUAGE_SERVER: provisioned("ragents.lsp-roslyn", "roslyn/Microsoft.CodeAnalysis.LanguageServer.dll"),
+  },
+  "ragents.lsp-fsharp": {
+    FSHARP_LANGUAGE_SERVER: provisioned("ragents.lsp-fsharp", "fsautocomplete/fsautocomplete.dll"),
+  },
+} as const satisfies RAgentsConfig;

package/scripts/agent/agent-cli.ts

@@ -2,14 +2,15 @@
 import "../../apps/server/src/host-resolution.ts";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { coreContracts } from "../../apps/server/src/api/contracts.ts";
-import { profileFileName } from "../../apps/server/src/config-file.ts";
+import { hostRecordFile, readHostRecord, removeHostRecord, writeHostRecord } from "../../apps/server/src/host-record.ts";
 import { hostRoot } from "../../apps/server/src/host-version.ts";
-import { readProfileTarget, type ProfileTarget } from "../../apps/server/src/profile-target.ts";
+import { callerDirectory, selectProfileTarget, type ProfileTarget } from "../../apps/server/src/profile-target.ts";
 import { RpcClient } from "../../apps/web/src/rpc/client.ts";
+import { RpcError } from "../../packages/ragents/src/rpc/protocol.ts";
 import { WORKSPACE_BINDING_OPTION_ID } from "../../plugins/ragents.workspace/contract.ts";
 import { JournalReader, journalLines, readJournal, RUN_ID_PATTERN, type JournalEvent } from "./journal.ts";
 
@@ -18,6 +19,10 @@ const HOST_START_TIMEOUT_MS = 120_000;
 const HOST_STOP_TIMEOUT_MS = 20_000;
 const POLL_INTERVAL_MS = 400;
 const HEALTH_TIMEOUT_MS = 2_000;
+const CHAT_READY_TIMEOUT_MS = 60_000;
+
+/** Vorgabeprofil der Agentenbefehle; RAGENTS_PROFILE gilt für alle Befehle derselben Shell. */
+export const defaultProfile = (): string => process.env.RAGENTS_PROFILE ?? DEFAULT_PROFILE;
 
 export const usage = (): string => `Verwendung: ragents <befehl> [argumente]
 
@@ -31,11 +36,13 @@ export const usage = (): string => `Verwendung: ragents <befehl> [argumente]
   stop <run> [--profile <p>]      den laufenden Turn abbrechen
   stop --host [--profile <p>]     den gemerkten Host beenden
 
-Vorgabeprofil ist ${DEFAULT_PROFILE}. Exit-Code: 0 fertig, 2 abgebrochen, 1 fehlgeschlagen oder
-Verbindungsproblem. Die letzte Zeile auf stdout ist "run: <id>". Die Adresse kommt aus
-<Datenordner>/host.json, sonst aus RAGENTS_URL, sonst aus host.PORT des Profils; RAGENTS_TOKEN
-geht als Bearer-Token mit, falls das Profil eine Anmeldung verlangt. Der so gestartete Host baut
-die Oberfläche nicht - ein Agent braucht sie nicht; mit Oberfläche startet ragents start <profil>.`;
+<p> ist ein Profilname neben dem Host oder der Pfad zu einer ragents.config.<profil>.ts an
+beliebiger Stelle; ohne --profile gilt RAGENTS_PROFILE, sonst ${DEFAULT_PROFILE}. Exit-Code:
+0 fertig, 2 abgebrochen, 1 fehlgeschlagen oder Verbindungsproblem. Die letzte Zeile auf stdout
+ist "run: <id>". Die Adresse kommt aus <Datenordner>/host.json, sonst aus RAGENTS_URL, sonst aus
+host.PORT des Profils; RAGENTS_TOKEN geht als Bearer-Token mit, falls das Profil eine Anmeldung
+verlangt. Der so gestartete Host baut die Oberfläche nicht - ein Agent braucht sie nicht; mit
+Oberfläche startet ragents start <profil>.`;
 
 export type AgentCommand =
   | { readonly kind: "run"; readonly profile: string; readonly folder: string; readonly text: string; readonly entry: string | undefined; readonly json: boolean }
@@ -76,7 +83,7 @@ const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
     index += 1;
   }
   return {
-    profile: values.get("--profile") ?? DEFAULT_PROFILE,
+    profile: values.get("--profile") ?? defaultProfile(),
     entry: values.get("--entry"),
     json: switches.has("--json"),
     tools: switches.has("--tools"),
@@ -125,35 +132,7 @@ export const parseArguments = (argv: readonly string[]): AgentCommand => {
   throw new Error(command ? `Unbekannter Befehl: ${command}\n\n${usage()}` : usage());
 };
 
-export interface HostRecord {
-  readonly profile: string;
-  readonly url: string;
-  readonly pid: number;
-  readonly log: string;
-  readonly startedAt: string;
-}
-
-export const hostRecordFile = (dataDirectory: string): string => path.join(dataDirectory, "host.json");
-
-export const readHostRecord = (dataDirectory: string): HostRecord | undefined => {
-  const file = hostRecordFile(dataDirectory);
-  if (!statSync(file, { throwIfNoEntry: false })?.isFile()) return undefined;
-  const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<HostRecord>;
-  // Eine PID unter 1 wäre für process.kill die ganze Prozessgruppe; sie darf nie aus dieser Datei kommen.
-  if (typeof parsed.url !== "string" || !Number.isInteger(parsed.pid) || (parsed.pid ?? 0) < 1) throw new Error(`${file} nennt keine Adresse oder keine PID des Hosts`);
-  return parsed as HostRecord;
-};
-
-export const writeHostRecord = (dataDirectory: string, record: HostRecord): void => {
-  mkdirSync(dataDirectory, { recursive: true });
-  writeFileSync(hostRecordFile(dataDirectory), `${JSON.stringify(record, null, 2)}\n`);
-};
-
-export const loadProfile = (profile: string, root = hostRoot()): Promise<ProfileTarget> =>
-  readProfileTarget(profile, path.join(root, profileFileName(profile)));
-
-/** pnpm und der bin-Befehl führen dieses Skript mit dem Arbeitsverzeichnis apps/server aus; ein relativer Ordner gilt trotzdem ab dem Aufrufer. */
-export const callerDirectory = (): string => process.env.RAGENTS_CWD ?? process.env.INIT_CWD ?? process.cwd();
+export const loadProfile = (selection: string, root = hostRoot()): Promise<ProfileTarget> => selectProfileTarget(selection, root);
 
 const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -239,6 +218,34 @@ const client = (baseUrl: string): RpcClient => {
   });
 };
 
+export const LOGIN_REQUIRED = "Das Profil verlangt eine Anmeldung; setze RAGENTS_TOKEN auf den persönlichen Token deines Benutzers "
+  + "(im Profil `token: env(...)`).";
+
+/** Ein 401 ist keine Fehlermeldung des Servers wert, sondern der Hinweis auf den persönlichen Token des Profils. */
+export const withLoginHint = async <T>(call: () => Promise<T>): Promise<T> => {
+  try {
+    return await call();
+  } catch (error) {
+    if (error instanceof RpcError && error.status === 401) throw new Error(`${LOGIN_REQUIRED} ${error.message}`);
+    throw error;
+  }
+};
+
+/** Ein Einstieg richtet den Run erst ein und bestimmt dabei seinen Chatpartner; bis dahin lehnt der Server die Nachricht ab. */
+const sendWhenChatReady = async (rpc: RpcClient, runId: string, text: string): Promise<void> => {
+  const deadline = Date.now() + CHAT_READY_TIMEOUT_MS;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      await rpc.call(coreContracts.chat.send, { runId, text });
+      return;
+    } catch (error) {
+      if (!(error instanceof RpcError) || error.domainCode !== "actor-chat-unsupported" || Date.now() >= deadline) throw error;
+      if (attempt === 0) note("== Der Einstieg richtet den Run ein; der Auftrag wartet auf seinen Chatpartner.");
+      await delay(POLL_INTERVAL_MS);
+    }
+  }
+};
+
 export type TurnOutcome = "completed" | "interrupted" | "failed";
 
 export const EXIT_CODES: Readonly<Record<TurnOutcome, number>> = { completed: 0, interrupted: 2, failed: 1 };
@@ -351,11 +358,18 @@ const runCommand = async (command: Extract<AgentCommand, { kind: "run" }>, write
   const baseUrl = await ensureHost(target);
   const rpc = client(baseUrl);
   const runId = randomUUID();
-  await rpc.call(coreContracts.startOptions.select, { runId, optionId: WORKSPACE_BINDING_OPTION_ID, value: { kind: "path", path: folder } });
-  note(`== Run ${runId} auf ${folder} (${baseUrl})`);
+  const options = await withLoginHint(() => rpc.call(coreContracts.startOptions.list, { runId }));
+  if (options.some((option) => option.id === WORKSPACE_BINDING_OPTION_ID)) {
+    await withLoginHint(() => rpc.call(coreContracts.startOptions.select, { runId, optionId: WORKSPACE_BINDING_OPTION_ID, value: { kind: "path", path: folder } }));
+    note(`== Run ${runId} auf ${folder} (${baseUrl})`);
+  } else {
+    note(`== Run ${runId} (${baseUrl}); das Profil ${target.profile} kennt ${WORKSPACE_BINDING_OPTION_ID} nicht und legt seinen Arbeitsbereich selbst an, ${folder} bleibt ungebunden.`);
+  }
   const reader = new JournalReader(target.dataDirectory, runId);
-  if (command.entry) await rpc.call(coreContracts.chat.start, { runId, entry: command.entry });
-  await rpc.call(coreContracts.chat.send, { runId, text: command.text });
+  if (command.entry) await withLoginHint(() => rpc.call(coreContracts.chat.start, { runId, entry: command.entry }));
+  await withLoginHint(() => command.entry
+    ? sendWhenChatReady(rpc, runId, command.text)
+    : rpc.call(coreContracts.chat.send, { runId, text: command.text }).then(() => undefined));
   const outcome = await follow({ reader, baseUrl, text: command.text.trim(), json: command.json, write });
   write(`run: ${runId}`);
   return EXIT_CODES[outcome];
@@ -368,7 +382,7 @@ const sendCommand = async (command: Extract<AgentCommand, { kind: "send" }>, wri
   const rpc = client(baseUrl);
   const reader = new JournalReader(target.dataDirectory, command.runId);
   reader.next();
-  await rpc.call(coreContracts.chat.send, { runId: command.runId, text: command.text });
+  await withLoginHint(() => rpc.call(coreContracts.chat.send, { runId: command.runId, text: command.text }));
   const outcome = await follow({ reader, baseUrl, text: command.text.trim(), json: command.json, write });
   write(`run: ${command.runId}`);
   return EXIT_CODES[outcome];
@@ -385,7 +399,7 @@ const journalCommand = async (command: Extract<AgentCommand, { kind: "journal" }
 const stopCommand = async (command: Extract<AgentCommand, { kind: "stop" }>): Promise<number> => {
   const target = await loadProfile(command.profile);
   const baseUrl = await addressOf(target);
-  await client(baseUrl).call(coreContracts.chat.stop, { runId: command.runId });
+  await withLoginHint(() => client(baseUrl).call(coreContracts.chat.stop, { runId: command.runId }));
   note(`== Turn von ${command.runId} abgebrochen`);
   return 0;
 };
@@ -404,7 +418,7 @@ const stopHostCommand = async (command: Extract<AgentCommand, { kind: "stop-host
   const noted = readHostRecord(target.dataDirectory);
   if (!noted) throw new Error(`Für das Profil ${command.profile} ist kein Host gemerkt (${hostRecordFile(target.dataDirectory)} fehlt).`);
   if (!alive(noted.pid)) {
-    rmSync(hostRecordFile(target.dataDirectory), { force: true });
+    removeHostRecord(target.dataDirectory);
     note(`== Der gemerkte Host (PID ${noted.pid}) läuft nicht mehr; der Vermerk ist weg.`);
     return 0;
   }
@@ -415,7 +429,7 @@ const stopHostCommand = async (command: Extract<AgentCommand, { kind: "stop-host
     process.kill(noted.pid, "SIGKILL");
     await delay(500);
   }
-  rmSync(hostRecordFile(target.dataDirectory), { force: true });
+  removeHostRecord(target.dataDirectory);
   note(`== Host ${noted.url} (PID ${noted.pid}) beendet`);
   return 0;
 };
@@ -430,10 +444,14 @@ export const execute = async (command: AgentCommand, write: LineWriter = toStdou
 
 const main = async (): Promise<number> => {
   const argv = process.argv.slice(2);
-  if (argv.length === 0 || argv[0] === "--help") {
+  if (argv[0] === "--help" || argv[0] === "help") {
     console.log(usage());
     return 0;
   }
+  if (argv.length === 0) {
+    console.error(usage());
+    return 1;
+  }
   return execute(parseArguments(argv));
 };
 

package/scripts/package/build-package.ts

@@ -22,7 +22,7 @@ const SKIPPED_IN_PACKAGE = /^scripts\/.*\.test\.tsx?$/;
 const packagePath = (packageRoot: string, file: string): string => path.relative(packageRoot, file).split(path.sep).join("/");
 
 /** Die neutralen Profile des Repositories; ragents start fährt sie aus dem Paket wie aus dem Checkout. */
-export const PACKAGED_PROFILES = ["core", "developer"] as const;
+export const PACKAGED_PROFILES = ["core", "developer", "showcase"] as const;
 
 export const PACKAGE_LICENSE = "PolyForm-Shield-1.0.0";
 export const PACKAGE_AUTHOR = "Ronald Schlenker";
@@ -217,7 +217,7 @@ export const buildPackage = async (target: string, root = repositoryRoot): Promi
     version: readPackageVersion(root),
     description: "RAgents-Host: Server, Engine, Plugins und Werkzeuge ohne Quell-Checkout",
     keywords: [...PACKAGE_KEYWORDS],
-    homepage: `${REPOSITORY_URL}#readme`,
+    homepage: "https://schlenkr.github.io/RAgents/",
     bugs: { url: `${REPOSITORY_URL}/issues` },
     license: PACKAGE_LICENSE,
     author: PACKAGE_AUTHOR,

package/scripts/package/ragents.mjs

@@ -29,11 +29,21 @@ const usage = `Verwendung: ragents <befehl> [argumente]
                                    geholten Stand starten; baut die Oberfläche bei Bedarf
   provision [<profil>|--workspace] Werkzeuge der Plugins holen
   workspace-client <server-url>    diesen Rechner als Arbeitsplatz anmelden
+  --help, help                     diese Verwendung
+
+run, send, journal und stop nehmen mit --profile <profil|pfad> ein anderes Profil: einen Namen
+neben dem Host oder den Pfad zu einer eigenen ragents.config.<profil>.ts. RAGENTS_PROFILE setzt
+dasselbe für alle Befehle einer Shell; verlangt das Profil eine Anmeldung, gehört der
+persönliche Token des Benutzers in RAGENTS_TOKEN.
 `;
 
 const main = () => {
   const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
   const [command, ...rest] = process.argv.slice(2);
+  if (command === "--help" || command === "help") {
+    console.log(usage);
+    process.exit(0);
+  }
   const script = command ? commands[command] : undefined;
   if (!script) {
     console.error(command ? `Unbekannter Befehl: ${command}\n\n${usage}` : usage);

package/scripts/remote/connect.ts

@@ -7,6 +7,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { extract as extractTar } from "tar";
 import { ragentsDataRoot } from "../../apps/server/src/data-directory.ts";
+import { removeHostRecord, writeHostRecord } from "../../apps/server/src/host-record.ts";
 import { hostRoot, readHostPackage, readHostVersion } from "../../apps/server/src/host-version.ts";
 import { readProfileTarget } from "../../apps/server/src/profile-target.ts";
 import { ensureWebBuild } from "../../apps/server/src/web-build.ts";
@@ -187,8 +188,13 @@ export const hostScript = (script: string, args: readonly string[] = []): { file
   cwd: path.join(hostRoot(), "apps/server"),
 });
 
-const run = (command: { file: string; args: readonly string[]; cwd: string }, env: NodeJS.ProcessEnv): Promise<number> => new Promise((resolve, reject) => {
+const run = (
+  command: { file: string; args: readonly string[]; cwd: string },
+  env: NodeJS.ProcessEnv,
+  started?: (pid: number) => void,
+): Promise<number> => new Promise((resolve, reject) => {
   const child = spawn(command.file, [...command.args], { cwd: command.cwd, env, stdio: "inherit" });
+  if (child.pid) started?.(child.pid);
   const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
   const onInterrupt = forward("SIGINT");
   const onTerminate = forward("SIGTERM");
@@ -233,9 +239,21 @@ export interface StartedProfile {
   readonly port: number | undefined;
 }
 
+/** ragents run und ragents start merken denselben Host im Datenordner des Profils; ein Port 0 sucht sich seinen Port selbst und lässt sich nicht merken. */
+export const noteHost = (profile: string, dataDirectory: string, port: number): ((pid: number) => void) | undefined =>
+  port > 0 ? (pid: number): void => writeHostRecord(dataDirectory, {
+    profile,
+    url: `http://localhost:${port}`,
+    pid,
+    log: path.join(dataDirectory, "logs", "server.log"),
+    startedAt: new Date().toISOString(),
+  }) : undefined;
+
 /** Provisioniert die Werkzeuge des Profils, baut sein Web falls nötig und startet den Server damit. */
 export const startProfile = async (started: StartedProfile): Promise<number> => {
-  const dataDirectory = started.dataDirectory ?? (await readProfileTarget(started.profile, started.profileFile)).dataDirectory;
+  const target = await readProfileTarget(started.profile, started.profileFile);
+  const dataDirectory = started.dataDirectory ?? target.dataDirectory;
+  const port = started.port ?? target.port;
   const env: NodeJS.ProcessEnv = {
     ...process.env,
     PRODUCT_PROFILE: started.profile,
@@ -254,7 +272,12 @@ export const startProfile = async (started: StartedProfile): Promise<number> =>
     log: (line) => console.log(line),
   });
   console.log(`== Server starten (Web ${webDirectory}, Daten ${dataDirectory})`);
-  return run(hostScript("apps/server/src/main.ts", started.port !== undefined ? ["--port", String(started.port)] : []), { ...env, WEB_DIST_DIR: webDirectory });
+  const note = noteHost(started.profile, dataDirectory, port);
+  try {
+    return await run(hostScript("apps/server/src/main.ts", started.port !== undefined ? ["--port", String(started.port)] : []), { ...env, WEB_DIST_DIR: webDirectory }, note);
+  } finally {
+    if (note) removeHostRecord(dataDirectory);
+  }
 };
 
 /** Startet einen Stand, den connect geholt hat, mit dem Web aus dem Cache. */

package/scripts/remote/start.ts

@@ -1,17 +1,14 @@
 // Der Hook löst @aicontainer/* auch für eine Profildatei außerhalb des Hosts auf; im Paket gibt es dort kein node_modules.
 import "../../apps/server/src/host-resolution.ts";
-import { statSync } from "node:fs";
 import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { profileFileName } from "../../apps/server/src/config-file.ts";
 import { ragentsDataRoot } from "../../apps/server/src/data-directory.ts";
-import { hostRoot } from "../../apps/server/src/host-version.ts";
-import { callerDirectory } from "../agent/agent-cli.ts";
+import { localProfile } from "../../apps/server/src/profile-target.ts";
 import { startCached, startProfile, type CachedProfile } from "./connect.ts";
 
 const usage = (): string => `Verwendung: ragents start <profil|pfad> [--port <n>]
-Startet ein Profil dieses Hosts (core, developer), eine eigene ragents.config.<profil>.ts an
+Startet ein Profil dieses Hosts (core, developer, showcase), eine eigene ragents.config.<profil>.ts an
 beliebiger Stelle oder einen Stand, den ragents connect schon geholt hat, ohne den Server zu
 fragen. Ein eigenes Profil bekommt sein Web beim Start gebaut, ein geholter Stand bringt es aus
 demselben Cache mit. Ohne Argument nennt der Befehl die Profile im Cache.`;
@@ -64,26 +61,6 @@ export const selectCachedProfile = (cached: readonly CachedProfile[], profile: s
     + "nimm ragents connect <server-url>.");
 };
 
-const PROFILE_FILE = /^ragents\.config\.([a-z0-9]+(?:-[a-z0-9]+)*)\.ts$/;
-
-export interface LocalProfile {
-  readonly profile: string;
-  readonly profileFile: string;
-}
-
-/** Ein Profil ist ein Name neben dem Host (Checkout wie Paket) oder ein Pfad zu einer ragents.config.<profil>.ts an beliebiger Stelle. */
-export const localProfile = (selection: string, root = hostRoot(), caller = callerDirectory()): LocalProfile | undefined => {
-  if (!selection.includes("/") && !selection.endsWith(".ts")) {
-    const file = path.join(root, profileFileName(selection));
-    return statSync(file, { throwIfNoEntry: false })?.isFile() ? { profile: selection, profileFile: file } : undefined;
-  }
-  const profileFile = path.resolve(caller, selection);
-  const match = PROFILE_FILE.exec(path.basename(profileFile));
-  if (!match) throw new Error(`Eine Profildatei heißt ragents.config.<profil>.ts, nicht ${path.basename(profileFile)}`);
-  if (!statSync(profileFile, { throwIfNoEntry: false })?.isFile()) throw new Error(`Die Profildatei fehlt: ${profileFile}`);
-  return { profile: match[1]!, profileFile };
-};
-
 const main = async (): Promise<void> => {
   const arguments_ = parseArguments(process.argv.slice(2));
   const own = localProfile(arguments_.selection);