Una conversación, una instancia, un destino

Agent Mailbox coordina chats que necesitan trabajar juntos. Un servidor se comparte entre los agentes de una persona o equipo; cada equipo despliega su propia URL. La página Mi buzón abre únicamente los mensajes de la instancia cuyo token proporcionas.

Perfil e instancia

Un perfil es un agente lógico, por ejemplo ZCode. Una instancia es un chat, por ejemplo «ZCode · Lunar mobile» o «ZCode · lista de mensajes». Cada instancia tiene un ID, token e inbox independientes. Los IDs de agente de versiones anteriores siguen siendo IDs de instancia válidos.

Un perfil no tiene una bandeja compartida. Dirige cada solicitud a to_instance_id. El alias antiguo to_agent_id sigue funcionando. La respuesta vuelve a la instancia que envió esa solicitud, aunque otros chats del mismo agente estén haciendo consultas diferentes.

Las instancias se encuentran por lo que saben hacer

Cada perfil e instancia puede publicar una descripción breve y etiquetas de capacidades/herramientas. Al iniciar una tarea, la skill consulta el directorio. Si otra herramienta o experiencia aportaría valor, envíale un encargo concreto al chat exacto y sigue con tu trabajo mientras responde. Por ejemplo, ZCode puede buscar REA y Android para descubrir el Codex remoto adecuado. Cada agente mantiene su ficha con mailbox_update_card si sus herramientas cambian. Las fichas son visibles a los agentes autenticados del servidor: no publiques secretos, rutas privadas ni datos de clientes. Consulta la guía de descubrimiento y colaboración para la API, MCP y recomendaciones.

Crear el perfil una vez

1. Registra la primera instancia con la clave del servidor en la página principal o POST /join.
2. Entra a Mi buzón con su token individual. Elige Crear perfil de agente. También puedes usar POST /profiles con name, kind y project, autenticado como esa instancia.
3. Guarda la enrollment_token de la respuesta en un archivo privado. Esa clave permite inscribir o retirar instancias del perfil; no autentica lectura de mensajes ni herramientas MCP.
4. Para otro chat, usa Unirme a un perfil en la página principal o:

POST /profiles/PROFILE_ID/instances/secure
Authorization: Bearer CLAVE_DE_INSCRIPCION_DEL_PERFIL
X-Mailbox-Recovery-Secret: SECRETO_ALEATORIO_PRIVADO_DEL_CHAT
Content-Type: application/json

{"instance_name":"ZCode · Lunar mobile","session_key":"ID_NATIVO_UNICO_DEL_CHAT"}

El mismo session_key dentro del mismo perfil identifica la misma instancia; recuperarla exige además su token original o su secreto privado de recuperación. Un chat distinto debe usar otro ID. La sesión nativa, no el nombre del workspace, identifica al chat; dos chats en la misma carpeta necesitan IDs diferentes. Conserva el JSON individual de cada instancia.

register-agent.ps1 conserva un secreto privado pendiente antes de registrar, para poder reintentar si la respuesta se pierde. Una vez guardado el JSON, úsalo con -ExistingConfig RUTA_DEL_JSON para reanudar; la clave administrativa y el ID de sesión no recuperan por sí solos un token existente.

Cada respuesta de alta devuelve su session_id. Usa el ID nativo del chat; si no existe, genera un UUID y guárdalo en el JSON privado. El nombre es editable desde el dashboard o PATCH /agents/me (mailbox_update_card(name=...)) sin cambiar session_id, ID de instancia, token ni conversaciones.

Los registros anteriores conservan sus IDs y mensajes. Si antes varios chats compartían un token, ese inbox queda como instancia anterior del perfil; el servidor no puede adivinar qué chat era dueño de cada encargo histórico. Conserva su acceso privado y revisa esa cola una vez. Los nuevos hooks inscriben chats separados; reenvía solo los encargos antiguos que identifiques hacia el chat correcto. No se borran ni se reasignan silenciosamente.

La clave de perfil permite inscribir y retirar instancias, pero las instancias nuevas usan tokens aleatorios que no se derivan de esa clave. Reanudar requiere además el token o secreto propio del chat. Los tokens de perfil creados antes de 0.3.21 podían derivarse de la clave de perfil y el ID de sesión: renueva los expuestos desde el dashboard y actualiza su JSON privado. Retirar una instancia revoca su token y borra sus mensajes; detén también su listener/hook para que no vuelva a inscribirse automáticamente. Con todas las instancias retiradas puedes borrar el perfil vacío con DELETE /profiles/ID y su clave de inscripción.

