Agent Squad, paso a paso

De ese insight salió la decisión fundacional: el producto es el substrato, no la app. No construir un Photoshop: si construís el consumer sin substrato repetís el patrón de cada SaaS de IA — los usuarios producen pixels pero el sistema no aprende. Agent Squad consumer nació como la primera ontology overlay y la prueba pública de que el substrato sirve (cuando se diseñó, la app era un plan; hoy está en producción y es el único ontology overlay activo). «Substrato simbólico» quedó definido así: memoria estructurada con primitives tipados donde cualquier afirmación es defendible, trazable y consultable por un sucesor. Y todo salió de una sola sesión de trabajo: del insight a workflows productivos con LLM real.

Antes de tocar código se alinearon siete forks (bifurcaciones de diseño) en esa misma sesión. Tres para destacar:

• Fork 03 — una sola ontology hasta saturar: profundidad antes que ancho. Sigue vigente: el overlay único es agent-squad-consumer, y ontology_overlays permite relabels por vertical sobre los mismos primitives.
• Fork 05 — plan compiler híbrido: primero 6 meses de templates curados a mano; después, un compilador con vector lookup sobre los rankings de templates. Es la predicción que se cumplió transformada: hoy ese rol lo juega Nova con el desenlace MATCH.
• Fork 06 — «Open spec. Closed engine.»: el spec es publicable (JSON Schema + Zod, no un DSL propio); el runtime no. Los conteos originales quedaron viejos — hoy el catálogo tiene 26 Operations, 9 Evaluators y 7 Templates.
• Fork 07 — Fase 0 en 4 semanas: spec+infra → catálogo+template → hook web↔substrato → standup-digest end-to-end en producción. Todos los entregables existen y el cron sigue corriendo.

Y el fork del multi-tenant dejó su marca desde el día cero: workspace_id viaja en los datos desde la migración 0001 — el multi-tenancy que falta es capa de routing, no migración de datos («el identificador de tenant va en los datos antes que en el routing»).

El descarte de alternativas también fue explícito. El substrato combina cuatro requisitos a la vez: recuperación semántica (lo que da RAG), DAGs reusables (lo que prometía LangChain, estructurado), durabilidad + human-gate (lo que da un workflow engine) y el grafo de claims tipados — el cuarto es el moat que ninguna alternativa pública ofrece. Los aforismos de aquella sesión de diseño, para tener a mano cuando te objeten:

• «RAG te dice qué se parece; el substrato, qué fue afirmado, por quién y cuándo.»
• «LangChain es el pegamento entre prompts; el substrato es el motor durable + la memoria estructurada» — con estado en memoria, un crash es arrancar de cero, y no hay human-in-the-loop durable.
• «Los agent frameworks son improvisación; el substrato es partitura con margen de improvisación dentro de cada step.»
• «El workflow engine es el verbo; el substrato agrega el sustantivo (claims tipados). Inngest + Postgres + spec = substrato» — cada cambio de estado es una fila tipada, no una mutación en memoria.

Una pata más del mismo desarme, con fecha: al as-built de junio, 11 de las 17 operations de entonces eran handlers deterministas — el LLM solo entraba en las de composición de texto. Determinismo donde importa, modelo donde aporta.

La validación llegó rápida y barata: el primer smoke test, el 19-may-2026, con Sonnet 4.5 real. Los cuatro templates llegaron a awaiting_human por un costo total de $0.064 (standup $0.0222, brief $0.0147, lead $0.0143, video $0.0124). Lo no trivial: Sonnet razonó sobre el propio backlog — trace.query le dio los traces reales y el narrative dijo textualmente «5 digests en cola desde 16:32» — validando la cadena retrieval→composer. Uno de los angles generados esa tarde: «RAG te da respuestas parecidas. Un grafo de claims tipados te da respuestas defendibles. Cuando tu negocio depende de que la IA no invente, la arquitectura importa más que el prompt.» El primer artifact aprobado (el brief «Substrato vs RAG») materializó 5 claims — approvedBy=human:roberto, comment 'Hook 2 gana' — que siguen consultables hoy en la DB.

Las dos mitades son dos programas que solo se hablan por HTTP; no comparten ni base de datos ni memoria:

• La app = apps/web, hecha en SvelteKit 5 / Threlte, desplegada en Vercel (managed, no corre en el servidor). Es la oficina 3D. Es intercambiable: es solo el frente.
• El substrato = apps/api, un runtime en Bun + Hono que corre en un servidor Hetzner como servicio systemd agent-squad-api.service. Es el system-of-record: la fuente de verdad.

