OPS Assistant - Fase de razonamiento estricto

Objetivo

Anadir razonamiento al asistente de OPS sin convertirlo en un agente autonomo peligroso. El asistente puede interpretar, proponer y preparar acciones, pero las mutaciones importantes siguen pasando por permisos, politica y confirmacion humana.

Principios

• El modelo razona; OPS decide.
• El modelo no ejecuta APIs directamente.
• Toda accion se representa como JSON estructurado antes de ejecutarse.
• El backend valida permisos, workspace, entidad, politica y estado actual.
• Las acciones sensibles requieren confirmacion explicita en UI.
• No hay fallback silencioso a otro runtime/modelo.
• No se usan Hermes ni proveedores no acordados para este asistente.
• Toda accion ejecutada queda auditada.

Flujo

1. Usuario escribe una orden en el panel.
2. Parser local detecta intenciones deterministas simples.
3. Si la orden requiere interpretacion, el frontend llama a /api/assistant/reason.
4. Backend construye un contexto minimo: usuario, workspace, vista actual, entidades mencionadas, permisos y capacidades habilitadas.
5. Runtime de razonamiento devuelve solo una propuesta JSON.
6. Policy engine valida la propuesta.
7. UI muestra preview: accion, entidad, diff, riesgos y botones.
8. Usuario confirma.
9. Backend ejecuta via endpoints internos seguros.
10. Audit log registra comando, plan aprobado, accion y resultado.

Contrato de salida del modelo

El modelo nunca devuelve texto libre para ejecutar. Debe devolver:

{

  "intent": "task.close",

  "confidence": 0.91,

  "summary": "Cerrar la tarea #701 registrando 20 minutos.",

  "actions": [

    {

      "type": "time_log.create",

      "task_id": 701,

      "minutes": 20,

      "executor": "human",

      "note": "Verificacion final"

    },

    {

      "type": "task.status.update",

      "task_id": 701,

      "status": "done"

    }

  ],

  "requires_confirmation": true,

  "risk": "medium",

  "questions": []

}

Si falta contexto, debe preguntar en vez de inventar:

{

  "intent": "clarify",

  "confidence": 0.42,

  "summary": "Falta identificar la tarea.",

  "actions": [],

  "requires_confirmation": false,

  "risk": "none",

  "questions": ["Que numero de tarea quieres cerrar?"]

}

Politicas

Acciones permitidas sin modelo, pero con confirmacion si mutan datos:

• task.open
• task.summarize
• task.create
• task.comment.create
• time_log.create
• task.status.update
• task.block
• task.unblock
• dispatch.health.read
• navigation.open

Acciones siempre bloqueadas hasta una fase posterior:

• borrar tareas, skills, perfiles, usuarios, workspaces o credenciales;
• modificar roles/permisos;
• revocar invitaciones;
• desplegar codigo;
• lanzar dispatch masivo;
• cambiar modelos/credenciales/runtimes;
• editar datos de cliente fuera del workspace activo.

Modelos y runtimes

Primera integracion recomendada:

• proveedor: MiniMax Token Plan u OpenCode Go segun disponibilidad real;
• modo: razonamiento de baja temperatura;
• salida: JSON schema estricto;
• maximo: una propuesta por turno;
• sin herramientas directas del modelo;
• sin ejecucion automatica.

Antes de activar otros modelos hay que completar la tarea pendiente de inventario de modelos OpenCode Go disponibles y pruebas de calidad/coste.

UI requerida

• Badge visible: Razonamiento: off/on.
• Panel de preview de accion antes de confirmar.
• Boton Confirmar.
• Boton Cancelar.
• Boton Abrir detalle.
• Mensaje claro si el asistente no entiende o no tiene permisos.

Backend requerido

• POST /api/assistant/reason
• POST /api/assistant/actions/:id/confirm
• tabla assistant_sessions
• tabla assistant_messages
• tabla assistant_action_proposals
• audit events: assistant.reasoned, assistant.action_confirmed, assistant.action_rejected, assistant.action_executed, assistant.action_failed

Criterios de aceptacion

• No se ejecuta ninguna mutacion sin confirmacion.
• Si el modelo devuelve JSON invalido, no pasa nada y se muestra error seguro.
• Si el usuario no tiene permisos, la accion se rechaza antes de preview.
• Si la entidad no pertenece al workspace activo, se rechaza.
• Si hay ambiguedad, el asistente pregunta.
• Las acciones sobre tareas IA mantienen los guardrails existentes de evidencia.
• Cada ejecucion deja trazabilidad en auditoria.