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_session copia 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_task dá 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_fork recebe None e não gasta o token.
  • Nomear uma ferramenta fora da allowlist retorna None sem gastar o token; qualquer outro None gasta.

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_iterations limita 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); o input_budget só 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:

  1. 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.
  2. 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.
  3. 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 fn nã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: o ctx.fork_session de um plugin de terceiros existe mas levanta PluginHostUnsupported (um RuntimeError), 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:moa ou refused: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 update as traz. O « não está na v0.23.1 » acima é um retrato da data de publicação.

Na prática:

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.