La app llama al substrato por HTTPS con un bearer token. El corazón del substrato es el runtime; a su alrededor usa tres piezas de infraestructura: Postgres (donde vive el grafo), Inngest (motor de ejecución durable) y Langfuse (observabilidad de las llamadas al LLM).

Fail-soft al leer, ruidoso al escribir: si el motor no responde en 2.5 segundos, la página carga igual con contenido de ejemplo etiquetado como tal — recuperar datos nunca bloquea usar el producto. Las escrituras son lo contrario: fallan ruidosamente. Es una regla transversal de diseño de la app.

La cadena, con sus tablas reales de Postgres: Intent (tabla intents, el pedido declarado) → Plan (tabla plans, se compila desde una PlanTemplate como standup-digest-v1) → Steps (tabla steps, cada uno referencia UNA operación vía operation_ref + qué agente lo ejecuta + si necesita gate, ordenados por ordinal) → Trace (tabla traces, UNA corrida concreta del plan) → Step Executions (tabla step_executions, qué pasó al ejecutar cada step) → Artifacts (lo producido) y Claims (hechos aprendidos con su fuente).

La distinción clave: el step es la parte estática del plan (la diligencia a realizar). El step_execution es la constancia de esa diligencia hecha dentro de una trace concreta: status, timing, costo, output, error. Un mismo step puede tener muchas ejecuciones distintas — una por cada trace que corra ese plan.

Puente sobre el orden: el step vive en el plan (es la definición, estática); la trace y sus step_executions son la corrida (la ejecución). Por eso a veces se lista trace antes que step (el orden del expediente) y a veces step antes que trace (el orden de runtime): es la misma cadena vista desde definición vs. ejecución.

Claim vs log vs embedding — y por qué «simbólico»: tres formas de recordar lo mismo: un log guarda una oración suelta, difícil de razonar después; un embedding son 384 números — similares matemáticamente pero no auditables en su origen; un claim ya lo conocés de este capítulo: estructurado, leíble y trazable a quién lo puso. Decir «substrato simbólico» es declarar bando frente al enfoque connectionist: claims con estructura, no nubes de números.

¿Qué es un DAG? (y una honestidad sobre el paralelismo): Un DAG es un grafo dirigido sin ciclos — el mismo modelo de Git, Excel y Airflow. El motor le hace topo-sort (algoritmo de Kahn, con detección de ciclos) para arrancar cada step cuando sus inputs terminaron. Honestidad verificada: el executor actual recorre el orden topológico secuencialmente — el paralelismo de ramas es potencial del modelo, no comportamiento implementado.

El pedido en lenguaje natural entra por POST /api/workspaces/:id/compose. Nova interpreta el texto y produce un desenlace (el resultado de cómo resolvió el pedido):

• MATCH: ya existe un SuperSkill del workspace que sirve; lo reusa (matcheando el pedido contra los SuperSkills guardados). Es el camino más barato: reuso, no compilación.
• PLAN: arma un plan nuevo combinando operaciones del catálogo cerrado (un DAG de steps).
• FORGE: la capacidad no existe; la construye en tiempo real (capítulo 5).
• CANNOT: no se puede honestamente — requiere poderes que el sistema no se auto-otorga (ej. efectos externos sin credenciales).

Hay una segunda puerta de entrada: POST /api/intents, para lo programático (crons, integraciones, el proxy de un MATCH). Declara un intent estructurado (subject_label + kind) directo, sin la interpretación de Nova, y compila el plan desde su PlanTemplate.

A los planes que Nova compone no se les cree: pasan una validación server-side de 4 capas antes de ejecutarse: (1) cada operación existe en el catálogo — la misma verificación de resolveOperation que vas a ver en el capítulo 8, (2) sin ciclos — Kahn, (3) tope de 10 steps, (4) el gate humano final lo agrega el sistema, no el modelo. Todo lanzamiento re-valida contra el catálogo, y el costo estimado lo calcula el servidor desde el catálogo — el modelo no puede mentir el costo. El propósito de fondo: que «el modelo decidió» nunca sea la explicación de una ejecución. Al modelo no se le confía nada que se pueda verificar. Y cada pedido a Nova — incluso los CANNOT — queda registrado en plan_drafts con su desenlace: los «no pude» son telemetría de demanda que prioriza el roadmap.

El ciclo de una trace: queued → running → (opcional) awaiting_human → succeeded. El Executor resuelve los steps y los encola en Inngest. Cada step corre operación + agente y luego un step de calidad, evaluator.run (actor system:evaluator), que valida el artifact contra los criterios de aceptación y deja un verdict — normalmente después de producir el artifact y antes del gate humano.

