ComandeskHelp Inicio

Plan: Contrato De Ejecucion Para Agentes

Fecha de referencia: 2026-05-06.

Este documento fija la situacion actual y el plan para convertir las instrucciones de agentes en una pieza robusta, configurable y escalable de OPS.

Situacion De Partida

OPS coordina tareas que pueden ejecutarse de dos formas:

  • Por dispatcher automatico en VPS o workers externos.
  • Reclamadas desde una aplicacion de escritorio, donde el operador ya tiene sesion, credenciales, repos y contexto local.

El dispatcher ya consume task.description al construir el prompt de ejecucion. Por eso se ha anadido una primera capa segura: un bloque Markdown Instrucciones para agente que puede insertarse desde la UI al crear o editar una tarea.

Esta primera capa es intencionadamente conservadora:

  • no cambia base de datos;
  • no cambia estados;
  • no toca la cola ni el drag/drop;
  • no modifica la seleccion de runtimes;
  • no fuerza ningun proveedor, modelo o agente;
  • no rompe tareas existentes.

Que Queremos Conseguir

OPS necesita un contrato de ejecucion que permita que cualquier agente entienda:

  • que debe hacer;
  • con que agente/modelo/perfil debe intentarlo primero;
  • que contexto local o remoto debe usar;
  • que entregable se espera;
  • donde debe registrar resultado, evidencia y tiempo;
  • que hacer si se bloquea;
  • cuando debe pedir validacion humana.

El objetivo es que una tarea reclamada desde escritorio y una tarea ejecutada por dispatcher produzcan la misma trazabilidad y respeten el mismo contrato de salida.

Estado De Implementacion

Estado actual:

  • Fase 1 completada: convencion Markdown Instrucciones para agente.
  • Fase 2 completada: campo estructurado execution_contract en tareas y plantillas.
  • Fase 3 iniciada: contrato efectivo mezcla workspace, profile, template y task.
  • Fase 4 iniciada: preflight opcional cuando preflight_required=true.
  • Fase 5 pendiente: snapshots/versionado completo por intento de ejecucion.

Lo Implementado En Fase 1

La UI permite insertar + Instrucciones agente:

  • al crear tarea;
  • al editar la descripcion de una tarea existente;
  • como tipo de entrada de contexto agent_instructions.

El bloque queda en task.description, que ya es leido por el dispatcher y tambien es visible para agentes/operadores desde escritorio.

Esto sigue siendo una base de compatibilidad util: mejora el flujo sin obligar a migrar tareas existentes.

Por Que No Debe Quedarse Ahi

Guardar el contrato como Markdown en la descripcion tiene limites:

  • mezcla descripcion humana y contrato tecnico;
  • no permite validar campos obligatorios facilmente;
  • no versiona cambios del contrato;
  • no permite herencia limpia desde workspace, perfil o plantilla;
  • dificulta detectar automaticamente si falta modelo, agente, credencial o criterio de terminado.

Por tanto, esta fase debe verse como compatibilidad inicial, no como modelo definitivo de datos.

Arquitectura Objetivo

OPS ya tiene una entidad estructurada inicial:

  • tasks.execution_contract
  • task_templates.execution_contract

Ambos campos son JSONB y deben ser objetos. A futuro se puede extraer a tabla versionada si hace falta auditoria avanzada.

Campos minimos recomendados:

  • preferred_agent_slug
  • preferred_model
  • profile_id
  • execution_mode
  • workspace_context
  • project_path
  • working_folder
  • depends_on
  • deliverables
  • verify_commands
  • repo_paths
  • docs_paths
  • required_credentials
  • acceptance_criteria
  • required_outputs
  • completion_checklist
  • blocked_fallback
  • human_gate_policy
  • time_logging_policy
  • documentation_policy

El contrato efectivo se hereda y sobrescribe en este orden:

  1. Workspace.
  2. Perfil/subagente.
  3. Plantilla.
  4. Tarea.
  5. Comentario/contexto de desbloqueo (pendiente de automatizar).

La tarea siempre debe mostrar el contrato efectivo resultante antes de dispatch o reclamo manual.

Plan De Trabajo

Fase 1: Convencion Segura

Estado: iniciada.

