​

El underlayer: AgentManifest v2 + mapa de migración

​

1. Lo que ya existe y se conserva (no partimos de cero)

​

2. Huecos de la v1 (por qué se evoluciona)

1. Es código, no datos — contextProviders/tools/actions son objetos con funciones. Un Worker declarado desde el chat necesita que el manifiesto sea serializable y que las funciones se resuelvan por NOMBRE contra registros.
2. Sin identidad de ledger (actor, acts-as) — el Steward hoy resuelve identidad a mano (owner del workspace); debe ser campo.
3. Sin cognición declarada — el Steward es determinista (cero LLM). Un manifiesto no debe presuponer modelo.
4. Sin budget, autonomía, envelope ni escalamiento — los campos que hacen a la autonomía legible, acotada y reversible (Art. VIII).
5. Sin criterion — el juicio versionado que se entrega pre-run (y que la ronda 1 ya sabe registrar como delivery).
6. Registry en memoria — los Workers de usuario viven en DB con gobernanza, no en un array de código.
7. Sin clase de cola — la disciplina distingue clase-agente (sandbox, watchdog 15/25min) de clase-batch (determinista acotado, estilo Steward).

​

3. El contrato: AgentManifest v2

interface AgentManifestV2 {
  // ── identidad ──────────────────────────────────────────────────────────────
  name: string                      // 'auditor' | 'librarian' | 'steward' | 'chat' | '<worker-slug>'
  version: number                   // el manifiesto es objeto versionado y gobernado
  system: boolean                   // true = agente de plataforma (seed); false = Worker declarado
  identity: {
    actor: `agent:${string}`        // sello en ledger/audit/record_events
    acts_as: 'workspace_owner' | 'key_creator' | 'none'   // resolución de credencial/visibilidad
  }

  // ── cuándo corre ───────────────────────────────────────────────────────────
  triggers: Trigger[]               // evolución de TriggerKind v1:
  // { kind:'schedule', cadence_setting?: string }        // cron con cadencia configurable (Steward)
  // { kind:'pull_request' | 'push' }                     // fuente github (Auditor)
  // { kind:'integration_event', source?: string }        // sync de Nango, etc. (Steward adelanta)
  // { kind:'drift_event' }                               // cola de drift tipada (WS4.2)
  // { kind:'human_message' }                             // Chat — deja de ser especial
  // { kind:'manual' }

  // ── con qué piensa ─────────────────────────────────────────────────────────
  cognition: 'llm' | 'deterministic'    // Steward: deterministic (sin modelo, sin skill)
  model?: { funding: 'byom' | 'driftless'; selection?: string }   // vía gateway, jamás key directa
  skill?: string                    // nombre en el registro de Skills (v1 Skill intacta)
  context_providers: string[]       // nombres en el registro (qué fragmentos de grafo recibe)
  criterion: string[]               // slugs de topics — el juicio; se entrega versionado (delivery)

  // ── qué puede tocar ────────────────────────────────────────────────────────
  tools: string[]                   // ToolSets nombrados: 'code.investigate', 'graph.read',
                                    // 'graph.curate', 'surface.read', 'broker.read',
                                    // 'broker.invoke:gmail', 'web.search', 'web.browse'
                                    // — TODOS resueltos por el único policy engine + observador T3
  surface?: { collections?: string[]; repos?: boolean }   // sustrato operacional que trabaja
  envelope?: Record<string, string[]>   // stage → operaciones permitidas (Playbook).
                                        // OBLIGATORIO si tools incluye broker.invoke:* y system=false
  actions: string[]                 // superficie cerrada v1 por nombre: 'createProposal',
                                    // 'postPRComment', 'createDraftTopic', 'writeEvidence',
                                    // 'updateRecord', 'shareNote' — cómo aterriza output

  // ── cuánto y con qué libertad ──────────────────────────────────────────────
  budget: { wallclock_soft_min: number; wallclock_hard_min: number;
            tokens?: number; invokes?: number; steps?: number }
  autonomy: Record<string, 'observe' | 'propose' | 'auto_reversible'>
            // por CLASE DE ACCIÓN; default 'propose'; 'auto_reversible' exige undo
            // (autovouch del Librarian es el precedente). Promoción/demotion = WS5,
            // alimentada por el dossier (evidence) de la ronda 1
  escalation: { on: string[]; to: 'review_queue' | 'note' }   // la salida legítima de no-acción

  // ── dónde corre ────────────────────────────────────────────────────────────
  runtime: {
    isolation: 'none' | 'sandbox'       // Daytona solo si toca código
    queue_class: 'agent' | 'batch'      // agent = watchdog 15/25min; batch = clase
                                        // webhook-processing (Steward) — misma cola,
                                        // mismos singletons, budget distinto
    interactive?: boolean               // Chat: streaming + suspend/resume (Mastra)
  }
}

​

4. La prueba del contrato: los cuatro agentes sin pérdida

​

5. Decisiones de diseño

