Migrer un client ACP vers CLI V3

Si vous maintenez un module d'extension pour un éditeur, une extension d'IDE ou un autre client ACP qui lance kiro-cli acp, ce guide présente les changements requis pour passer du serveur ACP CLI v2 à CLI V3 : comment lancer le nouveau serveur, comment fonctionne la négociation des capacités et quelles API v2 ont été remplacées ou supprimées.

Conservez des adaptateurs CLI v2 et CLI V3 distincts tant que vous prenez en charge les deux générations de serveurs. La version du protocole ACP n'identifie pas la génération du serveur, car les deux négocient la version 1.

Configurez votre client pour démarrer CLI V3 explicitement :

/full/path/to/kiro-cli acp --agent-engine=v3 --auth-method=cli

CLI V3 utilise JSON-RPC 2.0 délimité par des sauts de ligne sur l'entrée standard et la sortie standard. Chaque objet JSON occupe une ligne.

--auth-method=cli conserve la gestion des jetons d'accès dans le processus Kiro CLI. Si vous l'omettez, votre client doit implémenter la requête agent-vers-client _kiro/auth/getAccessToken et protéger les valeurs des jetons contre les journaux et les diagnostics. Privilégiez la gestion de l'authentification par CLI, sauf si votre client gère déjà l'authentification Kiro.

Retirez les indicateurs réservés à CLI v2 de la commande de lancement V3 :

• --agent
• --model
• --effort
• --trust-all-tools
• --trust-tools

CLI V3 rejette ces indicateurs sur la commande acp. Sélectionnez le mode agent, le modèle et l'effort après l'initialisation. Enregistrez durablement le consentement aux outils au moyen du flux de permissions CLI V3.

Appelez initialize, puis utilisez les capacités retournées pour décider quels comportements UI et protocole activer. N'inférez pas la prise en charge à partir d'une version de Kiro CLI ou d'une liste de méthodes codée en dur.

CLI V3 peut annoncer ces méthodes standard :

CLI V3 n'implémente pas session/set_model. Changez le modèle via l'option de configuration model annoncée :

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "session-1",
    "configId": "model",
    "value": "claude-sonnet"
  }
}

Utilisez configId: "effortLevel" pour l'effort. Changez le mode avec session/set_mode ou une option de configuration mode annoncée.

Lisez les méthodes de requête Kiro optionnelles depuis agentCapabilities._meta.kiro.extensionMethods. Lisez également les sources de session annoncées, les portées de liste, les cibles d'exécution, le marquage de relecture et la configuration de journalisation lorsque votre client les utilise.

L'annonce du serveur en cours d'exécution fait autorité. Différents déploiements peuvent retourner des tableaux différents. Conditionnez chaque requête optionnelle à la liste de méthodes annoncée, ignorez les champs inconnus et préservez les données _meta inconnues lors des relais et de la relecture.

Enregistrez tous les gestionnaires agent-vers-client requis avant de créer ou de charger une session :

• session/update : requis pour tous les clients; enregistrez-le avant de créer ou de charger une session, car les mises à jour en direct ne sont pas mises en mémoire tampon pour les futurs abonnés (la relecture fournit l'historique antérieur, pas les événements en direct manqués)
• session/request_permission : requis si le client présente des approbations d'outils
• _kiro/auth/getAccessToken : requis lorsque le serveur n'a pas été démarré avec --auth-method=cli

CLI V3 accepte cwd, mcpServers et les additionalDirectories standard de niveau supérieur sur session/new et session/load. Les clients compatibles Kiro peuvent également envoyer des valeurs initiales telles que modeId, modelId et effortLevel sous _meta.kiro.

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "session/new",
  "params": {
    "cwd": "/workspace/project",
    "additionalDirectories": ["/workspace/shared"],
    "mcpServers": [],
    "_meta": {
      "kiro": {
        "modeId": "vibe",
        "modelId": "claude-sonnet",
        "effortLevel": "high"
      }
    }
  }
}

Lisez les modes retournés et les options de configuration au lieu de coder les choix en dur.

Les définitions de serveurs MCP fournies par le client sont des entrées de session. CLI V3 ne persiste pas ces définitions dans session.json, donc renvoyez-les lors de session/load. Envoyez également le cwd actuel et les répertoires supplémentaires.

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "session/load",
  "params": {
    "sessionId": "session-1",
    "cwd": "/workspace/project",
    "additionalDirectories": ["/workspace/shared"],
    "mcpServers": []
  }
}