Objetivo:

  • usar bloque Markdown Instrucciones para agente;
  • documentar flujo hibrido escritorio/dispatcher;
  • no cambiar dispatcher ni base de datos.

Criterio de cierre:

  • UI inserta bloque sin duplicarlo;
  • docs explican cuando usar dispatcher y cuando escritorio;
  • agentes entienden donde registrar comentario, evidencia y tiempo.

Fase 2: Contrato Estructurado

Estado: completada en su primera version.

Objetivo:

  • anadir campo o tabla de contrato de ejecucion;
  • exponerlo en API;
  • renderizarlo separado de la descripcion;
  • mantener compatibilidad leyendo el bloque Markdown antiguo.

Trabajo tecnico:

  • migracion DB;
  • endpoints GET/PATCH para contrato;
  • UI dedicada en detalle de tarea;
  • parser/importador opcional desde Markdown fase 1.

Criterio de cierre:

  • una tarea puede tener descripcion limpia y contrato estructurado;
  • el dispatcher recibe el contrato estructurado;
  • el agente de escritorio ve el mismo contrato en UI.

Fase 3: Plantillas Y Herencia

Estado: iniciada.

Objetivo:

  • definir contratos por workspace, perfil y plantilla;
  • calcular contrato efectivo por tarea;
  • permitir overrides controlados.

Trabajo tecnico:

  • contrato default por workspace;
  • metadata/contrato por profile;
  • contrato por task_template;
  • vista contexto efectivo de ejecucion ampliada.

Criterio de cierre:

  • las tareas recurrentes nacen ya con contrato completo;
  • no hay que copiar manualmente instrucciones repetidas;
  • el contrato efectivo muestra origen de cada campo.

Fase 4: Preflight Y Bloqueos

Estado: iniciada.

Objetivo:

  • impedir dispatch/reclamo automatico cuando falten datos criticos;
  • convertir errores conceptuales en bloqueos accionables.

Checks minimos:

  • agente seleccionado o resoluble;
  • modelo indicado o heredado;
  • credencial compatible disponible si aplica;
  • repo/docs/target definidos si son necesarios;
  • criterio de terminado presente;
  • gate humano pendiente si la tarea es sensible.

Criterio de cierre:

  • Dispatch now avisa con motivos concretos;
  • tareas incompletas quedan waiting/blocked con pregunta concreta;
  • no se producen ejecuciones ambiguas.

Implementacion actual:

  • El preflight solo bloquea si el contrato efectivo contiene preflight_required=true, require_preflight=true o required=true.
  • Si no se activa esa bandera, el contrato informa pero no rompe tareas existentes.

Fase 5: Auditoria Y Versionado

Objetivo:

  • registrar cambios del contrato;
  • saber con que instrucciones exactas se ejecuto cada intento.

Trabajo tecnico:

  • snapshot de contrato al hacer dispatch/claim;
  • historial de cambios;
  • diff visible;
  • auditoria de fallback agente/modelo.

Criterio de cierre:

  • cada ejecucion puede reconstruirse: tarea, contrato, agente, modelo, credenciales inyectadas, output y tiempo.

Principios Que No Deben Romperse

  • Maxima flexibilidad: OPS no debe hardcodear una lista cerrada de agentes/modelos/proveedores.
  • Control explicito: ningun fallback silencioso a otro agente o modelo.
  • Compatibilidad: no romper tareas existentes ni automatismos ya operativos.
  • Multitenant: todo contrato operativo debe tener alcance de workspace.
  • Trazabilidad: toda ejecucion deja comentario, evidencia y tiempo.
  • Escalabilidad: los agentes pueden correr en VPS, workers externos o escritorios registrados.

Decision Operativa Actual

Hasta que exista el contrato estructurado, usar el bloque Instrucciones para agente como contrato transitorio.

Si una tarea requiere credenciales/sesion local, reclamar desde escritorio es valido. Si es repetible, estable y tiene credenciales configuradas en OPS, preferir dispatcher.

En ambos casos, la tarea no debe cerrarse sin:

  • comentario final;
  • evidencia visible;
  • tiempo registrado;
  • estado correcto;
  • documentacion actualizada si cambio el sistema o el flujo.