id: ADR-004 title: El estado compartido mantenido por la herramienta sigue la identidad propiedad del daemon y la propiedad del handle date: 2026-03-22 status: accepted relates-to:

• https://github.com/zeroclaw-labs/zeroclaw/issues/4057
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-api/src/tool.rs

ADR-004: El estado compartido mantenido por herramientas sigue la identidad propiedad del daemon y la propiedad del identificador

Este es un registro retroactivo restaurado. La ADR original se añadió en docs/architecture/adr-004-tool-shared-state-ownership.md y se eliminó durante la migración a mdBook. Las rutas de código se han տեղափոխado a crates del workspace desde el registro original; esta versión restaurada mantiene intacta la decisión aceptada mientras actualiza las referencias de ruta cuando resulta útil.

Contexto

ZeroClaw tools se ejecutan en un entorno multicliente donde un único proceso daemon puede atender a múltiples clientes conectados y sesiones de agente. Algunas herramientas necesitan estado compartido de larga duración:

• Las herramientas delegadas mantienen manejadores hacia las herramientas padre;
• Las herramientas orientadas a canales mantienen descriptores de mapas de canales;
• las herramientas de canvas mantienen el estado de visualización compartido;
• Las herramientas futuras pueden mantener limitadores de tasa, pools de conexiones, manejadores de credenciales o cachés con ámbito de sesión.

Esos estados no pueden tratarse todos de la misma manera. Algunos son estado compartido legítimo de visualización o de registro. Algunos son sensibles desde el punto de vista de la seguridad y deben aislarse por cliente o sesión.

Sin un contrato compartido, las nuevas herramientas corren el riesgo de introducir estado duplicado, fugas de datos entre clientes, estado obsoleto después de recargas o bloquear la validación de inicio en la fase incorrecta del ciclo de vida.

Decisión

Las herramientas pueden poseer estado compartido de larga duración cuando siguen el patrón de manejador y respetan las reglas de identidad, aislamiento, ciclo de vida y recarga propiedad del daemon.

1. Propiedad

Cuando una herramienta es legítimamente propietaria de estado compartido, usa un manejador clonable pasado en el momento de la construcción, normalmente un Arc<RwLock<T>> o un envoltorio fino alrededor de uno.

Los ejemplos en el espacio de trabajo actual incluyen:

Las herramientas que necesitan estado compartido deben:

• defina un tipo de identificador con nombre o un envoltorio;
• acepta el handle en el momento de la construcción;
• documentar el contrato de concurrencia y propiedad
• evita el estado mutable global para datos por solicitud o por cliente.

2. Identidad

El daemon posee la identidad del cliente y de la sesión. Las herramientas no deben construir sus propias claves duraderas de identidad de cliente a partir de detalles de transporte como direcciones IP, encabezados, nombres de usuario o cadenas de remitente específicas del canal.

Las herramientas que necesitan un espacio de nombres por cliente consumen la identidad asignada por el daemon o reciben un handle ya acotado. Las herramientas que no necesitan aislamiento por cliente pueden ignorar la superficie de identidad, pero no deben inventar una paralela.

3. Ciclo de vida

El ciclo de vida de la herramienta tiene cuatro fases:

1. Construcción: instanciar con manejadores y entradas derivadas de la configuración. No realice validación de red o del sistema de archivos que bloquee.
2. Registro: registra en el registro de herramientas. Una herramienta puede realizar validación de inicio si esa validación se requiere antes de su uso.
3. Ejecución: gestiona una sola solicitud. Evita bloquear la validación o las reconstrucciones del registro en esta ruta.
4. Apagado: limpie los recursos de los que es propietario mediante Drop o un método explícito de apagado cuando el propietario proporcione uno.

El estado de validación derivado de la configuración, las credenciales, la política o recursos externos debe invalidarse cuando la fuente cambie. El estado de visualización no relacionado con la seguridad puede persistir tras las recargas solo cuando la recarga no afecte a su validez.

4. Aislamiento

El estado que puede filtrar credenciales, políticas, cuotas, datos de usuario o datos de sesión debe aislarse por cliente, agente o sesión según la superficie propietaria. Un identificador compartido no debe almacenar secretos por cliente a menos que el espacio de claves esté delimitado por una identidad propiedad del daemon.

El estado que se comparte de forma natural, como el estado de visualización de difusión, los datos de registro de solo lectura o los identificadores de canal, puede compartirse entre clientes. Cuando utiliza claves de cadena, debe admitir el prefijo de espacio de nombres o metadatos de trazabilidad para que los operadores puedan seguir filtrando por cliente, agente, canal o sesión.

5. Semántica de recarga

La validación derivada de la configuración y las cachés no son válidas después de que cambien la configuración, las credenciales, la política, el espacio de trabajo o la fuente del proveedor relevantes. La herramienta debe volver a resolver desde la fuente de verdad en el momento de uso o recibir un identificador/valor derivado de la configuración nuevo del propietario.

La regla de recarga trata sobre la validez, no sobre la mutación del registro. Una herramienta puede conservar el estado de visualización no relacionado con la seguridad entre recargas solo cuando la recarga no afecta la validez de ese estado.

Consecuencias

Consecuencias positivas:

• El estado propiedad de la herramienta se vuelve detectable y auditable.
• Los datos sensibles a la seguridad tienen un requisito de aislamiento con nombre.
• El comportamiento de recarga en tiempo de ejecución tiene una regla clara de invalidación.
• Las nuevas herramientas pueden reutilizar el patrón de handle sin inventar estado global.
• Los revisores pueden pedir la fuente de verdad antes de aceptar un nuevo campo de herramienta o caché.

Consecuencias negativas:

• Las herramientas que parecen simples singletons deben seguir razonando sobre la identidad del cliente, del agente y de la sesión.
• Algunos identificadores antiguos necesitan migración cuando cambia la superficie de identidad del daemon o el modelo de recarga.
• El patrón de identificador no es suficiente por sí solo; la propiedad y el estado canónico aún tienen que nombrarse en la revisión.

Referencias

• Inventario de herramientas integrado
• Issue #4057
• AGENTS.md
• crates/zeroclaw-runtime/src/tools/mod.rs
• crates/zeroclaw-tools/src/ask_user.rs
• crates/zeroclaw-tools/src/poll.rs
• crates/zeroclaw-tools/src/reaction.rs
• crates/zeroclaw-tools/src/canvas.rs
• crates/zeroclaw-api/src/tool.rs
• crates/zeroclaw-gateway/src/lib.rs