Tareas y contexto

Crear una tarea activa de Task Guard por sesión de agente, recuperar su contrato actual al comienzo de cada ciclo de trabajo, registrar hitos significativos, y completar o transición explícitamente.

Iniciar una tarea#

Uso POST /v1/task-guard/tasks. POST /v1/task-guard/sessions es un alias con la misma solicitud y respuesta.

Requisitos task_guard:tasks:write.

curl -X POST "https://api.maetra.io/v1/task-guard/tasks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ref": "conversation_01JY8Q",
    "title": "Ship approval flow",
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "agent_name": "release-agent",
    "host_type": "CUSTOM_API",
    "integration_mode": "ADVISORY",
    "confirmation_capable": true,
    "effect_reporting_capable": true,
    "idempotency_key": "task-start-01JY8Q"
  }'

session_ref, objective, y cualquiera idempotency_key o direct_user_event_id son necesarios. Reutilizar la misma clave del evento con una petición diferente devuelve un conflicto.

{
  "ok": true,
  "session_id": "tgs_01JY8R",
  "session_ref": "conversation_01JY8Q",
  "task": {
    "id": "tgt_01JY8S",
    "sequence": 1,
    "status": "active",
    "title": "Ship approval flow",
    "completed_at": null
  },
  "contract_version": 1,
  "anchor": {
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "decisions": [],
    "open_questions": [],
    "accepted_expansions": [],
    "anchor_hash": "sha256:…",
    "anchor_text": "…"
  },
  "host": {
    "type": "custom_api",
    "integration_mode": "advisory"
  },
  "next_action": "Call get_task_context after compaction and check_task_alignment before meaningful actions."
}

Iniciar un nuevo objetivo en una sesión existente supera la tarea activa anterior. Una revisión posterior de la tarea o del contrato requiere una direct_user_event_id. In ENFORCED mode, task transitions must use the reliable host user-event endpoint below.

Recuperar el contexto activo#

Usar el punto final:

GET /v1/task-guard/tasks/{taskId}
GET /v1/task-guard/tasks/{taskId}/context

Ambos requieren task_guard:tasks:read y devolver la tarea actual, la versión del contrato, el ancla, el modo anfitrión, y next_action.

curl "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/context" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Refresh context at the start of a new work cycle, after context compaction or restart, and every an alignment check returns CONTEXT_REFRESH_REQUIRED.

Progresos registrados#

Uso POST /v1/task-guard/tasks/{taskId}/progress después de un hito significativo.

Requisitos task_guard:tasks:write.

{
  "summary": "API route and validation are complete.",
  "completed": ["Implemented the refund approval endpoint"],
  "next_steps": ["Connect the dashboard form", "Run integration tests"],
  "new_dependencies": [],
  "open_questions": [],
  "current_step": "Implement dashboard integration",
  "idempotency_key": "progress-01JY9A"
}

La respuesta devuelve el nuevo contract_version, paso actual, identificación de tareas y siguiente acción. Compruebe cada artículo en new_dependencies con el punto final de alineación antes de actuar en él.

Pausa, reanudar o cancelar#

Estos puntos finales del ciclo de vida requieren task_guard:tasks:write y ningún órgano de solicitud:

POST /v1/task-guard/tasks/{taskId}/pause
POST /v1/task-guard/tasks/{taskId}/resume
POST /v1/task-guard/tasks/{taskId}/cancel

Pausar o cancelar revoca las subvenciones activas de alineación. Resumir devuelve la tarea a active. Cada respuesta contiene task_id, status, y updated_at.

Completar la tarea#

Uso POST /v1/task-guard/tasks/{taskId}/complete después de que se cumplan los criterios objetivos y de éxito.

Requisitos task_guard:tasks:write.

{
  "summary": "Refund approvals are implemented and verified end to end.",
  "completion_event_id": "complete-01JY9Z"
}

{
  "ok": true,
  "task_id": "tgt_01JY8S",
  "status": "completed",
  "summary": "Refund approvals are implemented and verified end to end.",
  "completed_at": "2026-07-20T13:42:18.000Z"
}

Eventos de usuarios de host con confianza#

POST /v1/task-guard/sessions/{sessionId}/user-events inicia una tarea posterior o revisa la tarea activa de una instrucción verificada de usuario directo. Acepta los mismos campos que la solicitud de inicio y además requiere direct_user_event_id.

Este punto final requiere:

task_guard:confirmations:write
una clave de API marcada como una credencial de confirmación de Task Guard confiable
a session_ref coincidiendo con la sesión de Task Guard referencia

Utilice este punto final para iniciar tareas y transiciones en ENFORCED integraciones.