Synartesis

Eine Undo-Ebene für KI-Agenten.

Ein Agent mit Schreibzugriff auf ein echtes System führt zwanzig Schritte aus, liest Schritt sieben falsch und wendet den Rest auf die falschen Datensätze an. Heute haben Sie die Wahl, es von Hand anhand des Transkripts rückgängig zu machen, ein Backup wiederherzustellen und dabei jede legitime Änderung zu verlieren, die im selben Zeitraum vorgenommen wurde, oder den Schaden zu akzeptieren.

Synartesis sitzt zwischen Ihrem MCP-Client und den Servern, mit denen er spricht. Es zeichnet jeden Tool-Aufruf zusammen mit dem Zustand auf, den dieser Aufruf ersetzt hat, und es kann diesen Zustand wiederherstellen. Was nicht wiederhergestellt werden kann, lässt es einen Agenten nicht unbeaufsichtigt tun.

Es ist keine Sandbox: Der Container, in dem Ihr Agent läuft, ist wegwerfbar, aber die CRM-Zeile, die er über das Netzwerk aktualisiert hat, ist es nicht. Es ist kein Tracing-Werkzeug: Eine Spur sagt Ihnen, dass update_customer vierzigmal lief, nicht, wie die Werte vorher waren.

Was es kann und was nicht

Jedes Tool erhält eine von vier Klassifizierungen, die Sie in einem Manifest festhalten:

Ein Tool, das Ihr Manifest nicht erwähnt, wird als irreversible behandelt. Das ist beabsichtigt: Das stille Weiterleiten eines unbekannten destruktiven Aufrufs ist der eine Fehler, den man am meisten vermeiden sollte.

Related MCP server: mcp-compensator

Voraussetzungen

pnpm wird mit Node über corepack geliefert:

corepack enable pnpm

Die C-Toolchain wird einmal benötigt, um die nativen SQLite-Bindungen zu kompilieren. Unter macOS führen Sie xcode-select --install aus; unter Debian oder Ubuntu apt install build-essential.

Installation

curl -fsSL https://raw.githubusercontent.com/ArhaanDev24/Synartesis/main/install.sh | bash

Oder aus einem Klon, falls Sie es lieber zuerst lesen möchten:

git clone https://github.com/ArhaanDev24/Synartesis.git && cd Synartesis && ./install.sh

Das Skript prüft Ihre Node-Version, baut und verlinkt synartesis und synartesis-proxy in das erste beschreibbare Verzeichnis, das bereits in Ihrem PATH liegt. Es bearbeitet kein Shell-Profil und benötigt kein sudo. Übergeben Sie --no-link, um nur zu bauen.

synartesis --help

Wenn nichts verlinkt werden konnte, bricht nichts: Jeder Befehl, den Synartesis ausgibt, schreibt sich selbst in der Form aus, die auf Ihrer Maschine tatsächlich läuft.

Durchlauf

Dies verwendet ein Spielzeug-CRM, das im Repository enthalten ist, sodass Sie die gesamte Schleife sehen können, ohne etwas auf echte Daten zu richten. Führen Sie es aus einem leeren Verzeichnis aus.

mkdir -p /tmp/synartesis-demo && cd /tmp/synartesis-demo

1. Eine Richtlinie schreiben

init startet einen Server, fragt ihn, welche Tools er hat, und schreibt ein Manifest. Ersetzen Sie SYNARTESIS durch den Pfad, in den Sie geklont haben.

node SYNARTESIS/dist/cli.js init crm -- node SYNARTESIS/dist/toy-crm.js --state ./crm.json

Öffnen Sie synartesis.yaml. Jedes Tool, das kein selbstdeklarierter Lesezugriff ist, beginnt als irreversible mit einem TODO. Das Durcharbeiten dieser TODOs ist die Aufgabe. Eine fertige Richtlinie für dieses Fixture ist im Repository enthalten, also kopieren Sie sie, statt sie abzutippen:

cp SYNARTESIS/manifests/toy-crm.yaml ./synartesis.yaml

Bearbeiten Sie dann die eine Zeile, die angibt, wo der Server lebt, sodass sie auf Ihren Klon zeigt und seine Daten in diesem Verzeichnis behält:

servers:
  crm:
    command: node
    args: ["SYNARTESIS/dist/toy-crm.js", "--state", "./crm.json"]

