Plugins können den Agenten jetzt in den Hintergrund kopieren: fork_session und Idle-Tasks

Du schreibst ein Plugin, das nach jedem Turn eine Sache tun soll: prüfen, ob die Session einen Skill erstellt oder geändert hat, und wenn ja, entscheiden, ob es sich lohnt, ihn dem Team zu empfehlen.
Klingt klein. Ist es nicht. In post_llm_call bekommst du Kontext, aber keinen sauberen Griff auf die Frage „welche Tools hat dieser Turn genutzt, wo stehen die Zähler“ — also zählst du selbst. Um die Arbeit im Hintergrund laufen zu lassen, startest du einen Thread, sicherst Re-Entry ab und behandelst den Fall „der Nutzer hat gerade noch eine Nachricht geschickt“. Am Ende hast du eine zweite, schlechtere Implementierung des Background-Reviews, den der Core ohnehin fährt — mit anderem Verhalten und ohne gemeinsames Vokabular, wenn sie sich danebenbenimmt.
PR #146732 (49 Dateien, ~4.500 Zeilen, gemerged am 13. November) räumt das auf: Die beiden Hintergrundmuster, die der Core für sich selbst nutzt, sind jetzt Plugin-APIs — ctx.fork_session und ctx.register_idle_task. Hier steht, was sie tun, wo die Kanten sind und wie du dagegen programmierst, ohne in einem halben Jahr umzuschreiben.
Zwei Muster in einem Satz
ctx.fork_sessionkopiert den Agenten der Session nach einem Turn in den Hintergrund, mit demselben System-Prompt, derselben Tool-Liste, demselben Memory und derselben Konversation, und arbeitet einen mehrstufigen Prompt durch. Es ist das Muster hinter Hermes’ eigenem Background-Memory- und Skill-Review.ctx.register_idle_taskgibt Arbeit, die keinen Turn hat, an den sie sich hängen kann — Daten täglich neu bewerten, einen Cache kompaktieren, eine Aufräumaktion vorschlagen — den Idle-Schedule des Skill-Curators.
Beide sind experimental. Die Docs sagen ausdrücklich, dass sich Signaturen und die Form des Fork-Handles ändern können. Daraus folgt eine harte Code-Regel: Halte das Handle in einer kleinen Funktion, die reine Daten zurückgibt, und speichere es niemals über den Turn hinaus.
fork_session: eine Hintergrundkopie des Turn-Agenten
handle = ctx.fork_session(
token, # side_question_token aus post_llm_call
prompt, # <= 8192 Zeichen
tools=(), # erlaubte Tool-Namen
max_iterations=8, # 1..16
input_budget=None, # kann die Grenze nur enger ziehen
task=None, # auf dem Modell einer Auxiliary-Task-Lane laufen
timeout=None, # Sekunden, <= 1800
)
Es gibt ein Handle zurück, oder None, wenn nichts gestartet wurde.
Die wichtige Eigenschaft: Ein Fork teilt System-Prompt und tools[] des laufenden Turns Byte für Byte, seine erste Anfrage besteht also überwiegend aus Prompt-Cache-Reads. Du zahlst für „ein paar Schritte mehr im Hintergrund“, nicht dafür, einen frischen Agenten hochzuziehen.
Was ein Fork nicht tut, ist ebenso klar:
- Nichts wird ins Transkript oder in die Session-Datenbank geschrieben. Hintergrundarbeit kann die Konversation nicht verschmutzen.
- Genehmigungen für gefährliche Befehle werden automatisch verweigert. Ein Fork kann nicht in deinem Namen „approve“ klicken.
- Der nächste Live-Turn bricht den Fork ab — laufend, startend oder noch zurückgestellt.
Die letzte Regel ist das Designzentrum. Ein Fork ist die After-Party eines Turns, kein Daemon. Wenn du langlebige Arbeit über Turns hinweg brauchst, ist das Cron oder ein Idle-Task, kein Fork.
Ein Token, eine Chance
token ist das side_question_token aus post_llm_call, und die Regeln sind strenger, als der Name vermuten lässt:
- Eine Anfrage pro Turn, Side-Question oder Fork, geteilt von allen Plugins.
- Unbeaufsichtigte Turns haben kein Token: Cron-Läufe und Subagent-Turns bekommen
None. - Ein Plugin ohne
llm.session_forkbekommtNoneund verbraucht das Token nicht. - Ein Tool außerhalb der Allowlist zu nennen, gibt
Nonezurück, ohne das Token zu verbrauchen; jedes andereNoneverbraucht es.
Diese Unterscheidung zählt: Ein Tippfehler im Tool-Namen kostet dich nichts, aber eine Ablehnung aus einem anderen Grund (etwa weil der Session-Agent freigegeben wurde) verbrennt die eine Chance. Also nicht im Hook auf Verdacht probieren.
Die Tool-Allowlist: deine eigenen Tools, sonst nichts
Ein Fork darf eine schmale Menge aufrufen:
- Tools, die dein Plugin mit
register_toolregistriert hat (und deren aktuelle Registrierung noch deine ist, dispatcht über die Tool-Registry); - Core-Tools, die Hermes als fork-safe markiert — derzeit keine.
Alles andere liegt draußen: Tools anderer Plugins, jedes MCP-Tool, Connectoren, Memory-Provider- und Context-Engine-Tools sowie delegate_task, message_agent, cronjob_manage und die Kanban-Tools.
Es gibt noch eine subtilere Ebene: Selbst ein Name, den du registriert hast, liegt außerhalb der Allowlist, wenn Hermes ihn vor der Tool-Registry dispatcht (Agent-Level-Tools, Legacy-Aliase, die Tool-Search-Bridge, jeder Name der Form connectors__<connector>__<tool>), weil der Aufruf deinen Handler nie erreichen würde.
Der praktische Effekt: Ein Fork kann nur „Aktionen, die dieses Plugin definiert“. Er kann kein Hintertürchen werden, um einen Subagenten zu starten oder einen Cron-Job zu planen.
Budgets, Timeouts, Abbruch
max_iterationsbegrenzt die Schleife des Forks zwischen 1 und 16.- Aggregierte Input-Tokens sind begrenzt wie beim Background-Review (
auxiliary.background_review.max_input_tokens, Default 75 % des Kontextfensters);input_budgetkann das nur weiter senken. timeoutist Wall-Clock in Sekunden, maximal 1800, und kooperativ — der Fork stoppt an seiner nächsten Interrupt-Prüfung.- Nächster Turn startet → wartende und laufende Forks werden abgebrochen.
Eine Zeile aus den Docs gehört in deine Kommentare kopiert: Ein Provider-Aufruf, der den Interrupt ignoriert, hält das Handle offen, bis er zurückkehrt. Nutze immer ein begrenztes handle.wait(t); warte nie unbegrenzt.
Das Handle und seine Outcomes
Das Handle bietet done, cancelled, outcome, result (der finale Text des Forks oder None), actions (die aufgerufenen Allowlist-Tool-Namen, in Reihenfolge), wait(timeout) und cancel(). Es gibt niemals den Fork-Agenten selbst heraus.
Mit outcome debuggst du:
| outcome | Bedeutung |
|---|---|
deferred |
wartet auf eine freie Maschine auf einer lokal verwalteten Runtime (gebündelter llama-server), wie beim Background-Review |
running |
läuft gerade |
ok |
fertig, result hält den Text |
cancelled |
durch den nächsten Turn oder cancel() abgebrochen |
superseded |
ein neuerer zurückgestellter Fork desselben Plugins und derselben Session hat ihn ersetzt |
timeout |
Wall-Clock abgelaufen |
budget_exhausted |
Input-Budget aufgebraucht |
error |
Runtime-Fehler |
error:spawn |
der Worker-Thread konnte nicht starten (du bekommst ein abgeschlossenes Handle, keine Exception) |
refused:<reason> |
parent_gone, moa, agent_provider oder runtime_changed |
Einen Fork vom Live-Agenten unterscheiden
Ein Tool-Handler, der in einem Fork aufgerufen wird, bekommt das Keyword turn_origin="plugin_fork:<plugin id>". Aufrufe des Live-Agenten tragen kein turn_origin.
Das schließt ein echtes Loch: Ohne diese Info kann ein Tool nicht unterscheiden, ob „das Modell beschlossen hat, das zu teilen“ oder „der Hintergrund-Check hat das Teilen vorgeschlagen“. Das offizielle Beispiel nutzt genau das — das Tool bietet die Share-Karte nur an, wenn es aus plugin_fork:wisdom aufgerufen wird.
Auch die Abrechnung ist getrennt: Nutzung wird der Session als plugin_fork:<plugin id> berechnet, und jede Provider-Anfrage feuert pre_auxiliary_call / post_auxiliary_call mit aux_task="plugin_fork" und plugin_id — nie das turn-gebundene pre_api_request / post_api_request.
register_idle_task: Arbeit ohne Turn, an den sie sich hängt
ctx.register_idle_task(name, fn, interval_hours=24, min_idle_hours=2, first_run="defer")
Es gibt eine PluginRegistration zurück (dispose sie, um das Polling zu stoppen). Tasks werden geplant aus:
- dem Gateway-Housekeeping, für jedes bediente Profil;
- dem Start von CLI / TUI;
- dem Maintenance-Tick von
hermes serve.
fn läuft auf einem eigenen Thread, in dem Profil, das sie registriert hat. Der Host wartet nicht: Das Polling kehrt sofort zurück, und ein zweiter Lauf derselben Task startet nie, solange einer läuft.
Der State lebt im Datenverzeichnis des Plugins unter idle-tasks/<name>.json — last_run_at, run_count, paused, last_summary, last_status, last_error —, sodass jedes Profil seine eigene Kopie plant.
Drei Verträge für fn, deren Bruch über Nacht Rätsel produziert:
- Kurz halten. Gib ihr ein eigenes Zeitlimit, arbeite in kleinen Batches, checkpoint in die Plugin-Daten, damit der nächste Lauf weitermacht.
- Idempotent halten. Ein Lauf, den ein Restart abschneidet, zeichnet nichts auf und startet wieder von vorn. Denselben Batch zweimal laufen zu lassen, muss harmlos sein.
- Nicht auf ein Stop-Signal warten. Beim Herunterfahren des Gateways startet kein neuer Lauf, und das Gateway wartet ein paar Sekunden auf den laufenden und stoppt dann ohne ihn. Plugin-Code lässt sich nicht stoppen und
fnbekommt kein Signal — wenn sie fertig ist, zeichnet sie nichts auf (der State bleibt wie vor dem Lauf) und gibt ihren Claim frei.
Zu Claims: Ein Run-Claim hält seinen Owner fest (PID, Prozess-Start, Maschine). Ein abgestürzter Owner wird beim nächsten Poll übernommen, nicht erst nach einer Stunde; nur ein Owner, der nicht geprüft werden kann (ein Claim, der auf einer anderen Maschine geschrieben wurde), gilt nach einer Stunde als verlassen. Der Curator teilt diese Implementierung — das Interval-Gate und der Run-Claim sind in diesem PR nach agent/idle_schedule.py gewandert.
Modellaufrufe aus fn gehen über ctx.llm und dessen Trust-Gate. Beachte, was fn nicht hat: keinen Turn, also kein side_question_token, also keinen Fork.
Idle-Tasks von der CLI aus verwalten
hermes plugins idle-tasks # jeder Idle-Task in diesem Profil
hermes plugins idle-tasks <plugin> # die Tasks eines Plugins
hermes plugins idle-tasks <plugin> --pause nightly-reindex
hermes plugins idle-tasks <plugin> --resume nightly-reindex
Das Listing zeigt Status, Laufanzahl, letzten und nächsten Lauf sowie die letzte Zusammenfassung oder den letzten Fehler. Es ist der schnellste Weg, „lief mein Task überhaupt“ zu beantworten — viel schneller als Logs zu lesen.
review_signals: dem Rhythmus des Nutzers folgen
post_llm_call bekommt jetzt auch review_signals: ob Skill-Review und Memory-Review fällig sind, die Zähler, die Intervalle und ob Background-Review an ist.
Das zählt, weil der alte Workaround — „jeden N-ten Turn prüfen“ — deine Turns zählte, während der Nutzer einen anderen Rhythmus eingestellt hatte. Jetzt kannst du die Einstellungen des Nutzers lesen und dich dem Selbstlern-Rhythmus von Hermes anschließen, statt einen eigenen zu erfinden.
Wenn es nicht verfügbar ist
plugins.isolation: host: Dasctx.fork_sessioneines Drittanbieter-Plugins existiert, wirft aberPluginHostUnsupported(einRuntimeError), weil das Handle einen Thread des Live-Session-Agenten innerhalb des Hermes-Prozesses verfolgt.- Cron- und Subagent-Turns: kein
side_question_token, also kein Fork. - MoA- und Agent-as-Provider-Runtimes: Outcome ist
refused:moaoderrefused:agent_provider.
Die dokumentierte Degradierung ist schlicht: Behandle None und Exceptions als „diesmal kein Fork“, damit das Plugin in beiden Umgebungen funktioniert.
def _try_fork(ctx, token, prompt):
try:
return ctx.fork_session(token, prompt, tools=["wisdom_offer_share"], max_iterations=4)
except Exception: # PluginHostUnsupported oder irgendetwas anderes
return None
Ein minimales, funktionierendes Beispiel
import json
import threading
def register(ctx):
def offer_share(args, turn_origin=None, **kwargs):
if turn_origin != "plugin_fork:wisdom":
return json.dumps({"error": "only the background check may offer a share"})
return json.dumps({"offered": True})
ctx.register_tool("wisdom_offer_share", "wisdom", OFFER_SCHEMA, offer_share)
def on_post_llm_call(side_question_token=None, review_signals=None, **kwargs):
if side_question_token is None or not (review_signals or {}).get("skill_review_due"):
return
handle = ctx.fork_session(
side_question_token,
"Did this session change a skill the team would benefit from? "
"If so, call wisdom_offer_share once; otherwise answer 'no'.",
tools=["wisdom_offer_share"],
max_iterations=4,
)
if handle is not None:
threading.Thread(
target=lambda: handle.wait(600) and ctx.state.set("last_check", handle.outcome),
daemon=True,
).start()
ctx.register_hook("post_llm_call", on_post_llm_call)
Und die Capability gehört ins Plugin-Manifest:
capabilities:
- llm.session_fork
Der Consent-Screen, den Nutzer sehen, sagt ungefähr: „Run a background copy of your agent after a turn. It sees the whole session, including memory, can use the plugin’s own tools, and spends your main model’s tokens.“
Dieser Satz ist die beste Design-Notiz des ganzen Features: Ein Fork sieht die gesamte Session. Wenn dein Plugin die Ausgabe eines Forks an Dritte weiterreicht, denk das vorher durch.
Status: nur main, und experimental
PR #146732 wurde am 13. November 2026 gemerged, lebt auf main und ist nicht in v0.23.1. Beide APIs sind ausdrücklich experimental, Signaturen können sich also bewegen.
Update (17.11.2026): Diese Änderungen sind mit v0.23.2 (16. November) erschienen – ein
hermes updatebringt sie. Die Formulierung „nicht in v0.23.1“ oben ist eine Momentaufnahme vom Veröffentlichungstag.
Praxis:
- Das Plugin muss funktionieren, wenn
fork_sessionNoneliefert oder wirft („diesmal kein Fork“). - Behalte das Handle nie über Turns im State; es überlebt keinen.
- Warte immer mit einer Grenze.
- Führe
hermes plugins validatevor dem Ausliefern aus — siehe Plugin-Katalog-Leitfaden, Isolation Mode und die Liste der öffentlichen Plugin-API.
Wenn alles, was du brauchst, „meine Daten einmal am Tag neu bewerten“ ist, ist register_idle_task die einfachere Wahl: keine Capability, kein Token, und Pause/Resume plus Crash-Übernahme gibt es gratis. Ein Fork ist für Arbeit, die unmittelbar nach diesem Turn landen und den Kontext dieses Turns sehen muss. Wählst du das Falsche, kämpft der Code die ganze Zeit gegen dich.