Leer una sesión de Hermes sin abrirla: session.transcript


Estás montando un panel lateral pequeño para tu editor: a la izquierda, las diez últimas conversaciones; a la derecha, la que elija el usuario. Los datos vienen de un gateway de Hermes. Todo sencillo hasta que chocas con el muro: el gateway tiene exactamente una forma de releer una conversación, y se llama session.resume. El nombre no engaña: resume significa abrir. Lo llamas y el gateway construye un agent para esa sesión, suscribe a quien llama a sus eventos y convierte una conversación guardada en una conversación en marcha. Tú querías tres líneas de texto de vista previa y acabaste con un proceso vivo al que cuidar.

El lote que se fusionó el 6 de noviembre cierra ese hueco. El gateway ya tiene un método de solo lectura de verdad, session.transcript, más una opción picker: true en session.list. Ambos se autorizan como lecturas, no construyen ningún agent, no suscriben a nadie y no cuestan nada una vez enviada la respuesta. Este artículo repasa qué puedes leer ahora, cómo funciona el cursor y la única rama que parece un error sin serlo.

El rincón antiguo: mostrar una línea obligaba a abrir todo el hilo

Más que un error, era una herencia. session.resume significa «continúa esta conversación», así que tiene que poner la sesión en marcha: reclamarla, reconstruir el runtime y enganchar a quien llama al flujo de eventos. Para una lista de solo lectura ese intercambio está mal en ambos sentidos, y además es peligroso, porque abrir tu panel lateral podría apoderarse de la sesión en la que el usuario está escribiendo en ese mismo momento.

Por eso muchos clientes de terceros hicieron lo obvio y leyeron state.db directamente. Funciona justo hasta que cambia la forma del almacén, y entonces el cliente se rompe. El objetivo de este cambio es sacar a los clientes del archivo de base de datos y ponerlos delante de una interfaz versionada.

Un método, tres trabajos: listar, paginar, hijos

Lo que quiere el cliente Antes Ahora
Listar conversaciones con carpeta, última actividad y última respuesta session.list devolvía id, título, primer prompt y recuentos session.list con picker: true añade preview, last_reply, cwd, git_branch, workspace, last_active_at, pinned
Mostrar solo las conversaciones de esta carpeta sin filtro un parámetro workspace, con la misma regla que aplica hermes -c
Paginar el transcript sin adjuntarse solo session.resume, que se adjunta session.transcript
Sondear mensajes nuevos imposible sin adjuntarse devolver el next_cursor de la página anterior
Saber dónde resumió Hermes la conversación las filas de handoff se descartaban antes de llegar al cliente cada handoff es una fila row_kind: "compaction" en su posición
Leer la conversación de un hijo delegado no era posible el parámetro subagent_id
Saber a qué sesión pertenece la fila de un hijo las filas de subagent.list no lo decían las filas llevan child_session_id

La regla de workspace merece una frase propia: una conversación pertenece a la carpeta en la que estaba su primera fila, es decir, la raíz del repo git registrada si existe y, si no, su cwd. Por eso una sesión abierta en packages/webapp/ dentro de un monorepo se localiza filtrando por la raíz del repo, no por el paquete.

Cómo se ve: una petición, un cursor

La petición es deliberadamente aburrida. El orden por defecto va de lo más antiguo a lo más reciente, cien filas 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
}

Las rows son filas de presentación, no filas crudas del almacén: cada mensaje lógico aparece una vez, hasta 64 resultados de herramientas de la llamada del borde de la página viajan con él, y los handoffs de compactación se colocan donde ocurrieron. El orden que recibes es el orden en que lo vio el usuario.

El cursor es opaco. No lo interpretes ni lo lleves de una sesión a otra: está atado a la sesión, al hijo y al orden con el que se emitió.

El cursor también es el sondeo

Esta es la parte más elegante del diseño y la más fácil de usar mal.

Con order: "oldest" (el valor por defecto) next_cursor nunca es null. Cuando lees hasta que una página vuelve vacía, guarda el cursor y pásalo otra vez: recibes solo las filas escritas desde entonces. Algo que parecía paginación es también un feed incremental: sin websocket, sin callbacks, solo un sondeo.