Si el plan tiene un run-gate, la corrida se suspende de forma durable hasta 72h con step.waitForEvent() de Inngest, sin consumir recursos, esperando la decisión. El humano decide con POST /api/approvals (workspace_id, artifact_id, decision) contra el artifact en pending_review; eso reanuda la corrida y la lleva a succeeded. Orden típico en un standup-digest: …compose (s5) → evaluator.run (s6) → publish (s7) → human_gate (s8).

El run-gate no es una convención: es estructural. Todo lanzamiento — plan de fábrica, compuesto por Nova o SuperSkill custom — pasa por el mismo helper: assertHumanGatePresent exige al menos un gate humano terminal con fallback exactamente 'fail' antes de lanzar; sin gate no hay launch («el servidor no puede confiar en el upstream; lo fuerza acá»). Las garantías no dependen de quién creó el plan. Y el formulario de relanzado se deriva mecánicamente de las variables {{intent.constraints.*}} que el plan declara.

No todo workflow lleva gate: pricing-watch corre solo: Ojo con sobre-generalizar: pricing-watch está en producción como template monitor_event + una función Inngest con cron diario (04:00 Bogotá) que declara intents como system:scheduler — el primer workflow que corre sin humano que lo dispare. Es read-only y sin human gate (igual que document-query). El gate estructural aplica a lo que se lanza desde la app y a lo que tiene efectos con firma; los read-only autónomos no lo llevan. El primer side-effect externo (email-triage) todavía no existe, y entrará con tres condiciones: idempotencia ante retries, observabilidad del envío y gate antes de actuar hacia afuera.

Cicatriz: async.data vs event.data: en step.waitForEvent la condición de match debe escribirse sobre async.data (el evento que va a llegar). Escribirla sobre event.data evalúa al momento de la suspensión, matchea null — y todos los gates quedan colgados indefinidamente. Bug crítico aprendido en el camino.

FORGE se dispara cuando un pedido es un CANNOT genuino Y la capacidad faltante es PURA (sin efectos externos). El loop:

1. Generate: produce spec + tests + código (con Claude Code headless, $0).
2. Verify: lo ejecuta en un sandbox aislado (bwrap, red denegada, sin secrets).
3. Build-gate: pasa por aprobación humana (forge.approval, gate durable de Inngest, 72h).
4. Registry: si se aprueba, se registra en el catálogo tras assertPureContract + staticSafetyCheck — y queda callable.

En la práctica: pedís algo fuera de catálogo por /compose; Nova responde status:"forging" y construye en background (~20-90s). El candidato aparece en GET /api/forge/pending (el build-gate); lo aprobás con POST /api/forge/<CANDIDATE_ID>/decision. Después, el mismo pedido ya se resuelve con la op forjada (aparece el agente Forge en un step).

Una precisión que la ingeniería inversa dejó en evidencia (05-jul): el ruteo del MATCH no es vectorial — Nova recibe los SuperSkills del workspace (hasta 20, cargados fail-soft) inline en el system prompt, y una sola llamada LLM decide el desenlace con validación server-side de cada rama (compose.ts). El retrieval vectorial entra en el ciclo normal en el recall de contexto: durante la ejecución el executor recupera claims previos del grafo (claim.recall_*) para no rehacer trabajo — un RAG sobre el conocimiento ya establecido.

Aparte está el read-path de Q&A, la operación document.query, que hace recuperación híbrida: rama vectorial (e5) + rama léxica (ts_rank_cd de Postgres), fusionadas por RRF (Reciprocal Rank Fusion). Luego un reranker activo (Cohere Rerank 4 Pro) reordena una ventana de 20 candidatos y manda el top-5 al LLM. Si el proveedor externo falla, degrada limpio a RRF — no rompe.

El efecto compuesto del recall — y su gap real: Antes de componer, el motor ejecuta claim.recall_decisions y le pasa al modelo las decisiones previas («hace 1 día, sobre un brief similar, Roberto aprobó Hook 2») — el LLM no adivina ni recuerda: hereda la decisión como input. Ese circuito tuvo un gap hasta el 05-jul-2026: recall_decisions filtra por los predicates consolidatedDecision, workspace.decision y decision, y el approvalComment quedaba excluido. Hoy está cerrado: al aprobar/rechazar con comment, el executor emite además un claim decision (con embedding por tema) que el recall sí hereda — y los 33 comments históricos se backfillearon al grafo.

Antes de que cualquier documento o transcripción entre a la tabla de vectores, pasa por anonimización PII con Microsoft Presidio (microservicio Docker local substrate-presidio en 127.0.0.1:8400). La regla es custodia dual: el artefacto original con PII se marca confidencial y queda intacto en el grafo; a document_chunks, al reranker (Cohere) y al LLM solo entra texto anonimizado con placeholders (<PERSONA>, <EMAIL>, <ID_TRIBUTARIO>…). Cubre nombres, emails, IDs tributarios LATAM y empresas.

