Permettre aux agents IA et à votre propre app de demander à une ressource de votre produit qui tourne, un appareil par exemple, d'exécuter une action que votre produit a déclarée.

Ce qu'est une intention

Une intention demande à une ressource d'un produit (un appareil, une machine, tout hôte qui tourne) d'exécuter un outil que le produit a déclaré, par exemple restart. Yayaw décide si l'appelant peut le demander, signe une autorisation valable 30 secondes, la remet à l'hôte de la ressource et renvoie sa réponse : done avec un résultat, ou refused avec une raison.

Le fonctionnement est le même pour tous les produits : le produit déclare ses outils comme des données dans son bundle, et Yayaw fournit les contrôles, la remise et l'historique.

Déclarer les outils

La section intents du bundle liste, pour chaque type de ressource, les outils que ses hôtes acceptent, l'action qu'un appelant doit détenir sur la ressource pour chacun, et les arguments que chacun prend.

"intents": {
  "kinds": [
    {
      "resource": "acme-device",
      "type": "acme-agent-intent+jwt",
      "audience": "urn:yayaw:acme:agent-intent",
      "gateFlag": "acme:agent-intents-enabled",
      "tools": [
        { "name": "restart", "action": "update" },
        { "name": "rotate_key", "action": "manage",
          "arguments": { "keyId": { "type": "string", "maxLength": 64 } } }
      ]
    }
  ]
}

type vaut <clé du produit>-agent-intent+jwt et audience urn:yayaw:<clé du produit>:agent-intent : une autorisation d'un produit n'est jamais valable pour un autre.
Les arguments forment une liste fixe et typée, comparée exactement : un hôte ne reçoit jamais un champ que son produit n'a pas déclaré.
Rien n'est émis tant que gateFlag est désactivé.

Qui peut demander

Appelant	Comment
Un agent IA (Claude, ChatGPT…)	L'outil MCP `yayaw_resource_intent_issue` avec `resource`, `resourceId`, `tool`, `arguments`.
Votre app connectée	`POST /api/resources/{resource}/{resourceId}/intents` avec sa session d'appareil comme bearer.

Les deux attendent la réponse de l'hôte et renvoient le même résultat. Chacun lit son propre historique avec yayaw_resource_intents_list : les intentions qu'il a demandées et celles adressées à une ressource qu'il héberge.

Depuis votre app

POST /api/resources/acme-device/device-1/intents
Authorization: Bearer <session d'appareil>
Content-Type: application/json

{ "tool": "restart", "arguments": {} }

{ "success": true,
  "data": { "outcome": "done", "jti": "…", "resourceId": "device-1",
            "tool": "restart", "result": { "restarted": true } } }

Un refus de l'hôte est un 200 avec "outcome": "refused", un code et un message. La requête attend jusqu'aux 30 secondes de l'autorisation : donnez à votre client un délai supérieur à 40 secondes. L'indicateur de l'hôte affiche « Signed-in app » pour ces intentions.

Ce que Yayaw vérifie

Le jeton peut écrire.
Le type de ressource a déclaré des intentions et son gateFlag est activé.
L'outil est déclaré, et l'appelant détient son action sur cette ressource via ses groupes.
Les arguments correspondent à la déclaration.
L'hôte de la ressource a enregistré sa clé, et a été vu dans les 15 dernières secondes avec cette clé.

Code	Statut	Signification
`write_scope_required`	403	Le jeton ne peut pas écrire.
`forbidden_resource`	403	Outil non déclaré, ressource inconnue ou droit manquant : une seule réponse pour les trois.
`intents_unavailable`	404	Le type n'a pas déclaré d'intentions, ou son indicateur est désactivé.
`invalid_request`	400	Le corps ou les arguments ne correspondent pas.
`resource_identity_unknown`	409	La ressource n'a pas de clé d'hôte enregistrée.
`resource_unavailable`	409	L'hôte ne tourne pas avec le contrôle par agent activé.
`intent_timeout`	504	Pas de réponse à temps : le résultat est inconnu, relisez la ressource avant de réessayer.

Côté hôte

L'hôte se connecte avec sa propre session d'appareil et :

Signale sa présence toutes les quelques secondes avec PUT /api/resources/{resource}/{resourceId}/presence et { "hostFingerprint": "<sa clé>" }, et la retire avec DELETE quand il n'accepte plus d'intentions.
Lit ses autorisations dans /api/dynamic-data/runtime-events avec le sujet resource-intent:{resource}:{resourceId}, par interrogation ou en flux. Seul le compte de l'hôte peut les lire.
Vérifie chaque autorisation : un JWT signé par l'instance (clés sur /api/auth/jwks), avec le type et l'audience de votre produit, non expiré, qui nomme sa propre clé, un outil déclaré et des arguments déclarés.
Répond une seule fois avec POST /api/resources/intents/{jti}/ack et { "outcome": "done", "result": {…} } ou { "outcome": "refused", "code": "…", "message": "…" }. La première réponse l'emporte.

Intentions