Référence du protocole

Ce document fournit une référence complète des méthodes ACP (Agent Client Protocol) et des événements de streaming exposés par le serveur iac-code.

Aperçu du cycle de vie

Une session ACP typique suit ce flux :

initialize → new_session → prompt (loop) → close_session
                ↑                              │
                └── load_session / resume ──────┘

initialize -- Poignée de main. Négocier la version du protocole et découvrir les capacités du serveur.
session/new -- Créer une nouvelle session avec un runtime d'agent indépendant.
session/prompt -- Envoyer l'entrée utilisateur ; recevoir des événements en streaming jusqu'à une réponse finale.
session/close -- Libérer la session et ses ressources.

Les sessions peuvent également être chargées depuis l'historique (session/load) ou reprises (session/resume) au lieu d'en créer de nouvelles.

Sauvegardes de session

Les sessions ACP utilisent le même comportement de sauvegarde de session v2 que les exécutions interactives et headless. Lorsque IAC_CODE_CONFIG_BACKUP_DIR est défini, la fin normale d'un prompt enregistre une sauvegarde non bloquante normal_turn_end; si cette sauvegarde échoue, l'échec est journalisé comme warning et enregistré dans .backup-state.json, tandis que la réponse finale se termine encore sans champ warning garanti. Le mode Pipeline possède ses propres gates de sauvegarde critique.

Méthodes

initialize

Poignée de main du protocole. Doit être le premier appel sur chaque connexion.

Paramètres de requête

Champ	Type	Requis	Description
`protocolVersion`	integer	Oui	Version du protocole demandée (actuellement `1`)
`clientInfo`	object	Non	Nom et version du client
`clientCapabilities`	object	Non	Capacités prises en charge par le client

Champs de réponse

Champ	Type	Description
`protocolVersion`	integer	Version du protocole négociée
`agentCapabilities`	object	Capacités du serveur (voir ci-dessous)
`agentInfo`	object	Nom et version du serveur
`authMethods`	array	Méthodes d'authentification disponibles (vide si utilisation des identifiants intégrés)

Capacités de l'agent

Capacité	Valeur	Signification
`loadSession`	`true`	Prend en charge la restauration de sessions depuis l'historique
`promptCapabilities.embeddedContext`	`true`	Accepte le contenu de ressources embarquées dans les requêtes
`promptCapabilities.image`	`false`	Entrée image non prise en charge (dégradée en marqueur texte)
`promptCapabilities.audio`	`false`	Entrée audio non prise en charge (dégradée en marqueur texte)
`mcpCapabilities.http`	`true`	Accepte les serveurs MCP HTTP/streamable lors de la création de session
`mcpCapabilities.sse`	`true`	Accepte les serveurs MCP SSE lors de la création de session
`sessionCapabilities.list`	`{}`	Prend en charge le listage des sessions
`sessionCapabilities.close`	`{}`	Prend en charge la fermeture des sessions

session/new

Créer une nouvelle session avec un runtime d'agent indépendant, un registre d'outils et un contexte LLM.

Paramètres de requête

Champ	Type	Requis	Description
`cwd`	string	Oui	Chemin absolu vers le répertoire de travail
`mcpServers`	array	Non	Tableau de configuration des serveurs MCP injecte dans le runtime de la session ; les serveurs HTTP (streamable) et SSE sont connectés pour la session

Champs de réponse

Champ	Type	Description
`sessionId`	string	Identifiant de session unique pour les appels suivants
`modes`	object	Modes disponibles et mode actuel
`models`	object	Modèles disponibles et modèle actuel

Remarque

Chaque session crée un AgentLoop indépendant. Plusieurs sessions peuvent s'exécuter simultanément mais chacune consomme une connexion LLM.

session/load

Charger une session précédemment persistée depuis le disque, en restaurant son historique de messages.

Paramètres de requête

Champ	Type	Requis	Description
`cwd`	string	Oui	Chemin du répertoire de travail
`sessionId`	string	Oui	Identifiant de la session à charger

Champs de réponse