Conservez l'ID de session demandé dans l'état client. Ne comptez pas sur la réponse de chargement pour le répéter.

N'écrivez pas directement les fichiers de session Kiro et ne dépendez pas de la structure de répertoires CLI V3. Les sessions locales et distantes ne partagent pas un modèle de système de fichiers lisible par le client.

Utilisez session/list pour découvrir les sessions et session/load pour les restaurer. Pour le transfert de fichiers ou l'historique plus ancien, utilisez une méthode d'export ou d'historique annoncée. Ne passez pas de chemin d'archive à session/load. Un analyseur de fichiers CLI v2 en lecture seule peut rester dans l'adaptateur v2 tant que vous prenez en charge cette génération.

CLI V3 émet des mises à jour avec les discriminateurs snake_case existants et d'autres types de mises à jour standard. Les valeurs suivantes identifient les mises à jour dans le champ sessionUpdate d'une notification session/update.

Associez les mises à jour et les requêtes de permission à l'appel d'origine avec toolCallId, et non avec le nom de l'outil. Acheminez chaque notification par sessionId et traitez les mises à jour de chaque session dans l'ordre d'arrivée. Les types de mises à jour et les champs de métadonnées inconnus ne doivent pas faire échouer la session.

Lorsque les métadonnées d'identité stable sont absentes, affichez le kind et le title standard. Ne déduisez jamais l'identité d'un outil intégré à partir d'un titre lisible par l'humain, et n'utilisez jamais les métadonnées d'identité affichées pour autoriser une action.

Considérez une requête session/prompt en attente comme terminée uniquement lorsqu'elle renvoie une réponse ou une erreur. Ne considérez pas session_info_update avec _meta.kiro.kind: "turn_end" comme la fin de la requête. CLI V3 peut l'émettre, puis poursuivre le traitement avant le retour de la requête, et n'émet pas de discriminateur de mise à jour TurnEnd.

Si le transport est interrompu avant l'arrivée de la réponse, reconnectez-vous et enregistrez le gestionnaire session/update avant d'appeler session/load. Les mises à jour rejouées arrivent pendant le chargement; l'enregistrement après celui-ci peut donc les manquer. Ne renvoyez pas automatiquement la requête. Même si la relecture indique que le tour précédent est terminé, un nouvel envoi peut répéter ses modifications, et l'historique chargé ne peut pas récupérer la réponse perdue.

Une mise à jour rejouée d'une session locale peut porter _meta.kiro.replay: true dans la charge utile de mise à jour :

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "session-1",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": { "type": "text", "text": "Previously streamed response" },
      "_meta": { "kiro": { "replay": true } }
    }
  }
}

La relecture distante n'est pas garantie de marquer chaque mise à jour rejouée. Enregistrez le gestionnaire de mises à jour avant d'appeler session/load, car les mises à jour en direct ne sont pas conservées pour les futurs abonnés. Reconstruisez l'état après une reconnexion ou une perte de livraison suspectée.

Pour les sessions locales, traitez noReplay: true comme une suppression de la transcription, et non comme une suppression des mises à jour d'état actuel. Les chargements distants omettent également la connexion au flux de mises à jour en direct; n'utilisez donc pas noReplay pour une session distante si votre client a besoin des mises à jour suivantes.

session/request_permission reste une requête agent-vers-client. Traitez la liste options[] standard comme faisant autorité et affichez uniquement les choix fournis par l'agent.

Une requête CLI V3 peut ajouter un contexte de consentement sous _meta.kiro.consent :

{
  "method": "session/request_permission",
  "params": {
    "sessionId": "session-1",
    "toolCall": {
      "toolCallId": "call-1",
      "title": "Run tests",
      "status": "pending"
    },
    "options": [
      { "optionId": "accept", "name": "Allow", "kind": "allow_once" },
      { "optionId": "always-accept", "name": "Always allow", "kind": "allow_always" },
      { "optionId": "reject", "name": "Deny", "kind": "reject_once" },
      { "optionId": "always-reject", "name": "Always deny", "kind": "reject_always" }
    ],
    "_meta": {
      "kiro": {
        "consent": {
          "capability": "shell",
          "resource": "npm run test",
          "triggeringResource": "npm run test",
          "workspaceRoot": "/workspace/project",
          "persistableConsent": true
        }
      }
    }
  }
}

