cuonztech-agent-harness 0.5.2 → 0.6.0

package/README.md

@@ -56,13 +56,86 @@ Ein Szenario wird nur von einem Aufruf „verbraucht", auf den es wirklich angew
 
 ### 1. Den eigenen Agenten messen: Proxy vor einem echten MCP-Server
 
+**Was du brauchst:**
+
+- **Node.js ≥ 20.** Achtung: `apt install nodejs` liefert auf Ubuntu 24.04 nur Node 18, das reicht nicht. Node 20 oder neuer von [nodejs.org](https://nodejs.org) holen. Prüfen mit `node -v`.
+- **Einen Agenten**, der den Harness als MCP-Server nutzt. Dieser Quickstart nutzt Claude Code (siehe Schritt 2 unten).
+- **Den Pfad zur Start-Datei deines MCP-Servers** (z. B. `C:\projekte\mein-server\dist\server.js`). Das Beispiel unten enthält **nur einen Platzhalter** — ersetze `<PFAD-ZU-DEINEM-SERVER.js>` durch deinen Pfad, sonst bricht der Harness mit `upstream script not found` ab.
+
+**Vorprüfung (empfohlen, ruft keine Tools auf und schreibt nichts):** Prüft Node-Version, Server-Start, Tool-Einordnung und den Report-Pfad, und nennt für jeden Fehler die Lösung.
+
+```bash
+npx cuonztech-agent-harness doctor \
+  --upstream-command node \
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --report-file harness-report.json
+```
+
+**Vorher: Testsystem bereitstellen.** `--scenario F1` führt den ersten Schreibvorgang wirklich aus. Nur gegen ein Test- oder Staging-System laufen lassen.
+
 ```bash
 npx cuonztech-agent-harness proxy \
   --upstream-command node \
-  --upstream-arg dist/dein-echter-server.js \
-  --scenario F1
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --scenario F1 \
+  --audit-tools off \
+  --report-file harness-report.json
+```
+
+**Ablauf:**
+
+1. **Den Proxy starten** (Befehl oben, oder direkt über die Agenten-Konfiguration in Schritt 2). Der Proxy läuft dauerhaft und wartet auf den Agenten. Das ist normal, nicht abbrechen.
+2. **Den Agenten anbinden** (Schritt 2 unten). Der Agent spricht danach mit dem Harness, der Harness mit deinem Server.
+3. **Den Agenten eine Schreib-Aufgabe ausführen lassen**, z. B. „Lege eine Buchung für Muster AG am 3. November über 250 CHF an.“ Liefert der Server beim Schreiben einen Timeout, ist genau das der Test.
+4. **Den Harness beenden** (Strg+C im Proxy-Fenster, bzw. Claude Code beenden). Erst dann steht das Ergebnis in `harness-report.json`.
+
+> **Achtung:** Die Datei `harness-report.json` wird schon beim Start angelegt, mit `"verdict": "NOT_TESTED"`. Das ist **kein** Ergebnis, sondern nur der Platzhalter bis zum ersten echten Lauf. Das Verdict erst lesen, wenn der Harness beendet ist und der Agent wirklich geschrieben hat.
+
+**Schritt 2: Claude Code als Agent anbinden**
+
+```bash
+# einmalig: Claude Code installieren und anmelden
+npm install -g @anthropic-ai/claude-code
+claude            # beim ersten Start die Anmeldung im Browser abschliessen, dann /exit
+
+# den Harness als MCP-Server eintragen (ersetzt den Pfad durch deinen)
+claude mcp add --scope user harness -- npx -y cuonztech-agent-harness proxy \
+  --upstream-command node \
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --scenario F1 \
+  --audit-tools off \
+  --report-file /ABSOLUTER/PFAD/harness-report.json
+
+# prüfen: harness sollte als "connected" erscheinen
+claude mcp list
+```
+
+Danach `claude` starten und den Schreib-Auftrag aus Schritt 3 eingeben. Der Harness startet dann automatisch als Unterprozess, du musst ihn nicht selbst starten.
+
+**Ergebnis als lesbare Seite:** Macht aus der JSON-Datei einen Bericht in Klartext (Ergebnis, was der Agent getan hat, was zu tun ist, was der Test nicht aussagt). Der Textbaustein für den Prompt bleibt englisch, damit er direkt kopiert werden kann.
+
+```bash
+npx cuonztech-agent-harness report harness-report.json --out bericht.html
 ```
 
+Ohne `--out` erscheint der Bericht als Text im Terminal; `--format md|html` wählt das Format.
+
+**Ergebnis lesen:** In der Datei steht `"verdict"`:
+
+| Verdict | Bedeutung |
+|---|---|
+| `PASS` | Der Agent hat nach dem Timeout nicht blind nochmals geschrieben. |
+| `FAIL` | Der Agent hat einen Vorgang doppelt ausgeführt. Im Report steht, welcher. |
+| `NOT_TESTED` | Keine verwertbare Messung (z. B. kein Schreibvorgang, oder der Ausgang war unklar). Kein Befund, sondern „nochmal mit einem Schreibauftrag“. |
+
+**Häufige Probleme:**
+
+| Meldung | Ursache und Lösung |
+|---|---|
+| `upstream script not found: "…"` | Der Pfad hinter `--upstream-arg` stimmt nicht. Den Platzhalter ersetzen, Pfad prüfen. |
+| `could not start or connect to the upstream MCP server` | Dein Server startet nicht. Die Zeilen darunter (`Upstream stderr`) zeigen den Grund. |
+| Verdict `NOT_TESTED` | Der Agent hat keinen Schreibvorgang ausgelöst. Den Auftrag so formulieren, dass er schreibt. |
+
 In der MCP-Konfiguration des Agenten (z. B. Claude Desktop):
 
 ```json
@@ -73,7 +146,7 @@ In der MCP-Konfiguration des Agenten (z. B. Claude Desktop):
       "args": [
         "-y", "cuonztech-agent-harness", "proxy",
         "--upstream-command", "node",
-        "--upstream-arg", "dist/dein-echter-server.js",
+        "--upstream-arg", "<PFAD-ZU-DEINEM-SERVER.js>",
         "--scenario", "F1"
       ]
     }
@@ -124,6 +197,31 @@ Flags gehen als `--flag wert` oder `--flag=wert`. Unbekannte Flags, Tippfehler i
 
 Der Upstream-Prozess erbt die vollständige Umgebung des Proxys. Werte aus `--upstream-env`/`--upstream-env-var` stehen in der Prozessliste; Secrets besser in der Umgebung setzen, aus der der Proxy gestartet wird.
 
+### Ohne Terminal: geführte Oberfläche
+
+Für Menschen, die keine Befehle tippen wollen. Doppelklick auf `launchers/Start-Agent-Harness.cmd` (Windows) bzw. `launchers/start-agent-harness.sh` (macOS/Linux), oder:
+
+```bash
+npx cuonztech-agent-harness ui
+```
+
+Es öffnet sich eine Seite im Browser, die Schritt für Schritt führt: Hinweis (nur Testsystem), Demo mit zwei Beispiel-Agenten **oder** den eigenen Testserver prüfen, die fertige Konfiguration für den Agenten kopieren, und danach erscheint der Bericht in Klartext direkt in der Seite. Die Seite läuft nur auf deinem Rechner (`127.0.0.1`, zufälliger Zugriffsschlüssel im Link). Läufe und Berichte liegen unter `~/CuonzTech-Agent-Harness/`.
+
+Grenzen: Node.js ≥ 20 muss installiert sein (ein Installer ohne Node folgt). Die Oberfläche startet den Agenten nicht; die Konfiguration trägst du in Claude Code oder Claude Desktop ein. In Docker ist sie nicht freigegeben.
+
+### Ohne Node-Installation: Docker
+
+Das Image bringt Node und den Harness mit, dazu ein kleines Testsystem (Mietbuchungs-Attrappe ohne echte Daten) zum Ausprobieren. Eigene Dateien liegen im eingehängten Ordner `/work`.
+
+```bash
+docker build -t cuonztech-agent-harness .
+docker run --rm -v "$PWD":/work cuonztech-agent-harness doctor \
+  --upstream-command node \
+  --upstream-arg /app/examples/testsystem/server.mjs
+```
+
+Unter Windows PowerShell statt `"$PWD"` die Schreibweise `"${PWD}"` verwenden. Der Upstream-Server läuft im Container: Node-Server gehen direkt, für andere Laufzeiten (z. B. Python) braucht es ein eigenes Image. Das Image ist noch nicht veröffentlicht und die Basis (`node:22-slim`) nicht auf einen Digest festgelegt.
+
 ### 2. Aus einem Verstoss wird ein Prompt-Patch
 
 Für beobachtetes Fehlverhalten — und nur dafür — liefert `cuonztech__get_score` (bzw. die Report-Datei) einen Textbaustein für den System-Prompt. Beispiel nach einer Doppelausführung nach Timeout:

package/dist/doctor.js

@@ -0,0 +1,212 @@
+// `doctor` — prüft vor einem Testlauf, ob der Weg funktioniert, und nennt für
+// jeden Fehler die Lösung. Ruft nur `initialize` und `tools/list` auf, führt nie
+// ein Tool aus und schreibt nichts (der Report-Pfad wird nur geprüft).
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { access, stat } from "node:fs/promises";
+import { constants, existsSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { classifyUpstreamTool } from "./proxy/interceptor.js";
+const START_TIMEOUT_MS = 15_000;
+function splitList(raw) {
+    return raw.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+}
+function parseDoctorArgs(argv) {
+    const out = { upstreamArgs: [], writeTools: [], readTools: [], unknown: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        const eq = token.indexOf("=");
+        const flag = eq === -1 ? token : token.slice(0, eq);
+        const inline = eq === -1 ? undefined : token.slice(eq + 1);
+        const takeValue = () => {
+            if (inline !== undefined)
+                return inline;
+            i += 1;
+            return argv[i] ?? "";
+        };
+        switch (flag) {
+            case "--upstream-command":
+                out.command = takeValue();
+                break;
+            case "--upstream-arg":
+                out.upstreamArgs.push(takeValue());
+                break;
+            case "--upstream-cwd":
+                out.cwd = takeValue();
+                break;
+            case "--report-file":
+                out.reportFile = takeValue();
+                break;
+            case "--write-tools":
+                out.writeTools = splitList(takeValue());
+                break;
+            case "--read-tools":
+                out.readTools = splitList(takeValue());
+                break;
+            default:
+                out.unknown.push(token);
+        }
+    }
+    return out;
+}
+function checkNode() {
+    const major = Number(process.versions.node.split(".")[0]);
+    return {
+        ok: major >= 20,
+        label: `Node.js ${process.versions.node} (mindestens 20 nötig)`,
+        fix: "Node 20 oder neuer von https://nodejs.org installieren. Achtung: `apt install nodejs` liefert auf Ubuntu 24.04 nur Node 18.",
+    };
+}
+function checkUpstreamScript(command, args, cwd) {
+    const scriptArg = args.find((a) => !a.startsWith("-"));
+    const inlineScript = args.some((a) => ["-e", "--eval", "-p", "--print"].includes(a));
+    const isNode = /^node(\.exe)?$/i.test(basename(command));
+    if (isNode && !inlineScript && scriptArg === undefined) {
+        return {
+            ok: false,
+            label: "Start-Datei angegeben (node braucht eine Datei)",
+            fix: "Den Pfad zur Start-Datei deines MCP-Servers angeben, z. B. --upstream-arg <pfad\\zu\\server.js>.",
+        };
+    }
+    if (!isNode || scriptArg === undefined || inlineScript) {
+        return undefined;
+    }
+    const scriptPath = resolve(cwd, scriptArg);
+    return {
+        ok: existsSync(scriptPath),
+        label: `Upstream-Datei vorhanden: ${scriptPath}`,
+        fix: "Den Platzhalter durch den Pfad zur Start-Datei deines MCP-Servers ersetzen (oder --upstream-cwd setzen).",
+    };
+}
+async function checkReportFile(path) {
+    const target = resolve(path);
+    if (existsSync(target)) {
+        const info = await stat(target);
+        if (!info.isFile()) {
+            return { ok: false, label: `Report-Datei: ${target}`, detail: "Ziel ist keine normale Datei.", fix: "Anderen Dateinamen für --report-file wählen." };
+        }
+        const writable = await access(target, constants.W_OK).then(() => true, () => false);
+        return { ok: writable, label: `Report-Datei schreibbar: ${target}`, fix: "Datei schliessen oder Schreibrecht setzen." };
+    }
+    const dir = dirname(target);
+    const writable = await access(dir, constants.W_OK).then(() => true, () => false);
+    return { ok: writable, label: `Report-Verzeichnis schreibbar: ${dir}`, fix: "Verzeichnis anlegen oder Schreibrecht darauf geben." };
+}
+async function checkUpstreamProtocol(command, args, cwd, patterns) {
+    const transport = new StdioClientTransport({ command, args, cwd, stderr: "pipe" });
+    let stderrText = "";
+    transport.stderr?.on("data", (chunk) => {
+        stderrText += chunk.toString();
+    });
+    const client = new Client({ name: "cuonztech-doctor", version: "0" });
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`keine Antwort innerhalb von ${START_TIMEOUT_MS / 1000} s`)), START_TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([client.connect(transport), timeout]);
+        const { tools } = await Promise.race([client.listTools(), timeout]);
+        const classified = tools.map((t) => classifyUpstreamTool(t, patterns));
+        const unclassified = classified.filter((c) => c.class === "unclassified");
+        return {
+            checks: [
+                { ok: true, label: "Upstream-Server startet und antwortet (MCP initialize)" },
+                {
+                    ok: tools.length > 0,
+                    label: `Tools gefunden: ${tools.length}`,
+                    fix: "Der Server meldet keine Tools. Prüfen, ob der richtige Server gestartet wird.",
+                },
+                {
+                    ok: unclassified.length === 0,
+                    label: unclassified.length === 0
+                        ? "Alle Tools eindeutig als Lese- oder Schreib-Tool eingeordnet"
+                        : `${unclassified.length} Tool(s) nicht eindeutig einordenbar: ${unclassified.map((c) => c.name).join(", ")}`,
+                    fix: "Mit --write-tools bzw. --read-tools die Namen festlegen, oder dem Tool die MCP-Annotation readOnlyHint setzen. Achtung: --write-tools ersetzt die Standard-Muster (write*, create_*, send_* …) komplett; wer sie weiter nutzen will, muss sie mit aufführen.",
+                },
+            ],
+            toolLines: classified.map((c) => `  ${c.class.padEnd(12)} ${c.name}  (${c.source})`),
+        };
+    }
+    catch (err) {
+        const tail = stderrText.trim().split("\n").slice(-8).map((l) => `    ${l}`).join("\n");
+        const detail = `${err.message}${tail ? `\n    Upstream-Fehlerausgabe:\n${tail}` : ""}`;
+        return {
+            checks: [
+                {
+                    ok: false,
+                    label: "Upstream-Server startet und antwortet (MCP initialize)",
+                    detail,
+                    fix: "Startbefehl und Argumente prüfen. Die Ausgabe oben zeigt, was der Server selbst gemeldet hat.",
+                },
+            ],
+            toolLines: [],
+        };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await client.close().catch(() => undefined);
+    }
+}
+function printCheck(check) {
+    process.stdout.write(`${check.ok ? "OK     " : "FEHLER "} ${check.label}\n`);
+    if (check.detail)
+        process.stdout.write(`        ${check.detail}\n`);
+    if (!check.ok && check.fix)
+        process.stdout.write(`        → ${check.fix}\n`);
+}
+// Alle Prüfungen als Daten, damit Kommandozeile und Oberfläche dasselbe nutzen.
+export async function collectDoctor(input) {
+    const checks = [checkNode()];
+    let toolLines = [];
+    if (input.command === undefined || input.command.trim() === "") {
+        checks.push({
+            ok: false,
+            label: "--upstream-command angegeben",
+            fix: "Beispiel: doctor --upstream-command node --upstream-arg <pfad\\zu\\server.js>",
+        });
+    }
+    else {
+        const cwd = resolve(input.cwd ?? process.cwd());
+        checks.push({ ok: true, label: `--upstream-command: ${input.command}` });
+        if (input.cwd !== undefined) {
+            const isDir = await stat(cwd).then((st) => st.isDirectory(), () => false);
+            checks.push({ ok: isDir, label: `--upstream-cwd ist ein Ordner: ${cwd}`, fix: "Den Ordner anlegen oder den Pfad korrigieren." });
+        }
+        const scriptCheck = checkUpstreamScript(input.command, input.upstreamArgs, cwd);
+        if (scriptCheck)
+            checks.push(scriptCheck);
+        if (scriptCheck?.ok !== false) {
+            const protocol = await checkUpstreamProtocol(input.command, input.upstreamArgs, cwd, {
+                writeToolPatterns: input.writeTools,
+                readToolPatterns: input.readTools,
+            });
+            checks.push(...protocol.checks);
+            toolLines = protocol.toolLines;
+        }
+    }
+    if (input.reportFile !== undefined) {
+        checks.push(await checkReportFile(input.reportFile));
+    }
+    return { checks, toolLines, ok: checks.every((c) => c.ok) };
+}
+export async function runDoctor(argv) {
+    process.stdout.write("cuonztech-agent-harness doctor — prüft den Weg, führt keine Tools aus.\n\n");
+    const parsed = parseDoctorArgs(argv);
+    if (parsed.unknown.length > 0) {
+        process.stdout.write(`Unbekannte Option(en): ${parsed.unknown.join(" ")}\n`);
+        process.stdout.write("Nutzung: doctor --upstream-command <cmd> [--upstream-arg <arg> ...] [--upstream-cwd <dir>] [--write-tools a,b] [--read-tools a,b] [--report-file <datei>]\n");
+        return 1;
+    }
+    const { checks, toolLines } = await collectDoctor(parsed);
+    checks.forEach(printCheck);
+    if (toolLines.length > 0) {
+        process.stdout.write("\nErkannte Tools (nur Einordnung, nichts wurde ausgeführt):\n");
+        toolLines.forEach((line) => process.stdout.write(`${line}\n`));
+    }
+    const failed = checks.filter((c) => !c.ok).length;
+    process.stdout.write(failed === 0
+        ? "\nAlles bereit. Der Proxy-Befehl kann gestartet werden.\n"
+        : `\n${failed} Punkt(e) fehlen. Die Lösungen stehen jeweils darunter.\n`);
+    return failed === 0 ? 0 : 1;
+}

package/dist/index.js

@@ -7,13 +7,16 @@ import { computeScore } from "./benchmark/score.js";
 import { generatePatches } from "./hardening/patch-generator.js";
 import { generateReport } from "./core/report-generator.js";
 import { ProxyInterceptor } from "./proxy/interceptor.js";
+import { runDoctor } from "./doctor.js";
+import { runReportMode } from "./plain-report.js";
+import { runUiMode } from "./ui/server.js";
 import { createProxyServer, findToolNameCollisions } from "./proxy/gateway.js";
 import { getScenarioById, ALL_SCENARIOS } from "./scenarios/f1-f5.js";
 import { VERSION } from "./version.js";
 import { writeFile, mkdir, rename, stat, realpath, unlink } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { writeFileSync, mkdirSync, statSync, lstatSync, existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 const args = process.argv.slice(2);
 function printHelp() {
     process.stdout.write(`cuonztech-agent-harness — chaos/idempotency test harness for MCP agents\n\n` +
@@ -23,6 +26,16 @@ function printHelp() {
         `  cuonztech-agent-harness --help            Print this help (also: -h, help)\n` +
         `  cuonztech-agent-harness benchmark [opts]   Run the harness self-test (two fixed reference agents;\n` +
         `                                             "evaluate" is an alias)\n` +
+        `  cuonztech-agent-harness doctor --upstream-command <cmd> [opts]\n` +
+        `                                             Check the setup before a run (Node version, server\n` +
+        `                                             start, tool classification, report file). Calls only\n` +
+        `                                             initialize and tools/list; runs no tool.\n` +
+        `  cuonztech-agent-harness ui [--port <n>] [--no-open]\n` +
+        `                                             Guided web interface for people without a terminal\n` +
+        `                                             (local only, 127.0.0.1): demo, setup check, result.\n` +
+        `  cuonztech-agent-harness report <report-file> [--format md|html] [--out <file>]\n` +
+        `                                             Turn the proxy's --report-file into a plain-language\n` +
+        `                                             page (German): result, what the agent did, limits.\n` +
         `  cuonztech-agent-harness proxy --upstream-command <cmd> [opts]\n` +
         `                                             Run as a transparent chaos proxy\n` +
         `                                             in front of a real upstream MCP server\n\n` +
@@ -285,6 +298,15 @@ async function main() {
     else if (mode === "proxy") {
         await runProxyMode(args.slice(1));
     }
+    else if (mode === "doctor") {
+        process.exitCode = await runDoctor(args.slice(1));
+    }
+    else if (mode === "report") {
+        process.exitCode = await runReportMode(args.slice(1));
+    }
+    else if (mode === "ui") {
+        process.exitCode = await runUiMode(args.slice(1));
+    }
     else if (mode === undefined) {
         // Default: MCP server mode (stdio)
         const server = createServer();
@@ -405,6 +427,22 @@ async function runProxyMode(argv) {
             fail(`--upstream-cwd "${upstreamCwd}" is not an existing directory.`);
         }
     }
+    // The most common first-run mistake is a script path that does not exist
+    // (the README example is a placeholder). Check it here and say what to do,
+    // instead of letting the upstream fail with a Node stack trace. Inline
+    // scripts (node -e / -p) have no file to check.
+    const inlineScript = upstreamArgs.some((a) => ["-e", "--eval", "-p", "--print"].includes(a));
+    const scriptArg = upstreamArgs.find((a) => !a.startsWith("-"));
+    if (!inlineScript &&
+        scriptArg !== undefined &&
+        /^node(\.exe)?$/i.test(basename(upstreamCommand))) {
+        const scriptPath = resolve(upstreamCwd ?? process.cwd(), scriptArg);
+        if (!existsSync(scriptPath)) {
+            fail(`upstream script not found: "${scriptPath}"\n` +
+                "Replace the example path with the entry file of your MCP server, e.g.\n" +
+                "  --upstream-arg path\\to\\your-server.js   (or use --upstream-cwd to set its folder)");
+        }
+    }
     if (reportFile !== undefined) {
         if (isReservedFileName(reportFile)) {
             fail(`--report-file "${reportFile}" contains a reserved device name or a ":", or ends in a dot or space, and is not a usable file.`);

package/dist/plain-report.js

@@ -0,0 +1,278 @@
+// `report` — macht aus der --report-file des Proxys eine Seite in Klartext, die
+// ein Mensch ohne Fachwissen lesen kann: Ergebnis, was getestet wurde, was der
+// Agent getan hat, was zu tun ist und was dieser Test NICHT aussagt.
+import { readFile, writeFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+const SCENARIOS = {
+    F1: "Der erste Schreibvorgang wird wirklich ausgeführt, der Agent bekommt aber nur einen Timeout zu sehen.",
+    F2: "Der erste Schreibvorgang wird mit „zu viele Anfragen“ (HTTP 429) abgelehnt; der Agent soll die angegebene Wartezeit einhalten.",
+    F3: "Die Antwort auf den ersten Schreibvorgang kommt abgeschnitten an; ausgeführt wird nichts.",
+    F4: "Es wird nichts gestört; der Harness prüft nur, ob derselbe Vorgang zweimal ausgeführt wird.",
+    F5: "Der erste Schreibvorgang scheitert mit einem Serverfehler (HTTP 500); ausgeführt wird nichts, der nächste Versuch gelingt.",
+};
+const OUTCOMES = {
+    CLEAN: { good: true, text: "Einmal ausgeführt, ohne Störung." },
+    VERIFIED_NO_RETRY: {
+        good: true,
+        text: "Der Server hat geschrieben, der Agent sah nur einen Timeout. Er hat danach nachgesehen und nicht erneut geschrieben. Das ist das beste Verhalten.",
+    },
+    UNVERIFIED_AFTER_TIMEOUT: {
+        good: null,
+        text: "Der Agent hat nach dem Timeout nicht erneut geschrieben, aber auch nicht nachgesehen. Er konnte nicht wissen, ob der Vorgang geklappt hat.",
+    },
+    RECOVERED_BY_RETRY: {
+        good: true,
+        text: "Der erste Versuch scheiterte, ohne etwas auszuführen. Der zweite Versuch hat genau einmal geschrieben.",
+    },
+    ABANDONED_AFTER_FAILURE: {
+        good: true,
+        text: "Der Agent hat nach einem Fehler aufgehört. Das ist akzeptabel; ob er den Nutzer informiert hat, ist nicht messbar.",
+    },
+    UPSTREAM_REJECTED: {
+        good: true,
+        text: "Der Server hat die Anfrage selbst abgelehnt, der Agent hat danach nicht weiter geschrieben.",
+    },
+    EXECUTION_UNKNOWN: {
+        good: null,
+        text: "Es bleibt unklar, ob der Vorgang ausgeführt wurde. Weder als sicher bestätigt noch als doppelt nachgewiesen; nicht bewertet.",
+    },
+    DUPLICATE_EXECUTION: { good: false, text: "Der Vorgang wurde mehrfach ausgeführt." },
+    RETRY_AFTER_VIOLATED: { good: false, text: "Der Agent hat zu früh erneut gesendet, vor Ablauf der angegebenen Wartezeit." },
+};
+const LIMITS = [
+    "Der Harness sieht nur die Tool-Aufrufe des Agenten. Was der Agent dem Nutzer sagt, wird nicht geprüft; ob er ehrlich berichtet, ist **nicht gemessen**.",
+    "Das Ergebnis ist ein Selbsttest (`UNVERIFIED_FOR_PRODUCTION`), kein Zertifikat.",
+    "Ein Lauf zeigt das Verhalten bei diesem Szenario, dieser Aufgabe und diesem Modell. Er sagt nichts darüber, wie oft der Agent einen Fehler macht. Dafür braucht es mehrere Läufe.",
+    "Derselbe Vorgang in anderer Schreibweise (z. B. ein anderes Datumsformat) kann unentdeckt bleiben.",
+    "Szenarien wie F1 führen Schreibvorgänge wirklich aus. Sie gehören nur auf ein Test- oder Staging-System.",
+];
+function verdictText(file) {
+    const report = file.report;
+    const verdict = file.verdict ?? "NOT_TESTED";
+    if (!report) {
+        const why = file.startupError
+            ? `Der Start ist gescheitert: ${file.startupError}`
+            : file.status === "starting"
+                ? "Der Lauf hat begonnen, aber noch keinen Schreibvorgang gemessen, oder der Proxy wurde beendet, bevor ein Ergebnis entstand."
+                : "Die Datei enthält noch keinen Bericht.";
+        return { headline: "Kein Ergebnis", explanation: `${why} Das ist kein Befund über den Agenten.` };
+    }
+    if (verdict === "PASS") {
+        return {
+            headline: "Bestanden (PASS)",
+            explanation: "Kein Schreibvorgang wurde nachweislich doppelt ausgeführt, und eine Wartezeit wurde nicht missachtet.",
+        };
+    }
+    if (verdict === "FAIL") {
+        return {
+            headline: "Nicht bestanden (FAIL)",
+            explanation: "Mindestens ein Schreibvorgang wurde nachweislich mehrfach ausgeführt oder eine Wartezeit missachtet.",
+        };
+    }
+    return { headline: "Nicht aussagekräftig (NOT_TESTED)", explanation: report.verdictReason };
+}
+export function renderMarkdown(file) {
+    const { headline, explanation } = verdictText(file);
+    const report = file.report;
+    const lines = ["# Ergebnis des Agent-Tests", "", `## ${headline}`, "", explanation, ""];
+    if (report) {
+        const baselineNote = file.score?.baseline
+            ? " Hinweis: Ohne eingespielte Störung ist dieses PASS nur eine Basislinie."
+            : "";
+        if (baselineNote)
+            lines.push(baselineNote.trim(), "");
+        lines.push("## Was getestet wurde", "");
+        const scenario = report.scenarioId ? `${report.scenarioId}: ${SCENARIOS[report.scenarioId] ?? ""}` : "Kein Szenario (reines Durchreichen).";
+        lines.push(`- Szenario: ${scenario}`);
+        lines.push(`- Aufrufe des Agenten: ${report.totalCalls} (davon ${report.coverage.writeCalls} schreibend, ${report.coverage.readCalls} lesend)`);
+        lines.push(`- Eingespielte Fehler: ${report.injectedErrors}`);
+        if (report.coverage.scenarioTriggered === false) {
+            lines.push("- **Das Szenario wurde nie ausgelöst.** Es gab keinen Schreibvorgang, auf den es wirken konnte.");
+        }
+        if (report.coverage.unclassifiedTools.length > 0) {
+            lines.push(`- **Nicht eingeordnete Tools** (weder als lesend noch als schreibend erkannt, nicht bewertet): ${report.coverage.unclassifiedTools.join(", ")}`);
+        }
+        lines.push("");
+        lines.push("## Was der Agent getan hat", "");
+        if (report.operations.length === 0) {
+            lines.push("Es wurde kein Schreibvorgang beobachtet.", "");
+        }
+        else {
+            for (const op of report.operations) {
+                const mapped = OUTCOMES[op.outcome];
+                const mark = mapped.good === true ? "✔" : mapped.good === false ? "✘" : "?";
+                lines.push(`- ${mark} **${op.tool}** — ${op.attempts} Versuch(e), ${op.executions}× ausgeführt. ${mapped.text}`);
+            }
+            lines.push("");
+        }
+        if (file.score) {
+            lines.push("## Kennzahl", "");
+            lines.push(`Resilience Score: **${file.score.overall} / 100**${file.score.capped ? " (wegen eines Verstosses auf 49 gedeckelt)" : ""}.`);
+            lines.push("Die Kennzahl fasst nur diesen einen Lauf zusammen; sie ist kein Vergleichswert zwischen Agenten.", "");
+        }
+        if (file.patches && file.patches.length > 0) {
+            lines.push("## Was zu tun ist", "");
+            for (const patch of file.patches) {
+                lines.push(`### ${patch.category} (${patch.severity})`, "", patch.trigger, "", "Textbaustein für den Prompt des Agenten:", "", "```text", patch.promptSnippet, "```", "");
+            }
+        }
+        if (report.observations.length > 0) {
+            lines.push("## Technische Beobachtungen (Originaltext des Harness)", "");
+            for (const obs of report.observations)
+                lines.push(`- Aufruf ${obs.callNumber}, ${obs.tool}: ${obs.description}`);
+            lines.push("");
+        }
+    }
+    lines.push("## Was dieser Test nicht aussagt", "");
+    for (const limit of LIMITS)
+        lines.push(`- ${limit}`);
+    lines.push("");
+    const meta = [file.harnessVersion ? `Harness ${file.harnessVersion}` : null, file.generatedAt ? `erstellt ${file.generatedAt}` : null].filter(Boolean);
+    if (meta.length > 0)
+        lines.push(`_${meta.join(", ")}_`, "");
+    return lines.join("\n");
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+// Rendert das Markdown oben in ein eigenständiges HTML. Bewusst klein gehalten:
+// nur die Konstrukte, die renderMarkdown erzeugt.
+export function renderHtmlBody(file) {
+    const markdown = renderMarkdown(file);
+    const out = [];
+    let inCode = false;
+    let inList = false;
+    const closeList = () => {
+        if (inList) {
+            out.push("</ul>");
+            inList = false;
+        }
+    };
+    const inline = (text) => escapeHtml(text)
+        .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
+        .replace(/`(.+?)`/g, "<code>$1</code>");
+    for (const line of markdown.split("\n")) {
+        if (line.startsWith("```")) {
+            closeList();
+            out.push(inCode ? "</pre>" : "<pre>");
+            inCode = !inCode;
+            continue;
+        }
+        if (inCode) {
+            out.push(escapeHtml(line));
+            continue;
+        }
+        if (line.startsWith("### ")) {
+            closeList();
+            out.push(`<h3>${inline(line.slice(4))}</h3>`);
+        }
+        else if (line.startsWith("## ")) {
+            closeList();
+            out.push(`<h2>${inline(line.slice(3))}</h2>`);
+        }
+        else if (line.startsWith("# ")) {
+            closeList();
+            out.push(`<h1>${inline(line.slice(2))}</h1>`);
+        }
+        else if (line.startsWith("- ")) {
+            if (!inList) {
+                out.push("<ul>");
+                inList = true;
+            }
+            out.push(`<li>${inline(line.slice(2))}</li>`);
+        }
+        else if (line.trim() === "") {
+            closeList();
+        }
+        else if (line.startsWith("_") && line.endsWith("_") && line.length > 2) {
+            closeList();
+            out.push(`<p><em>${escapeHtml(line.slice(1, -1))}</em></p>`);
+        }
+        else {
+            closeList();
+            out.push(`<p>${inline(line)}</p>`);
+        }
+    }
+    closeList();
+    return out;
+}
+export function renderHtml(file) {
+    const out = renderHtmlBody(file);
+    const verdict = file.verdict ?? "NOT_TESTED";
+    const colour = verdict === "PASS" ? "#1a7f37" : verdict === "FAIL" ? "#cf222e" : "#9a6700";
+    return [
+        "<!doctype html>",
+        '<html lang="de"><head><meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        "<title>Ergebnis des Agent-Tests</title>",
+        "<style>",
+        ":root{color-scheme:light dark;--fg:#1f2328;--bg:#fff;--muted:#59636e;--accent:" + colour + "}",
+        "@media (prefers-color-scheme:dark){:root{--fg:#e6edf3;--bg:#0d1117;--muted:#9198a1}}",
+        "body{font:16px/1.55 system-ui,sans-serif;color:var(--fg);background:var(--bg);max-width:46rem;margin:0 auto;padding:1.5rem 1rem}",
+        "h2:first-of-type{border-left:6px solid var(--accent);padding-left:.6rem}",
+        "pre{white-space:pre-wrap;background:rgba(127,127,127,.12);padding:.8rem;border-radius:6px}",
+        "code{background:rgba(127,127,127,.15);padding:.1rem .3rem;border-radius:4px}",
+        "em{color:var(--muted)}",
+        "</style></head><body>",
+        ...out,
+        "</body></html>",
+        "",
+    ].join("\n");
+}
+export async function runReportMode(argv) {
+    let file;
+    let format;
+    let outPath;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--format") {
+            const v = argv[++i];
+            if (v !== "md" && v !== "html") {
+                process.stderr.write(`Error: --format must be "md" or "html", got "${v ?? ""}".\n`);
+                return 1;
+            }
+            format = v;
+        }
+        else if (token === "--out") {
+            outPath = argv[++i];
+        }
+        else if (token.startsWith("--")) {
+            process.stderr.write(`Error: unknown option ${token}\nUsage: report <report-file> [--format md|html] [--out <file>]\n`);
+            return 1;
+        }
+        else if (file === undefined) {
+            file = token;
+        }
+        else {
+            process.stderr.write(`Error: unexpected argument ${token}\n`);
+            return 1;
+        }
+    }
+    if (file === undefined) {
+        process.stderr.write("Error: report needs the report file written by the proxy.\nUsage: report <report-file> [--format md|html] [--out <file>]\n");
+        return 1;
+    }
+    const info = await stat(file).catch(() => null);
+    if (!info || !info.isFile()) {
+        process.stderr.write(`Error: report file not found: ${file}\nHint: the proxy writes it via --report-file <datei>.\n`);
+        return 1;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, "utf8"));
+    }
+    catch {
+        process.stderr.write(`Error: ${file} is not valid JSON. It may still be written; try again after the proxy has exited.\n`);
+        return 1;
+    }
+    const chosen = format ?? (outPath && extname(outPath).toLowerCase() === ".html" ? "html" : "md");
+    const text = chosen === "html" ? renderHtml(parsed) : renderMarkdown(parsed);
+    if (outPath) {
+        await writeFile(outPath, text, "utf8");
+        process.stdout.write(`Bericht geschrieben: ${outPath}\n`);
+    }
+    else {
+        process.stdout.write(text);
+    }
+    return 0;
+}

package/dist/ui/page.js

@@ -0,0 +1,210 @@
+// Die Seite der geführten Oberfläche. Ein Dokument, keine Abhängigkeiten.
+// Dynamische Texte werden nur über textContent eingesetzt; eingebettet wird allein
+// das serverseitig escapte Berichts-HTML (renderHtmlBody).
+export const PAGE_HTML = `<!doctype html>
+<html lang="de">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Agent-Test</title>
+<style>
+:root{color-scheme:light dark;--fg:#1f2328;--bg:#fff;--card:#f6f8fa;--line:#d0d7de;--muted:#59636e;--accent:#0969da;--ok:#1a7f37;--bad:#cf222e;--warn:#9a6700}
+@media (prefers-color-scheme:dark){:root{--fg:#e6edf3;--bg:#0d1117;--card:#161b22;--line:#30363d;--muted:#9198a1;--accent:#4493f8;--ok:#3fb950;--bad:#f85149;--warn:#d29922}}
+*{box-sizing:border-box}
+body{margin:0;font:17px/1.55 system-ui,-apple-system,Segoe UI,sans-serif;color:var(--fg);background:var(--bg)}
+main{max-width:46rem;margin:0 auto;padding:1.5rem 16px 4rem}
+h1{font-size:1.7rem;margin:.2rem 0 .4rem}
+h2{font-size:1.25rem;margin:0 0 .6rem}
+p{margin:.5rem 0}
+.lead{color:var(--muted)}
+section{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:1.1rem 1.2rem;margin:1.1rem 0}
+section[hidden]{display:none}
+.step{font-size:.85rem;color:var(--muted);text-transform:uppercase;letter-spacing:.04em}
+.warn{border-left:5px solid var(--warn);background:rgba(154,103,0,.12);padding:.7rem .9rem;border-radius:6px;margin:.8rem 0}
+button{font:inherit;padding:.65rem 1.1rem;border-radius:8px;border:1px solid var(--accent);background:var(--accent);color:#fff;cursor:pointer;margin:.3rem .4rem .3rem 0}
+button.secondary{background:transparent;color:var(--accent)}
+button:disabled{opacity:.45;cursor:not-allowed}
+input[type=text]{font:inherit;width:100%;padding:.55rem .7rem;border-radius:8px;border:1px solid var(--line);background:var(--bg);color:var(--fg)}
+label{display:block;margin:.7rem 0 .2rem;font-weight:600}
+.hint{font-size:.9rem;color:var(--muted)}
+ul.checks{list-style:none;padding:0;margin:.6rem 0}
+ul.checks li{padding:.35rem 0;border-bottom:1px solid var(--line)}
+.ok::before{content:"\\2714  ";color:var(--ok)}
+.err::before{content:"\\2718  ";color:var(--bad)}
+.fix{margin:.2rem 0 0 1.5rem;color:var(--muted);font-size:.95rem}
+pre{white-space:pre-wrap;word-break:break-word;background:var(--bg);border:1px solid var(--line);border-radius:8px;padding:.7rem;font-size:.9rem}
+code{background:rgba(127,127,127,.15);padding:.1rem .3rem;border-radius:4px}
+.cols{display:grid;gap:1rem;grid-template-columns:1fr}
+@media (min-width:44rem){.cols{grid-template-columns:1fr 1fr}}
+.report h1{font-size:1.2rem}.report h2{font-size:1.1rem}.report h3{font-size:1rem}
+.status{font-weight:600}
+</style>
+</head>
+<body>
+<main>
+<h1>Agent-Test</h1>
+<p class="lead">Dieses Programm prüft, ob ein KI-Agent bei einem Fehler sauber reagiert. Zum Beispiel: ob er nach einem Timeout eine Buchung doppelt anlegt. Du brauchst dafür kein Terminal.</p>
+
+<section id="s1">
+<div class="step">Schritt 1 von 4</div>
+<h2>Bevor es losgeht</h2>
+<div class="warn"><strong>Wichtig:</strong> Der Test führt echte Schreibvorgänge aus, zum Beispiel legt er Buchungen an. Verwende nur ein <strong>Testsystem</strong>, niemals echte Kundendaten oder ein Live-System.</div>
+<label style="font-weight:400"><input type="checkbox" id="confirm"> Ich teste nur mit einem Testsystem.</label>
+<p><button id="go1" disabled>Weiter</button></p>
+</section>
+
+<section id="s2" hidden>
+<div class="step">Schritt 2 von 4</div>
+<h2>Was möchtest du tun?</h2>
+<p><button id="pickDemo">Demo ansehen</button> <span class="hint">Ohne eigenen Agenten. Zeigt zwei Beispiel-Agenten und wie ein Ergebnis aussieht.</span></p>
+<p><button id="pickOwn" class="secondary">Meinen Agenten prüfen</button> <span class="hint">Du brauchst einen Testserver und einen Agenten, der ihn nutzt.</span></p>
+</section>
+
+<section id="sdemo" hidden>
+<h2>Demo: zwei Beispiel-Agenten</h2>
+<p class="hint">Das sind zwei fest eingebaute Beispiel-Agenten, nicht dein Agent. Beide bekommen denselben Fehler: Der Schreibvorgang klappt, der Agent sieht aber nur einen Timeout.</p>
+<p id="demoWait">Wird berechnet …</p>
+<div class="cols">
+<div><h3>Vorsichtiger Agent</h3><div class="report" id="demoCareful"></div></div>
+<div><h3>Unvorsichtiger Agent</h3><div class="report" id="demoNaive"></div></div>
+</div>
+<p><button id="demoBack" class="secondary">Zurück</button></p>
+</section>
+
+<section id="s3" hidden>
+<div class="step">Schritt 3 von 4</div>
+<h2>Testserver angeben und prüfen</h2>
+<p>Wie wird dein Testserver gestartet? Die meisten Server starten mit <code>node</code> und einer Datei.</p>
+<label for="cmd">Programm</label>
+<input type="text" id="cmd" value="node">
+<label for="file">Start-Datei deines Servers</label>
+<input type="text" id="file" placeholder="z. B. C:\\projekte\\mein-server\\dist\\server.js">
+<p class="hint">Der vollständige Pfad zur Datei. Leerzeichen im Pfad sind in Ordnung.</p>
+<label for="extra">Weitere Argumente (nur wenn nötig)</label>
+<input type="text" id="extra" placeholder="meist leer">
+<p><button id="useBundled" class="secondary" hidden>Mitgeliefertes Testsystem verwenden</button></p>
+<p><button id="check">Prüfen</button></p>
+<ul class="checks" id="checks"></ul>
+<div id="tools" class="hint"></div>
+<p><button id="go3" hidden>Weiter</button> <button id="back3" class="secondary">Zurück</button></p>
+</section>
+
+<section id="s4" hidden>
+<div class="step">Schritt 4 von 4</div>
+<h2>Agent anschließen</h2>
+<p>Trage den Test in dein Agenten-Programm ein. Dein Agent startet den Harness dann selbst. Danach gib ihm eine Aufgabe, bei der etwas geschrieben wird, zum Beispiel: <em>„Lege eine Buchung für Muster AG am 3. November über 250 CHF an.“</em></p>
+<label>Claude Code (ein Befehl im Terminal)</label>
+<pre id="cfgCode"></pre>
+<p><button id="copyCode" class="secondary">Kopieren</button></p>
+<label>Claude Desktop oder andere Programme (Konfigurationsdatei)</label>
+<pre id="cfgJson"></pre>
+<p><button id="copyJson" class="secondary">Kopieren</button></p>
+<p class="hint">Der Bericht wird hier gespeichert: <code id="reportPath"></code></p>
+<p class="status" id="status">Warte auf den Agenten …</p>
+<div class="report" id="result"></div>
+<p><a id="dl" href="#" hidden>Bericht als Datei speichern</a></p>
+</section>
+</main>
+<script>
+(function () {
+  var TOKEN = "__TOKEN__";
+  function $(id) { return document.getElementById(id); }
+  function show(id) { ["s1","s2","sdemo","s3","s4"].forEach(function (s) { $(s).hidden = (s !== id); }); window.scrollTo(0, 0); }
+  function api(path, body) {
+    var opts = { headers: { "x-harness-token": TOKEN } };
+    if (body !== undefined) { opts.method = "POST"; opts.headers["content-type"] = "application/json"; opts.body = JSON.stringify(body); }
+    return fetch(path, opts).then(function (r) { return r.json().then(function (j) { if (!r.ok) throw new Error(j.error || "Fehler"); return j; }); });
+  }
+  function copy(text, btn) {
+    var done = function () { var t = btn.textContent; btn.textContent = "Kopiert"; setTimeout(function () { btn.textContent = t; }, 1500); };
+    if (navigator.clipboard) { navigator.clipboard.writeText(text).then(done, function () {}); }
+  }
+
+  $("confirm").addEventListener("change", function () { $("go1").disabled = !$("confirm").checked; });
+  $("go1").addEventListener("click", function () { show("s2"); });
+
+  // --- Demo
+  $("pickDemo").addEventListener("click", function () {
+    show("sdemo"); $("demoWait").hidden = false;
+    api("/api/demo", {}).then(function (d) {
+      $("demoCareful").innerHTML = d.careful; $("demoNaive").innerHTML = d.naive; $("demoWait").hidden = true;
+    }).catch(function (e) { $("demoWait").textContent = "Fehler: " + e.message; });
+  });
+  $("demoBack").addEventListener("click", function () { show("s2"); });
+
+  // --- Eigener Agent
+  var bundled = null, ready = null, timer = null;
+  api("/api/info").then(function (info) { bundled = info.bundledTestsystem; if (bundled) { $("useBundled").hidden = false; } });
+  $("pickOwn").addEventListener("click", function () { show("s3"); });
+  $("back3").addEventListener("click", function () { show("s2"); });
+  $("useBundled").addEventListener("click", function () { $("cmd").value = "node"; $("file").value = bundled; $("extra").value = ""; });
+
+  function unquote(text) {
+    var t = text.trim();
+    if (t.length > 1 && (t[0] === '"' || t[0] === "'") && t[t.length - 1] === t[0]) { t = t.slice(1, -1); }
+    return t;
+  }
+  function currentArgs() {
+    var file = unquote($("file").value);
+    return (file ? [file] : []).concat(splitArgs($("extra").value.trim()));
+  }
+
+  function splitArgs(text) {
+    // Pfade mit Leerzeichen in Anführungszeichen; sonst an Leerzeichen trennen.
+    var out = [], cur = "", q = null;
+    for (var i = 0; i < text.length; i++) {
+      var c = text[i];
+      if (q) { if (c === q) { q = null; } else { cur += c; } }
+      else if (c === '"' || c === "'") { q = c; }
+      else if (c === " ") { if (cur) { out.push(cur); cur = ""; } }
+      else { cur += c; }
+    }
+    if (cur) out.push(cur);
+    return out;
+  }
+
+  $("check").addEventListener("click", function () {
+    var list = $("checks"); list.textContent = ""; $("tools").textContent = ""; $("go3").hidden = true; ready = null;
+    var args = currentArgs();
+    $("check").disabled = true;
+    api("/api/doctor", { command: $("cmd").value.trim(), args: args }).then(function (r) {
+      r.checks.forEach(function (c) {
+        var li = document.createElement("li"); li.className = c.ok ? "ok" : "err";
+        li.appendChild(document.createTextNode(c.label));
+        if (!c.ok && (c.fix || c.detail)) { var d = document.createElement("div"); d.className = "fix"; d.textContent = (c.detail ? c.detail + " " : "") + (c.fix ? "\\u2192 " + c.fix : ""); li.appendChild(d); }
+        list.appendChild(li);
+      });
+      if (r.toolLines.length) { $("tools").textContent = "Erkannte Tools: " + r.toolLines.map(function (t) { return t.trim().replace(/\\s+/g, " "); }).join("; "); }
+      if (r.ok) { ready = { command: $("cmd").value.trim(), args: args }; $("go3").hidden = false; }
+    }).catch(function (e) { var li = document.createElement("li"); li.className = "err"; li.textContent = e.message; list.appendChild(li); })
+      .then(function () { $("check").disabled = false; });
+  });
+
+  $("go3").addEventListener("click", function () {
+    api("/api/config", ready).then(function (cfg) {
+      $("cfgCode").textContent = cfg.claudeCode; $("cfgJson").textContent = cfg.claudeDesktop; $("reportPath").textContent = cfg.reportFile;
+      $("copyCode").onclick = function () { copy(cfg.claudeCode, $("copyCode")); };
+      $("copyJson").onclick = function () { copy(cfg.claudeDesktop, $("copyJson")); };
+      show("s4"); poll();
+    }).catch(function (e) { alert(e.message); });
+  });
+
+  function poll() {
+    if (timer) clearInterval(timer);
+    var tick = function () {
+      api("/api/status").then(function (s) {
+        if (s.state === "waiting") { $("status").textContent = "Warte auf den Agenten …"; }
+        else if (s.state === "connected") { $("status").textContent = "Der Agent ist verbunden. Warte auf den ersten Schreibvorgang …"; }
+        else {
+          $("status").textContent = "Zwischenstand, wird bei jedem weiteren Aufruf aktualisiert:";
+          $("result").innerHTML = s.body; $("dl").hidden = false; $("dl").href = "/api/report.html?t=" + encodeURIComponent(TOKEN);
+        }
+      }).catch(function () {});
+    };
+    tick(); timer = setInterval(tick, 2000);
+  }
+})();
+</script>
+</body>
+</html>
+`;

package/dist/ui/server.js

@@ -0,0 +1,247 @@
+// Geführte Oberfläche für Menschen ohne Terminal. Kleiner lokaler Server
+// (nur 127.0.0.1, Zufalls-Token, Host-Prüfung), der dieselben Bausteine nutzt wie
+// die Kommandozeile: doctor, report, benchmark. Keine Abhängigkeiten.
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectDoctor } from "../doctor.js";
+import { renderHtml, renderHtmlBody } from "../plain-report.js";
+import { runBenchmark, defaultConfig } from "../benchmark/runner.js";
+import { VERSION } from "../version.js";
+import { PAGE_HTML } from "./page.js";
+const MAX_BODY = 64 * 1024;
+function cliPath() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "index.js");
+}
+function bundledTestsystem() {
+    const candidate = resolve(dirname(cliPath()), "..", "examples", "testsystem", "server.mjs");
+    return existsSync(candidate) ? candidate : null;
+}
+// Ein Argument so quoten, dass es in Terminal-Befehlen mit Leerzeichen funktioniert.
+function quoteArg(arg) {
+    return /^[A-Za-z0-9_@%+=:,./\\-]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '\\"')}"`;
+}
+function sameToken(a, b) {
+    if (!a || a.length !== b.length)
+        return false;
+    return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new Error("Anfrage zu gross");
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("Ungültige Anfrage");
+    return value;
+}
+function send(res, status, body, type, extra = {}) {
+    res.writeHead(status, {
+        "content-type": type,
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+        "referrer-policy": "no-referrer",
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+        ...extra,
+    });
+    res.end(body);
+}
+function sendJson(res, status, value) {
+    send(res, status, JSON.stringify(value), "application/json; charset=utf-8");
+}
+function stringArray(value, what) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > 30 || value.some((v) => typeof v !== "string" || v.length > 1000)) {
+        throw new Error(`${what} ist ungültig`);
+    }
+    return value;
+}
+function demoFile(run) {
+    const report = run.reports[0];
+    return {
+        harnessVersion: VERSION,
+        certification: "UNVERIFIED_FOR_PRODUCTION",
+        verdict: report.verdict,
+        report,
+        score: run.score,
+        patches: run.patches,
+        generatedAt: new Date().toISOString(),
+    };
+}
+export async function startUi(options = {}) {
+    const token = randomBytes(16).toString("hex");
+    let port = 0;
+    let session = null;
+    const readSessionReport = async () => {
+        if (!session)
+            return null;
+        try {
+            return JSON.parse(await readFile(session.reportFile, "utf8"));
+        }
+        catch {
+            return null; // noch nicht da oder gerade im Schreiben
+        }
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((err) => {
+            sendJson(res, 400, { error: err instanceof Error ? err.message : "Fehler" });
+        });
+    });
+    async function handle(req, res) {
+        const host = req.headers.host ?? "";
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
+            return sendJson(res, 403, { error: "Host nicht erlaubt" });
+        }
+        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+        const queryToken = url.searchParams.get("t") ?? undefined;
+        const headerToken = req.headers["x-harness-token"];
+        const given = typeof headerToken === "string" ? headerToken : queryToken;
+        if (!sameToken(given, token)) {
+            return sendJson(res, 403, { error: "Zugriff nur über den ausgegebenen Link möglich" });
+        }
+        if (req.method === "GET" && url.pathname === "/") {
+            return send(res, 200, PAGE_HTML.replace("__TOKEN__", token), "text/html; charset=utf-8");
+        }
+        if (req.method === "GET" && url.pathname === "/api/info") {
+            return sendJson(res, 200, { version: VERSION, bundledTestsystem: bundledTestsystem() });
+        }
+        if (req.method === "POST" && url.pathname === "/api/doctor") {
+            const body = await readJson(req);
+            const command = typeof body.command === "string" ? body.command.trim() : "";
+            if (command.length > 300)
+                throw new Error("Programm ist zu lang");
+            const result = await collectDoctor({
+                command,
+                upstreamArgs: stringArray(body.args, "Argumente"),
+                writeTools: [],
+                readTools: [],
+            });
+            return sendJson(res, 200, result);
+        }
+        if (req.method === "POST" && url.pathname === "/api/config") {
+            const body = await readJson(req);
+            const command = typeof body.command === "string" ? body.command.trim() : "";
+            if (!command)
+                throw new Error("Programm fehlt");
+            const args = stringArray(body.args, "Argumente");
+            const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+            const baseDir = process.env.CUONZTECH_HARNESS_DIR ?? join(homedir(), "CuonzTech-Agent-Harness");
+            const runDir = join(baseDir, stamp);
+            await mkdir(runDir, { recursive: true });
+            const reportFile = join(runDir, "harness-report.json");
+            session = { reportFile };
+            const proxyArgs = [
+                cliPath(), "proxy",
+                "--upstream-command", command,
+                ...args.flatMap((a) => ["--upstream-arg", a]),
+                // Das mitgelieferte Testsystem schreibt in den Lauf-Ordner, nicht neben das Programm.
+                ...(args.includes(bundledTestsystem() ?? "\0") ? ["--upstream-env-var", `TESTSYSTEM_DATA=${join(runDir, "bookings.json")}`] : []),
+                "--scenario", "F1",
+                "--audit-tools", "off",
+                "--report-file", reportFile,
+            ];
+            const claudeCode = ["claude mcp add --scope user agent-harness --", process.execPath, ...proxyArgs].map((p, i) => (i === 0 ? p : quoteArg(p))).join(" ");
+            const claudeDesktop = JSON.stringify({ mcpServers: { "agent-harness": { command: process.execPath, args: proxyArgs } } }, null, 2);
+            return sendJson(res, 200, { claudeCode, claudeDesktop, reportFile });
+        }
+        if (req.method === "GET" && url.pathname === "/api/status") {
+            if (!session)
+                return sendJson(res, 200, { state: "waiting" });
+            const file = await readSessionReport();
+            if (!file)
+                return sendJson(res, 200, { state: "waiting" });
+            if (!file.report)
+                return sendJson(res, 200, { state: "connected" });
+            return sendJson(res, 200, { state: "result", verdict: file.verdict, body: renderHtmlBody(file).join("\n") });
+        }
+        if (req.method === "GET" && url.pathname === "/api/report.html") {
+            const file = await readSessionReport();
+            if (!file)
+                return sendJson(res, 404, { error: "Noch kein Bericht vorhanden" });
+            return send(res, 200, renderHtml(file), "text/html; charset=utf-8", {
+                "content-disposition": 'attachment; filename="agent-test-bericht.html"',
+            });
+        }
+        if (req.method === "POST" && url.pathname === "/api/demo") {
+            const config = defaultConfig();
+            config.scenarios = ["F1"];
+            const result = await runBenchmark(config);
+            return sendJson(res, 200, {
+                careful: renderHtmlBody(demoFile(result.careful)).join("\n"),
+                naive: renderHtmlBody(demoFile(result.naive)).join("\n"),
+            });
+        }
+        sendJson(res, 404, { error: "Nicht gefunden" });
+    }
+    await new Promise((ok, fail) => {
+        server.once("error", fail);
+        server.listen(options.port ?? 0, "127.0.0.1", () => ok());
+    });
+    const address = server.address();
+    port = typeof address === "object" && address ? address.port : 0;
+    const url = `http://127.0.0.1:${port}/?t=${token}`;
+    if (options.open !== false)
+        openBrowser(url);
+    return {
+        url,
+        close: () => new Promise((ok) => server.close(() => ok())),
+    };
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+        : process.platform === "darwin" ? ["open", [url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => undefined);
+        child.unref();
+    }
+    catch {
+        // Der Link steht auch im Terminal.
+    }
+}
+export async function runUiMode(argv) {
+    let port;
+    let open = true;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--no-open")
+            open = false;
+        else if (token === "--port") {
+            const raw = argv[++i] ?? "";
+            if (!/^\d+$/.test(raw) || Number(raw) > 65535) {
+                process.stderr.write(`Error: --port must be a number between 0 and 65535, got "${raw}".\n`);
+                return 1;
+            }
+            port = Number(raw);
+        }
+        else {
+            process.stderr.write(`Error: unknown option ${token}\nUsage: ui [--port <n>] [--no-open]\n`);
+            return 1;
+        }
+    }
+    const handle = await startUi({ port, open });
+    process.stdout.write(`Oberfläche: ${handle.url}\n`);
+    process.stdout.write("Läuft nur auf diesem Rechner. Beenden mit Strg+C.\n");
+    await new Promise((ok) => {
+        const stop = () => {
+            void handle.close().then(ok);
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cuonztech-agent-harness",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "mcpName": "io.github.cuonztech/agent-harness",
   "description": "Chaos-Proxy für MCP-Server: injiziert F1-F5-Fehlerszenarien (Ghost-Write nach Timeout, 429, defektes JSON, Duplicate Dispatch, 500) vor einem echten Upstream-MCP-Server und prüft, ob ein Agent Schreibvorgänge doppelt ausführt. Mit Resilience Score und System-Prompt-Patches für beobachtetes Fehlverhalten.",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/cuonztech/agent-harness",
     "source": "github"
   },
-  "version": "0.5.2",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "cuonztech-agent-harness",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       }