Champ	Type	Description
`models`	object	Modèles disponibles et état du modèle actuel
`modes`	object	Modes disponibles et état du mode actuel

Remarque

Le chargement d'une session lit l'historique depuis ~/.iac-code/sessions/, répare automatiquement les messages interrompus et injecte l'historique dans un nouvel AgentLoop.

session/fork

Dupliquer une session existante pour créer une branche indépendante avec le même historique.

Paramètres de requête

Champ	Type	Requis	Description
`cwd`	string	Oui	Chemin du répertoire de travail
`sessionId`	string	Oui	Identifiant de la session à dupliquer

Champs de réponse

Champ	Type	Description
`sessionId`	string	Nouvel identifiant de session pour la branche dupliquée
`models`	object	Modèles disponibles et état du modèle actuel
`modes`	object	Modes disponibles et état du mode actuel

session/resume

Reprendre ou se reconnecter à une session existante. Charge automatiquement l'historique si nécessaire.

Paramètres de requête

Champ	Type	Requis	Description
`cwd`	string	Oui	Chemin du répertoire de travail
`sessionId`	string	Oui	Identifiant de la session à reprendre

Champs de réponse

Champ	Type	Description
`models`	object	Modèles disponibles et état du modèle actuel (optionnel)
`modes`	object	Modes disponibles et état du mode actuel (optionnel)

Remarque

Contrairement à session/new, la réponse n'inclut pas de champ sessionId puisque le client connaît déjà l'identifiant de session depuis la requête.

session/prompt

Envoyer l'entrée utilisateur et déclencher les réponses de l'agent en streaming.

Paramètres de requête

Champ	Type	Requis	Description
`sessionId`	string	Oui	Identifiant de la session cible
`prompt`	array	Oui	Tableau de blocs de contenu (voir Types de blocs de contenu ci-dessous)

Types de blocs de contenu

Type	Description
`TextContentBlock`	Entrée texte brut de l'utilisateur
`EmbeddedResourceContentBlock`	Contenu de fichier embarqué en ligne
`ResourceContentBlock`	Référence de lien vers une ressource
`ImageContentBlock`	Image (dégradée en marqueur texte `[image: mime/type]`)
`AudioContentBlock`	Audio (dégradé en marqueur texte `[audio: mime/type]`)

Champs de réponse

Champ	Type	Description
`stopReason`	string	Raison de la fin de la requête (voir Raisons d'arrêt)
`_meta.usage`	object	Utilisation des tokens sous l'objet `_meta` de la réponse : `input_tokens`, `output_tokens`, `total_tokens`

Raisons d'arrêt

Valeur	Signification
`end_turn`	Le modèle a terminé normalement
`max_turn_requests`	Limite maximale de la boucle d'appels d'outils atteinte
`max_tokens`	Limite de tokens en sortie atteinte
`cancelled`	Le client a annulé la requête
`refusal`	Le modèle a refusé de répondre

Remarque

Pendant l'exécution, le serveur envoie des notifications session/update avec des événements en streaming avant de retourner la réponse finale.

session/cancel

Annuler une tâche de requête en cours d'exécution.

Paramètres de requête

Champ	Type	Requis	Description
`sessionId`	string	Oui	Session avec la requête en cours d'exécution

Comportement

Arrête la consommation des événements du flux
Les outils en cours d'exécution ne sont pas terminés de force, mais les résultats sont ignorés
L'appel prompt en attente retourne avec stopReason: "cancelled"

session/close

Fermer une session et libérer ses ressources.

Paramètres de requête

Champ	Type	Requis	Description
`sessionId`	string	Oui	Session à fermer

Comportement

La session est supprimée de la mémoire
L'historique persisté reste sur le disque
Les appels prompt suivants à cette session retournent une erreur

session/list

Lister toutes les sessions persistées pour un répertoire de travail donné.

Paramètres de requête

Champ	Type	Requis	Description
`cwd`	string	Oui	Répertoire de travail pour limiter la portée du listage

Champs de réponse

Champ	Type	Description
`sessions`	array	Liste d'objets session avec `sessionId` et métadonnées

session/set_config_option

Définir dynamiquement une option de configuration pour une session.

Paramètres de requête

Champ	Type	Requis	Description
`sessionId`	string	Oui	Session cible
`configId`	string	Oui	Clé de configuration à définir
`value`	any	Oui	Nouvelle valeur

Événements de streaming

Pendant l'exécution de session/prompt, le serveur envoie des notifications session/update contenant des données d'événements en streaming.

Format des événements

Chaque notification session/update contient un objet de mise à jour avec un type spécifique :

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "abc123",
    "update": { "type": "agent_message_chunk", "text": "..." }
  }
}

