La empresa digital operada por trabajadores agénticos, diseñada para que el silencio no cueste nada.
Empresa primero. Agentes después. Trabajo verificable siempre.
30 segundos · Empezar · Modelo mental · Arquitectura · Estado · Documentación
Estado: desarrollo activo. La fundación y la primera vertical empresarial ya corren de punta a punta contra PostgreSQL vivo y DeepSeek real. IO todavía no es un sistema listo para producción. Esta documentación describe el estado real, sin inflar capacidades.
IO no intenta construir un chatbot más grande ni un enjambre de agentes hablando entre sí. Su unidad principal es la empresa.
Trabajadores de IA ejecutan trabajo de negocio — documentos, análisis y entregables — dentro de sandboxes reversibles, bajo autoridad humana explícita. Cada activación tiene costo, cada trabajador tiene límites y cada resultado debe dejar evidencia verificable.
| Contrato | Qué significa en IO |
|---|---|
| Empresa antes que agente | Estrategia, procesos, puestos y autoridad existen antes de elegir un modelo. |
| El silencio cuesta cero | Si no hay novedad material, el heartbeat termina sin invocar al LLM. |
| Autoridad proporcional al riesgo | El fundador/directorio conserva finalidad, capital y acciones irreversibles. |
| Evidencia antes que confianza | Receipts, eventos y journals prueban qué ocurrió. |
| Costo como parte del razonamiento | Tokens, contexto y KV-cache se tratan como recursos económicos. |
La visión completa — capas empresariales, memoria y economía cognitiva — está en el documento fundacional.
Requisitos: Node 24 LTS (ver .nvmrc), pnpm 11 y Docker.
git clone https://github.com/riquelmechile/io.git
cd io
nvm use
corepack enable
pnpm install
docker compose up -d
pnpm testPostgreSQL local queda disponible mediante docker-compose.yml en:
postgresql://io:io_dev@localhost:5432/io_dev
Para ejecutar todas las puertas de calidad:
pnpm checkpnpm check ejecuta, en orden: format → typecheck → build → lint → test.
Qué comprueba el CI con PostgreSQL en vivo
El CI (ci.yml) corre integración y E2E contra un servicio postgres:18 real con IO_REQUIRE_PG=1. Si la base no está disponible, las suites fallan ruidosamente: el vertical real no se oculta detrás de skips silenciosos.
La idea central es simple: estar disponible 24/7 no significa llamar al modelo 24/7.
Empresa → estrategia → portafolio → procesos → puestos
→ trabajadores agénticos → trabajo → artefactos
→ resultados → aprendizaje
Un evento entra al sistema. Antes de gastar tokens, un gate determinístico decide si existe novedad material. Solo entonces se activa la empresa, se despacha trabajo y un worker puede usar el LLM. El resultado vuelve como evidencia y aprendizaje.
- Evento de negocio. Algo cambia en el stream append-only de la empresa.
- Heartbeat. Una función pura decide si existe novedad material.
- Cero tokens cuando corresponde. Si nada exige acción, termina como
no-llm-heartbeat. - Supervisor. Descubre empresas y activa únicamente las que tienen trabajo real.
- Work dispatch. Se toma el
Workaceptado más antiguo. - Worker. Plan LLM → sandbox reversible → cierre atómico.
- Evidencia. Receipts de negocio y journal de idempotencia dejan constancia verificable.
Abrir el flujo técnico
flowchart TD
E["Stream de eventos de negocio\nappend-only · PostgreSQL"] --> G{"Heartbeat gate\nfunción pura · sin LLM"}
G -- "sin novedad material" --> Z["no-llm-heartbeat\n0 tokens"]
G -- "novedad material" --> S["Supervisor\nactiva la empresa"]
S --> D["Work dispatch\nWork aceptado más antiguo"]
D --> W["Ciclo de worker"]
W --> P["Plan LLM\nDeepSeek Flash"]
P --> X["Sandbox\nreversible"]
X --> R["Cierre atómico\nreceipts + journal"]
R --> E
La fuente de verdad es un log de eventos de negocio append-only en PostgreSQL. Los cursores permiten procesamiento at-least-once y recuperación segura ante caídas.
Muchos sistemas agénticos gastan tokens incluso cuando no hay trabajo nuevo: loops periódicos consultan al modelo solo para descubrir que no deben hacer nada. Eso eleva el costo, invalida contexto útil y hace difícil sostener una empresa agéntica 24/7.
IO parte de otra premisa: el costo es parte del razonamiento.
- Cada activación tiene presupuesto y utilidad esperada.
- El contexto se compila con prefijos estables por cohorte para favorecer hits de KV-cache.
- El modelo se invoca después de una decisión determinística, no para decidir si merece ser invocado.
- La autonomía se asigna por autoridad y riesgo, no por entusiasmo con el modelo.
IO es un monorepo TypeScript con pnpm workspaces y arquitectura hexagonal. El dominio puro no depende de proveedores externos; PostgreSQL, DeepSeek y el sandbox viven detrás de puertos reemplazables.
| Paquete | Responsabilidad |
|---|---|
@io/business-domain |
Dominio puro: Work, receipts, eventos de negocio y heartbeat. |
@io/trust-kernel |
Principals y evaluación de autoridad. |
@io/context |
Compilación de contexto y prefijos estables para economía de KV-cache. |
@io/database |
PostgreSQL: eventos append-only, cursores, work, receipts y journal. |
@io/llm-client |
Cliente DeepSeek: thinking, tools y costo de cache. |
@io/app |
Composición: supervisor, dispatch y proceso worker con sandbox. |
Las decisiones arquitectónicas aceptadas se registran como ADR en el índice de decisiones.
Qué autoridad mantiene el humano
El fundador/directorio conserva la autoridad constitucional de la empresa: finalidad, capital, límites críticos y acciones irreversibles. Los trabajadores operan con libertad proporcional al riesgo y con límites explícitos de misión, presupuesto y desempeño.
Qué significa «evidencia verificable»
IO no considera suficiente que un agente declare «terminé». Las acciones relevantes deben quedar reflejadas en artefactos, eventos, receipts o journals que permitan comprobar qué ocurrió y reconstruir el estado sin depender de memoria conversacional.
IO se construye por incrementos verificables: cada incremento debe funcionar y producir evidencia antes de avanzar al siguiente.
| Estado | Qué |
|---|---|
| Completado | Fundación de desarrollo root-only (ADR-0004), dominio (Work, receipts, eventos y heartbeat), trust kernel, persistencia PostgreSQL, cliente DeepSeek con E2E en vivo, compilador de contexto, activación por heartbeat, supervisor timer y work dispatch, daemon durable, heartbeat decision events, escalada Flash→Pro, fencing tokens, supervisor recovery (Scope B), cold-start discovery, Skill outcome BusinessEvents y la fundación de evidencia de Learning/promotion (contratos de candidatos, políticas, agregación de outcomes, validación descriptor-safe de evidencia, observaciones, evidencia explícita y referencias y alcances de autoridad). |
| Siguiente | Incremento 8 — Learning/promotion: evaluador de promociones y puertos de candidatos y autoridad sobre la fundación de evidencia ya entregada; luego capa app y persistencia PostgreSQL para completar el ciclo candidate → active, trazado en pasos siguientes. |
Todo el trabajo se entrega bajo Spec-Driven Development. El historial verificable está en openspec/changes/archive/.
| Necesito | Ir a |
|---|---|
| Entender la visión completa | Arquitectura maestra, memoria y economía cognitiva |
| Revisar decisiones aceptadas | Índice de ADR |
| Seguir el próximo incremento | Pasos siguientes |
| Contribuir al proyecto | Guía de contribución |
| Auditar cambios entregados | Archivo OpenSpec |
| Operar el proceso durable | Operación del daemon |
Compatibilidad de los visuales
GitHub selecciona automáticamente los pares dark/light del hero, mapa y flujo mediante <picture>. docs/assets/io-operating-model.svg aporta una vista estable del modelo operativo, independiente del tema, para enlaces o renderizadores que necesiten una única ruta fija.
IO se desarrolla con Spec-Driven Development sobre OpenSpec: propuesta → especificación → diseño → tareas → implementación → verificación → archivo.
La implementación sigue TDD estricto (RED → GREEN → REFACTOR) y la entrega se autoriza mediante evidencia de revisión. La documentación obedece la misma idea: primero el camino mínimo para entender y ejecutar; la profundidad queda disponible cuando hace falta.
PostgreSQL no está disponible
Comprueba primero que el servicio local esté levantado:
docker compose up -dLas suites que requieren PostgreSQL deben fallar de forma explícita cuando IO_REQUIRE_PG=1; no esperes un skip silencioso.
No sé por dónde seguir leyendo
- Si quieres entender la idea: empieza por IO en 30 segundos.
- Si quieres ejecutar el repo: ve a Empezar en 5 minutos.
- Si quieres entender la arquitectura completa: abre el documento fundacional.
- Si quieres entender por qué se tomó una decisión: revisa los ADR.
- Si quieres ver qué se entregó realmente: revisa OpenSpec.
IO no se mide por cantidad de agentes ni tokens gastados.
Se mide por trabajo terminado, costo por resultado y aprendizaje comprobado.