Durable agents (experimental)

Experimental. El protocolo, el SDK y esta página pueden cambiar, o la funcionalidad puede eliminarse, en una versión menor posterior. Actualmente solo los propios ejemplos de Collie implementan el protocolo. La salida indica el criterio que decide si se mantiene. Si no se conecta ningún agente persistente, Collie se visualiza y funciona como antes.

Si se compiló un agente persistente con Pi Durable o cualquier programa que implemente el protocolo, Collie puede mostrarlo en el teléfono. Obtiene solicitudes de aprobación, historial y una vista de chat sin código de interfaz de usuario.

Un agente durable es un origen posible de un session, y cada una de sus conversaciones constituye una sesión. Los términos se encuentran en Terminología. Collie no almacena ninguna clave de modelo: un agente durable utiliza su propia clave de API o un inicio de sesión de ChatGPT, y no es posible usar una suscripción de Anthropic a través de un harness de terceros.

Guía rápida

Un agente durable de diez líneas, un collie durable attach y una tarjeta de pregunta en el teléfono.

Se necesita Collie 1.22.0 o posterior en ejecución en esta máquina, con el teléfono emparejado (Instalación).

Un agente durable se ejecuta en Linux o macOS, con Node 22.19 o posterior, o Bun 1.4 o posterior. Instale el SDK en la carpeta del agente durable:

npm install @colliepwa/durable-sdk@experimental
# or
bun add @colliepwa/durable-sdk@experimental

El paquete se publica bajo la etiqueta de distribución de npm experimental, nunca latest, y sigue la salida descrita en ADR 0104: si el protocolo de conexión durable desaparece, el paquete queda obsoleto (ADR 0105).

La entrada Pi Durable del SDK se ha probado con Pi Durable 1.1.0 y 1.2.0. Node 22.19 es el requisito mínimo para Pi Durable 1.2.0.

Guarde este agente durable como hello.mjs. Ocupa diez líneas:

import { openCollie } from "@colliepwa/durable-sdk";

const socket = process.env.COLLIE_DURABLE_SOCKET ?? `${process.env.XDG_RUNTIME_DIR}/hello/app.sock`;
const collie = await openCollie({ socket, hostName: "hello", caps: { asks: true } });
const pane = collie.workspace("hello", { title: "Hello" }).tab("main", { title: "Questions" }).pane("deploy", { title: "Deploy", harness: "hello" });
collie.ready();
console.log(`listening ${collie.address}`);
const options = [{ id: "yes", label: "Yes" }, { id: "no", label: "No" }];
const answer = await pane.ask({ kind: "choice", toolCallId: "deploy-1", itemId: "deploy-1", title: "Deploy to staging?", options });
console.log(`answer: ${answer.optionIds[0]}`);
await collie.close();

Ejecútelo con node hello.mjs o bun hello.mjs. Imprime listening /run/user/1000/hello/app.sock y espera. El mismo agente durable es examples/durable-member/hello.ts en un clon de Collie.

En Node primero escribe una línea adicional: Node no puede determinar quién se conecta al socket del agente durable, por lo que cualquier proceso del usuario puede responder a su pregunta. Bun en Linux sí puede, y rechaza respuestas procedentes del propio agente durable o de un proceso iniciado por este.

En macOS, ejecútelo con Node. Allí Bun requiere callerCheck: "off", que este agente durable no define. macOS no dispone de XDG_RUNTIME_DIR, por lo que se debe asignar previamente una ruta absoluta a COLLIE_DURABLE_SOCKET.

En una segunda terminal, conéctelo a Collie y reinicie para que Collie lea la nueva entrada:

collie durable attach hello --socket /run/user/1000/hello/app.sock
collie restart

Utilice la ruta que imprimió el agente durable. Añada --restart al primer comando para reiniciar en el mismo paso. --restart reinicia el puente de Collie: el teléfono se vuelve a conectar en unos segundos y las sesiones de terminal continúan en ejecución.

Abra Collie en el teléfono. La sección Agentes durables muestra una fila, hello, con la etiqueta Experimental y una pregunta en espera. Toque la fila: se abre la lista de conversaciones del agente durable, donde la conversación Deploy espera con "Deploy to staging?". Ábrala y pulse Yes o No. El agente durable imprime la respuesta y finaliza.

Para programar un agente durable propio, consulte El SDK durable y El protocolo durable.

Conectar un agente durable

Cada agente durable constituye una entrada en sources.json, y collie durable attach la genera.