Correspondance des types d'événements

Événement interne	Type de mise à jour ACP	Description
`TextDeltaEvent`	`AgentMessageChunk`	Sortie texte incrémentale de l'agent
`ThinkingDeltaEvent`	`AgentThoughtChunk`	Contenu de raisonnement/réflexion du modèle
`ToolUseStartEvent`	`ToolCallStart`	Début de l'invocation d'un outil
`ToolResultEvent`	`ToolCallProgress`	Résultat de l'outil (terminé ou échoué)
`CompactionEvent`	`AgentMessageChunk`	Notification de compaction du contexte
`ErrorEvent`	`AgentMessageChunk`	Informations d'erreur

Statut et avertissements MCP

ACP expose l'etat runtime MCP dans session/update.params.update._meta.iac_code sur le wire :

Cle de metadonnees	Type de mise a jour ACP	Description
`mcpStatus`	`session_info_update`	Etat courant des serveurs MCP, pousse apres la creation de session et quand l'etat MCP auth, connection ou capability change.
`mcpWarning`	`agent_message_chunk`	Un avertissement de demarrage ou de configuration, associe a un court message visible par l'utilisateur.

mcpStatus contient servers et warnings. Les entrees server incluent serverName, state, authState, toolsCount, resourcesCount et promptsCount. Les valeurs de authState incluent configured, needs-auth et not-configured.

Les etats server courants sont connected, failed, pending, needs-auth, pending-approval et disabled.

Les grands status frames peuvent inclure truncated, truncationReason avec la valeur acp-frame-size-limit, serversOmittedCount, warningsOmittedCount ou des compteurs d'omission de capability list comme toolsOmittedCount.

Les entrees tool sous servers[].tools[] incluent publicName, originalServerName, originalToolName, et peuvent inclure annotations. Les annotations MCP peuvent porter des hints comme readOnlyHint et destructiveHint.

Les records permission audit operation peuvent inclure isReadOnly et isDestructive lorsque les annotations MCP fournissent des hints read-only ou destructive.

Les entrees mcpWarning incluent serverName, code, message, severity, source, et facultativement sourcePath ou scope. Les warning codes courants sont duplicate_config, invalid_name, invalid_config, missing_env, pending_approval, needs_auth, connection_failed, command_conflict, skill_read_failed, skill_truncated, alias_conflict, ainsi que les warnings dynamiques comme <capability>_failed.

Cycle de vie des appels d'outils

