@schlenkr/ragents 0.1.5 → 0.1.6

package/scripts/agent/agent-cli.ts

@@ -1,4 +1,4 @@
-// Der Hook löst @aicontainer/* auch für eine Profildatei außerhalb des Hosts auf; im Paket gibt es dort kein node_modules.
+// Der Hook löst @ragents/* 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 { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -10,9 +10,12 @@ import { hostRecordFile, readHostRecord, removeHostRecord, writeHostRecord } fro
 import { hostRoot } from "../../apps/server/src/host-version.ts";
 import { callerDirectory, selectProfileTarget, type ProfileTarget } from "../../apps/server/src/profile-target.ts";
 import { RpcClient } from "../../apps/web/src/rpc/client.ts";
+import type { RunView, Turn, TurnToolCall } from "../../packages/ragents/src/domain/model.ts";
+import { runContracts } from "../../packages/ragents/src/http/contracts.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";
+import { WORKSPACE_BINDING_OPTION_ID, WORKSPACE_CLIENT_ID_PATTERN, type WorkspaceBindingPresentation } from "../../plugins/ragents.workspace/contract.ts";
+import { interruptPrimaryTurn, stopWholeRun } from "./turn-control.ts";
+import { journalLines, readJournal, RUN_ID_PATTERN, type JournalEvent } from "./journal.ts";
 
 const DEFAULT_PROFILE = "developer";
 const HOST_START_TIMEOUT_MS = 120_000;