collie durable attach desk --socket /run/user/1000/desk/app.sock
export EDGE_TOKEN=your-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

En Windows solo está disponible la modalidad HTTPS: attach --socket finaliza con el código de salida 2 e indica utilizar --url y --token-env, ya que un socket privado requiere identificadores de usuario de Unix.

sources.json reside en la carpeta de configuración junto a su .env: la carpeta de configuración del plugin de Herdr (~/.config/herdr/plugins/config/herdr.collie/) en instalaciones administradas por Herdr, o bien ~/.config/collie/. attach muestra la ruta generada. Los dos comandos anteriores escriben este archivo:

[
  { "name": "desk", "kind": "durable", "socket": "/run/user/1000/desk/app.sock" },
  {
    "name": "edge",
    "kind": "durable",
    "url": "https://edge.example.com",
    "token": "your-32-byte-random-token-here"
  }
]

El puente lee el archivo al inicio, por lo que una entrada surte efecto tras reiniciar. Las terminales se ven y funcionan como antes, junto a los agentes duraderos.

Collie es estricto con el archivo, ya que un agente duradero omitido en silencio nunca aparecería:

• —
  Un campo no especificado en la tabla detiene el puente. También lo hace un kind incorrecto, un nombre que incumple la regla, un nombre usado dos veces, tanto socket como url, ninguno de los dos, o un url sin token.
• —
  Un archivo erróneo detiene el puente al inicio con una sola línea. La línea comienza con [bridge] FATAL: e indica la entrada y el campo. collie logs lo muestra. attach y detach también rehúsan sobrescribir un archivo que no pueden leer, por lo que una errata nunca afecta a las demás entradas.
• —
  El archivo se mantiene en modo 0600. attach lo escribe de esa forma. Cuando el archivo tiene permisos más amplios, el puente los restringe al inicio y lo registra en su log.
• —
  Un nombre no puede coincidir con el de su sesión de terminal. Ese es default en la mayoría de las instalaciones, y en una instancia exclusiva para agentes duraderos default es el nombre de su propio agente duradero. El puente se detiene al inicio e indica la entrada.
• —
  Un agente duradero conserva su nombre frente a una sesión de Herdr. Cuando una sesión de Herdr tiene el nombre de un agente duradero, el teléfono muestra el agente duradero, oculta dicha sesión de Herdr y el log lo registra una vez.

attach comprueba la ruta del socket, la URL y el token según las reglas que figuran abajo. Una entrada escrita a mano se comprueba cuando el puente contacta con el agente duradero: si se incumple una regla, el agente duradero se muestra como inaccesible junto con el motivo.

Dos formas de acceder a un agente duradero

El transporte mediante socket es para Linux y macOS. En Windows use la URL y el token. La ruta del socket debe ser absoluta y tener como máximo 103 bytes. Manténgala bajo $XDG_RUNTIME_DIR, no bajo /tmp: el servicio Collie en Linux se ejecuta con un /tmp privado.

Collie se conecta a un socket solo cuando la ruta completa es privada, ya que el socket no transmite ningún token. El socket le pertenece y no tiene permisos de grupo u otros. Su carpeta le pertenece con el modo 0700. Ninguna parte de la ruta es un enlace simbólico, y ninguna carpeta superior permite la escritura a grupo u otros, salvo un directorio sticky como /tmp. El SDK crea la carpeta del socket con el modo 0700 cuando no existe.

La URL debe comenzar con https://. La única excepción es http://127.0.0.1:<port> o http://localhost:<port>, con un puerto, para un agente duradero en la misma máquina. Collie rechaza cualquier otra dirección http://, ya que el token viajaría por la red sin cifrar.

Precaución. A través de https, el token es la única barrera de acceso. Cualquiera que lo posea puede leer cada conversación y responder cada pregunta, y el host ve el texto. Un agente duradero al que se acceda de esta manera solo debe ofrecer Allow y Deny, nunca permitir siempre.

Seguridad de los agentes duraderos indica qué puede hacer un agente duradero y qué registra Collie.

Cada sondeo a través de https es una petición que su host puede facturar, y una respuesta de tipo "nada ha cambiado" también cuenta. Sin ningún teléfono abierto, el sondeo en inactividad se ejecuta cada 10 s, por lo que Collie consulta 8640 veces al día. Compruebe lo que permite el plan de su host al respecto.

Un agente duradero tras una URL debe implementar el protocolo Collie wire y verificar el token bearer. La demo estándar de Pi Durable no hace ninguna de las dos cosas, por lo que Collie no puede vincularla tal como está.

