Passer au contenu principal
Quand une règle de firewall renvoie le verdict pending_approval, l’appel d’outil de l’agent est mis en attente au lieu d’être dispatché — il attend désormais un humain. Cette page est pour le relecteur : comment approuver une mise en attente d’appel d’outil d’agent (ou la rejeter) depuis la console, ce que la file vous montre, et comment OrcaRouter empêche deux relecteurs de se télescoper sur la même décision. C’est la moitié résolution du human-in-the-loop. Pour pourquoi un appel est mis en attente et comment l’agent mis en attente re-soumet ensuite, voir verdicts et la référence des approbations plus approfondie. Pour résoudre depuis votre propre système plutôt que la console, voir webhooks d’approbation.

​
1. Le cycle de vie d’un appel mis en attente, du siège d’un relecteur

Un appel mis en attente est une courte boucle hors-bande. Votre travail est l’étape du milieu :
1

L'appel est mis en attente

Une règle se résout en pending_approval. Le relais renvoie HTTP 400 avec le code firewall_approval_pending et un id d’approbation ; l’appel n’atteint jamais l’outil. L’agent commence à interroger sur cet id.
2

Vous le résolvez

Vous ouvrez la file Approvals, lisez pourquoi l’appel a été mis en attente, et l’approuvez ou le rejetez — le sujet de cette page.
3

L'agent procède (ou s'arrête)

Sur approbation, l’agent re-soumet l’appel d’origine avec un en-tête X-OrcaRouter-Firewall-Approval à usage unique et la passerelle le laisse passer cette unique fois. Sur rejet, l’appel reste bloqué.
Résoudre une mise en attente est filtré à Developer+ — la même porte que le flux Events du firewall. Les rôles inférieurs peuvent lire la politique firewall, les réglages et les outils découverts, mais seuls les rôles Developer-et-au-dessus peuvent lister la file d’approbations ou approuver/rejeter un appel d’outil mis en attente. Voir rôles et portée.

​
2. Lister la file pending

