Plugins agora podem copiar o agente para o background: fork_session e tarefas idle

Você escreve um plugin que deveria fazer uma coisa depois de cada turno: verificar se a sessão criou ou alterou uma skill e, em caso positivo, decidir se vale recomendar ao time.
Parece pequeno. Não é. Dentro de post_llm_call você recebe contexto, mas nenhum handle limpo para “quais ferramentas este turno usou, onde os contadores estão” — então você mesmo conta. Para rodar o trabalho em background você cria uma thread, protege a reentrada e trata “o usuário acabou de mandar outra mensagem”. O que sobra é uma segunda implementação, pior, da revisão em background que o core já roda, com comportamento diferente e sem vocabulário compartilhado quando ela se comporta mal.
O PR #146732 (49 arquivos, ~4.500 linhas, mergeado em 13 de novembro) resolve isso: os dois padrões de background que o core usa para si agora são APIs de plugin — ctx.fork_session e ctx.register_idle_task. Aqui está o que eles fazem, onde ficam as bordas e como escrever código contra eles sem precisar reescrever em seis meses.
Dois padrões em uma frase
ctx.fork_sessioncopia o agente da sessão para o background depois de um turno, carregando o mesmo system prompt, a lista de ferramentas, a memória e a conversa, e trabalha através de um prompt de vários passos. É o padrão por trás da revisão de memória e de skill do próprio Hermes.ctx.register_idle_taskdá lugar a trabalho que não tem turno ao qual se pendurar — recalcular scores de dados diariamente, compactar um cache, sugerir uma limpeza — o agendamento idle do curador de skills.
Ambos são experimentais. A documentação é explícita que assinaturas e o formato do handle de fork podem mudar. Isso te dá uma regra de código dura: mantenha o handle dentro de uma única função pequena que retorna dados simples, e nunca o guarde além do turno.
fork_session: uma cópia em background do agente do turno
handle = ctx.fork_session(
token, # side_question_token do post_llm_call
prompt, # <= 8192 caracteres
tools=(), # nomes de ferramentas permitidos
max_iterations=8, # 1..16
input_budget=None, # só pode apertar o limite
task=None, # roda no modelo de uma lane de tarefa auxiliar
timeout=None, # segundos, <= 1800
)
Retorna um handle, ou None quando nada foi iniciado.
A propriedade importante: um fork compartilha o system prompt e o tools[] do turno vivo byte a byte, então a primeira requisição dele é quase toda leitura de prompt cache. Você paga por “mais alguns passos em background”, não por levantar um agente novo.
O que um fork não faz é igualmente claro:
- Nada é escrito no transcript nem no banco da sessão. Trabalho em background não pode poluir a conversa.
- Aprovações de comando perigoso são negadas automaticamente. Um fork não pode clicar em “aprovar” no seu lugar.
- O próximo turno vivo cancela o fork — rodando, começando ou ainda adiado.
Essa última regra é o centro do design. Um fork é a after-party de um turno, não um daemon. Se você precisa de trabalho de vida longa atravessando turnos, isso é cron ou uma tarefa idle, não um fork.
Um token, uma chance
token é o side_question_token do post_llm_call, e as regras são mais estritas do que o nome sugere:
- Uma requisição por turno, side question ou fork, compartilhada entre todos os plugins.
- Turnos sem supervisão não têm token: execuções de cron e turnos de subagente recebem
None. - Um plugin sem
llm.session_forkrecebeNonee não gasta o token. - Nomear uma ferramenta fora da allowlist retorna
Nonesem gastar o token; qualquer outroNonegasta.
Essa distinção importa: um erro de digitação no nome de uma ferramenta não te custa nada, mas uma recusa por outro motivo (digamos, o agente da sessão foi liberado) queima a única chance. Então não fique sondando por tentativa e erro dentro do hook.
A allowlist de ferramentas: suas ferramentas, nada mais
Um fork pode chamar um conjunto estreito:
- ferramentas que seu plugin registrou com
register_tool(e cujo registro atual ainda é seu, despachadas pelo tool registry); - ferramentas do core que o Hermes marca como fork-safe — atualmente nenhuma.
Todo o resto fica de fora: ferramentas de outros plugins, toda ferramenta MCP, connectors, ferramentas de memory-provider e de context-engine, e delegate_task, message_agent, cronjob_manage e as ferramentas de Kanban.
Há uma camada mais sutil ainda: mesmo um nome que você registrou fica fora da allowlist se o Hermes o despacha antes do tool registry (ferramentas de nível de agente, aliases legados, a ponte do Tool Search, qualquer nome connectors__<connector>__<tool>), porque a chamada nunca chegaria ao seu handler.
O efeito prático: um fork só consegue fazer “ações que este plugin define”. Ele não pode virar porta dos fundos para criar um subagente ou agendar um cron job.
Orçamentos, timeouts, cancelamento
max_iterationslimita o loop do fork entre 1 e 16.- Os tokens de entrada agregados são limitados como na revisão em background (
auxiliary.background_review.max_input_tokens, padrão de 75% da janela de contexto); oinput_budgetsó pode baixar isso. timeouté em segundos de relógio, no máximo 1800, e é cooperativo — o fork para na próxima checagem de interrupção.- Próximo turno começa → forks na fila e rodando são cancelados.
Uma linha da documentação merece ser copiada para os seus comentários: uma chamada de provider que ignora a interrupção mantém o handle aberto até retornar. Sempre use um handle.wait(t) limitado; nunca espere sem limite.
O handle e seus desfechos
O handle expõe done, cancelled, outcome, result (o texto final do fork ou None), actions (os nomes de ferramentas da allowlist que ele chamou, em ordem), wait(timeout) e cancel(). Ele nunca expõe o próprio agente do fork.
outcome é com o que você depura:
| outcome | significado |
|---|---|
deferred |
esperando a máquina ficar idle num runtime gerenciado localmente (llama-server embutido), como a revisão em background |
running |
em execução |
ok |
terminou, result tem o texto |
cancelled |
cancelado pelo próximo turno ou por cancel() |
superseded |
um fork adiado mais novo do mesmo plugin e sessão o substituiu |
timeout |
o relógio estourou |
budget_exhausted |
orçamento de entrada esgotado |
error |
erro de runtime |
error:spawn |
a thread de worker não pôde iniciar (você recebe um handle resolvido, não uma exceção) |
refused:<reason> |
parent_gone, moa, agent_provider ou runtime_changed |
Distinguindo um fork do agente vivo
Um handler de ferramenta chamado dentro de um fork recebe a keyword turn_origin="plugin_fork:<plugin id>". Chamadas feitas pelo agente vivo não carregam turn_origin.
Isso fecha um buraco real: sem ele, uma ferramenta não consegue distinguir “o modelo decidiu compartilhar isto” de “a checagem em background sugeriu compartilhar”. O exemplo oficial usa exatamente isso — a ferramenta só oferece o card de compartilhamento quando é chamada a partir de plugin_fork:wisdom.
A cobrança também é separada: o uso é faturado para a sessão como plugin_fork:<plugin id>, e cada requisição ao provider dispara pre_auxiliary_call / post_auxiliary_call com aux_task="plugin_fork" e plugin_id — nunca o pre_api_request / post_api_request do escopo do turno.
register_idle_task: trabalho sem turno ao qual se pendurar
ctx.register_idle_task(name, fn, interval_hours=24, min_idle_hours=2, first_run="defer")
Retorna um PluginRegistration (descarte-o para parar o polling). As tarefas são agendadas a partir de:
- housekeeping do gateway, para cada profile atendido;
- inicialização da CLI / TUI;
- o tick de manutenção do
hermes serve.
fn roda na própria thread, no profile que a registrou. O host não espera: o poll retorna imediatamente, e uma segunda execução da mesma tarefa nunca começa enquanto uma está em execução.
O estado vive no diretório de dados do plugin em idle-tasks/<name>.json — last_run_at, run_count, paused, last_summary, last_status, last_error — então cada profile agenda a própria cópia.
Três contratos para fn, e quebrá-los produz mistérios da noite para o dia:
- Mantenha curto. Dê um limite de tempo próprio, trabalhe em lotes pequenos, faça checkpoint no diretório de dados do plugin para que a próxima execução continue.
- Mantenha idempotente. Uma execução cortada por um restart não registra nada e roda de novo desde o início. Rodar o mesmo lote duas vezes precisa ser inofensivo.
- Não espere um sinal de parada. No shutdown do gateway nenhuma execução nova começa e o gateway espera alguns segundos pela que está em execução, depois encerra sem ela. Código de plugin não pode ser parado e
fnnão recebe sinal — quando termina, ela não registra nada (o estado fica como estava antes da execução) e libera a claim.
Sobre claims: uma claim de execução registra seu dono (pid, início do processo, máquina). Um dono que crashou é assumido no próximo poll, não depois de uma hora; só um dono que não pode ser verificado (uma claim escrita em outra máquina) conta como abandonado depois de uma hora. O curador compartilha esta implementação — o portão de intervalo e a claim de execução foram para agent/idle_schedule.py neste PR.
Chamadas de modelo a partir de fn passam pelo ctx.llm e pelo portão de confiança dele. Note o que fn não tem: sem turno, portanto sem side_question_token, portanto sem fork.
Gerenciando tarefas idle pela CLI
hermes plugins idle-tasks # todas as tarefas idle deste profile
hermes plugins idle-tasks <plugin> # as tarefas de um plugin
hermes plugins idle-tasks <plugin> --pause nightly-reindex
hermes plugins idle-tasks <plugin> --resume nightly-reindex
A listagem mostra status, contagem de execuções, última e próxima execução, e o último resumo ou erro. É o jeito mais rápido de responder “minha tarefa realmente rodou” — muito mais rápido do que ler logs.
review_signals: siga a cadência do próprio usuário
O post_llm_call agora também recebe review_signals: se a revisão de skill e a de memória estão no prazo, os contadores, os intervalos e se a revisão em background está ligada.
Isso importa porque o workaround antigo — “checar a cada N turnos” — contava os seus turnos enquanto o usuário configurava uma cadência diferente. Agora você pode ler as configurações do usuário e acompanhar o ritmo de autoaprendizado do próprio Hermes em vez de inventar um.
Quando não está disponível
plugins.isolation: host: octx.fork_sessionde um plugin de terceiros existe mas levantaPluginHostUnsupported(umRuntimeError), porque o handle acompanha uma thread do agente da sessão viva dentro do processo do Hermes.- Turnos de cron e de subagente: sem
side_question_token, logo sem fork. - Runtimes MoA e agent-as-provider: o outcome é
refused:moaourefused:agent_provider.
A degradação documentada é simples: trate None e exceções como “sem fork desta vez” para que o plugin funcione nos dois ambientes.
def _try_fork(ctx, token, prompt):
try:
return ctx.fork_session(token, prompt, tools=["wisdom_offer_share"], max_iterations=4)
except Exception: # PluginHostUnsupported, ou qualquer outra coisa
return None
Um exemplo 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)
E a capacidade vai no manifest do plugin:
capabilities:
- llm.session_fork
A tela de consentimento que os usuários veem diz mais ou menos: “Rodar uma cópia do seu agente em background depois de um turno. Ela vê a sessão inteira, incluindo a memória, pode usar as ferramentas do próprio plugin e gasta tokens do seu modelo principal.”
Essa frase é a melhor nota de design de todo o recurso: um fork vê a sessão inteira. Se o seu plugin encaminha a saída de um fork para terceiros, pense nisso antes.
Status: só na main, e experimental
O PR #146732 foi mergeado em 13 de novembro de 2026, vive na main e não está na v0.23.1. As duas APIs são explicitamente experimentais, então assinaturas podem mudar.
Atualização (17/11/2026): essas mudanças saíram na v0.23.2 (16 de novembro): um
hermes updateas traz. O « não está na v0.23.1 » acima é um retrato da data de publicação.
Na prática:
- O plugin precisa funcionar quando
fork_sessionretornaNoneou levanta exceção (“sem fork desta vez”). - Nunca guarde o handle em estado entre turnos; ele não sobrevive a um.
- Sempre
waitcom limite. - Rode
hermes plugins validateantes de publicar — veja o guia do catálogo de plugins, o modo de isolamento e a lista de APIs públicas de plugin.
Se tudo o que você precisa é “recalcular meus dados uma vez por dia”, register_idle_task é a escolha mais fácil: sem capacidade, sem token, e você ganha pause/resume e assunção de crash de graça. Um fork é para trabalho que precisa cair imediatamente depois deste turno e precisa ver o contexto deste turno. Escolha o errado e o código briga com você o caminho todo.