Collie sondea un agente duradero alojado. Consulta cada 2 s mientras un teléfono observa; de lo contrario, cada 10 s. Cada sondeo reactiva un Durable Object en hibernación, por lo que un objeto alojado permanece activo mientras Collie observa. La conexión wire no utiliza WebSocket, por lo que las funciones de hibernación y WebSocket de los Durable Objects no resultan útiles aquí.

El ejemplo de Cloudflare está archivado y no forma parte de una versión publicada. Se encuentra en experiments/durable-member-cloudflare/.

Los tres verbos

attach, detach y list modifican o leen sources.json, y no reinician nada a menos que se solicite.

collie durable attach <name> --socket <path> [--restart]
collie durable attach <name> --url <url> --token-env <VAR> [--restart]
collie durable detach <name> [--restart]
collie durable list

collie durable sin verbo, o con uno desconocido, muestra el modo de uso y sale con 2. Con --restart, attach y detach ejecutan el mismo reinicio que collie restart.

list consulta al bridge en ejecución sobre cada entrada y espera como máximo 3 s por ella:

Cuando un durable agent no aparece, ejecute collie doctor, que indica la comprobación que falla. Las tres causas habituales son una entrada aún no cargada (reiniciar), un socket que no es privado (socket-not-private) y un archivo de socket obsoleto dejado por un bloqueo (connection refused: elimínelo e inicie el durable agent). Resolución de problemas de durable agents cubre los casos de durable agent. Resolución de problemas cubre Collie en su conjunto.

Tokens

Una entrada url incluye su token, y el token constituye la puerta de acceso completa.

openssl rand -hex 32

El resultado son 64 caracteres hexadecimales, por encima del límite mínimo de 32 bytes.

Genere un token de 32 bytes aleatorios o más, como se indica arriba, y asigne el mismo valor al durable agent. attach lo lee de la variable nombrada por --token-env, de modo que no figura en ninguna línea de comandos ni en el historial de la shell. Dicha variable debe estar definida al ejecutar attach.

attach copia el valor en sources.json en texto plano. Por lo tanto, el archivo es tan secreto como el token: Collie lo mantiene con modo 0600, y una copia de seguridad o una sincronización de la carpeta de configuración incluirá el token. Collie envía el token con cada petición y nunca lo muestra: list indica (token set).

El token no expira. Para cambiarlo, vuelva a ejecutar attach con el mismo nombre y el nuevo token, y luego reinicie:

export EDGE_TOKEN=your-new-32-byte-random-token-here
collie durable attach edge --url https://edge.example.com --token-env EDGE_TOKEN
collie restart

attach muestra updated edge. Asigne el nuevo token al durable agent antes de reiniciar Collie, o el teléfono indicará que el durable agent rechazó el token. Un durable agent puede aceptar un segundo token durante una rotación, para que ninguna de las partes quede bloqueada. El ejemplo aparcado de Cloudflare admite COLLIE_TOKEN y, mientras esté definido, COLLIE_TOKEN_NEXT (ADR 0103). Defina el nuevo token como COLLIE_TOKEN_NEXT en el durable agent, vuelva a ejecutar attach y reinicie Collie; luego mueva el valor a COLLIE_TOKEN y elimine la definición de COLLIE_TOKEN_NEXT.

Un durable agent aislado en un Collie

Una instancia sin terminal, como un host Windows o un durable agent alojado, puede controlar un durable agent desde su .env.

# a durable agent on this machine, as you
COLLIE_MUX=durable
COLLIE_DURABLE_SOCKET=/run/user/1000/durable/session.sock

# or a durable agent you deployed behind TLS
COLLIE_MUX=durable
COLLIE_DURABLE_URL=https://durable-member.example.com
COLLIE_DURABLE_TOKEN=your-32-byte-random-token-here

Dicha instancia nombra a su durable agent default, y ese durable agent es su sesión primaria. Las entradas en sources.json aún se ejecutan junto a ella, bajo otros nombres.

Configure el socket, o la URL con su token, nunca ambos. Configurar ambos, una URL sin token o un token sin URL constituye un error de configuración: Collie inicia, detalla el error en su registro y muestra el durable agent como inaccesible por ese motivo.

Una compilación anterior guardaba los registros de una instancia durable-only directamente en <state>/durable/. En el primer inicio de esta compilación se mueven una sola vez a durable/default/, con una línea en el registro.