@@ -26,41 +29,58 @@ export const defaultProfile = (): string => process.env.RAGENTS_PROFILE ?? DEFAU
 
 export const usage = (): string => `Verwendung: ragents <befehl> [argumente]
 
-  run <ordner> "<auftrag>" [--profile <p>] [--entry <einstieg>] [--json]
+  run [<ordner>] "<auftrag>" [--profile <p>] [--entry <vorlage>] [--workstation <kennung>] [--json]
       Startet den Host des Profils, falls keiner läuft, legt einen Run mit Bindung path auf den
-      Ordner an, schickt den Auftrag und wartet, bis der Turn endet.
+      Ordner an, schickt den Auftrag und wartet, bis der Turn endet. Ein einzelner Wert ist immer
+      der Auftrag: ohne <ordner> wählt run keine Bindung, es gilt die Vorgabe des Profils oder die
+      der Vorlage. Legt die Vorlage die Bindung fest, ist ein <ordner> ein Fehler. Mit
+      --workstation liegt der Ordner auf dem am Host angemeldeten Arbeitsplatz mit dieser Kennung
+      (pnpm workspace-client <server-url> <ordner> --id <kennung>) statt auf dem Server; ohne ihn
+      bricht run ab, und ohne <ordner> gibt es kein --workstation.
   send <run> "<text>" [--profile <p>] [--json]
       Folgeauftrag im selben Run, gleiches Warten.
   journal <run> [--profile <p>] [--json] [--tools]
-      Den Verlauf des Runs kompakt lesen.
-  stop <run> [--profile <p>]      den laufenden Turn abbrechen
+      Den Verlauf des Runs kompakt lesen: aus dem Datenordner des Profils, mit RAGENTS_URL vom
+      Server (dort mit dem Recht runs.inspect).
+  stop <run> [--profile <p>]      den laufenden Turn des Primary-Actors unterbrechen; der Run
+                                  bleibt aktiv und nimmt den nächsten Auftrag an
+  stop <run> --run [--profile <p>]
+      Not-Aus: alle Turns abbrechen und alle Actors des Runs stoppen
   stop --host [--profile <p>]     den gemerkten Host beenden
+  plugin build <ordner...> [--out <o>] [--watch] [--no-typecheck]
+      Plugin-Quellordner zu Bundles bauen; Einzelheiten mit plugin --help.
 
 <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
+ist "run: <id>". run und send folgen dem Turn über den Server (Kanal ragents.run und
+ragents.runs.view), auch auf einem anderen Rechner; Werkzeugzeilen zeigt der Server nur mit
+runs.inspect, --json liefert dieselben Schritte als JSON. Reißt die Verbindung ab, endet der
+Befehl mit 1 und der Ursache. 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 }
+  | { readonly kind: "run"; readonly profile: string; readonly folder: string | undefined; readonly text: string; readonly entry: string | undefined; readonly json: boolean; readonly workstation?: string }
   | { readonly kind: "send"; readonly profile: string; readonly runId: string; readonly text: string; readonly json: boolean }
   | { readonly kind: "journal"; readonly profile: string; readonly runId: string; readonly json: boolean; readonly tools: boolean }
   | { readonly kind: "stop"; readonly profile: string; readonly runId: string }
+  | { readonly kind: "stop-run"; readonly profile: string; readonly runId: string }
   | { readonly kind: "stop-host"; readonly profile: string };
 
 interface Flags {
   readonly profile: string;
   readonly entry: string | undefined;
+  readonly workstation: string | undefined;
   readonly json: boolean;
   readonly tools: boolean;
   readonly host: boolean;
+  readonly run: boolean;
   readonly positional: readonly string[];
 }
 
-const VALUE_FLAGS = new Set(["--profile", "--entry"]);
+const VALUE_FLAGS = new Set(["--profile", "--entry", "--workstation"]);
 
 const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
   const positional: string[] = [];
@@ -85,9 +105,11 @@ const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
   return {
     profile: values.get("--profile") ?? defaultProfile(),
     entry: values.get("--entry"),
+    workstation: values.get("--workstation"),
     json: switches.has("--json"),
     tools: switches.has("--tools"),
     host: switches.has("--host"),
+    run: switches.has("--run"),
     positional,
   };
 };
@@ -95,11 +117,17 @@ const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
 export const parseArguments = (argv: readonly string[]): AgentCommand => {
   const [command, ...rest] = argv;
   if (command === "run") {
-    const flags = scan(rest, ["--profile", "--entry", "--json"]);
-    const [folder, text, ...extra] = flags.positional;
-    if (!folder || !text) throw new Error(`run braucht <ordner> und "<auftrag>".\n\n${usage()}`);
-    if (extra.length > 0) throw new Error(`run nimmt genau zwei Werte, nicht ${flags.positional.length}.`);
-    return { kind: "run", profile: flags.profile, folder, text, entry: flags.entry, json: flags.json };
+    const flags = scan(rest, ["--profile", "--entry", "--workstation", "--json"]);
+    if (flags.positional.length > 2) throw new Error(`run nimmt höchstens zwei Werte, nicht ${flags.positional.length}.`);
+    const [folder, text] = flags.positional.length === 2 ? flags.positional : [undefined, flags.positional[0]];
+    if (!text) throw new Error(`run braucht "<auftrag>", davor optional <ordner>.\n\n${usage()}`);
+    if (folder === "") throw new Error("run braucht einen nicht leeren <ordner> oder nur den Auftrag.");
+    if (flags.workstation !== undefined && folder === undefined) throw new Error("--workstation braucht <ordner>, den Pfad auf dem Arbeitsplatz.");
+    if (flags.workstation !== undefined && !WORKSPACE_CLIENT_ID_PATTERN.test(flags.workstation)) {
+      throw new Error(`Ungültige Arbeitsplatz-Kennung: ${flags.workstation} (8 bis 64 Zeichen aus Buchstaben, Ziffern, _ und -).`);
+    }
+    return { kind: "run", profile: flags.profile, folder, text, entry: flags.entry, json: flags.json,
+      ...(flags.workstation ? { workstation: flags.workstation } : {}) };
   }
   if (command === "send") {
     const flags = scan(rest, ["--profile", "--json"]);
@@ -118,7 +146,8 @@ export const parseArguments = (argv: readonly string[]): AgentCommand => {
     return { kind: "journal", profile: flags.profile, runId, json: flags.json, tools: flags.tools };
   }
   if (command === "stop") {
-    const flags = scan(rest, ["--profile", "--host"]);
+    const flags = scan(rest, ["--profile", "--host", "--run"]);
+    if (flags.host && flags.run) throw new Error("stop nimmt entweder --host oder --run.");
     if (flags.host) {
       if (flags.positional.length > 0) throw new Error("stop --host nimmt keine Run-Id.");
       return { kind: "stop-host", profile: flags.profile };
@@ -127,7 +156,7 @@ export const parseArguments = (argv: readonly string[]): AgentCommand => {
     if (!runId) throw new Error(`stop braucht <run> oder --host.\n\n${usage()}`);
     if (extra.length > 0) throw new Error(`stop nimmt genau einen Wert, nicht ${flags.positional.length}.`);
     if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Ungültige Run-Id: ${runId}`);