ToolCallStart (status=in_progress)
    │
    ├── ToolCallProgress (status=in_progress, résumé d'entrée / entrée de prompt sûre)
    │
    ├── ToolCallProgress (status=completed, raw_output=result)   ← success
    │
    └── ToolCallProgress (status=failed, raw_output=error)       ← failure

Correspondance des types d'outils

Outil	ToolKind ACP
`read_file`, `list_files`	`read`
`glob`, `grep`	`search`
`write_file`, `edit_file`	`edit`
`bash`, `agent`	`execute`
`web_fetch`	`fetch`
Autres	`other`

Demandes de permission

Avant d'exécuter des outils à haut risque, iac-code envoie un callback request_permission au client.

Catégories de permissions des outils

Catégorie	Outils	Auto-approuvé
Lecture seule	`read_file`, `list_files`, `glob`, `grep`, `web_fetch`	Oui
API cloud en lecture seule	Actions `aliyun_api` classées en lecture seule	Oui
Écriture	`write_file`, `edit_file`	Non -- nécessite une approbation
Exécution	`bash`, `agent`	Non -- nécessite une approbation
API cloud d'écriture	Appels `aliyun_api` qui ne sont pas en lecture seule	Non -- nécessite une approbation par API

Événement request_permission

Le serveur envoie un callback request_permission avec :

Champ	Type	Description
`options`	array	Choix de permission disponibles
`sessionId`	string	Session demandant la permission
`toolCall`	object	Détails de l'appel d'outil (titre, type, entrée)

Pour les prompts de permission MCP, le title du ToolCallUpdate ACP utilise le libelle public de l'operation et le contenu transporte un resume d'entree redacte. Via le champ d'extensibilite ACP _meta, l'objet toolCall._meta.iac_code.permission contient permissionId, toolName, toolUseId, scope, inputSummary et, si disponibles, publicName, originalServerName, originalToolName, isReadOnly et isDestructive. inputSummary decrit la forme et les metadonnees de redaction, pas l'entree sensible brute.

Options de permission

Identifiant d'option	Signification
`allow_once`	Autoriser cette invocation spécifique
`allow_always`	Autoriser tous les appels futurs de cet outil dans cette session lorsque l'outil prend en charge l'autorisation globale ; non proposé par défaut pour `bash` ni `aliyun_api`
`allow_rule:<rules>`	Autoriser les futurs appels correspondant aux règles suggérées dans cette session
`deny_rule:<rules>`	Refuser les futurs appels correspondant aux règles suggérées dans cette session
`reject_once`	Refuser cette invocation spécifique
`reject_always`	Refuser tous les appels futurs de cet outil dans cette session

Pour aliyun_api, les actions en lecture seule sont autorisées automatiquement. Les actions RPC et ROA qui ne sont pas en lecture seule peuvent proposer une règle exacte comme aliyun_api(ros:CreateStack) ou aliyun_api(cs:CreateCluster). Les règles allow avec jokers n'approuvent toujours pas les appels qui ne sont pas en lecture seule.

Format de réponse

{
  "outcome": "selected",
  "optionId": "allow_once"
}

Ou pour refuser :

{
  "outcome": "cancelled"
}

Réponse du client	Comportement de l'outil
`AllowedOutcome`	L'outil s'exécute normalement
`DeniedOutcome`	L'outil est ignoré ; le modèle reçoit une erreur "Permission denied."

Gestion des erreurs

Format RequestError

Les erreurs suivent le format d'erreur JSON-RPC 2.0 :

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {"session_id": "Session not found"}
  }
}

Codes d'erreur courants

Code	Nom	Description
`-32700`	Erreur d'analyse	JSON invalide
`-32600`	Requête invalide	JSON-RPC malformé
`-32601`	Méthode introuvable	Méthode inconnue
`-32602`	Paramètres invalides	Paramètres manquants ou invalides (ex. : identifiant de session inconnu)
`-32603`	Erreur interne	Défaillance côté serveur

Aperçu du cycle de vie​

Sauvegardes de session​

Méthodes​

initialize​

session/new​

session/load​

session/fork​

session/resume​

session/prompt​

session/cancel​

session/close​

session/list​

session/set_config_option​

Événements de streaming​

Format des événements​

Correspondance des types d'événements​

Statut et avertissements MCP​

Cycle de vie des appels d'outils​

Demandes de permission​

Catégories de permissions des outils​

Événement request_permission​

Options de permission​

Format de réponse​

Gestion des erreurs​

Format RequestError​

Codes d'erreur courants​

Aperçu du cycle de vie

Sauvegardes de session

Méthodes

initialize

session/new

session/load

session/fork

session/resume

session/prompt

session/cancel

session/close

session/list

session/set_config_option

Événements de streaming

Format des événements

Correspondance des types d'événements

Statut et avertissements MCP

Cycle de vie des appels d'outils

Demandes de permission

Catégories de permissions des outils

Événement request_permission

Options de permission

Format de réponse

Gestion des erreurs

Format RequestError

Codes d'erreur courants