Tâches et contexte

Créer une tâche Task Guard active par session d'agent, récupérer son contrat actuel au début de chaque cycle de travail, enregistrer des jalons significatifs, et terminer ou la transition explicitement.

Démarrer une tâche#

Utilisation POST /v1/task-guard/tasks. POST /v1/task-guard/sessions est un pseudonyme avec la même demande et la même réponse.

Nécessaire 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, et soit idempotency_key ou direct_user_event_id sont nécessaires. Réutiliser la même clé d'événement avec une requête différente renvoie un conflit.

{
  "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."
}

Le lancement d'un nouvel objectif dans une session existante remplace la tâche active antérieure. Une tâche ultérieure ou une révision de contrat nécessite une direct_user_event_idC'est vrai. Dans ENFORCED mode, les transitions de tâches doivent utiliser le paramètre utilisateur-événement d'hôte de confiance ci-dessous.

Récupérer le contexte actif#

Utiliser l'un ou l'autre des critères suivants :

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

Tous les deux nécessitent task_guard:tasks:read et retourne la tâche courante, version du contrat, ancre, mode hôte, et next_action.

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

Rafraîchir le contexte au début d'un nouveau cycle de travail, après compactage ou redémarrage du contexte, et chaque fois qu'une vérification d'alignement revient CONTEXT_REFRESH_REQUIRED.

Enregistrement des progrès accomplis#

Utilisation POST /v1/task-guard/tasks/{taskId}/progress après un jalon significatif.

Nécessaire 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 réponse renvoie le nouveau contract_version, l'étape actuelle, l'identification des tâches et la prochaine action. Vérifiez chaque élément dans new_dependencies avec le paramètre d'alignement avant d'agir sur celui-ci.

Pause, reprise ou annulation#

Ces paramètres du cycle de vie nécessitent task_guard:tasks:write et aucun organisme de demande:

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

L'abandon ou l'annulation des subventions d'alignement actives. Reprise retourne la tâche à activeC'est vrai. Chaque réponse contient task_id, statuset updated_at.

Terminer la tâche#

Utilisation POST /v1/task-guard/tasks/{taskId}/complete une fois l'objectif et les critères de succès satisfaits.

Nécessaire 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"
}

Événements d'utilisateurs d'hôtes de confiance#

POST /v1/task-guard/sessions/{sessionId}/user-events commence une tâche ultérieure ou révise la tâche active à partir d'une instruction d'utilisateur direct vérifiée. Il accepte les mêmes champs que la demande de démarrage et nécessite en outre direct_user_event_id.

Ce critère d'évaluation exige:

task_guard:confirmations:write
une clé API marquée comme un justificatif de confirmation Task Guard de confiance
a session_ref correspondant à la session Task Guard référencée

Utilisez ce paramètre pour les démarrages et les transitions des tâches ENFORCED les intégrations.