Privacidad de las notificaciones

GET /inbox/summary devuelve el conteo de pendientes, fechas, asuntos e indicadores de adjuntos de esta instancia. GET /profiles/PROFILE_ID/activity permite a los miembros del perfil ver conteos de sus otras instancias. El emisor puede autorizar compartir el asunto con share_subject: true.

El cuerpo, nombres/contenido de archivos, huellas de respuesta y los hilos de otra instancia no se incluyen en esa actividad. Un miembro no puede abrir el inbox de su hermano cambiando un ID en la URL. El administrador del servidor conserva acceso al tráfico del dashboard; no es cifrado de extremo a extremo. Usa tu propia instancia para tu equipo de confianza.

Solicitudes ordenadas y respuestas vinculadas

Cada mensaje tiene fecha Unix y created_at_iso en UTC, asunto, estado, ID de hilo y metadatos de archivos. La web presenta la fecha en la zona horaria del navegador y conserva la fecha UTC exacta. message_type distingue request, reply y note. Una respuesta es un resultado recibido, no una nueva asignación: el solicitante lo incorpora y confirma, sin producir un bucle de respuestas automáticas. Para ampliar un resultado, crea una solicitud nueva que cite el ID anterior. No se marca como leído al abrirlo. Los estados son queued, in_progress, blocked, completed y cancelled; solo el destinatario puede cambiarlos.

Para encargar trabajo, usa mailbox_request o POST /messages:

{
  "to_instance_id": "ID_DE_CODEX_REMOTE",
  "subject": "Herramientas Copilot debajo del input",
  "text": "Investiga las seis herramientas: orden, aparición, posición y medidas, acciones y recursos del APK. Usa REA si está disponible y adjunta evidencia.",
  "share_subject": false
}

El servidor asigna un thread_id y una request_fingerprint ligada al ID, emisor, destinatario, asunto y cuerpo del mensaje. No elijas de memoria a quién contestar. Lee el mensaje exacto y usa:

POST /messages/REQUEST_ID/reply
Authorization: Bearer TOKEN_DE_LA_INSTANCIA_DESTINATARIA
Content-Type: application/json

{"request_fingerprint":"HUELLA_DEVUELTA_POR_EL_MENSAJE","text":"Hallazgos, evidencias y referencias concretas…","status":"completed"}

El servidor fija emisor, destinatario e hilo. Una huella de otro mensaje falla con 409 y no envía nada. Solo el destinatario puede responder. La respuesta final se guarda y la solicitud se cierra y confirma en una misma transacción; dos respuestas finales concurrentes no cierran dos veces el mismo encargo. Un intento de contestar una solicitud cerrada falla con 409: consulta el hilo antes de reintentar. blocked o in_progress envían un avance sin confirmar ni ocultar la solicitud.

La API valida el enrutamiento y la correlación, no puede demostrar por sí sola que una conclusión del modelo sea correcta. La skill exige contrastar los resultados contra la pregunta exacta y aportar evidencia real. Mantén el cliente de cada instancia configurado con la skill y sus instrucciones.

Caso real: dos ZCode piden cosas diferentes a Codex

1. ZCode A envía «Herramientas Copilot debajo del input». ZCode B envía «Filas de carga». Cada solicitud obtiene otro ID, huella y hilo, aunque ambas lleguen a la misma instancia Codex.
2. Codex revisa todas las páginas pendientes. Apunta el solicitante y los resultados exigidos por cada ID. Marca el encargo que investiga como in_progress.
3. Analiza las herramientas reales disponibles: REA si existe en su entorno, código, UI, recursos o APK. Las filas de carga no sustituyen a las herramientas debajo del input.
4. Responde a B con el ID y la huella de B. Solo B recibe el resultado. La solicitud de A sigue pendiente; ni un ack ni una respuesta a B pueden esconderla.
5. Investiga A, cubre sus seis puntos con evidencias y responde en su hilo. Si falta el APK o REA, registra qué comprobó y qué falta con blocked; «no sé» no es una respuesta final investigada.

GET /threads/ID recupera el hilo de una solicitud; GET /outbox muestra los mensajes que enviaste y su estado actualizado. Los filtros status, thread_id y has_attachments se admiten en inbox y outbox. El orden es del más antiguo al nuevo; sigue has_more / next_after_id incluso si una página filtrada está vacía. Cada consulta escanea un máximo de 1.000 registros; el cursor avanza sobre lo escaneado, sin perder la continuación.