Para cambiar el token, despliegue el nuevo en el durable agent, establézcalo en el .env y ejecute collie restart. Una instancia durable-only se une a un crew bajo su nombre de host; por lo tanto, asígnele un nombre con collie crew join <lead-address> --label durable si comparte host con el lead.

Para desactivar temporalmente cada durable agent de sources.json, defina COLLIE_PROGRAMS=off en .env y ejecute collie restart. El bridge ignorará el archivo, registrará una línea y se ejecutará como una instalación sin agentes durables, por lo que el teléfono no mostrará la sección Durable agents. collie doctor y collie durable list indican que los agentes durables están desactivados. El archivo permanece intacto: elimine la variable y reinicie para restablecer los agentes durables. La variable no afecta al formato de entorno anterior mencionado arriba.

Dónde almacena Collie los datos de un durable agent

El durable agent conserva el historial de sus conversaciones. Collie mantiene una caché, sus comprobantes y su memoria de push en su carpeta de estado.

La carpeta de estado es ~/.local/state/collie/, o COLLIE_STATE_DIR si está definida. <program> es el nombre en sources.json, o default. La carpeta de cada durable agent tiene modo 0700, y cada registro tiene modo 0600.

La caché permite que Chat abra con rapidez y funcione mientras el durable agent responde lento. Una conversación cerrada se lee siempre desde el durable agent, nunca desde la caché.

Un durable agent conserva solo la parte más reciente de una conversación extensa. Si ha descartado el inicio de una conversación antes de que Collie pudiera leerlo, Chat muestra una línea en su lugar: "Older messages were left out: the durable agent no longer keeps them." No se perdió nada en su teléfono: Collie nunca tuvo esos mensajes.

Qué muestra el teléfono

Una sección Durable agents en el panel y, para cada durable agent, una lista de sus conversaciones.

Cada durable agent ocupa una fila en la sección Durable agents, con su nombre, una insignia Experimental, su entorno de ejecución y si se ejecuta aquí o en otro lugar. A la derecha contabiliza sus conversaciones abiertas y, en el color needs-you, aquellas en espera de su intervención. La sección se desplaza sobre sus espacios mientras una pregunta espera respuesta. Un durable agent que esté iniciando o inaccesible lo indica en lugar de los contadores. Un token rechazado y una versión de protocolo rechazada tienen sus propios mensajes en el teléfono; collie doctor describe cualquier otro motivo.

Pulse una fila para abrir la lista de conversaciones del durable agent, como la lista de chats de una aplicación de mensajería. Aquello que requiere su atención aparece primero, luego las demás conversaciones abiertas, y después las cerradas bajo la etiqueta Closed. Las abiertas se visualizan en Chat, y las cerradas en modo de solo lectura. Un durable agent detalla en su saludo inicial sus capacidades (asks, starters, send, steer, abort, rename, close, actions, history, reopen), y el teléfono dibuja un control únicamente para lo indicado. Un durable agent carece de pantalla, por lo que no tiene vista de Terminal ni teclas pulsadas.

Al enviar a un durable agent, la etiqueta queued es la propia interpretación del turno por parte de Collie. Collie no muestra lo que espera en la bandeja de entrada de Pi. Una tarea que duerme hasta un plazo se muestra como inactiva o trabajando, nunca como en espera. Sesiones contiene más información.

Una tarjeta de pregunta nombra al agente duradero y muestra el tiempo restante cuando el agente duradero estableció uno. Una pregunta resuelta en el agente duradero, o agotada por tiempo, deja una línea en el chat. Durable agents en el teléfono muestra cada uno de estos casos con una figura.

Send y Ask a través del bridge

Un agente duradero no tiene pantalla, por lo que Collie no lee ninguna pantalla para él. El bridge lee su propio estado en su lugar. Un agente duradero recibe los mismos Send y Ask que un panel de terminal.

• —
  El estado. El turno proviene del estado de su panel. Una pregunta proviene de su ask abierto más antiguo. El cuadro de entrada siempre está vacío, porque un agente duradero no tiene cuadro. El teléfono recibe este estado con cada panel, con la misma estructura que para un panel de terminal.
• —
  Un send. POST /api/send toma un id de solicitud del teléfono. El bridge escribe la solicitud en el disco y bloquea la conversación. Luego envía el texto al agente duradero una vez, para el turno que leyó. Su respuesta es la prueba, y el recibo indica el id de solicitud que tomó. Durante un turno, el agente duradero conserva el texto para después de ese turno, y el recibo dice queued.