L’onglet Approvals lit GET /api/workspace/firewall/approvals. Sans filtre, il renvoie la file pending, de la plus ancienne à la plus récente — de sorte que l’appel qui attend le plus longtemps est en haut et que vous traitez le backlog dans l’ordre. 
GET /api/workspace/firewall/approvals?state=pending
state est le seul filtre qui compte. Les valeurs mappent au cycle de vie de l’approbation :
stateApprobations renvoyées
pending (défaut)En attente d’une décision — votre file de travail.
approvedDéjà laissées passer.
rejectedDéjà bloquées.
C’est une route de console sur votre session — configurez-la et relisez-la depuis le dashboard, pas avec une clé de relais sk-orca-…. Les clés de relais sont pour les appels de modèle /v1/* ; la gestion du firewall s’exécute sous votre login console.

​
3. Lire pourquoi l’appel a été mis en attente

Chaque ligne porte les entrées de décision dont un relecteur a besoin — le nom de l’outil (tool_name), une empreinte des arguments (args_hash, le SHA-256 des arguments canonicalisés de l’appel — les valeurs brutes des arguments ne sont pas stockées dans l’approbation), l’id de requête, et une ligne de provenance en clair qui nomme la politique, la règle et la clause qui s’est déclenchée :
La politique nommée à laquelle appartient la règle correspondante, résolue à portée d’espace de travail de sorte qu’un id périmé ne peut jamais faire remonter le nom de politique d’un autre tenant.
Le label de la règle et un descripteur « pourquoi » d’une ligne — par ex. command contains rm -rf, ou tool matches "http_fetch" pour une règle uniquement glob. Cela rend la ligne « Held because… » dans la file.
true quand la règle correspondante a été éditée au moment de ou après la création de cette approbation. Le label et la clause en live sont alors supprimés (ils peuvent ne plus refléter ce qui a réellement mis l’appel en attente), et la file montre une note « règle modifiée depuis » au lieu d’une provenance périmée. Le nom de l’outil et les arguments — les vraies entrées de décision — sont toujours montrés.
rule_changed est un signal d’honnêteté délibéré, pas une erreur. Si quelqu’un édite la règle de firewall pendant qu’un appel attend dans la file, OrcaRouter préfère cacher une raison possiblement erronée que de vous montrer une provenance qui ne correspond plus. Décidez sur le nom de l’outil et le nom de la politique (toujours montrés) dans ce cas.

​
4. Approuver ou rejeter

Résoudre envoie PATCH /api/workspace/firewall/approvals/:id avec une decision de approved ou rejected et un reason optionnel. La console fait cela pour vous quand vous cliquez le bouton ; la forme est : 
PATCH /api/workspace/firewall/approvals/507f1f77bcf86cd799439011
Content-Type: application/json

{ "decision": "approved", "reason": "verified target host with the on-call" }
  • approved → l’appel mis en attente peut procéder. La prochaine re-soumission de l’agent, portant l’en-tête d’approbation à usage unique, est laissée passer une fois.
  • rejected → l’appel reste bloqué. L’agent voit le rejet et peut choisir un autre chemin, demander à l’utilisateur, ou s’arrêter.
decision est validé contre l’ensemble fermé {approved, rejected} — tout autre est rejeté. Le reason est enregistré avec la décision et écrit dans le journal d’audit du firewall aux côtés de l’acteur, du nom de l’outil et de l’id de requête.
Chaque résolution écrit une ligne d’audit d’espace de travail nommant qui a décidé, la décision et la raison. Les résolutions de console enregistrent l’acteur humain ; les résolutions par webhook enregistrent un acteur système. La provenance de résolution n’est jamais silencieusement abandonnée.

​
5. First-writer-wins : pas de double résolution

Une approbation pending peut faire l’objet d’une course — deux relecteurs dans la console, ou un clic de console et un callback webhook arrivant ensemble. OrcaRouter résout cela avec une seule règle first-writer-wins :
  • La décision est une mise à jour conditionnelle atomique qui ne se déclenche que tant que l’approbation est encore pending. Le premier écrivain gagne et applique la décision.
  • Tout écrivain ultérieur observe « déjà résolue » et est traité comme un no-op idempotent — il reçoit HTTP 200 avec le document déjà résolu, pas une erreur.
La réponse vous indique de quel côté vous étiez : 
{
  "resolved": false,
  "already_resolved": true,
  "approval": { "state": "approved", "decision": "approved", "...": "..." }
}
resolved: true signifie que votre appel a appliqué la décision ; already_resolved: true signifie que quelqu’un (ou un webhook) y est arrivé en premier et que vous voyez son résultat. Dans les deux cas, la file se réconcilie en un seul état cohérent.
Parce que la résolution est idempotente, un réseau instable ou un double-clic ne peut pas corrompre une mise en attente ni inverser une décision. Le premier approuver/rejeter est le seul qui compte ; tout ce qui vient après ne fait que relire le résultat.

​
6. Un passage concret dans la file

Un espace de travail en autonomie balanced met en attente l’appel shell.exec d’un agent parce qu’une règle a correspondu à command contains rm -rf. En tant que relecteur, vous :
  1. Ouvrez Approvals — le shell.exec mis en attente est en haut de la liste pending de la plus ancienne à la plus récente.
  2. Lisez la ligne : outil shell.exec, l’empreinte args_hash, l’id de requête, et la ligne « Held because… command contains rm -rf » (rendue à partir de la clause de la règle correspondante). Aucun flag rule_changed, donc la provenance est à jour.
  3. La cible est un répertoire scratch, donc vous approuvez avec une raison.
  4. Votre PATCH renvoie resolved: true ; la prochaine interrogation de l’agent voit approved, re-soumet avec son en-tête à usage unique, et la commande s’exécute exactement une fois.
Si un coéquipier l’avait approuvée une seconde plus tôt, votre clic aurait renvoyé already_resolved: true avec sa décision — aucun dommage, aucune double exécution.

​
Où aller ensuite

Référence des approbations

La boucle HITL complète : mise en attente, interrogation, re-soumission, et l’en-tête à usage unique.

Webhooks d'approbation

Résoudre les mises en attente depuis votre propre système avec un callback signé HMAC.

Verdicts

Où pending_approval se situe parmi les six verdicts firewall.

Journal d'événements

Confirmer le résultat aval d’un appel résolu dans le flux.
Pour les risques que ces mises en attente sont censées attraper, voir appels d’outils dangereux et agence excessive.