Fail-safe: si Presidio cae, la ingesta NO indexa nada y encola el original en cuarentena — nunca filtra PII a medias. En la recuperación, cada chunk lleva un security_level jerárquico (publico < interno < confidencial; se eleva a confidencial si el chunk tuvo PII), y document.query filtra por el clearance_level del request, fail-closed a publico: sin clearance explícito, solo ves chunks públicos.

La jerarquía, con ejemplos reales:

• Operation = la pieza atómica del catálogo, pura y tipada. Ej.: text.compose_narrative, artifact.publish. Los planes se arman con éstas.
• PlanTemplate = un DAG de steps reusable. Ej.: standup-digest-v1.
• Workflow = el nombre de cara al usuario de un flujo ejecutable. Ej.: "Digest diario".
• SuperSkill = un flujo propio del workspace, promovido desde un plan que funcionó (la receta guardada del usuario). Es contra esto que matchea Nova en MATCH.
• Skill (SKILL.md) = ojo, es distinto: el formato de archivo (Agent Skills) en que se describen workflows instalables. Ej.: skills/thalx/SKILL.md.
• Agente = una persona del squad que ejecuta steps (el actor de un step).

Los tres pilares de la tesis: catálogo cerrado (los agentes solo usan operaciones registradas, no improvisan) · nada sin firma (toda capacidad nueva la aprueba un humano una vez, el build-gate) · nunca inventa (Nova responde cannot en vez de alucinar).

La inversión catálogo↔personas, el concepto detrás del roster: las personas del squad son etiquetas de identidad, no procesos con capacidad. La capacidad vive en las operations del catálogo, y Nova asigna el actor desde ahí — nunca lee el squad. El «3» de los primeros squads era un default de presentación: hoy una conversación inicial de setup (multi-turno) descubre qué trabajo necesita el usuario, y deriveSquad deriva el equipo determinísticamente de los skills elegidos («el LLM jamás decide composición de equipo»). El equipo nace del trabajo, no al revés — la inversión que ningún flujo de nodos tiene.

Dos reglas inviolables del catálogo: Regla A — el WorkspaceManifest es primitive: el agente se rehúsa a ejecutar sin manifest; se pre-computa nightly y el hot-path no hace queries inestables. Regla B — todo acceso vectorial se declara (knowledge_access.requires_vector): el runtime rechaza un vector lookup no declarado — ~70% menos queries a pgvector y auditabilidad de qué operations son caras de leer. Ambas siguen enforced hoy en el catálogo del spec.

La vista completa en un solo lugar: GET /api/workspaces/:id/traces/:trace_id con bearer. Lo ensambla la función buildTraceDetail (head + steps + artifacts + claims) — es el mismo endpoint que usa la oficina/demo. En el JSON identificás: el intent (qué se pidió), el plan (de qué PlanTemplate salió), los steps con su exec (status/timing de cada ejecución), los artifacts y claims con su provenance, y el summary.

Los 4 lugares para profundizar:

1. DB (Postgres) — step_executions, la capa 1: siempre está, una fila por step, con status/cost/error.
2. Inngest — el executor durable (execute-plan.ts); se correlaciona por traces.inngest_run_id. Dashboard en 127.0.0.1:8288.
3. Langfuse — un span por step con id determinista ${trace_id}-${stepId} + la generation LLM anidada (prompt/tokens/costo). En 127.0.0.1:3030.
4. journald — los logs del systemd agent-squad-api.service.

La cicatriz del idleTimeout y los tres anillos de verificación: Una cicatriz instructiva: el default de Bun corta toda conexión muda de más de 10s, y el modelo razona en silencio (los thinking deltas se filtran del stream) — las preguntas cortas pasaban, las «de trabajo real» morían y degradaban al camino clásico. Fix: idleTimeout: 120. El bug pasó todos los tests unit y E2E: lo cazó el anillo exterior — un manual de 34 pasos que un navegador re-ejecuta contra producción con usuario efímero y un verification.json por paso («si un paso se rompe, su sello deja de decir VERIFICADO»). Tres anillos: unit (app+motor), E2E Playwright y el manual vivo. «Si tu sistema le habla a usuarios, algo tiene que recorrerlo como un usuario.» Precisión: la suite E2E de CI corre contra un mock determinista del motor (puerto 4998), por push — el manual vivo es el único que toca producción; no hay robot nocturno. Otra cicatriz del mismo cuaderno: un runaway de ClickHouse clavó 7.7 cores durante 19 horas — hoy corre capado a 2 CPUs.