Cómo está pensado Kanb

Qué es Kanb

Cuando alguien trabaja con agentes de IA en serio, aparecen tres problemas que ninguna herramienta de tareas resuelve. El primero es que no se sabe qué está pasando: un agente corre en una terminal, otro en otra, y no hay un lugar que muestre el estado real. El segundo es que el gasto es invisible hasta que la cuota se agota. El tercero es que nada queda registrado: cuando el trabajo termina, no hay rastro verificable de qué se decidió ni por qué.

Kanb existe para eso. Es un plano de control: no ejecuta la inteligencia, la coordina. Los agentes siguen siendo Claude, Codex o el que prefieras; Kanb es quien reparte el trabajo, mira lo que ocurre, mide el consumo y guarda la evidencia.

Tres compromisos que no se negocian

• Local primero. La base de datos vive en tu máquina y es la autoridad. Los servicios en la nube son opcionales y nunca mandan sobre lo local.
• Neutral entre proveedores. Ningún agente es especial. Agregar uno nuevo no debería tocar el núcleo.
• La aprobación humana es final. Un agente puede proponer, ejecutar y reportar. No puede aprobar su propio trabajo ni saltarse un límite.

El modelo de ejecución

La mayoría de las herramientas tienen un solo concepto: «la tarea». Kanb tiene cuatro niveles, y la distinción no es burocracia — cada uno responde una pregunta distinta que el sistema necesita poder contestar después de un reinicio, un corte de luz o un proceso que murió sin avisar.

El nivel que más cuesta entender es el último, y es el más importante. Un Dispatch es lo que pediste: «resolvé este bug con Claude». Una ProcessIncarnation es un arranque concreto de un proceso del sistema operativo. Si el proceso muere y hay que reintentar, nace una encarnación nueva — pero la petición sigue siendo la misma. Sin esa separación, un reintento parece trabajo nuevo, y el consumo se cuenta dos veces.

Arquitectura

El reparto de autoridad es deliberado. El escritorio ejecuta porque es donde están los CLIs y los archivos. El móvil nunca ejecuta — puede aprobar lo que el escritorio propone, pero no puede iniciar trabajo. Y la sincronización, si la contratás, intercambia eventos versionados con bandeja de salida, identificadores globales y resolución explícita de conflictos. Copiar filas entre bases en las dos direcciones está prohibido: es la receta clásica para que dos dispositivos se peleen por quién tiene razón.

Conexión con proveedores

La decisión más importante de seguridad del producto es una que no se tomó: Kanb no custodia tus credenciales de suscripción. Cuando ejecuta a Claude, lanza el CLI de Claude que ya tenés instalado y autenticado. El token nunca pasa por Kanb.

Ciclo de vida de un trabajo

La regla que gobierna todo el diagrama es una sola: nunca se sintetiza certeza desde una señal ausente. Si Kanb pidió arrancar un proceso y no recibió confirmación, el estado no es «falló» ni «corrió» — es start_unknown, y alguien tiene que reconciliarlo. Un sistema que adivina en ese punto es un sistema que algún día mata un proceso que estaba trabajando bien, o cobra dos veces el mismo trabajo.

Toda transición deja un recibo: un registro que solo se agrega, nunca se edita. Si algo estuvo mal, se agrega un recibo que lo corrige; la historia no se reescribe. Eso es lo que hace que el historial sirva como evidencia.

Propiedad y cerebro dividido

El problema se llama cerebro dividido y no es teórico: pasa cuando la aplicación se reinicia mientras un agente sigue corriendo, o cuando alguien abre Kanb dos veces. Si ambas creen ser dueñas del proceso, una puede matarlo mientras la otra le manda trabajo.

Cada vez que la propiedad cambia de manos, un contador —la generación— sube. Toda operación lleva ese número escrito. Una orden emitida por un dueño vencido llega con un número viejo y se rechaza, tanto en la base de datos como al borde del proceso real. Y hay una regla adicional que evita el error opuesto: tomar la propiedad no borra lo que hizo el dueño anterior. Un trabajo que quedó en estado incierto hay que reconciliarlo o abandonarlo explícitamente; no se puede ignorar.

Y si Kanb encuentra un agente que no lanzó él

Pasa: reiniciás la aplicación y quedó un proceso corriendo, o algo se ejecutó por fuera. Kanb clasifica lo que encuentra en categorías explícitas —instalado, mío y activo, mío y retomable, ajeno observado, desconocido— y actúa distinto en cada caso.

La regla dura es esta: un proceso que Kanb no lanzó no se adopta nunca automáticamente. Retomar uno propio exige que esté asentado y que haya evidencia de que efectivamente era suyo. Para los ajenos no hay ruta de adopción en absoluto — no es que esté desactivada por configuración, es que no existe el camino en el código.

Consumo y cuota

Ningún proveedor publica un contador oficial de cuota para herramientas externas. Lo que hay son señales indirectas. Kanb las usa, pero es explícito sobre lo que son: toda medición lleva de dónde salió, cuánta confianza merece y cuándo se observó.

Los tres canales nunca se mezclan en un solo número. Sumar una medición real con una estimación produce una cifra que parece precisa y no lo es — y sobre esa cifra alguien tomaría decisiones de gasto.

Cuatro reglas que se siguen de ahí

• La utilización siempre significa consumido, normalizada entre 0 y 1. Un proveedor que reporta «lo que queda» se invierte en el borde, una sola vez.
• Una lectura vieja se marca como vieja. No se presenta como fresca.
• Si el formato del proveedor cambia y el lector falla, falla cerrado: reporta desconocido, no un número inventado.
• Ante la duda, el respaldo son los datos de las ejecuciones propias, no una exploración más agresiva del sistema ajeno.