2. Ihren Agenten auf den Proxy richten

Wo immer Ihr MCP-Client Server auflistet, ersetzen Sie den Eintrag für den Server, den Sie abdecken möchten, durch den Proxy. Für Claude Desktop oder Claude Code ist das ein mcpServers-Block:

{
  "mcpServers": {
    "crm": {
      "command": "node",
      "args": ["SYNARTESIS/dist/proxy.js", "--manifest", "/tmp/synartesis-demo/synartesis.yaml"]
    }
  }
}

Der Agent sieht dieselben Tools mit denselben Namen und denselben Ergebnissen. Das ist der Punkt: An Ihrem Agenten ändert sich nichts.

Für diesen Durchlauf benötigen Sie keinen echten Agenten. Das bewirkt dasselbe:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo-agent","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"update_customer","arguments":{"id":"c_001","plan":"free","notes":"wrong edit"}}}' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"delete_customer","arguments":{"id":"c_002"}}}' | node SYNARTESIS/dist/proxy.js --manifest ./synartesis.yaml --journal ./journal.db > /dev/null

Sehen Sie sich den Schaden an:

cat crm.json

Ada ist auf dem falschen Plan mit den falschen Notizen, und Grace ist weg.

3. Sehen, was es getan hat

node SYNARTESIS/dist/cli.js list --journal ./journal.db

node SYNARTESIS/dist/cli.js show RUN_ID --journal ./journal.db

show gibt jeden Aufruf mit seiner Klasse, seinem Status und dem genauen Aufruf aus, der ihn rückgängig machen würde, bereits zu Literalwerten aufgelöst.

4. Rückgängig machen

Erst schauen, dann springen:

node SYNARTESIS/dist/cli.js undo RUN_ID --dry-run --journal ./journal.db

Dann ausführen:

node SYNARTESIS/dist/cli.js undo RUN_ID --journal ./journal.db

cat crm.json

Grace ist zurück und Ada ist auf ihrem ursprünglichen Plan, mit ihren ursprünglichen Notizen.

5. Zusehen, wie es sich weigert

Undo ist kein stumpfes Werkzeug. Wenn etwas anderes einen Datensatz geändert hat, nachdem der Agent ihn berührt hat, würde das Zurückschreiben des alten Werts diese Arbeit zerstören. Synartesis stoppt also und zeigt Ihnen beide Werte.

Führen Sie den Schadensbefehl aus Schritt 2 erneut aus. Das erzeugt einen zweiten Lauf, also nehmen Sie die Lauf-ID von oben aus list, das nach neuestem zuerst sortiert ist. Bearbeiten Sie dann den Datensatz von Hand:

node -e 'const f="./crm.json",s=JSON.parse(require("fs").readFileSync(f));s.customers.c_001.notes="a human wrote this";require("fs").writeFileSync(f,JSON.stringify(s,null,2))'

node SYNARTESIS/dist/cli.js undo RUN_ID --journal ./journal.db

Es hält an, gibt den erwarteten und den tatsächlichen Zustand aus, beendet sich mit einem Exit-Code ungleich Null und ändert nichts.

Genehmigen, was nicht rückgängig gemacht werden kann

send_email ist als irreversible klassifiziert, sodass der Agent keinen von sich aus senden kann. Der Aufruf wird sofort abgelehnt mit einer Aktions-ID und dem Befehl, der ihn genehmigen würde. Der Agent sagt es Ihnen, Sie entscheiden, und er versucht es erneut.

Es hält den Aufruf nicht offen, während es wartet. Das war das erste Design und es überlebt keinen Kontakt mit einem echten Client: Jedes brauchbare Zeitfenster für einen Menschen, es zu bemerken, ein Terminal zu öffnen und zu entscheiden, ist länger, als ein Client auf ein Tool warten wird, sodass die beiden nicht durch die Wahl eines besseren Timeouts in Einklang gebracht werden können.

Die Genehmigung erfolgt auch nicht auf dem Terminal, das der Agent verwendet: Der Proxy spricht MCP über stdin und stdout, sodass es dort nichts gibt, worauf man auffordern könnte, und ein Desktop-Client hat überhaupt kein Terminal. Die Anfrage geht an das Journal, und Sie beantworten sie von überall:

node SYNARTESIS/dist/cli.js gates --journal ./journal.db

node SYNARTESIS/dist/cli.js approve ACTION_ID --by your-name --journal ./journal.db