1. El manifiesto es datos; las capacidades son registros de código. El chat/ CLI/MCP componen jsonb; ToolSets/Skills/ContextProviders se resuelven por nombre. Añadir una capability nueva sí es código (revisado); añadir un agente jamás.
2. Un solo loop bajo el seam existente. AgentRuntime ya es la abstracción; la migración consolida agentic-loop + ThinLoopRuntime en una impl (y MastraRuntime entra por el mismo seam según su contrato de adopción). Se preserva el invariante del trace (mismo objeto a onStep y al store).
3. Un solo camino de tools. Los ToolSets nombrados componen las tools canónicas (surface-tools E2 + investigation + graph + broker) SIEMPRE a través del policy engine y el observador T3. Mueren las tres composiciones bespoke.
4. Un dispatcher. Tabla de triggers derivada de los manifiestos aprobados → agentsForTrigger (la firma v1, ahora sobre DB) → enqueue. La disciplina de cola no cambia: singletonKey por (agente, workspace), budget único, drops ruidosos. agent-schedule.service se vuelve el dispatcher genérico.
5. Dos clases de cola, un runtime. La distinción que el Steward estrenó (clase webhook-processing) se legitima DENTRO del runtime (queue_class), no como excusa para otro servicio bespoke.
6. El ledger de la ronda 1 es la salida del runtime. El loader de criterion escribe context_deliveries (source nuevos: collection_criterion / connection_criterion); el contexto del run inyecta run_id en cada invoke y cada record_event automáticamente — lo que en la ronda 1 se pasa a mano, el runtime lo estampa solo. El dossier (evidence) se vuelve el insumo del campo autonomy (WS5).
7. IntegrationManifest v1 se conserva como está (inbound→TriggerEvent, outbound→Actions) — es la otra mitad del bus y no estorba; se materializa cuando un caso real lo pida (no en esta migración).

​

6. Mapa de migración

​

Fase 0 — Contratos sin cambio de comportamiento

• Materializar AgentManifestV2 + tabla agent_manifests + seed de los 4 (system:true, describiendo la realidad ACTUAL de cada uno).
• Los runners existentes LEEN su config del manifiesto (triggers, budget, tools nombrados) pero conservan su ejecución bespoke.
• Registros nombrados de ToolSets/Skills/ContextProviders envolviendo lo que ya existe (cero lógica nueva).
• Gate: comportamiento byte-idéntico (evals de loop existentes verdes); los manifiestos sembrados describen fielmente cada agente (revisión humana).
• Rollback: trivial — los runners ignoran el manifiesto.

​

Fase 1 — Un loop; primer inquilino: Librarian

• Consolidar la ejecución bajo el seam AgentRuntime (ThinLoop como impl canónica; decisión Mastra-vs-ThinLoop se toma AQUÍ con el spike del contrato de adopción — es intercambiable por diseño del seam).
• Migrar Librarian (el más simple: sin sandbox, tools de grafo, safe-lane con undo ya probada): su service se reduce a run(manifest, trigger).
• Gate: mismo output en corpus golden; autovouch conserva undo; approval rate del Librarian no cae.
• Rollback: el service bespoke sigue en el árbol una release; flag por workspace.

​

Fase 2 — Steward y Auditor

• Steward: prueba cognition:'deterministic' + queue_class:'batch' dentro del runtime (sin modelo, sin skill — el loop degenera a pipeline determinista). Su lógica pura (digest, cadencia, notas) ya son funciones con tests: se re-usa intacta; solo muere el cableado. Aquí se paga la ironía de haberlo construido bespoke — y se paga barato precisamente porque su lógica quedó pura.
• Auditor (el más difícil): sandbox Daytona + BYOM + land loop + comment. El punto de enchufe del refuter (plan SOTA WS3) queda como paso del runtime, no del runner.
• Gate por agente: pass^k en corpus sembrado ≥ baseline; approval rate sostenido; cero dobles-runs (singleton respetado).
• Rollback: igual que F1, por agente.

​

Fase 3 — Chat entra al registro

• Trigger human_message, interactive:true (streaming + suspend/resume — si Mastra ganó en F1, sus approvals mecánicos entran aquí). El turno del chat se vuelve run(manifest,…) con stream.
• Gate: paridad de latencia p95 y de citations; los threads no pierden invariantes (topic chat-turn-lifecycle-invariants).

​

Fase 4 — Muerte de los silos + candado mecánico

• Borrar los runners bespoke.
• El candado se vuelve CI: un guard de arquitectura (patrón architecture.spec.ts) que falla si aparece un *RunnerService nuevo fuera del runtime, o un dispatch que no pase por agentsForTrigger. El invariante de worker-manifest-northstar deja de depender de la memoria de nadie.

​

Fase 5 — Worker v1 interno (dogfooding)

• El agente de campaña de outbound como primer manifiesto system:false (redactado a mano, aprobado por owner) — el primer inquilino de negocio.
• Corre semanas fabricando evidencia en el ledger. La declaración conversacional (el “compilador” del chat) se construye DESPUÉS de que esto demuestre que un manifiesto acotado no puede hacer daño fuera de su envelope.
• Gate de apertura a usuarios: invariante 3 del north star — dogfooding primero, apertura después.

​

Dónde enchufa la branch de la ronda 1

​

7. Riesgos nombrados

1. Mastra: que su estado no respete “sin semántica de producto” — el contrato de adopción ya define blockers/rollback; la decisión se toma en F1 con spike, no por fe.
2. Chat streaming: la paridad interactiva es el gate más frágil (F3 va al final a propósito).
3. Sandbox lifecycle dentro del loop consolidado (Auditor): el warm-pool y los 3 sitios de daytona.create (gotcha conocida) se unifican en F2.
4. Scope creep del manifiesto: la tentación de añadir campos “por si acaso”. Regla: un campo entra solo si uno de los 5 casos de prueba lo exige.

​

8. Qué NO decide este documento

• Mastra vs ThinLoop como impl definitiva (se decide en F1 con el spike y los gates del contrato de adopción — el seam hace la decisión reversible).
• El schema del “compilador” conversacional (F5+; depende de aprender del primer Worker manual).
• Multi-workspace / marketplace de manifiestos (parked bets; señales propias).