order: "latest" va en la dirección contraria: primero lo más reciente, paginando hacia atrás, y next_cursor pasa a null al final. Esa es la forma que quieres para un lector que se abre desplazado hasta abajo.

reset: true no es un error. Sustituye lo que tengas.

Si hay una rama que hay que acertar, es esta.

El cursor responde por más que una posición: registra el estado de las filas que cubrió. Mientras cada cambio intermedio sea un append — un mensaje nuevo, un resultado de herramienta nuevo —, la página siguiente continúa después del cursor y dice reset: false. Pero cualquier otra cosa no alarga el recorrido: una compactación en sitio, una rotación a un segmento nuevo, un rewind, una reescritura o el borrado de una fila ya cubierta. Entonces la respuesta es reset: true y vuelve a empezar por la primera página. Solo hay una reacción correcta: tirar tu copia en caché y quedarte con esta página.

Para un lector eso es una ventaja, porque nunca acabas con la primera mitad de una conversación de una versión y la segunda de otra. Para quien escribe el cliente es una rama normal del protocolo, no un camino de fallo. Una respuesta que no trae ningún cursor también es reset: true.

Leer un hijo delegado

Pasa subagent_id y el método lee en su lugar un hijo de esa sesión. La respuesta gana cuatro campos: subagent_id, available, running, child_session_id.

Las compuertas son intencionadas:

  • La sesión tiene que estar viva en este gateway, o recibes not_found.
  • Un hijo en ejecución debe estar en el roster vivo del padre, incluidos los hijos anidados.
  • Un hijo terminado se localiza por el _subagent_id que se le estampó en la fila al crearse, y solo si su cadena de padres llega a esta conversación mediante saltos delegate-child o de continuación por compresión. Una rama de la conversación no te presta sus hijos.
  • Un hijo ajeno o desconocido responde available: false, rows: [], next_cursor: null, reset: true. Sin error y sin filtración.

Las filas de subagent.list llevan ahora child_session_id, así que «a qué sesión pertenece este hijo» deja de ser adivinación.

Límites con los que conviene diseñar

  • limit va de 1 a 500, por defecto 100, contando las filas de compactación.
  • Una página lleva como máximo 2 MiB de JSON, cortado entre grupos de herramientas, de modo que una llamada y su resultado nunca se parten entre páginas.
  • Una fila que por sí sola pase de eso conserva solo su rol, tipo, hora, ids y el inicio del texto, y avisa con truncated: true.
  • Las imágenes se muestran como [image] salvo que pidas inline_images: true.

La autorización es la misma comprobación de lectura que usa session.resume (perfil, propietario u operador), y la lectura corre en el carril concurrente de lecturas del gateway, así que un prompt que envíes no se quedará detrás de las peticiones de página de otra persona.

¿Puedes usarlo hoy?

Desde una release estable, no. Estos commits entraron en main el 6 y el 7 de noviembre (el PR #150102, que absorbió las lecturas de subagentes del #140477) y no están en la etiqueta v0.23.0, cortada el 5 de noviembre. Comprueba la capacidad en lugar de la versión: un gateway que sirve esto anuncia session-transcript-v1 en runtime.describe.capabilities, y session-list-picker-v1 para las opciones de lista. Si no lo anuncia, tira de la alternativa.

Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.

Si hoy solo necesitas sacar una copia de una conversación de la máquina, exportar una sesión es el camino. Y si las filas compaction te descolocan, el motivo por el que una sola conversación son varios segmentos —y por el que el transcript tiene que mostrarlos en su sitio— está en los límites de sesión. La semántica del lado adjunto que este método sustituye se explica en el artículo sobre reanudar en Chat C.

La versión corta

session.transcript separa dos cosas que estuvieron soldadas mucho tiempo: leer una conversación y abrirla. Un cliente ya puede mirar sin entrar, paginar y sondear con el mismo cursor, y recibir un aviso claro cuando la conversación de debajo cambia de forma. Si tu cliente todavía abre state.db por su cuenta, este es el motivo para dejarlo.