node SYNARTESIS/dist/cli.js deny ACTION_ID --by your-name --reason "not this one" --journal ./journal.db

Eine Genehmigung ist einmalig verwendbar und läuft nach einer Stunde ab, sodass sie den Wiederholungsversuch abdeckt, für den sie erteilt wurde, und nicht stillschweigend denselben Aufruf morgen autorisieren kann. Sie ist nicht an eine Sitzung gebunden, weil Menschen ihren Client neu starten und eine in einer toten Sitzung gestrandete Genehmigung überhaupt keine Genehmigung wäre.

Nichts wird jemals durch Schweigen genehmigt. Eine unbeantwortete Anfrage bleibt einfach unbeantwortet, sichtbar in synartesis gates, bis jemand entscheidet.

Dem Agenten wird all dies mitgeteilt, wenn er sich verbindet, sodass er sich erklären kann, statt einen undurchsichtigen Fehler zu melden.

Echte Server

Wenn Sie lieber Schritten folgen, als darüber zu lesen, gibt es eine Anleitung zum Ausführen gegen Ihre eigenen Dateien, wobei das Gate und die Driftprüfung die beiden Dinge sind, die es wert sind, absichtlich getestet zu werden.

Synartesis hat nichts Besonderes mit E-Mail zu tun. Es sitzt auf dem MCP-Protokoll, sodass sein Gegenstand das ist, was die Server, die Sie verbunden haben, tun können: Ihre Dateien, Ihre Repositorys, Ihre Datenbank, Ihre Tickets, das eigene Gedächtnis Ihres Agenten. Was es rückgängig machen kann, hängt vollständig davon ab, was diese Server bereitstellen, und jedes Manifest unten sagt klar, wo das endet.

Jedes davon außer github.yaml wurde gegen den tatsächlich laufenden Server geprüft. Zwei Demos führen die gesamte Schleife wirklich aus:

./demo/filesystem-demo.sh
./demo/memory-demo.sh

Die Dateisystem-Demo überschreibt eine Datei und verschiebt eine andere, stellt beide wieder her und zeigt dann, wie Undo sich weigert, wenn ein Mensch die Datei zwischendurch bearbeitet hat, und wie das Gate sich weigert, ein Verzeichnis zu erstellen, das dieser Server nicht entfernen kann.

Die Speicher-Demo ist die schärfere. Der Agent fügt zwei Personen zum Graphen hinzu, von denen eine bereits vorhanden war, und der Server ignoriert das Duplikat stillschweigend. Undo muss daher genau eine von ihnen entfernen: Die Inverse wird aus dem gebaut, was der Server gesagt hat, dass es erstellt wurde, nicht aus dem, was der Agent verlangt hat, sodass die Person, die zuerst da war, das Rückgängigmachen überlebt. Dieselbe Sitzung versucht dann, eine Entität zu löschen, und wird angehalten, weil das Löschen einer Entität auch jede Beziehung löscht, die sie berührt, und ein inverser Aufruf nicht beides zurückbringen kann.

Wo jedes einzelne endet

Die Grenzen sind der interessante Teil, und sie sind Eigenschaften der Server und nicht von Synartesis.

• filesystem: move_file ist allein aus seinen Argumenten reversibel, daher wird kein Vorab-Lesen deklariert und Drift kann dafür nicht geprüft werden. create_directory ist irreversible, nicht weil Verzeichnisse kostbar sind, sondern weil dieser Server keine Möglichkeit bietet, eines zu entfernen.

• memory: add_observations und delete_observations sind exakte Gegensätze, die sich darüber uneinig sind, wie dasselbe Feld zu nennen ist. Ein Pfad kann ein Feld lesen und keines umbenennen, daher kann diese Inverse überhaupt nicht geschrieben werden und der Aufruf wird stattdessen gegated.

• git: Fast jede Leseoperation, die dieser Server anbietet, antwortet in Prosa, die für einen Menschen gedacht ist, sodass fast nichts aus einem erfassten Zustand invertiert werden kann, wie reversibel die zugrunde liegende Git-Operation auch sein mag. Commits werden gegated, weil dieser Server kein Reset, kein Revert und keine Möglichkeit bietet, einen Branch zu verschieben.

Zwei Dinge, die es wert sind zu wissen, wenn Sie Ihr eigenes schreiben, beide gefunden, indem diese gegen Live-Server ausgeführt wurden, statt durch das Lesen von Dokumentation:

$result ist der strukturierte Block, und er muss nicht mit dem Textblock übereinstimmen. Der Speicher-Server antwortet auf create_entities mit einer nackten Liste in seinem Textblock und {"entities": [...]} in structuredContent. Synartesis durchläuft den strukturierten, weil das der maschinenlesbare Vertrag ist.

Und synartesis check beweist, dass ein Tool existiert, nicht, dass ein Pfad aufgelöst wird. Das kann es nicht: Es wurde kein Aufruf getätigt, also gibt es kein Ergebnis zu durchlaufen. Führen Sie das Ding einmal aus und lesen Sie synartesis show, bevor Sie sich auf eine Inverse verlassen.

Ein Manifest schreiben

Das Manifest ist das gesamte Produkt. Es sollte fünfzehn Minuten für eine API dauern, die Sie kennen.

version: 1

servers:
  crm:
    command: node
    args: ["./crm-server.js"]

tools:
  - match: "crm.get_customer"
    class: readonly

  # Read the record before overwriting it, then write that record back.
  - match: "crm.update_customer"
    class: reversible
    snapshot:
      tool: "crm.get_customer"
      args:
        id: "$.id"
    inverse:
      tool: "crm.update_customer"
      args:
        id: "$.id"
        name: "$snapshot.name"
        plan: "$snapshot.plan"

  # Nothing to read beforehand; the id only exists once the call returns.
  - match: "crm.create_customer"
    class: compensable
    inverse:
      tool: "crm.delete_customer"
      args:
        id: "$result.id"

  - match: "crm.send_*"
    class: irreversible
    gate: always

Es gibt genau drei Dinge, auf die sich ein Wert beziehen kann:

Alles andere ist ein Literal. Eine Referenz kann allein stehen, in welchem Fall der Wert seinen Typ behält, oder innerhalb eines Satzes sitzen, in welchem Fall sie als Text eingesetzt wird:

sha: "$result.content.sha"                 # the value itself
message: "Revert agent change to $.path"   # text with the path substituted

Schreiben Sie $$ für ein literales Dollarzeichen. Es gibt keine Ausdrücke, Bedingungen oder Funktionen, und es wird sie nicht geben: In dem Moment, in dem dies eine Sprache wird, hört es auf, etwas zu sein, das Sie in fünfzehn Minuten schreiben können.

Pfade können eine Liste mit [0] indizieren und ein Feld von jedem Element mit [] lesen:

labels: "$snapshot.labels[].name"   # [{name: "bug"}, ...] becomes ["bug", ...]

Das deckt den häufigen Fall ab, in dem eine API ein Feld reicher zurückgibt, als sie es annimmt, was GitHub mit Issue-Labels tut. [] liest denselben Schlüssel aus jedem Element und sonst nichts: Es ist immer noch ein Pfad, keine Transformation. Eine Referenz kopiert Werte, sie kann sie nicht berechnen, sodass eine API, die eine wirklich andere Form benötigt, eine ist, bei der die Inverse dieses Feld weglassen sollte – und das sagen sollte.

Weitere Dinge, die Sie wissen sollten:

• match unterstützt *, das innerhalb eines Segments passt: crm.send_* passt zu crm.send_email, aber nicht zu crm.a.b. Das spezifischste Muster gewinnt, unabhängig von der Reihenfolge, in der die Regeln geschrieben sind.

• Die Umkehrung eines Patches sollte jede Feld wiederherstellen, nicht einen Patch erneut anwenden. Wenn derselbe Datensatz in einem Lauf zweimal bearbeitet wird, lässt eine partielle Umkehrung die Felder zurück, die die zweite Bearbeitung berührt hat.

• gate: on_write ist eine Absicherung für Werke wie ein Raw-SQL-Werkzeug, bei dem Zerstörungskraft nicht aus dem Werkzeugnamen ablesen lässt. Alles, was nicht eindeutig als eine einzelne Leseanweisung eingestuft werden kann, wird über das Gate geführt. Verwenden Sie gate: always, wo Sicherheit von Bedeutung ist.

• Ein fehlerhaftes Manifest verhindert das Starten des Proxys: Datei und Zeile, die zu korrigieren sind, werden genannt. Er wird nie mit einer Richtlinie laufen, die er nicht verstehen konnte.