-    return { kind: "stop", profile: flags.profile, runId };
+    return { kind: flags.run ? "stop-run" : "stop", profile: flags.profile, runId };
   }
   throw new Error(command ? `Unbekannter Befehl: ${command}\n\n${usage()}` : usage());
 };
@@ -231,7 +260,7 @@ export const withLoginHint = async <T>(call: () => Promise<T>): Promise<T> => {
   }
 };
 
-/** Ein Einstieg richtet den Run erst ein und bestimmt dabei seinen Chatpartner; bis dahin lehnt der Server die Nachricht ab. */
+/** Eine Vorlage 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) {
@@ -240,7 +269,7 @@ const sendWhenChatReady = async (rpc: RpcClient, runId: string, text: string): P
       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.");
+      if (attempt === 0) note("== Die Vorlage richtet den Run ein; der Auftrag wartet auf seinen Chatpartner.");
       await delay(POLL_INTERVAL_MS);
     }
   }
@@ -262,88 +291,148 @@ const seconds = (from: string | undefined, to: string | undefined): string => {
   return Number.isNaN(start) || Number.isNaN(end) ? "?" : ((end - start) / 1000).toFixed(1);
 };
 
-export interface FollowState {
-  readonly inputId: string | undefined;
-  readonly turnId: string | undefined;
+/** Ein Schritt des eigenen Turns: `line` für stdout (fehlt bei einem sauberen Ende), `data` für --json. */
+export interface ProgressEntry {
+  readonly key: string;
+  readonly at: string;
+  readonly line: string | undefined;
+  readonly data: Readonly<Record<string, unknown>>;
+}
+
+export interface TurnProgress {
+  readonly entries: readonly ProgressEntry[];
   readonly outcome: TurnOutcome | undefined;
   readonly reason: string | undefined;
 }
 