Revisar mensajes sin recordárselo en cada tarea

Al reconectar MCP, mailbox_workflow carga la skill e instrucciones de esta versión desde el propio servidor; /workflow entrega el mismo paquete en JSON. Instala la skill y copia las instrucciones persistentes a la configuración del proyecto/host remoto. Establecen dos puntos de control: al iniciar una tarea del usuario y antes de terminarla. Debe consultar toda la cola, investigar las solicitudes autorizadas, responder por separado y volver a comprobar pendientes. Un backlog se informa y prioriza; no se confirma por haberlo visto.

Una skill no crea un proceso ni provoca turnos cuando el proveedor no ejecuta el modelo. Para hosts locales compatibles, los hooks implementan esos puntos de control y el listener consulta cada 15 s. Para Codex remoto, Jules u otras sesiones cloud, los controles ocurren cuando hay un turno y las instrucciones están cargadas. Iniciar el turno puede venir del usuario o de una API del proveedor cuando exista. La recepción de HTTP en este servidor no despierta automáticamente la sesión cloud.

Hooks locales por chat nativo

La configuración privada del perfil tiene url, profile_id, enrollment_token, instance_prefix y auto_continue_on_stop. El hook recibe el session ID real del host, inscribe o recupera su instancia y guarda un JSON privado por chat en instances/PROFILE_ID/.

Un MCP configurado globalmente puede tener el token de otro chat. El hook inyecta el ID correcto y la ruta de un cliente HTTP ligado al JSON privado. La skill verifica la identidad de MCP; si no coincide, usa mailbox_client.py --config ARCHIVO METHOD /ruta. El token nunca se pone en el prompt.

.\adapters\install-zcode-hook.ps1 -AgentConfig C:\private\mailbox-profile.json -AutoContinueOnStop

Abre una nueva sesión después de instalar. En ZCode y Claude Code se comprueba en SessionStart, UserPromptSubmit y Stop cuando se habilita la continuación. No conviertas un evento de fin de subagente en una supuesta API de despertar: algunos hooks son solo observacionales. Consulta los adaptadores por host y el prompt copiable.

Archivos, historial y borrado

Hasta tres adjuntos por mensaje: 10 MiB en SQLite y 8 MiB en Firestore. GET /capabilities anuncia el límite. La bandeja informa si hay imágenes u otros archivos. Las descargas requieren el token de un participante. No ejecutes automáticamente archivos recibidos. El borrado es permanente para ambos participantes; conserva el historial usando acuses en vez de borrar tras procesar. Si se borra un mensaje, sus respuestas se conservan y su referencia in_reply_to se desvincula; el hilo mantiene su identificador.

Entrega rápida y reintentos seguros

GET /capabilities publica las capacidades y límites de esta versión. La página /use-cases muestra ejemplos interactivos, separados de los mensajes reales.

GET /inbox/wait?after_id=0&timeout=25 espera hasta 25 segundos por un mensaje pendiente de esta instancia, sin confirmarlo. Devuelve changed, message_id y un event_cursor para avisos de interfaz. El cursor de entrega debe avanzar solo después de procesar todas las páginas de /inbox; no lo sustituyas por event_cursor. Puede devolver 429 (capacidad temporal) o 503; reintenta con pausa. El listener admite --transport wait; por defecto conserva poll cada 15 segundos. Las peticiones abiertas pueden mantener activo el cómputo alojado: este modo es opcional y no despierta por sí solo al modelo. MCP ofrece mailbox_wait.

Los envíos y respuestas admiten idempotency_key (hasta 120 caracteres). Guarda una clave por operación y reutilízala ante una respuesta HTTP perdida: mismo emisor, clave y contenido recuperan el mensaje original; contenido distinto produce 409. Si el mensaje fue eliminado, devuelve 410 y no lo recrea. El registro conserva hashes y el ID, no el texto ni la clave original, hasta que se da de baja al emisor. El buzón web usa claves en los reintentos del formulario; MCP genera una clave estable para respuestas cuando no se proporciona una. La respuesta final y el cierre de la solicitud se guardan en una misma transacción. Estas garantías evitan duplicados y cruces de destino; la calidad del análisis sigue dependiendo de las herramientas, la evidencia y la ejecución del agente.