@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/fr-FR/harness-agents.md

@@ -0,0 +1,349 @@
+---
+title: "Exploiter les agents"
+description: "Exécutez Claude Code, Codex, Pi et d'autres harnais de codage complets en tant qu'agents intégrés dans Agent-Native, avec leur propre boucle, sandbox, outils natifs et sessions avec reprise basées sur SQL."
+search: "exploiter les agents AgentHarness ai-sdk HarnessAgent Claude Code Codex Pi Cursor Mastra agent de codage intégré solveAgentHarness startAgentHarnessRun outils hôte sandbox de session avec reprise"
+---
+
+# Exploiter les agents
+
+> **À qui s'adresse-t-il :** les auteurs d'hôtes câblant un environnement d'exécution de codage complet (code Claude,
+> Codex, Pi) dans Agent-Native en tant qu'agent. Créer une application ? Commencez par
+> [Creating Templates](/docs/creating-templates).
+
+Un agent de harnais est un environnement d'exécution d'agent complet – Code Claude, Codex, Pi et similaire –
+qui possède sa propre boucle, son espace de travail, ses outils de fichiers natifs, son état de session, son compactage,
+modèle d'approbation et comportement du bac à sable. Agent-Native les exécute via le
+**substrat `AgentHarness`** dans `@agent-native/core/agent/harness`, diffuse leur
+événements dans la transcription normale et conserve leur session native donc un fil de discussion
+peut mettre en pause et reprendre.
+
+Ceci est différent de l'agent de chat intégré et de l'apport de votre propre chat
+exécution. L'agent intégré et `AgentEngine` sont destinés à un modèle aller-retour
+sous `runAgentLoop`. Un harnais n'est pas un fournisseur `AgentEngine` : il exécute son
+propre boucle de bout en bout, donc Agent-Native la pilote comme une session, pas comme une seule
+appel de modèle.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Quel document de codage dois-je souhaiter ? {#which-doc}
+
+| Vous voulez…                                                                             | Utiliser                                     |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Exécutez Claude Code / Codex / Pi **en tant qu'agent**, avec leur propre boucle + outils | **Exploiter les agents** (cette page)        |
+| Afficher un **espace de travail de codage de style Claude-Code/Codex**                   | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Échangez le backend qui exécute l'**outil `run-code`** de l'agent                        | [Adapters](/docs/sandbox-adapters)           |
+| Encapsuler un outil CLI (`gh`, `ffmpeg`) pour que l'agent appelle                        | [Adapters](/docs/sandbox-adapters)           |
+
+Surfaces adjacentes : placez un agent que vous avez construit ailleurs derrière le chat de Agent-Native
+UI avec [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes) ; laissez un
+Appel hôte externe MCP dans votre application via [External Agents](/docs/external-agents) ;
+apparaître en arrière-plan/sous-agent avec [Custom Agents & Teams](/docs/agent-teams).
+
+## Harnais intégrés {#built-in}
+
+`registerBuiltinAgentHarnesses()` enregistre trois adaptateurs soutenus par l'IA SDK
+`HarnessAgent`:
+
+| Nom                          | Exécution   | Bac à sable | Approbations |
+| ---------------------------- | ----------- | ----------- | ------------ |
+| `ai-sdk-harness:claude-code` | Code Claude | oui         | oui          |
+| `ai-sdk-harness:codex`       | Codex       | oui         | non          |
+| `ai-sdk-harness:pi`          | Pi          | non         | oui          |
+
+Leurs packages d'exécution sont des **dépendances homologues facultatives** et se chargent paresseusement, donc
+une application qui n'utilise jamais de harnais ne paie pas pour cela. Chaque adaptateur porte un
+Indice `installPackage` (par exemple `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` lance une installation claire
+erreur si les packages sont manquants, et `isAgentHarnessPackageInstalled(entry)`
+vous permet de vérifier en premier.
+
+`registerBuiltinAgentHarnesses()` enregistre également les harnais [ACP](#acp)
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## Agents ACP {#acp}
+
+Agent-Native peut agir comme un [ACP](https://agentclientprotocol.com) (Agent Client
+Protocole) **client** et piloter un agent de codage local – Gemini CLI, Claude Code,
+ou tout agent conforme à la norme ACP — via ce même substrat. L'agent s'exécute en tant que
+sous-processus local qui parle JSON-RPC délimité par des nouvelles lignes sur stdio ; Éditeur de ACP
+↔ le modèle d'agent a exactement cette forme.
+
+Cet adaptateur est limité au **codage local**. Le processus enfant hérite du
+environnement parent, de sorte que l'agent réutilise la connexion locale CLI dont il dispose déjà
+(par exemple, authentification `gemini` ou `claude` dans le répertoire personnel de l'utilisateur). Ce n'est pas un
+transport hébergé ou en bac à sable, et ce n'est pas un transport chat/A2A — pour ceux-là,
+voir [Agent Surfaces](/docs/agent-surfaces).
+
+| Nom               | Commande par défaut                               | Reprise\* |
+| ----------------- | ------------------------------------------------- | --------- |
+| `acp`             | _(fournir `command`/`args` via la configuration)_ | oui       |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp`    | oui       |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`          | oui       |
+
+\*La reprise fonctionne lorsque l'agent annonce la fonctionnalité `loadSession` et
+se dégrade en une nouvelle session sinon.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+Le transport de protocole (`@zed-industries/agent-client-protocol`) est facultatif
+dépendance chargée paresseusement via l'indice `installPackage`, tout comme l'IA SDK
+harnais. Le binaire de l'agent lui-même (`@google/gemini-cli`,
+`@zed-industries/claude-code-acp`, …) est un CLI externe distinct ; les préréglages
+lancez-le via `npx` et la commande/les arguments restent modifiables car l'agent ACP
+les drapeaux d'entrée évoluent encore.
+
+`permissionMode` mappe sur ACP `session/request_permission` à l'aide de l'appel d'outil
+type de rapport de l'agent : les lectures sont toujours exécutées, les modifications sont exécutées sous `allow-edits` et
+tout est risqué sauf si `allow-all`. Les approbations semblent normales
+Événements `approval-request`. L'adaptateur sert `fs/read_text_file` et
+`fs/write_text_file` contre l'espace de travail de session (refusant les chemins qui s'échappent
+it) et écrit des événements `file-change` ; les méthodes de terminal ne sont pas annoncées,
+l'agent utilise donc son propre shell.
+
+## Authentification Codex : code UI par rapport aux bacs à sable de harnais {#codex-auth}
+
+Il existe deux surfaces Codex, et elles s'authentifient différemment :
+
+- **Agent-Native Code / Desktop** exécute `codex exec` sur la machine de l'utilisateur. Si
+  l'utilisateur a exécuté `codex login`, cette exécution locale réutilise tout ChatGPT
+  l'abonnement ou la clé API authentifie les rapports Codex CLI installés via
+  `codex login status`.
+- **`ai-sdk-harness:codex`** charge `@ai-sdk/harness-codex`, qui pilote Codex
+  à l'intérieur du bac à sable du harnais via `@openai/codex-sdk`. Cela ne se fait pas en silence
+  hériter de la connexion Desktop `~/.codex` de l'utilisateur, car le bac à sable peut être distant
+  ou isolé. Pour les bacs à sable fiables/privés, inscrivez-vous avec `codexCliAuth: true` ;
+  Agent-Native copie le fichier d'authentification local Codex CLI dans le bac à sable avant le
+  le harnais démarre. Pour les sandbox hébergés ou partagés, configurez la clé/passerelle API
+  auth à la place.
+
+Donc, si quelqu'un demande quel paquet contient le chemin Codex OAuth : pour le codage local
+sessions, utilisez `@agent-native/core` / Desktop plus celui installé
+`@openai/codex` CLI et `codex login`. Pour le `ai-sdk-harness:codex` en bac à sable,
+utilisez l'opt-in explicite `codexCliAuth` lors de la copie de cette connexion dans le bac à sable
+est acceptable.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` lit `CODEX_HOME/auth.json` ou `~/.codex/auth.json`. À
+pointez sur une autre connexion locale, passez
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` ou
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## Enregistrer et résoudre {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+`resolveAgentHarness(name, config?)` renvoie un `AgentHarnessAdapter`. Le
+Le `config` facultatif est transmis à l'usine d'adaptateurs – pour les adaptateurs AI SDK
+qui correspond à `AiSdkHarnessAdapterOptions` (`label`, `description`,
+`permissionMode`, `harnessOptions`, `agentOptions` et Codex uniquement
+`codexCliAuth`). Utilisez `listAgentHarnesses()` pour énumérer ce pour quoi vous êtes enregistré
+un sélecteur.
+
+## Faire un tour {#run-a-turn}
+
+`startAgentHarnessRun` relie une session de harnais au gestionnaire d'exécution partagé
+cycle de vie. Il crée (ou réutilise) la session native, la conserve, diffuse le
+tourne, traduit chaque événement de harnais en événements de transcription et détache le
+état pouvant être repris une fois le tour terminé.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+`startAgentHarnessRun` renvoie le `ActiveRun` du gestionnaire d'exécution, donc le tour
+apparaît dans les itinéraires de course existants, la transcription et l'annulation, tout comme
+tout autre agent exécuté. Passer un `session` déjà créé au lieu de `createSession`
+pour continuer une session que vous gardez en mémoire.
+
+## Séances et CV {#sessions}
+
+Un harnais possède un état de session natif de longue durée. Agent-Native le conserve dans SQL
+afin qu'un thread puisse survivre à travers les tours, les processus et les déploiements. Le `resumeState`
+est **opaque** — Agent-Native le stocke et le rend, mais ne l'inspecte jamais ou
+l'interprète.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+Le magasin expose également `saveAgentHarnessSession`, `updateAgentHarnessSession`,
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped` et `ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` appelle les chemins de sauvegarde/mise à jour/arrêt pour vous ; atteignez-les
+directement uniquement dans un hôte personnalisé.
+
+## Outils d'hébergement et autorisations {#host-tools}
+
+Un harnais apporte ses propres outils natifs (lecture, modification, écriture, shell, etc.), donc
+vous ne **pas** réexposer l'édition de fichiers en tant qu'outils hôtes. Passez seulement un **étroit,
+ensemble intentionnel** de Agent-Native actions à `createSession.tools` lorsque vous
+vous souhaitez que le harnais atteigne des opérations d'application spécifiques et conservez `defineAction`
+authentification, contexte de requête, délais d'attente, troncature et métadonnées en lecture seule intacts lorsque
+vous le faites.
+
+`permissionMode` contrôle ce que le harnais peut faire sans approbation :
+
+| Mode          | Signification                                                                     |
+| ------------- | --------------------------------------------------------------------------------- |
+| `allow-reads` | Par défaut. Les lectures sont exécutées ; modifications et invite actions risquée |
+| `allow-edits` | Les lectures et les modifications sont exécutées ; autre invite actions risquée   |
+| `allow-all`   | Pas de contrôle d'approbation                                                     |
+
+Lorsqu'un harnais s'arrête pour approbation, il émet un événement `approval-request` et le
+la session est marquée `idle` avec l'approbation en attente enregistrée, afin que le UI puisse
+faites-le surface et reprenez la décision de l'utilisateur. Voir
+[Human Approval](/docs/human-approval) pour la surface d'approbation.
+
+## Événements {#events}
+
+Une session de harnais diffuse les valeurs `AgentHarnessEvent`, lesquelles Agent-Native
+se traduit en flux `AgentChatEvent` standard avec
+`agentHarnessEventToAgentChatEvents`. Le syndicat événementiel couvre `text-delta`,
+`thinking-delta`, `activity`, `tool-start`, `tool-done` (pouvant transporter un
+Charge utile `mcpApp` pour les widgets natifs), `approval-request`, `file-change`,
+`compaction`, `usage`, `error` et `done`. Parce que les résultats des outils transitent par le
+même traduction, les widgets natifs déclarés par action sont toujours rendus – voir
+[Native Chat UI](/docs/native-chat-ui).
+
+## Exécutions en arrière-plan et UI {#background-runs}
+
+Harness exécute le projet dans la forme `BackgroundAgentRun` partagée avec
+`createAgentHarnessBackgroundAgentController()` et sont disponibles via le
+itinéraires d'exécution existants sous le nom `goalId=agent-harness`. Cela signifie un Claude de longue durée
+La session Code ou Codex apparaît dans les mêmes surfaces d'exécution en arrière-plan et de transcription
+en tant qu'équipes d'agents et autres adaptateurs, avec `listAgentHarnessBackgroundRuns`,
+`listAgentHarnessBackgroundTranscriptEvents`, `getAgentHarnessBackgroundRun` et
+`stopAgentHarnessBackgroundRun` disponible pour les hôtes personnalisés.
+
+## Adaptateurs personnalisés {#custom-adapters}
+
+Pour encapsuler un runtime qui ne fait pas partie des éléments intégrés, implémentez
+`AgentHarnessAdapter` et enregistrez-le. L'adaptateur déclare ses capacités et
+crée des sessions ; une session expose `streamTurn` et `continueTurn` en option,
+`approve`, `detach`, `stop` et `destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+Gardez le package d'exécution en option avec une importation dynamique dans `createSession` et un
+Indice `installPackage`. Pour les faisceaux de codage à pont, nécessitez un véritable
+fournisseur sandbox/espace de travail plutôt que d'exécuter un agent de codage arbitraire dans
+processus hôte — voir [Sandbox Adapters](/docs/sandbox-adapters). L'adaptateur AI SDK
+(`createAiSdkHarnessAdapter`, soutenu par `HarnessAgent` de `@ai-sdk/harness`) est
+une seule mise en œuvre de ce contrat, pas l'abstraction publique.
+
+## Ne pas faire {#donts}
+
+- N'ajoutez pas de code Claude, Codex, Cursor, Mastra ou Pi en tant que `AgentEngine`. Ils
+  posséder leur boucle ; en exécuter un sous `AgentEngine.stream()` double la boucle
+  et perd la sémantique du cycle de vie de la session.
+- Ne rejouez pas l'historique complet des discussions de Agent-Native dans un harnais à chaque tour. Reprendre
+  la séance harnais avec son `resumeState` à la place.
+- Ne stockez pas `resumeState` dans `application_state`. Sa place est dans le harnais
+  tableau de session SQL.
+- N'exposez pas chaque action de l'application à chaque session d'exploitation par défaut. Donnez-lui un
+  petit ensemble d'outils intentionnel.
+
+## Documents associés {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) : mettez votre propre agent derrière le chat UI avec `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces) : choisissez sans tête, chat, side-car ou application complète.
+- [Agent-Native Code UI](/docs/code-agents-ui) : la surface de l'espace de travail de codage réutilisable.
+- [Custom Agents & Teams](/docs/agent-teams) — exécutions en arrière-plan et délégation de sous-agents.
+- [Sandbox Adapters](/docs/sandbox-adapters) – backends d'exécution enfichables pour les faisceaux de codage.
+- [Human Approval](/docs/human-approval) : le faisceau de surface d'approbation est utilisé.

package/corpus/core/docs/content/locales/fr-FR/human-approval.md

@@ -0,0 +1,86 @@
+---
+title: "Approbations humaines dans la boucle"
+description: " Suspendre l'agent avant l'exécution d'une action à conséquences élevées : la porte needApproval de defineAction émet un événement d'approbation_required, l'humain approuve, et ensuite seulement l'outil s'exécute."
+---
+
+# Approbations humaines dans la boucle
+
+La plupart des actions devraient simplement s'exécuter. Quelques-unes – envoyer un e-mail, charger une carte, supprimer un compte – sont orientées vers l'extérieur et difficiles à annuler, et vous ne voulez pas que l'agent les fasse de manière autonome. Pour ceux-ci, `defineAction` dispose d'une **porte d'approbation** opt-in : lorsque l'agent tente d'appeler l'action, la boucle s'arrête, présente une autorisation Approuver/Refuser à l'humain et exécute l'action _uniquement_ après que l'humain ait approuvé cet appel spécifique.
+
+> [!WARNING]
+> Gardez les approbations rares. Chaque action fermée est un arrêt brutal dans la boucle de l'agent : elle interrompt l'exécution et nécessite un aller-retour humain. Utilisez le `needsApproval` uniquement pour les opérations véritablement lourdes de conséquences, difficiles à annuler et orientées vers l'extérieur. Si vous vous retrouvez à bloquer des lectures ou des écritures de routine, vous vous trompez. La valeur par défaut est **off**, et presque toutes les actions devraient la laisser désactivée.
+
+## La porte `needsApproval` {#needs-approval}
+
+Définissez `needsApproval` sur un `defineAction`. Il accepte un booléen ou un prédicat :
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — nécessite toujours une approbation.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** : nécessite une approbation uniquement lorsque le prédicat renvoie vrai. Porte conditionnellement, par ex. uniquement pour les destinataires externes ou uniquement au-dessus d'un seuil monétaire :
+
+  ```ts
+  needsApproval : (args) => !args.to.endsWith("@votre-entreprise.com"),
+  ```
+
+  Gardez le prédicat pur et rapide. **La fermeture échoue** : si le prédicat est lancé, le framework traite cela comme une « approbation requise » plutôt que d'exécuter silencieusement une action à haute conséquence.
+
+Lorsque `needsApproval` est omis, le comportement reste inchangé octet par octet — il n'y a aucun coût supplémentaire sur le chemin commun.
+
+Cela fonctionne de la même manière pour les anciens actions de style `parameters` et les actions basés sur un schéma, ainsi que pour l'agent intégré à l'application, les sous-agents, les appelants A2A et MCP (chaque surface d'agent est acheminée via la même boucle).
+
+## Comment la boucle se met en pause {#loop}
+
+Lorsque l'agent appelle une action fermée et que cet appel spécifique n'a **pas** déjà été approuvé, la boucle n'exécute **pas** `run()`. Au lieu de cela :
+
+1. Résout la porte. Pour un prédicat, il appelle `needsApproval(input, ctx)` ; un lancer est traité comme "doit approuver" (échec clos).
+2. Émet un événement `tool_start` (donc le UI affiche l'appel) suivi immédiatement d'un événement **`approval_required`**, puis arrête le tour. L'effet secondaire de l'action ne se produit jamais.
+
+L'événement `approval_required` contient tout ce dont le client a besoin pour proposer une offre :
+
+| Champ         | Tapez    | Remarques                                                              |
+| ------------- | -------- | ---------------------------------------------------------------------- |
+| `tool`        | `string` | Le nom de l'action que l'agent a tenté d'appeler.                      |
+| `input`       | objet    | Les arguments transmis par l'agent.                                    |
+| `approvalKey` | `string` | **Clé stable** que le client renvoie pour approuver _cet appel exact_. |
+| `toolCallId`  | `string` | L'identifiant d'appel d'outil côté modèle, lorsqu'il est disponible.   |
+
+Le `approvalKey` est dérivé de manière déterministe du nom de l'outil et de son entrée, de sorte que le même appel logique produit toujours la même clé. Le modèle ne le voit ni ne le définit jamais : il s'agit simplement d'une poignée de main entre le cadre et l'accessibilité d'approbation de l'humain.
+
+L'outil en pause renvoie un résultat indiquant au modèle que le virage est en pause et qu'il ne doit pas réessayer, afin que le modèle ne tourne pas.
+
+## Comment l'humain approuve {#approve}
+
+Sur `approval_required`, le chat UI affiche une autorisation **Approuver/Refuser** lors de l'appel d'outil en pause. Ceci est automatiquement intégré dans `AssistantChat` — vous ne le construisez pas par modèle.
+
+- **Approuver** réémet le tour (un message de suite ordinaire) portant la clé d'appel dans `approvedToolCalls: [approvalKey]`. Au tour réédité, la porte voit la clé dans le jeu approuvé et laisse cet appel spécifique se dérouler normalement.
+- **Deny** rejette l'affordance localement ; rien n'est réédité, donc l'action ne s'exécute jamais.
+
+`approvedToolCalls` est un champ sur la demande de chat (`AgentChatRequest.approvedToolCalls`). Les clés qui n'y sont pas présentes restent en pause : l'approbation d'un appel n'en approuve jamais directement les autres. Parce que la clé est adressée au contenu, une approbation autorise *cet appel avec ces arguments* ; si le modèle propose ultérieurement un envoi différent, c'est une nouvelle clé et une nouvelle approbation.
+
+## De bout en bout {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+L'utilisation canonique (et intentionnellement rare) de cette porte dans le framework est l'action `send-email` du modèle de courrier, qui définit `needsApproval: true` afin que l'agent puisse rédiger et mettre en file d'attente librement mais ne puisse jamais réellement envoyer un message sans qu'un humain n'approuve l'envoi spécifique.
+
+## Connexe
+
+- [**Actions**](/docs/actions#needs-approval) : la surface `defineAction` complète, y compris `outputSchema` pour valider les valeurs de retour.
+- [**Security**](/docs/security) – quand atteindre une porte d'approbation ou cacher une action au modèle.
+- [**Mail template**](/docs/template-mail) — `send-email` est l'exemple de référence.

package/corpus/core/docs/content/locales/fr-FR/internationalization.md

@@ -1,15 +1,18 @@
 ---
 title: "Internationalisation"
-description: "Localisez les apps Agent Native avec des catalogues partagés, un sélecteur de langue, un fallback navigateur et du contenu docs par locale."
+description: "Localisez les applications Agent Native avec des catalogues de paramètres régionaux partagés, un sélecteur de langue, une langue de secours du navigateur et un contenu de documents prenant en compte les paramètres régionaux."
 ---
 
 # Internationalisation
 
-Les apps Agent Native peuvent localiser l'UI du framework et des modèles via le runtime partagé `@agent-native/core/client/i18n`. Le framework stocke le choix de langue de l'utilisateur dans les settings SQL, l'expose sous forme d'actions et revient à English lorsqu'une app n'a pas encore traduit une chaîne.
+Les applications Agent Native peuvent localiser le framework et le modèle UI via le partage
+Exécution `@agent-native/core/client/i18n`. Le framework stocke les informations
+choix de la langue dans les paramètres SQL, l'expose sous le nom actions et revient à
+En anglais lorsqu'une application n'a pas encore traduit une chaîne.
 
-## Runtime {#runtime}
+## Exécution
 
-Utilisez le provider via `AppProviders` :
+Utilisez le fournisseur via `AppProviders` :
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-`getLocaleInitScript()` définit le `lang`, le `dir` et `window.__AGENT_NATIVE_LOCALE__` initiaux avant l'hydratation React. Les routes SSR publiques peuvent appeler `resolveLocaleFromRequest()` depuis `@agent-native/core/server` et transmettre le locale/catalog résolu au script pour éviter les écarts d'hydratation.
+`getLocaleInitScript()` définit les valeurs initiales `lang`, `dir` et
+`window.__AGENT_NATIVE_LOCALE__` avant que React ne s'hydrate. Les itinéraires publics SSR peuvent
+appelez `resolveLocaleFromRequest()` depuis `@agent-native/core/server` et passez le
+résolution des paramètres régionaux/catalogue dans ce script pour éviter les incompatibilités d'hydratation.
 
-## Catalogues {#catalogs}
+## Catalogues
 
-Chaque modèle localisé conserve ses catalogues dans `app/i18n/` :
+Chaque modèle localisé conserve les catalogues sous `app/i18n/` :
 
 ```ts
 // app/i18n/index.ts
@@ -52,51 +58,88 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-Emballez toujours `en-US`. Importez dynamiquement les catalogues non English afin que les utilisateurs ne téléchargent que le locale actif. Les locale codes pris en charge sont `en-US`, `zh-CN`, `es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` et `ar-SA`.
+Toujours regrouper `en-US`. Importation dynamique de catalogues dans une langue autre que l'anglais pour les utilisateurs uniquement
+téléchargez les paramètres régionaux actifs. Les codes régionaux pris en charge sont `en-US`, `zh-CN`,
+`es-ES`, `fr-FR`, `de-DE`, `ja-JP`, `ko-KR`, `pt-BR`, `hi-IN` et `ar-SA`.
 
-## UI {#ui}
+## UI
 
-Utilisez `useT()` pour les textes d'interface et `<LanguagePicker />` dans les settings :
+Utilisez `useT()` pour les chaînes d'interface et mettez `<LanguagePicker />` sur l'application
+Page `/settings`. Les applications de la barre latérale doivent afficher les **Paramètres** dans la barre latérale de l'application ;
+l'icône de langue d'en-tête n'est qu'un raccourci.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-Utilisez `useFormatters()` pour les dates, nombres, temps relatifs et listes. Ne placez pas de formatage sensible au locale dans les chaînes traduites.
+Le contrôle "Paramètres de l'agent" doit ouvrir l'onglet Paramètres de la barre latérale droite de l'agent
+pour le modèle, la clé API, l'automatisation, la voix et d'autres commandes au niveau du framework.
+Les applications peuvent dupliquer des paramètres de framework de grande valeur dans leur propre page de paramètres
+lorsque le paramètre est au centre de l'application, mais que l'onglet des paramètres de la barre latérale reste le
+source de vérité.
+
+Utilisez `useFormatters()` pour les dates, les nombres, l'heure relative et les listes. Ne mettez pas
+Formatage de date/nombre sensible aux paramètres régionaux dans les chaînes de traduction.
 
-## Contenu du site docs {#docs-site-content}
+## Contenu du site Docs {#docs-site-content}
 
-Les pages publiques de docs utilisent le même core provider, mais avec `persistPreference={false}` afin que le trafic anonyme utilise localStorage et la langue du navigateur au lieu des actions de settings SQL. La source English reste dans `packages/core/docs/content/*.md`. Les remplacements localisés vivent dans `packages/core/docs/content/locales/<locale>/<slug>.md`.
+Les pages de documents publics utilisent le même fournisseur principal, mais avec
+`persistPreference={false}` afin que le trafic de documents anonymes utilise localStorage et
+langue du navigateur au lieu des paramètres SQL actions. La source anglaise reste en
+`packages/core/docs/content/*.md`. Les remplacements de page localisés sont affichés à côté sous
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-Utilisez les mêmes BCP-47 locale codes que les catalogues d'app. Gardez le même slug que la source English, préservez les ancres stables avec `{#anchor}` sur les titres traduits, et ne traduisez pas les routes, action names, protocol fields, env vars ou provider names. Si un locale n'a pas de Markdown traduit pour une page, le site revient à English pour cette page tout en localisant la navigation et le chrome.
+Utilisez les mêmes codes régionaux BCP-47 que les catalogues d'applications. Gardez le même slug que le
+Source anglaise, préserver les ancrages stables avec `{#anchor}` sur les titres traduits,
+et laissez les routes, les noms d'action, les champs de protocole, les variables d'environnement et les noms de fournisseur
+non traduit. Si un paramètre régional n'a pas de Markdown traduit pour une page, le site de documentation
+revient à l'anglais pour cette page tout en localisant la navigation et Chrome.
 
-## Actions et persistance {#actions-and-persistence}
+## Actions et persistance
 
-Chaque app hérite de :
+Chaque application hérite :
 
 - `get-localization-preference` — lit le `{ locale }` de l'utilisateur actuel
-- `set-localization-preference` — définit `"system"` ou un locale pris en charge
+- `set-localization-preference` : définissez `"system"` ou un paramètre régional pris en charge
 
-La valeur durable vit dans les settings SQL à portée utilisateur sous `localization`. `localStorage` sert uniquement au pre-hydration et au fallback anonyme. Le locale actif est reflété dans application state comme contexte ambiant afin que les agents voient la langue actuelle de l'interface.
+La valeur durable réside dans les paramètres SQL définis par l'utilisateur sous `localization`.
+`localStorage` est utilisé uniquement pour la pré-hydratation et le repli anonyme. L'actif
+les paramètres régionaux sont reflétés dans l'état de l'application en tant que contexte ambiant afin que les agents puissent voir
+la langue actuelle de l'interface.
 
-## Guard {#guard}
+## Garde
 
-Exécutez :
+Exécuter :
 
 ```bash
 pnpm guard:i18n-catalogs
 ```
 
-Le guard vérifie les noms de fichiers locale pris en charge, key parity, placeholder parity, stale keys et catégories plurales CLDR via `Intl.PluralRules`. Il vérifie la structure, pas la qualité de traduction ; les chaînes très visibles nécessitent encore une revue humaine.
+Le gardien vérifie les noms de fichiers de paramètres régionaux pris en charge, la parité des clés, la parité des espaces réservés,
+clés périmées et catégories plurielles CLDR via `Intl.PluralRules`. Il vérifie
+la structure, pas la qualité de la traduction ; les chaînes à haute visibilité ont toujours besoin d'humains
+révision.
 
-Ne traduisez pas les identifiants stables comme action names, routes, enum values, app-state keys, database values, protocol fields, env var names ou provider names.
+Ne traduisez pas les identifiants stables tels que les noms d'actions, les routes, les valeurs d'énumération,
+Clés d'état de l'application, valeurs de base de données, champs de protocole, noms de variables d'environnement ou fournisseur
+noms.