-export const INITIAL_FOLLOW_STATE: FollowState = { inputId: undefined, turnId: undefined, outcome: undefined, reason: undefined };
-
-/** Verfolgt genau den Turn, den der eigene Text ausgelöst hat: Eingabe, Turn, Ende. */
-export const advance = (state: FollowState, event: JournalEvent, text: string): FollowState => {
-  const payload = event.payload;
-  if (state.inputId === undefined) {
-    if (event.type === "actor.input.enqueued" && payload.content === text) return { ...state, inputId: String(payload.inputId) };
-    return state;
-  }
-  if (state.turnId === undefined) {
-    if (event.type === "turn.started" && payload.inputId === state.inputId) return { ...state, turnId: String(payload.turnId) };
-    return state;
-  }
-  if (payload.turnId !== state.turnId) return state;
-  if (event.type === "turn.finished") {
-    return payload.outcome === "failed"
-      ? { ...state, outcome: "failed", reason: String(payload.reason ?? "") }
-      : { ...state, outcome: "completed", reason: undefined };
-  }
-  if (event.type === "turn.interrupted") return { ...state, outcome: "interrupted", reason: String(payload.reason ?? "") };
-  return state;
+const PENDING: TurnProgress = { entries: [], outcome: undefined, reason: undefined };
+
+const TOOL_ENDS: Readonly<Record<Exclude<TurnToolCall["status"], "running">, string>> = { completed: "ok", failed: "Fehler", interrupted: "abgebrochen" };
+
+const toolEntries = (call: TurnToolCall): ProgressEntry[] => [
+  { key: `tool:${call.id}`, at: call.startedAt, line: `> ${call.name}`, data: { kind: "tool", call } },
+  ...call.status === "running" ? [] : [{
+    key: `tool-end:${call.id}`,
+    at: call.finishedAt ?? call.startedAt,
+    line: `< ${call.name} ${seconds(call.startedAt, call.finishedAt ?? undefined)}s ${TOOL_ENDS[call.status]}`,
+    data: { kind: "tool-end", call },
+  }],
+];
+
+const endEntry = (turn: Turn): ProgressEntry => ({
+  key: `turn:${turn.id}`,
+  at: turn.finishedAt ?? turn.startedAt,
+  line: turn.status === "failed" ? `! Turn fehlgeschlagen: ${shorten(turn.reason, 300)}`
+    : turn.status === "interrupted" ? `! Turn abgebrochen: ${shorten(turn.reason, 300)}` : undefined,
+  data: { kind: "turn", id: turn.id, status: turn.status, reason: turn.reason },
+});
+
+/** Die neue Eingabe des Owners mit diesem Text, der Turn, der sie begonnen oder eingespeist bekommen hat, und seine Schritte ab ihr. */
+export const progressOf = (view: RunView | null, known: ReadonlySet<string>, text: string): TurnProgress => {
+  const input = view?.inputs.find((entry) => !known.has(entry.id) && entry.enqueuedBy === view.ownerId && entry.subscriptionId === null
+    && entry.content.trim() === text.trim());
+  if (!input) return PENDING;
+  if (input.lifecycle.kind === "discarded") return { entries: [], outcome: "interrupted", reason: input.lifecycle.reason };
+  if (input.lifecycle.kind === "pending") return PENDING;
+  const turnId = input.lifecycle.turnId;
+  const turn = view?.turns.find((entry) => entry.id === turnId);
+  if (!turn) return PENDING;
+  const entries = [
+    ...turn.toolCalls.filter((call) => Date.parse(call.startedAt) >= Date.parse(input.enqueuedAt)).flatMap(toolEntries),
+    ...turn.outputs.filter((output) => output.sequence > input.sequence && output.text.trim()).map((output): ProgressEntry =>
+      ({ key: `output:${output.sequence}`, at: output.occurredAt, line: output.text.trim(), data: { kind: "output", output } })),
+  ].sort((left, right) => Date.parse(left.at) - Date.parse(right.at));
+  if (turn.status === "running") return { entries, outcome: undefined, reason: undefined };
+  return { entries: [...entries, endEntry(turn)], outcome: turn.status, reason: turn.status === "completed" ? undefined : turn.reason ?? "" };
 };
 
-export const streamLines = (event: JournalEvent, started: Map<string, JournalEvent>): readonly string[] => {
-  const payload = event.payload;
-  const callId = typeof payload.toolCallId === "string" ? payload.toolCallId : "";
-  if (event.type === "tool.call.started") {
-    started.set(callId, event);
-    return [`> ${String(payload.name ?? "")} ${shorten(payload.input, 200)}`];
-  }
-  if (event.type === "tool.call.completed" || event.type === "tool.call.failed") {
-    const begin = started.get(callId);
-    started.delete(callId);
-    const duration = seconds(begin?.occurredAt, event.occurredAt);
-    return event.type === "tool.call.completed"
-      ? [`< ${String(payload.name ?? "")} ${duration}s ok`]
-      : [`< ${String(payload.name ?? "")} ${duration}s Fehler: ${shorten(payload.error, 300)}`];
-  }
-  if (event.type === "model.output.completed") {
-    const answer = typeof payload.text === "string" ? payload.text.trim() : "";
-    return answer ? [answer] : [];
-  }
-  if (event.type === "turn.interrupted") return [`! Turn abgebrochen: ${shorten(payload.reason, 300)}`];
-  if (event.type === "turn.finished" && payload.outcome === "failed") return [`! Turn fehlgeschlagen: ${shorten(payload.reason, 300)}`];
-  return [];
+interface RunWatch {
+  /** Kehrt zurück, sobald der Kanal seit dem letzten Aufruf etwas gemeldet hat; ein Abriss des Stroms ist ein harter Fehler. */
+  readonly changed: () => Promise<void>;
+  readonly close: () => void;
+}
+
+/** Wie Web und VS Code: der Kanal ragents.run meldet erst ready, dann jede Journaländerung; den Stand liefert ragents.runs.view. */
+const watchRun = (rpc: RpcClient, runId: string): RunWatch => {
+  let dirty = false;
+  let failure: Error | undefined;
+  let wake: (() => void) | undefined;
+  const signal = (): void => {
+    const waiting = wake;
+    wake = undefined;
+    waiting?.();
+  };
+  const fail = (message: string): void => {
+    failure ??= new Error(message);
+    signal();
+  };
+  const unsubscribe = rpc.subscribe(coreContracts.channels.run, { runId }, () => {
+    dirty = true;
+    signal();
+  }, (message) => fail(`Der Ereignisstrom des Runs fällt aus: ${message}`));
+  const stopStatus = rpc.onStatus((status) => {
+    if (status.kind === "unauthorized") fail(LOGIN_REQUIRED);
+  });
+  return {
+    changed: async () => {
+      while (!dirty && !failure) await new Promise<void>((resolve) => { wake = resolve; });
+      if (failure) throw failure;
+      dirty = false;
+    },
+    close: () => {
+      stopStatus();
+      unsubscribe();
+    },
+  };
 };
 
 interface FollowOptions {
-  readonly reader: JournalReader;
+  readonly rpc: RpcClient;
   readonly baseUrl: string;
+  readonly runId: string;
   readonly text: string;
   readonly json: boolean;
   readonly write: (line: string) => void;
+  readonly send: () => Promise<void>;
 }
 
+/** Abonniert den Run, merkt sich die vorhandenen Eingaben, schickt den Auftrag und folgt ihm über die Run-Ansicht bis zum Turn-Ende. */
 const follow = async (options: FollowOptions): Promise<TurnOutcome> => {
-  const started = new Map<string, JournalEvent>();
-  let state = INITIAL_FOLLOW_STATE;
-  let unhealthy = 0;
-  let checkedAt = Date.now();
-  for (;;) {
-    for (const event of options.reader.next()) {
-      if (options.json) options.write(JSON.stringify(event));
-      else for (const line of streamLines(event, started)) options.write(line);
-      state = advance(state, event, options.text);
-      if (state.outcome) {
-        if (state.reason && !options.json) note(`== ${state.reason}`);
-        return state.outcome;
+  const { rpc, runId } = options;
+  const watch = watchRun(rpc, runId);
+  try {
+    await watch.changed();
+    const before = await rpc.call(runContracts.view, { runId });
+    const known = new Set(before?.inputs.map((input) => input.id));
+    await options.send();
+    return await followSent(options, watch, known);
+  } finally {
+    watch.close();
+  }
+};
+
+/** Nach dem Senden läuft der Turn beim Server weiter, was immer hier scheitert; der Fehler sagt das. */
+const followSent = async (options: FollowOptions, watch: RunWatch, known: ReadonlySet<string>): Promise<TurnOutcome> => {
+  const { rpc, runId } = options;
+  try {
+    const written = new Set<string>();
+    for (;;) {
+      const progress = progressOf(await rpc.call(runContracts.view, { runId }), known, options.text);
+      for (const entry of progress.entries.filter((candidate) => !written.has(candidate.key))) {
+        written.add(entry.key);
+        if (options.json) options.write(JSON.stringify(entry.data));
+        else if (entry.line !== undefined) options.write(entry.line);
+      }
+      if (progress.outcome) {
+        if (progress.reason && !options.json) note(`== ${progress.reason}`);
+        return progress.outcome;
       }
+      await watch.changed();
     }
-    await delay(POLL_INTERVAL_MS);
-    if (Date.now() - checkedAt < 5_000) continue;
-    checkedAt = Date.now();
-    unhealthy = await healthy(options.baseUrl) ? 0 : unhealthy + 1;
-    if (unhealthy >= 2) throw new Error(`Der Host unter ${options.baseUrl} antwortet nicht mehr; der Run läuft ohne ihn nicht weiter.`);
+  } catch (error) {
+    if (error instanceof RpcError && error.status === 401) throw error;
+    throw new Error(`Der Turn in ${runId} lässt sich über ${options.baseUrl} nicht weiter verfolgen und läuft dort womöglich weiter: `
+      + (error instanceof Error ? error.message : String(error)));
   }
 };
 
@@ -351,26 +440,61 @@ export type LineWriter = (line: string) => void;
 
 const toStdout: LineWriter = (line) => { process.stdout.write(`${line}\n`); };
 
+/** Der angemeldete Arbeitsplatz mit dieser Kennung, wie die Startoption ihn nennt; fehlt er, bricht run mit Ursache ab. */
+const workstationOf = (presentation: unknown, id: string): { client: string; label: string } => {
+  const clients = (presentation as WorkspaceBindingPresentation | null)?.clients ?? [];
+  const found = clients.find((entry) => entry.id === id);
+  if (!found) {
+    const registered = clients.map((entry) => `${entry.id} (${entry.label})`).join(", ") || "keiner";
+    throw new Error(`Am Host ist kein Arbeitsplatz mit der Kennung ${id} angemeldet; angemeldet: ${registered}. Anmelden mit pnpm workspace-client <server-url> <ordner> --id ${id}.`);
+  }
+  return { client: found.id, label: found.label };
+};
+
+/** Legt die Vorlage die Ordnerbindung selbst fest, widerspricht ihr jeder genannte Ordner; run überstimmt keine Seite still. */
+const assertEntryLeavesBinding = async (rpc: RpcClient, entryId: string, folder: string): Promise<void> => {
+  const { startEntries } = await withLoginHint(() => rpc.call(coreContracts.plugins.bootstrap, {}));
+  const entry = startEntries.find((candidate) => candidate.id === entryId);
+  if (!entry) throw new Error(`Die Vorlage ${entryId} gibt es in diesem Profil nicht, oder sie ist für Deinen Benutzer nicht freigegeben.`);
+  const fixed = entry.fixedStartOptions?.[WORKSPACE_BINDING_OPTION_ID];
+  if (fixed !== undefined) {
+    throw new Error(`Die Vorlage ${entryId} legt die Ordnerbindung selbst fest (${JSON.stringify(fixed)}), genannt ist aber der Ordner ${folder}. `
+      + "Lass <ordner> weg oder starte ohne diese Vorlage.");
+  }
+};
+
+const bindFolder = async (rpc: RpcClient, runId: string, folder: string, command: Extract<AgentCommand, { kind: "run" }>, profile: string, baseUrl: string): Promise<void> => {
+  if (command.entry) await assertEntryLeavesBinding(rpc, command.entry, folder);
+  const options = await withLoginHint(() => rpc.call(coreContracts.startOptions.list, { runId }));
+  const binding = options.find((option) => option.id === WORKSPACE_BINDING_OPTION_ID);
+  if (command.workstation) {
+    if (!binding) throw new Error(`Das Profil ${profile} kennt ${WORKSPACE_BINDING_OPTION_ID} nicht; ohne Ordnerbindung gibt es keinen Arbeitsplatz für --workstation.`);
+    const machine = workstationOf(binding.presentation, command.workstation);
+    await withLoginHint(() => rpc.call(coreContracts.startOptions.select, { runId, optionId: WORKSPACE_BINDING_OPTION_ID, value: { machine, folder: { path: folder } } }));
+    note(`== Run ${runId} auf Arbeitsplatz ${machine.label}: ${folder} (${baseUrl})`);
+  } else if (binding) {
+    await withLoginHint(() => rpc.call(coreContracts.startOptions.select, { runId, optionId: WORKSPACE_BINDING_OPTION_ID, value: { machine: "server", folder: { path: folder } } }));
+    note(`== Run ${runId} auf ${folder} (${baseUrl})`);
+  } else {
+    note(`== Run ${runId} (${baseUrl}); das Profil ${profile} kennt ${WORKSPACE_BINDING_OPTION_ID} nicht und legt seinen Arbeitsbereich selbst an, ${folder} bleibt ungebunden.`);
+  }
+};
+
 const runCommand = async (command: Extract<AgentCommand, { kind: "run" }>, write: LineWriter): Promise<number> => {
-  const folder = path.resolve(callerDirectory(), command.folder);
-  if (!statSync(folder, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`Kein Verzeichnis: ${folder}`);
+  const folder = command.folder === undefined || (command.workstation && path.win32.isAbsolute(command.folder))
+    ? command.folder : path.resolve(callerDirectory(), command.folder);
+  if (folder !== undefined && !command.workstation && !statSync(folder, { throwIfNoEntry: false })?.isDirectory()) throw new Error(`Kein Verzeichnis: ${folder}`);
   const target = await loadProfile(command.profile);
   const baseUrl = await ensureHost(target);
   const rpc = client(baseUrl);
   const runId = randomUUID();
-  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 (folder !== undefined) await bindFolder(rpc, runId, folder, command, target.profile, baseUrl);
+  else note(`== Run ${runId} (${baseUrl}) ohne Ordner; die Bindung kommt aus ${command.entry ? `der Vorlage ${command.entry} oder ` : ""}der Vorgabe des Profils ${target.profile}.`);
   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 });
+  const outcome = await withLoginHint(() => follow({ rpc, baseUrl, runId, text: command.text, json: command.json, write,
+    send: () => command.entry
+      ? sendWhenChatReady(rpc, runId, command.text)
+      : rpc.call(coreContracts.chat.send, { runId, text: command.text }).then(() => undefined) }));
   write(`run: ${runId}`);
   return EXIT_CODES[outcome];
 };
@@ -380,27 +504,43 @@ const sendCommand = async (command: Extract<AgentCommand, { kind: "send" }>, wri
   const baseUrl = await addressOf(target);
   if (!await healthy(baseUrl)) throw new Error(`Unter ${baseUrl} antwortet kein RAgents-Server; starte ihn mit ragents run.`);
   const rpc = client(baseUrl);
-  const reader = new JournalReader(target.dataDirectory, command.runId);
-  reader.next();
-  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 });
+  const outcome = await withLoginHint(() => follow({ rpc, baseUrl, runId: command.runId, text: command.text, json: command.json, write,
+    send: () => rpc.call(coreContracts.chat.send, { runId: command.runId, text: command.text }).then(() => undefined) }));
   write(`run: ${command.runId}`);
   return EXIT_CODES[outcome];
 };
 
+/** Mit RAGENTS_URL liegt das Journal beim Server, nicht im Datenordner des lokalen Profils; ragents.runs.events braucht runs.inspect. */
+const serverJournal = async (target: ProfileTarget, runId: string): Promise<readonly JournalEvent[]> => {
+  const baseUrl = await addressOf(target);
+  try {
+    const events = await withLoginHint(() => client(baseUrl).call(runContracts.events, { runId }));
+    return events.map((event) => ({ sequence: event.sequence, type: event.type, actorId: event.actorId, occurredAt: event.occurredAt,
+      payload: event.payload as Record<string, unknown> }));
+  } catch (error) {
+    if (error instanceof RpcError && error.status === 403) throw new Error(`Das Journal über ${baseUrl} braucht das Recht runs.inspect: ${error.message}`);
+    throw error;
+  }
+};
+
 const journalCommand = async (command: Extract<AgentCommand, { kind: "journal" }>, write: LineWriter): Promise<number> => {
   const target = await loadProfile(command.profile);
-  const events = readJournal(target.dataDirectory, command.runId);
+  const events = process.env.RAGENTS_URL ? await serverJournal(target, command.runId) : readJournal(target.dataDirectory, command.runId);
   if (command.json) for (const event of events) write(JSON.stringify(event));
   else for (const line of journalLines(events, command.tools ? "tools" : "chat", 0)) write(line);
   return 0;
 };
 
-const stopCommand = async (command: Extract<AgentCommand, { kind: "stop" }>): Promise<number> => {
+const stopCommand = async (command: Extract<AgentCommand, { kind: "stop" | "stop-run" }>): Promise<number> => {
   const target = await loadProfile(command.profile);
-  const baseUrl = await addressOf(target);
-  await withLoginHint(() => client(baseUrl).call(coreContracts.chat.stop, { runId: command.runId }));
-  note(`== Turn von ${command.runId} abgebrochen`);
+  const rpc = client(await addressOf(target));
+  if (command.kind === "stop-run") {
+    await withLoginHint(() => stopWholeRun(rpc, command.runId));
+    note(`== Run ${command.runId} angehalten (Not-Aus)`);
+    return 0;
+  }
+  const actorId = await withLoginHint(() => interruptPrimaryTurn(rpc, command.runId));
+  note(`== Laufender Turn von ${actorId} in ${command.runId} unterbrochen; der Run bleibt aktiv`);
   return 0;
 };
 
@@ -413,6 +553,17 @@ const alive = (pid: number): boolean => {
   }
 };
 
+/** Die PID, die der Host unter dieser Adresse selbst nennt; undefined, wenn dort kein Host antwortet. */
+const hostPidAt = async (baseUrl: string): Promise<number | undefined> => {
+  try {
+    const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
+    const body = response.ok ? await response.json() as { pid?: unknown } : undefined;
+    return typeof body?.pid === "number" ? body.pid : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
 const stopHostCommand = async (command: Extract<AgentCommand, { kind: "stop-host" }>): Promise<number> => {
   const target = await loadProfile(command.profile);
   const noted = readHostRecord(target.dataDirectory);
@@ -422,6 +573,12 @@ const stopHostCommand = async (command: Extract<AgentCommand, { kind: "stop-host
     note(`== Der gemerkte Host (PID ${noted.pid}) läuft nicht mehr; der Vermerk ist weg.`);
     return 0;
   }
+  const answering = await hostPidAt(noted.url);
+  if (answering !== noted.pid) {
+    removeHostRecord(target.dataDirectory);
+    const found = answering === undefined ? "kein Host, der seine PID nennt" : `ein anderer Host (PID ${answering})`;
+    throw new Error(`Unter ${noted.url} antwortet ${found}; die gemerkte PID ${noted.pid} gehört nicht nachweislich zum Host und wird nicht beendet. Der Vermerk ist weg.`);
+  }
   process.kill(noted.pid, "SIGTERM");
   const deadline = Date.now() + HOST_STOP_TIMEOUT_MS;
   while (Date.now() < deadline && alive(noted.pid)) await delay(250);
@@ -438,7 +595,7 @@ export const execute = async (command: AgentCommand, write: LineWriter = toStdou
   if (command.kind === "run") return runCommand(command, write);
   if (command.kind === "send") return sendCommand(command, write);
   if (command.kind === "journal") return journalCommand(command, write);
-  if (command.kind === "stop") return stopCommand(command);
+  if (command.kind === "stop" || command.kind === "stop-run") return stopCommand(command);
   return stopHostCommand(command);
 };
 
@@ -452,6 +609,7 @@ const main = async (): Promise<number> => {
     console.error(usage());
     return 1;
   }
+  if (argv[0] === "plugin") return (await import("../plugin/plugin-cli.ts")).main(argv.slice(1));
   return execute(parseArguments(argv));
 };
 

package/scripts/agent/journal.ts

@@ -113,10 +113,12 @@ export const journalLines = (events: readonly JournalEvent[], mode: JournalMode,
     } else if (type === "actor.input.enqueued" && mode !== "tools") {
       const input = payload.input as Record<string, unknown> | undefined;
       lines.push(`[${event.sequence}] INPUT -> ${String(payload.actorId ?? "").slice(0, 14)}: ${text(payload.text ?? input?.text).slice(0, 300)}`);
+    } else if (type === "turn.input-steered" && mode !== "tools") {
+      lines.push(`[${event.sequence}] STEERING -> ${actor}: ${String(payload.inputId ?? "")} in ${String(payload.turnId ?? "")}`);
     } else if (type.startsWith("tool.call.") && mode !== "chat") {
       const body = type.endsWith("started") ? payload.input : type.endsWith("failed") ? payload.error : undefined;
       if (body !== undefined) lines.push(`[${event.sequence}] ${type.split(".").pop()} ${actor} ${String(payload.name ?? "")}: ${JSON.stringify(body).slice(0, 300)}`);
-    } else if (mode !== "tools" && (type.includes("failed") || type.includes("stopped") || type.includes("question"))) {
+    } else if (mode !== "tools" && (type.includes("failed") || type.includes("stopped") || type.startsWith("action."))) {
       lines.push(`[${event.sequence}] ${type} ${actor}: ${JSON.stringify(payload).slice(0, 300)}`);
     }
   }

package/scripts/agent/turn-control.ts

@@ -0,0 +1,19 @@
+import { randomUUID } from "node:crypto";
+import { coreContracts } from "../../apps/server/src/api/contracts.ts";
+import type { RpcClient } from "../../apps/web/src/rpc/client.ts";
+import { runContracts } from "../../packages/ragents/src/http/contracts.ts";
+
+/** Wie die Chat-Eingabe: nur der laufende Turn des Primary-Actors endet, Run und Actors bleiben aktiv. */
+export const interruptPrimaryTurn = async (rpc: RpcClient, runId: string): Promise<string> => {
+  const view = await rpc.call(runContracts.view, { runId });
+  if (!view) throw new Error(`Der Run ${runId} ist nicht gestartet.`);
+  const actorId = view.primaryActorId;
+  if (!actorId) throw new Error(`Der Run ${runId} hat keinen Primary-Actor, dessen Turn sich unterbrechen ließe; den ganzen Run hält stop mit --run an.`);
+  await rpc.call(runContracts.interruptTurn, { runId, commandId: randomUUID(), actorId });
+  return actorId;
+};
+
+/** Not-Aus: bricht alle Turns ab und stoppt alle Actors des Runs. */
+export const stopWholeRun = async (rpc: RpcClient, runId: string): Promise<void> => {
+  await rpc.call(coreContracts.chat.stop, { runId });
+};