Befehle

--manifest und --journal werden gefunden, nicht getippt. Beide werden vom aktuellen Verzeichnis aufwärts gesucht, so wie ein Versionskontrollsystem seine Wurzelnung findet. In einem Projekt mit einer synartesis.yaml funktionieren daher alle Befehle ganz ohne Flags. Ein noch nicht vorhandenes Journal wird neben der Richtlinie abgelegt, damit der Proxy, der es erstellt, und die CLI, die es liest, übereinstimmen, ohne dass einem von beiden etwas mitgeteilt werden müsste.

Weitere Flags: --dry-run, --to <seq> und --replan für undo, --all für approve und deny, --json für list, show und gates.

Exit-Codes: 0 Erfolg, 1 Anhalten oder Verweigern, 2 Fehlerhafter Aufruf oder Fehlkonfiguration.

Der Proxy verarbeitet --manifest, --journal, --gate-timeout <seconds> und --log-level. Er schreibt strukturiertes JSON nach stderr; stdout bleibt dem Protokoll vorbehalten.

Was er nicht tut

• Es kann nicht ungesendet machen, was einmal gesehen wurde. Eine gelesene E-Mail, ein bereits geposteter Kommentar, eine ohne Backup gelöschte Datei. Dafür gibt es das Gate.

• Kompensierbare Aktionen können nicht auf Drift geprüft werden. Sie deklarieren keine Vorab-Lesung, deshalb kompensiert Undo sie und markiert sie in seinem Bericht als [unverified].

• Undo bleibt bei Unsicherheit stehen, und wandert über das bloß Endgültige hinweg. Drift, ein unbekannter Ausgang oder ein fehlgeschlagene Aufruf zur Umkehrung stoppen ihn, weil ein Hinweggehen darüber etwas zerstören könnte. Eine Aktion die sich nur nicht umkehren lässt, wie nach dem Senden einer E-Mail, wird gemeldet und bleibt an Ort und Quelle, während alles andere zurückgesetzt wird: Kein Anhalten macht sie rückgängig, und ein Anhalten würde er nur den Rest falsch wiederherstellen. In jedem Fall erhält der Lauf den Status partial.

• Ein mitten im Übertragungszustand unterbrochener Aufruf wird als unbekannt erfasst, nicht als fehlgeschlagen. Undo weigert sich, daran vorbei zu gehen, weil sich nicht feststellen lässt, ob er überhaupt gewirkt hat.

• Ein Undo ist nur so gut wie die Richtlinie, die ihn aufgezeichnet hat. Die Umkehrung wird beim Zeitpunkt des Aufrufes aufgelöst, nicht beim Ausführen des Undo. Ein Fehler im Manifest fließt daher in jeden Lauf unter diesem Manifest ein. undo --replan baut sie aus einem korrigierten Manifest anhand der bereits erfassten Zustände neu auf – das ist der Ausweg.

Das kann man dabei sehen

Synartesis ist kein Dienstprogramm und kann auches nicht vertretbar. Ein MCP-Client startet einen Stdio-Server selbst und kontrolliert seine Lebensdauer, deshalb kann kein lang laufender Prozess dazwischensicher sein und die Aufrufe sehen. Was man sich von einem Daemon erwünscht, ist meistens die Sicherheit, dass er da ist und arbeitet; dafür braucht es eine Stelle zum Nachsehen und keinen Halbgrundprozess:

synartesis watch

Es zeichnet sich neu, '''wührend der Agent arbeitet:''' was aufgerufen wurde, welche Klasse ein Aufruf hatte und was auf eine Entscheidung wartet, mit dem Befehl zum Freigeben. Ctrl-C stoppt ihn. Kommt es als Pipedpipe statt im Terminal, gibt es den Zustand einmal aus und endet.

Vertrauen

Ein Manifest nennt Befehle und Synartesis führt sie aus. Gehen Sie mit einem, das Sie nicht geschrieben haben, so um wie mit einem Shell-Skript aus derselben Quelle: Lesen Sie es zuerst. Es gibt hier keine Sandbox, und das ist auch nicht vorgesehen.

Entwicklung

pnpm test

pnpm typecheck && pnpm lint

Jeder Push läuft auf Linux und macOS mit Node 22 und 24 aus, plus der Demo und dem Installer.

Lizenz

MIT. Siehe LICENSE.