Leia uma sessão do Hermes sem abri-la: session.transcript

Você está montando um painelzinho lateral para o seu editor: as últimas dez conversas à esquerda, a escolhida à direita. Os dados vêm de um gateway do Hermes. Simples — até bater na parede: o gateway tem exatamente um jeito de ler uma conversa de volta, e ele se chama session.resume. O nome é honesto: resume quer dizer abrir. Chame o método e o gateway constrói um agent para aquela sessão, inscreve quem chamou nos eventos dela e transforma uma conversa armazenada em uma conversa em execução. Você queria três linhas de texto de prévia e ganhou um processo vivo para tomar conta.
O lote integrado em 6 de novembro fecha essa lacuna. O gateway agora tem um método somente-leitura de verdade, session.transcript, mais uma opção picker: true em session.list. Os dois são autorizados como leitura, não constroem agent nenhum, não inscrevem ninguém e não custam nada depois que a resposta é enviada. Este post cobre o que você já pode ler, como o cursor funciona e o único ramo que parece erro mas não é.
O velho beco: mostrar uma linha exigia abrir a coisa toda
Isso não era tanto um erro quanto uma herança. session.resume significa “continue esta conversa”, então ele precisa tornar a sessão viva: reivindicá-la, reconstruir o runtime, anexar quem chamou ao fluxo de eventos. Para uma lista somente-leitura, essa troca está errada nas duas direções — e é ativamente perigosa, porque abrir o seu painel poderia tomar a sessão em que o usuário está digitando naquele momento.
Então muitos clientes de terceiros fizeram o óbvio e leram o state.db direto. Isso funciona muito bem até o formato do store mudar, e aí o cliente quebra. O objetivo desta mudança é tirar os clientes do arquivo de banco e colocá-los diante de uma interface versionada.
Um método, três trabalhos: listar, paginar, filhos
| O que o cliente quer | Antes | Agora |
|---|---|---|
| Listar conversas com pasta, última atividade e última resposta | session.list devolvia id, título, primeiro prompt e contagens |
session.list com picker: true acrescenta preview, last_reply, cwd, git_branch, workspace, last_active_at, pinned |
| Mostrar só as conversas desta pasta | nenhum filtro | um parâmetro workspace, casado pela mesma regra do hermes -c |
| Paginar o transcript sem se anexar | só session.resume, que anexa |
session.transcript |
| Fazer poll por mensagens novas | impossível sem se anexar | devolver o next_cursor da página anterior |
| Saber onde o Hermes resumiu a conversa | as linhas de handoff eram descartadas do que os clientes viam | todo handoff é uma linha row_kind: "compaction" na posição em que aconteceu |
| Ler a conversa de um filho delegado | não era possível | o parâmetro subagent_id |
| Saber a que sessão pertence uma linha de filho | as linhas de subagent.list não diziam |
as linhas carregam child_session_id |
A regra do workspace merece uma frase própria: uma conversa pertence à pasta em que a primeira linha dela estava — a raiz do repo git registrada, se houver, senão o cwd. É por isso que uma sessão aberta em packages/webapp/ dentro de um monorepo é encontrada filtrando pela raiz do repo, não pelo pacote.
Como fica: uma requisição, um cursor
A requisição é deliberadamente sem graça. A ordem padrão é da mais antiga para a mais nova, cem linhas por página:
{"method": "session.transcript", "params": {"session_id": "ses_8f21", "limit": 50}}
{
"session_id": "ses_8f21",
"rows": [
{"row_kind": "message", "role": "user", "text": "the build fails on CI only"},
{"row_kind": "message", "role": "assistant", "text": "Which stage?"},
{"row_kind": "compaction", "role": "system", "text": "Summary of 34 earlier messages...", "compacted_messages": 34}
],
"next_cursor": "c2VzXzhmMjE6MToxMjM0",
"reset": false
}
rows são linhas de exibição, não linhas cruas do store: cada mensagem lógica aparece uma vez, até 64 resultados de ferramenta da chamada na borda da página vão junto, e os handoffs de compactação ficam onde aconteceram. A ordem que você recebe é a ordem que o usuário viu.
O cursor é opaco. Não tente interpretá-lo nem o leve de uma sessão para outra — ele está amarrado à sessão, ao filho e à ordem para a qual foi emitido.
O cursor também é o poll
Esta é a parte mais bonita do desenho e a mais fácil de usar errado.
Com order: "oldest" (o padrão), next_cursor nunca é null. Quando você lê até uma página voltar vazia, guarde o cursor e passe de novo: você recebe só as linhas escritas desde então. Algo que parecia paginação também é um feed incremental — sem websocket, sem callbacks, só um poll.
order: "latest" vai na outra direção: mais nova primeiro, paginando para trás, e next_cursor vira null no fim. É o formato que você quer para um leitor que abre já rolado até o fim.
reset: true não é erro. Substitua o que você tem na mão.
Se há um ramo para acertar, é este.
O cursor garante mais do que uma posição. Ele registra o estado das linhas que cobriu. Enquanto toda mudança no meio for um append — uma mensagem nova, um resultado de ferramenta novo — a próxima página continua depois do cursor e diz reset: false. Mas qualquer outra coisa não estende o caminho: uma compactação in-place, uma rotação para um segmento novo, um rewind, uma reescrita ou a remoção de uma linha coberta. Aí a resposta vem com reset: true e ela recomeça da primeira página. Existe exatamente uma reação correta: jogar fora a sua cópia em cache e usar esta página.
Para um leitor, isso é um recurso — você nunca acaba com a primeira metade de uma conversa em uma versão e a segunda metade em outra. Para quem escreve o cliente, é um ramo normal do protocolo, não um caminho de falha. Uma resposta que não traz cursor nenhum também é reset: true.
Lendo um filho delegado
Passe subagent_id e o método lê um filho daquela sessão em vez dela. A resposta ganha quatro campos: subagent_id, available, running, child_session_id.
Os portões são deliberados:
- A sessão precisa estar viva neste gateway, senão você recebe
not_found. - Um filho em execução precisa estar no roster vivo do pai, incluindo filhos aninhados.
- Um filho terminado é localizado pelo
_subagent_idcarimbado na linha dele no spawn, e só se a cadeia de pais dele chegar a esta conversa por saltos de delegate-child ou de continuação por compactação. Um ramo da conversa não te empresta os filhos dele. - Um filho estrangeiro ou desconhecido responde
available: false,rows: [],next_cursor: null,reset: true. Sem erro, sem vazamento.
As linhas de subagent.list agora carregam child_session_id, então “a que sessão este filho pertence” deixou de ser adivinhação.
Limites contra os quais você deve projetar
limitvai de 1 a 500, padrão 100, contando as linhas de compactação.- Uma página carrega no máximo 2 MiB de JSON, cortado entre grupos de ferramentas, para que uma chamada e o resultado dela nunca sejam divididos entre páginas.
- Uma única linha maior que isso guarda só o role, o kind, o horário, os ids e o começo do texto, e diz
truncated: true. - Imagens aparecem como
[image]a menos que você peçainline_images: true.
A autorização é a mesma checagem de leitura que o session.resume usa (profile, dono ou operador), e a leitura roda na lane concorrente de leitura do gateway — um prompt que você mandar não vai ficar na fila atrás das buscas de página de outra pessoa.
Dá para usar hoje
Não a partir de uma release estável. Esses commits chegaram ao main em 6 e 7 de novembro (PR #150102, que incorporou as leituras de subagent do #140477) e não estão na tag v0.23.0, cortada em 5 de novembro. Verifique a capacidade, não a versão: um gateway que serve isso anuncia session-transcript-v1 em runtime.describe.capabilities, e session-list-picker-v1 para as opções de lista. Se não anunciar, use o caminho antigo.
Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um
hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.
Se hoje você só precisa tirar uma cópia de uma conversa da máquina, exportar uma sessão é o caminho. E se as linhas compaction te intrigam, o motivo de uma conversa ser vários segmentos — e de o transcript ter que mostrá-los no lugar — está em fronteiras de sessão. A semântica do lado anexado que este método substitui está no texto sobre o resume no Chat C.
A versão curta
session.transcript separa duas coisas que ficaram soldadas por muito tempo: ler uma conversa e abri-la. Um cliente agora pode olhar sem entrar, paginar e fazer poll com o mesmo cursor, e ser avisado com clareza quando a conversa por baixo mudou de forma. Se o seu cliente ainda abre o state.db sozinho, este é o motivo para parar.