@schlenkr/ragents 0.1.0

package/scripts/agent/agent-cli.ts

@@ -0,0 +1,461 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { coreContracts } from "../../apps/server/src/api/contracts.ts";
+import { profileFileName } from "../../apps/server/src/config-file.ts";
+import { isEnvironmentReference } from "../../apps/server/src/config-definition.ts";
+import { defaultDataDirectory } from "../../apps/server/src/data-directory.ts";
+import { hostRoot } from "../../apps/server/src/host-version.ts";
+import { RpcClient } from "../../apps/web/src/rpc/client.ts";
+import { WORKSPACE_BINDING_OPTION_ID } from "../../plugins/ragents.workspace/contract.ts";
+import { JournalReader, journalLines, readJournal, RUN_ID_PATTERN, type JournalEvent } from "./journal.ts";
+
+const DEFAULT_PROFILE = "developer";
+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;
+
+export const usage = (): string => `Verwendung: ragents <befehl> [argumente]
+
+  run <ordner> "<auftrag>" [--profile <p>] [--entry <einstieg>] [--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.
+  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
+  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.`;
+
+export type AgentCommand =
+  | { readonly kind: "run"; readonly profile: string; readonly folder: string; readonly text: string; readonly entry: string | undefined; readonly json: boolean }
+  | { 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-host"; readonly profile: string };
+
+interface Flags {
+  readonly profile: string;
+  readonly entry: string | undefined;
+  readonly json: boolean;
+  readonly tools: boolean;
+  readonly host: boolean;
+  readonly positional: readonly string[];
+}
+
+const VALUE_FLAGS = new Set(["--profile", "--entry"]);
+
+const scan = (argv: readonly string[], allowed: readonly string[]): Flags => {
+  const positional: string[] = [];
+  const values = new Map<string, string>();
+  const switches = new Set<string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]!;
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
+      continue;
+    }
+    if (!allowed.includes(argument)) throw new Error(`Unbekanntes Argument: ${argument}\n\n${usage()}`);
+    if (!VALUE_FLAGS.has(argument)) {
+      switches.add(argument);
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`${argument} braucht einen Wert.`);
+    values.set(argument, value);
+    index += 1;
+  }
+  return {
+    profile: values.get("--profile") ?? DEFAULT_PROFILE,
+    entry: values.get("--entry"),
+    json: switches.has("--json"),
+    tools: switches.has("--tools"),
+    host: switches.has("--host"),
+    positional,
+  };
+};
+
+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 };
+  }
+  if (command === "send") {
+    const flags = scan(rest, ["--profile", "--json"]);
+    const [runId, text, ...extra] = flags.positional;
+    if (!runId || !text) throw new Error(`send braucht <run> und "<text>".\n\n${usage()}`);
+    if (extra.length > 0) throw new Error(`send nimmt genau zwei Werte, nicht ${flags.positional.length}.`);
+    if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Ungültige Run-Id: ${runId}`);
+    return { kind: "send", profile: flags.profile, runId, text, json: flags.json };
+  }
+  if (command === "journal") {
+    const flags = scan(rest, ["--profile", "--json", "--tools"]);
+    const [runId, ...extra] = flags.positional;
+    if (!runId) throw new Error(`journal braucht <run>.\n\n${usage()}`);
+    if (extra.length > 0) throw new Error(`journal nimmt genau einen Wert, nicht ${flags.positional.length}.`);
+    if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Ungültige Run-Id: ${runId}`);
+    return { kind: "journal", profile: flags.profile, runId, json: flags.json, tools: flags.tools };
+  }
+  if (command === "stop") {
+    const flags = scan(rest, ["--profile", "--host"]);
+    if (flags.host) {
+      if (flags.positional.length > 0) throw new Error("stop --host nimmt keine Run-Id.");
+      return { kind: "stop-host", profile: flags.profile };
+    }
+    const [runId, ...extra] = flags.positional;
+    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 };
+  }
+  throw new Error(command ? `Unbekannter Befehl: ${command}\n\n${usage()}` : usage());
+};
+
+export interface ProfileTarget {
+  readonly profile: string;
+  readonly profileFile: string;
+  readonly port: number;
+  readonly dataDirectory: string;
+  readonly baseUrl: string;
+}
+
+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 = async (profile: string, root = hostRoot()): Promise<ProfileTarget> => {
+  const profileFile = path.join(root, profileFileName(profile));
+  if (!existsSync(profileFile)) throw new Error(`Die Profildatei fehlt: ${profileFile}`);
+  const module = await import(pathToFileURL(profileFile).href) as { config: { host: { PORT?: number; DATA_DIR?: unknown } } };
+  const port = Number(process.env.PORT || module.config.host.PORT);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`host.PORT des Profils ${profile} ist keine gültige Portnummer.`);
+  const configured = module.config.host.DATA_DIR;
+  const fromFile = isEnvironmentReference(configured) ? process.env[configured.name] : typeof configured === "string" ? configured : undefined;
+  const dataDirectory = path.resolve(process.env.DATA_DIR ?? fromFile ?? defaultDataDirectory(profile));
+  return { profile, profileFile, port, dataDirectory, baseUrl: `http://localhost:${port}` };
+};
+
+/** 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();
+
+const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+const healthy = async (baseUrl: string): Promise<boolean> => {
+  try {
+    const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+
+const note = (line: string): void => { process.stderr.write(`${line}\n`); };
+
+const tail = (file: string, lines: number): string =>
+  (statSync(file, { throwIfNoEntry: false })?.isFile() ? readFileSync(file, "utf8") : "").split("\n").slice(-lines).join("\n");
+
+/** Der gemerkte Host, sonst RAGENTS_URL, sonst die Adresse aus host.PORT des Profils. */
+export const addressOf = async (target: ProfileTarget): Promise<string> => {
+  const noted = readHostRecord(target.dataDirectory);
+  if (noted && await healthy(noted.url)) return noted.url;
+  return process.env.RAGENTS_URL ?? target.baseUrl;
+};
+
+const startHost = async (target: ProfileTarget): Promise<void> => {
+  mkdirSync(target.dataDirectory, { recursive: true });
+  const log = path.join(target.dataDirectory, "host.log");
+  const handle = openSync(log, "a");
+  const child = spawn(process.execPath, ["--import", "tsx", path.join(hostRoot(), "apps/server/src/main.ts")], {
+    cwd: path.join(hostRoot(), "apps/server"),
+    detached: true,
+    stdio: ["ignore", handle, handle],
+    env: {
+      ...process.env,
+      PRODUCT_PROFILE: target.profile,
+      PRODUCT_PROFILE_FILE: target.profileFile,
+      PORT: String(target.port),
+      DATA_DIR: target.dataDirectory,
+    },
+  });
+  child.unref();
+  closeSync(handle);
+  if (!child.pid) throw new Error(`Der Host ${target.profile} ließ sich nicht starten; das Log steht in ${log}.`);
+  note(`== Host ${target.profile} startet auf ${target.baseUrl} (Log ${log})`);
+  const deadline = Date.now() + HOST_START_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await healthy(target.baseUrl)) {
+      writeHostRecord(target.dataDirectory, {
+        profile: target.profile,
+        url: target.baseUrl,
+        pid: child.pid,
+        log,
+        startedAt: new Date().toISOString(),
+      });
+      note(`== Host bereit unter ${target.baseUrl} (PID ${child.pid})`);
+      return;
+    }
+    if (child.exitCode !== null || child.signalCode !== null) break;
+    await delay(500);
+  }
+  throw new Error(`Der Host ${target.profile} antwortet nicht unter ${target.baseUrl}. Ende von ${log}:\n${tail(log, 20)}`);
+};
+
+const ensureHost = async (target: ProfileTarget): Promise<string> => {
+  const address = await addressOf(target);
+  if (await healthy(address)) return address;
+  if (process.env.RAGENTS_URL) throw new Error(`Unter ${process.env.RAGENTS_URL} (RAGENTS_URL) antwortet kein RAgents-Server.`);
+  await startHost(target);
+  return target.baseUrl;
+};
+
+const client = (baseUrl: string): RpcClient => {
+  const token = process.env.RAGENTS_TOKEN;
+  return new RpcClient({
+    baseUrl,
+    fetch: (input, init) => fetch(input, {
+      ...init,
+      headers: {
+        ...init?.headers as Record<string, string> | undefined,
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
+    }),
+  });
+};
+
+export type TurnOutcome = "completed" | "interrupted" | "failed";
+
+export const EXIT_CODES: Readonly<Record<TurnOutcome, number>> = { completed: 0, interrupted: 2, failed: 1 };
+
+const shorten = (value: unknown, limit: number): string => {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const collapsed = (text === undefined ? "" : text).replace(/\s+/g, " ").trim();
+  return collapsed.length > limit ? `${collapsed.slice(0, limit)}...` : collapsed;
+};
+
+const seconds = (from: string | undefined, to: string | undefined): string => {
+  const start = from ? Date.parse(from) : Number.NaN;
+  const end = to ? Date.parse(to) : Number.NaN;
+  return Number.isNaN(start) || Number.isNaN(end) ? "?" : ((end - start) / 1000).toFixed(1);
+};
+
+export interface FollowState {
+  readonly inputId: string | undefined;
+  readonly turnId: string | undefined;
+  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;
+};
+
+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 FollowOptions {
+  readonly reader: JournalReader;
+  readonly baseUrl: string;
+  readonly text: string;
+  readonly json: boolean;
+  readonly write: (line: string) => void;
+}
+
+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;
+      }
+    }
+    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.`);
+  }
+};
+
+export type LineWriter = (line: string) => void;
+
+const toStdout: LineWriter = (line) => { process.stdout.write(`${line}\n`); };
+
+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 target = await loadProfile(command.profile);
+  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 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 });
+  const outcome = await follow({ reader, baseUrl, text: command.text.trim(), json: command.json, write });
+  write(`run: ${runId}`);
+  return EXIT_CODES[outcome];
+};
+
+const sendCommand = async (command: Extract<AgentCommand, { kind: "send" }>, write: LineWriter): Promise<number> => {
+  const target = await loadProfile(command.profile);
+  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 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];
+};
+
+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);
+  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 target = await loadProfile(command.profile);
+  const baseUrl = await addressOf(target);
+  await client(baseUrl).call(coreContracts.chat.stop, { runId: command.runId });
+  note(`== Turn von ${command.runId} abgebrochen`);
+  return 0;
+};
+
+const alive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+const stopHostCommand = async (command: Extract<AgentCommand, { kind: "stop-host" }>): Promise<number> => {
+  const target = await loadProfile(command.profile);
+  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 });
+    note(`== Der gemerkte Host (PID ${noted.pid}) läuft nicht mehr; der Vermerk ist weg.`);
+    return 0;
+  }
+  process.kill(noted.pid, "SIGTERM");
+  const deadline = Date.now() + HOST_STOP_TIMEOUT_MS;
+  while (Date.now() < deadline && alive(noted.pid)) await delay(250);
+  if (alive(noted.pid)) {
+    process.kill(noted.pid, "SIGKILL");
+    await delay(500);
+  }
+  rmSync(hostRecordFile(target.dataDirectory), { force: true });
+  note(`== Host ${noted.url} (PID ${noted.pid}) beendet`);
+  return 0;
+};
+
+export const execute = async (command: AgentCommand, write: LineWriter = toStdout): Promise<number> => {
+  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);
+  return stopHostCommand(command);
+};
+
+const main = async (): Promise<number> => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "--help") {
+    console.log(usage());
+    return 0;
+  }
+  return execute(parseArguments(argv));
+};
+
+const moduleUrl: string | undefined = import.meta.url;
+if (moduleUrl && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(moduleUrl)) {
+  main().then((code) => process.exit(code), (error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/scripts/agent/journal.ts

@@ -0,0 +1,125 @@
+import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import path from "node:path";
+
+export interface JournalEvent {
+  readonly sequence: number;
+  readonly type: string;
+  readonly actorId: string;
+  readonly occurredAt: string;
+  readonly payload: Record<string, unknown>;
+}
+
+interface JournalRecord {
+  command?: { actorId?: string };
+  occurredAt?: string;
+  events: { sequence: number; type: string; occurredAt?: string; payload?: Record<string, unknown> }[];
+}
+
+export interface ActorUsage {
+  calls: number;
+  inputTokens: number;
+  cacheReadTokens: number;
+  outputTokens: number;
+  costUsd: number;
+}
+
+export const RUN_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+export const journalFile = (dataDirectory: string, runId: string): string => {
+  if (!RUN_ID_PATTERN.test(runId)) throw new Error(`Ungültige Run-Id: ${runId}`);
+  return path.join(dataDirectory, "runs", runId, "journal.jsonl");
+};
+
+/** Ein Journalsatz trägt Actor und Zeitpunkt im Kommando, seine Ereignisse nicht; beides zusammen ist ein Ereignis. */
+const eventsOf = (line: string): readonly JournalEvent[] => {
+  const record = JSON.parse(line) as JournalRecord;
+  const actorId = record.command?.actorId ?? "";
+  return record.events.map((event) => ({
+    sequence: event.sequence,
+    type: event.type,
+    actorId,
+    occurredAt: event.occurredAt ?? record.occurredAt ?? "",
+    payload: event.payload ?? {},
+  }));
+};
+
+/** Liest ein Journal fortlaufend: jeder Aufruf liefert die Ereignisse, die seit dem letzten dazugekommen sind. */
+export class JournalReader {
+  readonly #file: string;
+  #offset = 0;
+  #partial = "";
+
+  constructor(dataDirectory: string, runId: string) {
+    this.#file = journalFile(dataDirectory, runId);
+  }
+
+  get file(): string {
+    return this.#file;
+  }
+
+  next(): readonly JournalEvent[] {
+    const size = statSync(this.#file, { throwIfNoEntry: false })?.size;
+    if (size === undefined || size <= this.#offset) return [];
+    const handle = openSync(this.#file, "r");
+    const buffer = Buffer.allocUnsafe(size - this.#offset);
+    try {
+      readSync(handle, buffer, 0, buffer.length, this.#offset);
+    } finally {
+      closeSync(handle);
+    }
+    this.#offset = size;
+    const lines = (this.#partial + buffer.toString("utf8")).split("\n");
+    this.#partial = lines.pop() ?? "";
+    return lines.filter((line) => line.trim()).flatMap(eventsOf);
+  }
+}
+
+export const readJournal = (dataDirectory: string, runId: string): readonly JournalEvent[] => {
+  const reader = new JournalReader(dataDirectory, runId);
+  if (!existsSync(reader.file)) throw new Error(`Journal fehlt: ${reader.file}`);
+  return reader.next();
+};
+
+export const usageByActor = (events: readonly JournalEvent[]): Map<string, ActorUsage> => {
+  const result = new Map<string, ActorUsage>();
+  for (const event of events) {
+    const model = event.payload.usage as Record<string, unknown> | undefined;
+    if (!model) continue;
+    const entry = result.get(event.actorId) ?? { calls: 0, inputTokens: 0, cacheReadTokens: 0, outputTokens: 0, costUsd: 0 };
+    entry.calls += 1;
+    for (const key of ["inputTokens", "cacheReadTokens", "outputTokens", "costUsd"] as const) {
+      const value = model[key];
+      if (typeof value === "number") entry[key] += value;
+    }
+    result.set(event.actorId, entry);
+  }
+  return result;
+};
+
+const text = (value: unknown): string => (typeof value === "string" ? value : "").replace(/\n/g, " ");
+
+export type JournalMode = "chat" | "tools" | "all";
+
+export const journalLines = (events: readonly JournalEvent[], mode: JournalMode, since: number): string[] => {
+  const lines: string[] = [];
+  for (const event of events) {
+    if (event.sequence < since) continue;
+    const actor = event.actorId.slice(0, 14);
+    const payload = event.payload;
+    const type = event.type;
+    if (type === "model.output.completed" && mode !== "tools") {
+      const output = text(payload.text);
+      if (output.trim()) lines.push(`[${event.sequence}] ${actor}: ${output.slice(0, 800)}`);
+    } 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.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"))) {
+      lines.push(`[${event.sequence}] ${type} ${actor}: ${JSON.stringify(payload).slice(0, 300)}`);
+    }
+  }
+  lines.push(`-- letzte Sequenz: ${events.at(-1)?.sequence ?? 0}`);
+  return lines;
+};