Ne synthétisez jamais une option que l'agent a omise. Retournez une option ponctuelle immédiatement. Pour une option persistante offerte, un client compatible Kiro peut recueillir à la fois un motif de ressource et une portée de persistance, puis retourner l'optionId original avec des métadonnées de consentement canoniques :

{
  "outcome": {
    "outcome": "selected",
    "optionId": "always-accept"
  },
  "_meta": {
    "kiro": {
      "consent": {
        "scope": "workspace",
        "resource": "npm run *",
        "workspaceRoot": "/workspace/project"
      }
    }
  }
}

CLI V3 valide la réponse, persiste une règle valide, reconstruit la politique et réévalue l'invocation initiale. Une opération multi-ressources peut émettre une autre requête de permission pour la prochaine ressource non couverte.

Pour le texte saisi pendant qu'une permission est en attente, choisissez un comportement explicite :

• Pour accompagner le choix de permission, mettez le texte en file d'attente comme guidage avant de retourner la disposition sélectionnée.
• Pour remplacer le tour bloqué, annulez les permissions en attente, envoyez session/cancel, attendez que la réponse session/prompt originale se résolve, puis envoyez un nouveau session/prompt. N'attendez pas de discriminateur de mise à jour TurnEnd.

Gardez un refus simple distinct d'une interruption qui porte une nouvelle instruction.

CLI V3 peut inclure une enveloppe _meta.kiro.mcpTool versionnée avec l'identité du serveur et de l'outil résolue par l'hôte, plus des indications optionnelles de comportement MCP. Lisez la version 1 lorsqu'elle est présente, et revenez aux champs plats mcpToolIdentity et mcpAnnotations CLI v2 uniquement pendant la prise en charge du serveur hérité.

{
  "method": "session/request_permission",
  "params": {
    "sessionId": "session-1",
    "toolCall": {
      "toolCallId": "call-2",
      "title": "@example-server/search",
      "status": "pending"
    },
    "options": [
      { "optionId": "accept", "name": "Allow", "kind": "allow_once" },
      { "optionId": "reject", "name": "Deny", "kind": "reject_once" }
    ],
    "_meta": {
      "kiro": {
        "mcpTool": {
          "version": 1,
          "identity": {
            "serverName": "example-server",
            "toolName": "search"
          },
          "annotations": {
            "readOnlyHint": true,
            "openWorldHint": true
          }
        }
      }
    }
  }
}

L'objet annotations est optionnel. Les quatre indications prises en charge sont readOnlyHint, destructiveHint, idempotentHint et openWorldHint. Préservez la différence entre un champ omis et un false explicite. N'utilisez jamais une indication seule pour approuver un appel, éviter une demande d'autorisation, réduire le risque, réessayer automatiquement ou contourner une politique réseau.

Les mises à jour d'outils échouées peuvent inclure _meta.kiro.failureReason avec cancelled, denied ou error. Utilisez-le lorsqu'il est présent, conservez un repli hérité lorsqu'il est absent, et traitez une valeur inconnue comme un échec générique.

CLI V3 supprime les API génériques _kiro.dev/commands/execute et _kiro.dev/commands/options. Ne les remplacez pas par un transport session/prompt universel. Utilisez le comportement local au client, les méthodes ACP standard, la configuration annoncée ou une extension typée négociée pour chaque commande.

Utilisez available_commands_update pour les commandes invocables, _kiro/tools/didChange pour les outils natifs et _kiro/mcp/status pour l'inventaire MCP. Gardez la découverte de commandes séparée de l'invocation : affichez une commande uniquement lorsque votre client dispose d'une route définie pour celle-ci.

Le tableau suivant couvre les API privées CLI v2 à fort impact restantes. Conditionnez chaque extension CLI V3 à l'annonce de capacités.

_session/steer conserve intentionnellement son nom de méthode _session/ existant dans CLI V3. Ne le renommez pas en _kiro/session/steer.

Les mises à jour retry_warning, stream_stall_notice et stream_discarded v2 sont intentionnellement retirées. Maintenez le tour actif jusqu'à l'arrivée d'un signal de cycle de vie ordinaire ou terminal. N'inférez pas un état de réessai ou de blocage à partir de la latence, et ne supprimez pas de façon heuristique une sortie déjà diffusée.