• —
  Los resultados. Un send finaliza con sent, refused con un motivo, o unknown. unknown significa que el agente duradero no indicó que tomó el texto. Lea el chat antes de enviarlo de nuevo. Un send se convierte en effective cuando el agente duradero lo escribe en la conversación. Su elemento user nombra el id de solicitud de ese send. Un send simple se rechaza mientras haya alguna pregunta abierta, incluso una que Collie no pueda leer. Responda a la pregunta, o use Steer o Stop. Un turno iniciado después de haber mirado rechaza el send, y nada llega al agente duradero.
• —
  Una pregunta. POST /api/ask/<id> la responde. El ask id es de un solo uso. La respuesta incluye el hash de la pregunta visualizada. El bridge lo compara con la pregunta listada actualmente por el agente duradero. Si difieren, nada llega al agente duradero. La réplica muestra la pregunta tal como está ahora. La respuesta va al agente duradero mediante su propio ask id. No se envía ninguna clave. El recibo indica channel: program y conserva el hash.
• —
  Qué permanece en la tarjeta. Algunas preguntas no se resuelven con un solo toque, por lo que el estado las muestra como una pregunta que Collie no puede leer (modal: unreadable). Se responden en su propia tarjeta. - Una pregunta de texto permanece en la propia tarjeta del agente duradero, porque la respuesta es una línea escrita. - Una selección múltiple permanece en la propia tarjeta del agente duradero, porque la respuesta requiere más de una elección. - Un formulario permanece en la propia tarjeta del agente duradero, porque la respuesta es un conjunto de campos. - Always allow nunca es una opción de contrato. Su concesión permanece después de esta pregunta. Por ello, la tarjeta del agente duradero solicita primero un segundo toque, y un toque a través de /api/ask no debe omitir dicho toque.
• —
  Los contadores. collie doctor cuenta estas lecturas y resultados en una sola fila, program.

En esta máquina, el teléfono utiliza estas rutas. Un send simple va a través de /api/send, y un toque en la tarjeta de pregunta va a través de /api/ask. El compositor indica el resultado bajo el pulgar en los términos del agente duradero. Cuando una pregunta bloquea el send, un botón dirige a su tarjeta. La lista de Recent sends del panel muestra cada recibo, y un send en cola lo indica. Steer y Stop permanecen en las rutas propias de la conversación, ya que un steer no forma parte del Send Protocol. Un agente duradero en un crew member conserva las rutas propias de la conversación para todas las escrituras. Cada ruta comprueba el turno antes de que el texto llegue al agente duradero. Todas las escrituras hacia una conversación comparten un mismo bloqueo. Mientras se ejecuta un send, Steer y la respuesta de una tarjeta se rechazan por ocupado. Stop espera el bloqueo, como máximo hasta su límite de tiempo, de modo que un send bloqueado nunca impida el paso de Stop.

Versiones

Collie y un agente duradero acuerdan una versión de protocolo en el hello, y actualmente existe una: versión 1.

Collie utiliza 1..1. Cuando se publique una versión 2, Collie aceptará la versión 1 durante una versión menor posterior, y la siguiente versión menor la descartará. Actualmente no hay ninguna versión anterior para aceptar.

Cuando los dos rangos no coinciden, Collie no lee nada más del agente duradero. Su registro recibe una línea por cada rango rechazado, como [durable] The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK. El inicio del agente duradero en el teléfono muestra la misma frase en un cuadro de advertencia, y su fila en el dashboard muestra Version mismatch en lugar de Unreachable. collie doctor muestra ambos rangos en su fila durable-hello: incompatible: the durable agent speaks 2..3, this Collie speaks 1..1. Una vez por cada inicio del agente duradero, Collie también le envía un hello con su propia versión, para que el agente duradero pueda registrar la discrepancia en su lado. Actualice el extremo más antiguo.

La salida

La funcionalidad solo se mantiene si alguien fuera de este repositorio la utiliza.

Para la versión 1.24.0, debe cumplirse una de dos condiciones: existe un repositorio público compatible con el protocolo, o existe una incidencia o debate externo sobre un agente duradero. Si no se cumple ninguna, el código durable se retira del release hacia experiments/, y esta página desaparece (ADR 0104). Al eliminarse, una entrada sources.json se ignora con una línea de registro durante una versión, el socket continúa funcionando para su agente duradero, y el paquete npm se marca como obsoleto, no se elimina (ADR 0105).