De dónde sale el dato, y qué no se hace para conseguirlo

Kanb obtiene consumo por tres vías, y las tres están acotadas a propósito.

• Lo que Kanb presencia. Cuando lanza un agente, lee el consumo del flujo que ese proceso emite. Es la vía más confiable porque no depende de interpretar el sistema de nadie.
• Sondeo por línea de comandos. Kanb puede preguntarle al CLI del proveedor por sus ventanas de cuota, con argumentos fijos, tope de salida y un intervalo mínimo entre consultas. Sin ninguna llamada de red propia — hay una prueba automática que falla si alguien agrega un cliente HTTP a ese módulo.
• Importar histórico, solo si vos lo autorizás. Kanb puede leer transcripciones locales para recuperar consumo anterior a su instalación. Requiere consentimiento explícito y por ruta: no explora tu disco buscando nada.

Del histórico se extraen únicamente contadores y marcas de tiempo. El contenido de las conversaciones no se lee, ni se guarda, ni se registra — y no por disciplina, sino porque no existe un campo ni una columna donde pueda entrar.

Qué modelos y cuentas hay disponibles

Kanb también enumera qué modelos y cuentas expone cada runtime instalado, para no tener que preguntártelo. De una cuenta guarda una referencia opaca, nunca la identidad ni la credencial. Y distingue explícitamente entre lo que un proveedor declara y lo que Kanb verificó: hoy, para los dos proveedores incluidos, la información es declarada y así aparece marcada.

Control de admisión

Esta es la lógica más consecuente del sistema: es lo que impide que un agente consuma tu cuota del mes sin freno. Por eso está diseñada como una función pura: recibe la política, las ventanas de consumo, la petición y la hora, y devuelve un veredicto. No hace llamadas de red, no lee el reloj —el tiempo se le inyecta— y no sabe nada de proveedores. Se puede probar exhaustivamente sin conexión ni subprocesos.

La decisión sutil está en el último recuadro. Si no hay telemetría —porque el proveedor no publica nada o porque la lectura falló— el veredicto por defecto permite. La alternativa sería bloquear ante la duda, y eso convertiría cualquier fallo de lectura en una parálisis total del producto por una medición que quizás nunca existió.

Seguridad

Kanb es una aplicación de escritorio con una interfaz web adentro. Ese diseño tiene un riesgo conocido: si alguien logra inyectar código en la interfaz, hereda todo lo que la interfaz pueda hacer. La respuesta habitual —habilitar complementos genéricos para base de datos o terminal— es exactamente lo que Kanb no hace.

Un comando como «registrar esta observación de consumo» no se puede convertir en otra cosa. Comodidad para quien programa no vale entregarle a un atacante una herramienta de propósito general.

Lo que se sostiene alrededor

• Los procesos se lanzan con argumentos fijos, sin terminal intermedia, con entorno mínimo y sin que la interfaz pueda influir en la ruta, los argumentos ni las variables.
• Toda salida de un agente es dato no confiable. Se valida con lista blanca y tope de tamaño; lo que excede se rechaza sin siquiera intentar leerlo.
• Los secretos no entran en la base, ni en registros, ni en recibos, ni en capturas, ni en la memoria del asistente. Se usan referencias, no valores.
• Leer archivos tuyos requiere consentimiento explícito por ruta. Kanb no explora tu disco buscando nada.

Protocolo y sincronización

Kanb publica un protocolo versionado con los esquemas de comandos, eventos y recibos. No es documentación: es un contrato con suite de conformidad, y cualquier implementación tiene que pasarla para decir que lo cumple.

Esa decisión salió de un problema real. Dos partes del sistema —una en Rust, otra en TypeScript— implementaron la misma frase de una especificación escrita en prosa y la entendieron distinto. Las dos pasaban sus propias pruebas. Solo chocaron al integrarse. La conclusión fue que un contrato en prosa se interpreta; un contrato ejecutable se cumple o no.

Cómo llegaría una orden desde el teléfono

El transporte todavía no existe, pero el contrato sí, y define el camino que una orden remota tendrá que recorrer. Cada comando entrante se trata como no confiable y se revalida entero contra el contrato antes de tocar nada durable. Si llega con una generación de propiedad vencida, se rechaza — nunca se aplica «por las dudas».

El vocabulario de comandos es cerrado por construcción: aprobar, pausar, cancelar y reintentar. No hay forma de que llegue algo fuera de esa lista, y no incluye iniciar trabajo nuevo, porque el teléfono no ejecuta. Reusar una clave de idempotencia con un contenido distinto se rechaza, que es lo que impide que una orden repetida se aplique dos veces.

Licencia y modelo

Kanb se publica bajo AGPL-3.0. Es una licencia libre con una condición: quien modifique Kanb y lo ponga a disposición de otros por red está obligado a publicar sus modificaciones. Eso impide que alguien tome el trabajo, lo cierre y lo ofrezca como servicio sin devolver nada.

El código es abierto porque la inspeccionabilidad es parte del producto. Kanb corre en tu máquina, lanza procesos y —con tu consentimiento explícito— lee transcripciones. «Confiá en mí» no es vendible a código cerrado desde esa posición.

Dónde está el negocio

Muchas organizaciones tienen políticas internas que prohíben usar software con licencia AGPL, incluso puertas adentro. Para ellas Kanb vende una licencia comercial: una excepción a esas obligaciones. Lo gratuito es el programa con copyleft; lo que se cobra es el derecho a usarlo sin él.

Estado de la implementación

Índice de decisiones

Cada decisión de esta página está registrada como ADR en el repositorio, con su contexto, sus alternativas descartadas y sus consecuencias.