Traitez chaque notification _kiro/mcp/status comme un instantané complet, pas comme un événement à ajouter. Remplacez l'instantané précédent par nom de serveur, affichez les états connected, failed et disabled, et évitez de réafficher un échec inchangé.

Pour une session CLI V3 locale, un flux OAuth interactif utilise trois messages :

1. _kiro/mcp/status signale un serveur échoué avec failedAuthorization: true.
2. Le client appelle _kiro/mcp/resetServer annoncé avec startOAuth: true après que l'utilisateur choisit de s'authentifier.
3. L'agent envoie _kiro/openExternalUrl avec la nouvelle URL d'autorisation.

Enregistrez _kiro/openExternalUrl avant l'initialisation et annoncez clientCapabilities._meta.kiro.openExternalUrl: true. Ouvrez uniquement l'URL fournie par cette requête, utilisez une action visible de l'utilisateur, et ne journalisez ni ne partagez jamais l'URL d'autorisation.

resetServer démarre une réauthentification forcée. Ce n'est pas une opération d'annulation ou de déconnexion autonome, et ne garantit pas la révocation chez le fournisseur distant.

Vérifiez le client contre les deux adaptateurs avant de supprimer la prise en charge CLI v2.

• CLI V3 démarre avec --agent-engine=v3 et le propriétaire d'authentification prévu.
• Aucun indicateur de lancement CLI v2 uniquement ne reste.
• Le client n'utilise pas protocolVersion ACP comme discriminateur de génération.
• Les méthodes optionnelles ne sont activées que lorsqu'elles sont annoncées.
• Les champs inconnus, les types de mises à jour et les champs voisins de _meta sont ignorés sans problème.

• session/new et session/load envoient toutes les entrées actuelles appartenant au client.
• Les sessions sont découvertes via session/list, pas le système de fichiers.
• Chaque mise à jour est acheminée par sessionId et chaque événement d'outil par toolCallId.
• La réponse de requête termine le tour sans attendre une mise à jour TurnEnd.
• La relecture, la reconnexion et les sessions concurrentes préservent l'ordre et l'isolation.

• Le client affiche uniquement les options de permission fournies par l'agent.
• Les choix persistants retournent la portée de consentement canonique et les métadonnées de ressource.
• Les annotations MCP sont des affirmations non fiables à affichage uniquement.
• Les jetons d'accès et les URL OAuth n'entrent jamais dans les journaux, les données analytiques ou les rapports de plantage.
• Les requêtes agent-vers-client inconnues reçoivent une erreur JSON-RPC au lieu de bloquer.

• Chaque commande affichée dispose d'une route locale, ACP standard ou d'extension annoncée.
• Les API privées supprimées ne sont pas appelées par l'adaptateur CLI V3.
• Les notifications d'instantané remplacent l'état précédent au lieu d'accumuler des doublons.
• Les événements de réessai et de blocage de flux retirés ne sont pas synthétisés.

Utilisez le chemin complet vers kiro-cli, confirmez qu'il est exécutable et supprimez les indicateurs de lancement incompatibles avec V3. Vérifiez la sortie d'erreur standard pour le message exact d'erreur d'argument CLI.

Confirmez que le client écrit un objet JSON-RPC par ligne. Si --auth-method=cli est absent, vérifiez que le client répond à _kiro/auth/getAccessToken. Toute requête agent-vers-client avec un id nécessite une réponse ou une erreur JSON-RPC explicite.

Utilisez uniquement des valeurs provenant des options de configuration annoncées actuelles. Ne réutilisez pas une valeur mise en cache depuis un autre compte, une autre génération de serveur ou un autre déploiement.

Renvoyez les définitions mcpServers appartenant au client lors de session/load. Ne supposez pas que le serveur les a persistées avec la session.

Terminez le tour depuis la réponse session/prompt. N'attendez pas de discriminateur de mise à jour TurnEnd. Si une requête de permission est en attente, l'agent attend la réponse du client.

Relisez le résultat initialize actuel. Appelez uniquement les méthodes listées dans agentCapabilities._meta.kiro.extensionMethods et prenez en charge les déploiements qui annoncent un ensemble plus restreint.

• Agent Client Protocol (ACP) — comment les clients se connectent au harnais d'agent unifié
• Configuration d'un éditeur ACP et référence CLI v2
• Guide de migration — étapes de mise à niveau de CLI 2.x vers V3
• Migration des permissions — remplacement des indicateurs de confiance par des permissions basées sur les capacités
• Spécification Agent Client Protocol