Los plugins ya pueden copiar el agente en segundo plano: fork_session y tareas idle

Escribes un plugin que debería hacer una cosa después de cada turno: comprobar si la sesión creó o cambió una skill y, si es así, decidir si merece la pena recomendarla al equipo.
Suena pequeño. No lo es. Dentro de post_llm_call tienes contexto pero ningún asidero limpio sobre “qué herramientas usó este turno, dónde están los contadores”, así que los cuentas tú. Para ejecutar el trabajo en segundo plano lanzas un hilo, te proteges contra la reentrada y gestionas “el usuario acaba de mandar otro mensaje”. Con lo que terminas es con una segunda implementación, peor, de la revisión en segundo plano que el core ya ejecuta, con comportamiento distinto y sin vocabulario compartido cuando falla.
El PR #146732 (49 archivos, unas 4.500 líneas, fusionado el 13 de noviembre) arregla eso: los dos patrones de segundo plano que el core usa para sí mismo son ahora APIs de plugin, ctx.fork_session y ctx.register_idle_task. Aquí va qué hacen, dónde están los bordes y cómo escribir contra ellas sin tener que reescribir todo en seis meses.
Dos patrones en una frase
ctx.fork_sessioncopia el agente de la sesión al segundo plano después de un turno, arrastrando el mismo system prompt, lista de herramientas, memoria y conversación, y trabaja sobre un prompt de varios pasos. Es el patrón que hay detrás de la revisión de memoria y de skills del propio Hermes.ctx.register_idle_taskda trabajo que no tiene turno del que colgarse — volver a puntuar datos a diario, compactar una caché, sugerir una limpieza — el calendario idle del curador de skills.
Ambas son experimentales. La documentación dice explícitamente que las firmas y la forma del handle de fork pueden cambiar. Eso te da una regla de código dura: mantén el handle dentro de una función pequeña que devuelva datos planos, y no lo guardes más allá del turno.
fork_session: una copia en segundo plano del agente del turno
handle = ctx.fork_session(
token, # post_llm_call's side_question_token
prompt, # <= 8192 characters
tools=(), # allowed tool names
max_iterations=8, # 1..16
input_budget=None, # can only tighten the bound
task=None, # run on one auxiliary task lane's model
timeout=None, # seconds, <= 1800
)
Devuelve un handle, o None cuando no se arrancó nada.
La propiedad importante: un fork comparte el system prompt y el tools[] del turno vivo byte a byte, así que su primera petición es sobre todo lecturas de caché de prompt. Estás pagando por “unos pasos más en segundo plano”, no por levantar un agente nuevo desde cero.
Lo que un fork no hará está igual de claro:
- No se escribe nada en la transcripción ni en la base de datos de sesión. El trabajo en segundo plano no puede contaminar la conversación.
- Las aprobaciones de comandos peligrosos se deniegan automáticamente. Un fork no puede pulsar “aprobar” en tu nombre.
- El siguiente turno vivo cancela el fork, ya esté corriendo, arrancando o todavía diferido.
Esa última regla es el centro del diseño. Un fork es la fiesta posterior de un turno, no un demonio. Si necesitas trabajo de larga vida que cruce turnos, eso es cron o una tarea idle, no un fork.
Un token, una oportunidad
token es el side_question_token de post_llm_call, y las reglas son más estrictas de lo que sugiere el nombre:
- Una petición por turno, sea side question o fork, compartida por todos los plugins.
- Los turnos no atendidos no tienen token: las ejecuciones de cron y los turnos de subagente reciben
None. - Un plugin sin
llm.session_forkrecibeNoney no gasta el token. - Nombrar una herramienta fuera de la allowlist devuelve
Nonesin gastar el token; cualquier otroNonesí lo gasta.
Esa distinción importa: una errata en el nombre de una herramienta no te cuesta nada, pero un rechazo por otra razón (digamos que el agente de la sesión ya se liberó) quema la única oportunidad. Así que no pruebes a base de intentos dentro del hook.
La allowlist de herramientas: las tuyas, nada más
Un fork puede llamar a un conjunto estrecho:
- herramientas que tu plugin registró con
register_tool(y cuyo registro actual siga siendo tuyo, despachadas por el registro de herramientas); - herramientas del core que Hermes marque como seguras para fork: actualmente ninguna.
Todo lo demás queda fuera: herramientas de otros plugins, todas las herramientas MCP, los conectores, las herramientas de proveedor de memoria y de motor de contexto, y delegate_task, message_agent, cronjob_manage y las herramientas de Kanban.
Hay una capa más sutil: incluso un nombre que tú registraste queda fuera de la allowlist si Hermes lo despacha antes del registro de herramientas (herramientas a nivel de agente, alias heredados, el puente de Tool Search, cualquier nombre connectors__<connector>__<tool>), porque la llamada nunca llegaría a tu handler.
El efecto práctico: un fork solo puede hacer “acciones que este plugin define”. No puede convertirse en una puerta trasera para lanzar un subagente o programar un cron job.
Presupuestos, timeouts, cancelación
max_iterationslimita el bucle del fork entre 1 y 16.- Los tokens de entrada agregados están acotados igual que en la revisión en segundo plano (
auxiliary.background_review.max_input_tokens, por defecto el 75% de la ventana de contexto);input_budgetsolo puede bajarlo. timeoutson segundos de reloj de pared, como máximo 1800, y es cooperativo: el fork se detiene en su siguiente comprobación de interrupción.- Empieza el siguiente turno → los forks en cola y en ejecución se cancelan.
Una línea de la documentación merece copiarse en tus comentarios: una llamada al proveedor que ignora la interrupción mantiene el handle abierto hasta que vuelve. Usa siempre un handle.wait(t) acotado; nunca esperes sin límite.
El handle y sus resultados
El handle expone done, cancelled, outcome, result (el texto final del fork o None), actions (los nombres de herramientas de la allowlist que llamó, en orden), wait(timeout) y cancel(). Nunca expone el agente del fork en sí.
outcome es con lo que depuras:
| outcome | significado |
|---|---|
deferred |
esperando a que la máquina esté idle en un runtime gestionado localmente (llama-server empaquetado), como la revisión en segundo plano |
running |
en vuelo |
ok |
terminó, result lleva el texto |
cancelled |
cancelado por el siguiente turno o por cancel() |
superseded |
un fork diferido más nuevo del mismo plugin y sesión lo reemplazó |
timeout |
se agotó el tiempo de reloj |
budget_exhausted |
presupuesto de entrada agotado |
error |
error de runtime |
error:spawn |
el hilo del worker no pudo arrancar (recibes un handle resuelto, no una excepción) |
refused:<reason> |
parent_gone, moa, agent_provider o runtime_changed |
Distinguir un fork del agente vivo
Un handler de herramienta llamado dentro de un fork recibe la palabra clave turn_origin="plugin_fork:<plugin id>". Las llamadas que hace el agente vivo no llevan turn_origin.
Esto cierra un agujero real: sin ello, una herramienta no puede distinguir “el modelo decidió compartir esto” de “la comprobación en segundo plano sugirió compartirlo”. El ejemplo oficial usa exactamente eso: la herramienta solo ofrece la tarjeta de compartir cuando se llama desde plugin_fork:wisdom.
La facturación también queda separada: el uso se factura a la sesión como plugin_fork:<plugin id>, y cada petición al proveedor dispara pre_auxiliary_call / post_auxiliary_call con aux_task="plugin_fork" y plugin_id, nunca los pre_api_request / post_api_request del ámbito de turno.
register_idle_task: trabajo que no tiene turno del que colgarse
ctx.register_idle_task(name, fn, interval_hours=24, min_idle_hours=2, first_run="defer")
Devuelve un PluginRegistration (dispónlo para dejar de sondear). Las tareas se programan desde:
- el housekeeping del gateway, para cada perfil servido;
- el arranque de la CLI / TUI;
- el tick de mantenimiento de
hermes serve.
fn corre en su propio hilo, en el perfil que lo registró. El host no espera: el sondeo vuelve de inmediato, y una segunda ejecución de la misma tarea nunca arranca mientras una esté en vuelo.
El estado vive en el directorio de datos del plugin, en idle-tasks/<name>.json — last_run_at, run_count, paused, last_summary, last_status, last_error — así que cada perfil programa su propia copia.
Tres contratos para fn, y romperlos produce misterios de madrugada:
- Que sea corta. Dale su propio límite de tiempo, trabaja en lotes pequeños, guarda checkpoints en los datos del plugin para que la siguiente ejecución continúe.
- Que sea idempotente. Una ejecución cortada por un reinicio no registra nada y vuelve a empezar desde el principio. Correr el mismo lote dos veces tiene que ser inofensivo.
- No esperes una señal de parada. Al apagar el gateway no arranca ninguna ejecución nueva y el gateway espera unos segundos a la que está en vuelo, luego se detiene sin ella. El código de un plugin no se puede detener y
fnno recibe señal: cuando termina no registra nada (el estado queda como estaba antes de la ejecución) y libera su claim.
Sobre los claims: un claim de ejecución registra su dueño (pid, arranque del proceso, máquina). Un dueño caído se toma en el siguiente sondeo, no una hora después; solo un dueño que no se puede comprobar (un claim escrito en otra máquina) cuenta como abandonado tras una hora. El curador comparte esta implementación: la puerta de intervalo y el claim de ejecución se movieron a agent/idle_schedule.py en este PR.
Las llamadas al modelo desde fn pasan por ctx.llm y su puerta de confianza. Nota lo que fn no tiene: ni turno, por tanto ni side_question_token, por tanto ni fork.
Gestionar tareas idle desde la CLI
hermes plugins idle-tasks # every idle task in this profile
hermes plugins idle-tasks <plugin> # one plugin's tasks
hermes plugins idle-tasks <plugin> --pause nightly-reindex
hermes plugins idle-tasks <plugin> --resume nightly-reindex
El listado muestra estado, número de ejecuciones, última y próxima ejecución, y el último resumen o error. Es la forma más rápida de responder a “¿se ejecutó de verdad mi tarea?”, mucho más rápida que leer logs.
review_signals: seguir el ritmo del propio usuario
post_llm_call ahora también recibe review_signals: si toca revisión de skills y de memoria, los contadores, los intervalos y si la revisión en segundo plano está activa.
Esto importa porque el apaño anterior — “comprobar cada N turnos” — contaba tus turnos mientras el usuario configuraba otro ritmo. Ahora puedes leer los ajustes del usuario y seguir el ritmo de autoaprendizaje del propio Hermes en vez de inventarte uno.
Cuándo no está disponible
plugins.isolation: host: elctx.fork_sessionde un plugin de terceros existe pero lanzaPluginHostUnsupported(unRuntimeError), porque el handle sigue un hilo del agente de la sesión viva dentro del proceso de Hermes.- Turnos de cron y de subagente: sin
side_question_token, así que sin fork. - Runtimes MoA y agente como proveedor: el outcome es
refused:moaorefused:agent_provider.
La degradación documentada es simple: trata None y las excepciones como “esta vez no hay fork”, para que el plugin funcione en ambos entornos.
def _try_fork(ctx, token, prompt):
try:
return ctx.fork_session(token, prompt, tools=["wisdom_offer_share"], max_iterations=4)
except Exception: # PluginHostUnsupported, or anything else
return None
Un ejemplo mínimo que funciona
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)
Y la capacidad va en el manifiesto del plugin:
capabilities:
- llm.session_fork
La pantalla de consentimiento que ven los usuarios dice más o menos: “Ejecuta una copia en segundo plano de tu agente después de un turno. Ve toda la sesión, incluida la memoria, puede usar las herramientas del propio plugin y gasta tokens de tu modelo principal.”
Esa frase es la mejor nota de diseño de toda la funcionalidad: un fork ve la sesión entera. Si tu plugin reenvía la salida de un fork a un tercero, piénsalo dos veces antes.
Estado: solo en main, y experimental
El PR #146732 se fusionó el 13 de noviembre de 2026, vive en main y no está en v0.23.1. Ambas APIs son explícitamente experimentales, así que las firmas pueden cambiar.
Actualización (17/11/2026): estos cambios salieron en la v0.23.2 (16 de noviembre):
hermes updatelos trae. Lo de «no está en la v0.23.1» es una foto del momento de la publicación.
Práctica:
- El plugin tiene que funcionar cuando
fork_sessiondevuelveNoneo lanza excepción (“esta vez no hay fork”). - Nunca guardes el handle en el estado entre turnos; no sobrevive a uno.
- Haz siempre
waitcon un límite. - Ejecuta
hermes plugins validateantes de publicar; mira la guía del catálogo de plugins, el modo de aislamiento y la lista de API pública de plugins.
Si lo único que necesitas es “volver a puntuar mis datos una vez al día”, register_idle_task es la opción fácil: sin capacidad, sin token, y obtienes pausa/reanudación y toma de control tras un crash gratis. Un fork es para trabajo que debe aterrizar justo después de este turno y debe ver el contexto de este turno. Elige mal y el código te peleará todo el camino.