@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/fr-FR/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "Tâches récurrentes"
+description: "Invites planifiées par Cron que l'agent exécute seul : résumés quotidiens, rapports hebdomadaires, interrogations horaires."
+---
+
+# Tâches récurrentes
+
+Une **tâche récurrente** est une invite qui s'exécute selon une planification cron. C'est ainsi que l'agent fait les choses tout seul : "chaque matin à 7 heures, résumez mes e-mails de la nuit", "chaque lundi, publiez les numéros d'inscription de la semaine dernière sur Slack", "chaque heure recherchez les brouillons périmés et supprimez-les."
+
+Les tâches récurrentes se déclenchent selon une horloge. Pour réagir aux _événements_ (une réservation créée, un e-mail reçu) — même format de fichier `jobs/` plus conditions — voir [Automations](/docs/automations).
+
+Les tâches sont en direct dans le [workspace](/docs/workspace) sur `jobs/<name>.md` — juste un fichier Markdown avec le frontmatter YAML. Pas d'enregistrement, pas de câblage. Déposez le fichier et le framework le récupère.
+
+## Un fichier de travail {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+C'est tout. Le corps est une invite que l'agent exécute à chaque déclenchement planifié. L'agent a accès aux mêmes outils et au même contexte d'espace de travail que dans un chat interactif : actions, skills, mémoire, serveurs MCP connectés, sous-agents.
+
+## Première question {#frontmatter}
+
+| Champ        | Tapez                         | Par défaut      | Description                                                                                                                            |
+| ------------ | ----------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | expression cron               | _(obligatoire)_ | Cron standard à 5 champs. `"0 7 * * *"` = tous les jours à 07h00 ; `"0 */4 * * *"` = toutes les 4 heures.                              |
+| `enabled`    | booléen                       | `true`          | Basculez vers `false` pour mettre en pause sans supprimer la tâche.                                                                    |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`     | `"creator"` s'exécute avec l'identité du propriétaire de la tâche et `ANTHROPIC_API_KEY`. `"shared"` utilise la clé de l'organisation. |
+| `createdBy`  | e-mail                        | _(auto)_        | Rempli lorsque le travail est créé via l'espace de travail UI ou par l'agent.                                                          |
+| `orgId`      | chaîne                        | _(auto)_        | Portée de l'organisation ; hérité de l'organisation active du créateur.                                                                |
+| `lastRun`    | Horodatage ISO                | _(géré)_        | Écrit par le planificateur après chaque exécution.                                                                                     |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(géré)_        | Dernier résultat.                                                                                                                      |
+| `lastError`  | chaîne                        | _(géré)_        | Message d'erreur si la dernière exécution a échoué.                                                                                    |
+| `nextRun`    | Horodatage ISO                | _(géré)_        | Calculé à partir de `schedule` ; utilisé par le planificateur pour décider quand déclencher ensuite.                                   |
+
+Les champs `last*` et `nextRun` sont écrits par le planificateur. Vous pouvez les lire pour voir l'historique, mais ne les modifiez pas manuellement : la prochaine exécution les écrasera.
+
+## Syntaxe Cron {#cron}
+
+Cron standard à 5 champs (minute, heure, jour du mois, mois, jour de la semaine) :
+
+| Cron           | Signification               |
+| -------------- | --------------------------- |
+| `*/5 * * * *`  | Toutes les 5 minutes        |
+| `0 * * * *`    | Toutes les heures           |
+| `0 */4 * * *`  | Toutes les 4 heures         |
+| `0 7 * * *`    | Tous les jours à 07h00      |
+| `0 9 * * 1`    | Tous les lundis à 09h00     |
+| `0 17 * * 1-5` | En semaine à 17h00          |
+| `0 0 1 * *`    | Premier jour de chaque mois |
+
+Le framework comprend des utilitaires cron (`isValidCron()` et `describeCron()`) pour valider et restituer les chaînes cron, utilisées en interne par les couches de ressources et de planificateur.
+
+## Créer une tâche {#creating}
+
+### Depuis l'onglet Espace de travail
+
+`+` → **Tâche planifiée** dans le panneau de l'espace de travail. Remplissez l'invite et le calendrier. Enregistre sous `jobs/<slug>.md` et commence à s'exécuter au prochain tick correspondant.
+
+### En demandant à l'agent
+
+> "Créez une tâche planifiée qui résume mes e-mails non lus chaque matin à 7 heures."
+
+L'agent écrit le fichier pour vous.
+
+### À la main
+
+Déposez un fichier Markdown dans `jobs/` via la ressource APIs du framework :
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## Fonctionnement du planificateur {#how-scheduler-runs}
+
+Le planificateur est un plugin de framework (la routine interne `processRecurringJobs()`) qui s'exécute en cours de processus : un `setInterval` se déclenche toutes les 60 secondes (avec un délai de démarrage de 10 secondes) dans le plugin de chat de l'agent, partout où le serveur est en cours d'exécution.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## Débogage d'une tâche {#debugging}
+
+- Ouvrez `jobs/<name>.md` dans l'espace de travail : le premier plan affiche `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- **Testez-le sans attendre :** il n'y a pas d'outil de tir forcé. Pour effectuer le même travail à la demande, collez l'invite du travail dans le chat de l'agent et laissez-le s'y exécuter, ou définissez temporairement le planning sur la minute suivante afin que le planificateur le récupère au tick suivant (puis restaurez le vrai cron).
+- **Mettez-le en pause :** retournez `enabled: false`. Le fichier reste en place, arrête simplement de s'exécuter.
+
+## Outil d'agent {#agent-tool}
+
+Un seul outil `manage-jobs` est enregistré dans chaque modèle. Le paramètre `action` sélectionne l'opération :
+
+| Actions  | Paramètres                                                            | Objectif                                                                                     |
+| -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `create` | `name`, `schedule`, `instructions` (obligatoire) ; `scope`, `runAs`   | Créer une nouvelle tâche récurrente                                                          |
+| `list`   | `scope` (`personal`, `shared` ou tous)                                | Liste de toutes les tâches avec statut (planification, activé, dernière/prochaine exécution) |
+| `update` | `name` (obligatoire) ; `schedule`, `instructions`, `enabled`, `runAs` | Modifier une tâche existante                                                                 |
+| `delete` | `name` (obligatoire)                                                  | Supprimer une tâche – toujours confirmer d'abord avec l'utilisateur                          |
+
+**Portée personnelle ou partagée.** Chaque tâche se déroule soit dans une portée personnelle (s'exécute en tant que et n'est visible que par le créateur), soit dans une portée partagée/organisationnelle (s'exécute au nom du créateur mais est visible par les membres de l'organisation). Les paramètres `scope` et `runAs` contrôlent cela au moment de la création. Les administrateurs de l'organisation peuvent mettre à jour ou supprimer n'importe quelle tâche partagée ; Les membres non-administrateurs ne peuvent gérer que les leurs.
+
+## Différent du package de planification {#vs-scheduling-package}
+
+Ne confondez pas les tâches récurrentes avec `@agent-native/scheduling` :
+
+- **Tâches récurrentes (cette page)** — _invites_ planifiées par cron que l'agent exécute en arrière-plan. Au niveau du framework. Vit dans l'espace de travail. S'exécute sur n'importe quelle application native d'agent.
+- **`@agent-native/scheduling`** — un package de domaine réutilisable pour créer des fonctionnalités de calendrier/réservation (types d'événements, fenêtres de disponibilité, réservations). Alimente le modèle `calendar` et les surfaces de planification personnalisées.
+
+Les tâches récurrentes sont : "Comment faire en sorte que l'agent agisse seul ?" Le package de planification est « Comment puis-je créer une application de calendrier ? » Différentes préoccupations.
+
+## Quelle est la prochaine étape
+
+- [**Automations**](/docs/automations) : ajoutez des déclencheurs d'événements et des conditions au même format `jobs/`
+- [**Workspace**](/docs/workspace) — où les tâches cohabitent avec skills, la mémoire et les agents personnalisés
+- [**Actions**](/docs/actions) — les outils qu'un travail appelle
+- [**Agent Teams**](/docs/agent-teams) — les tâches génèrent souvent des sous-agents pour effectuer un travail parallèle

package/docs/content/locales/fr-FR/routing.md

@@ -0,0 +1,79 @@
+---
+title: "Routage"
+description: "Routage basé sur des fichiers pour les applications natives d'agent avec React Router v7 : pages, paramètres dynamiques et navigation."
+---
+
+# Routage
+
+Les applications natives d'agent utilisent le **routeur React v7** avec un routage basé sur des fichiers via `flatRoutes()` à partir de `@react-router/fs-routes`. Chaque fichier de `app/routes/` devient un URL. Les modèles utilisent la convention de notation par points : des points séparent les segments URL à l'intérieur d'un seul nom de fichier.
+
+## Routage basé sur des fichiers {#file-based-routing}
+
+### Fichier → Mappage URL
+
+| Fichier               | URL                  | Remarques                                       |
+| --------------------- | -------------------- | ----------------------------------------------- |
+| `_index.tsx`          | `/`                  | Indexer l'itinéraire                            |
+| `settings.tsx`        | `/settings`          | Page simple                                     |
+| `inbox.$threadId.tsx` | `/inbox/:threadId`   | Point = `/`, `$` = paramètre dynamique          |
+| `_app.tsx`            | (pas de segment URL) | Mise en page sans chemin – préfixe avec `_`     |
+| `inbox/route.tsx`     | `/inbox`             | Formulaire de dossier — `route.tsx` est l'index |
+
+Préfixez un segment avec `$` pour un paramètre dynamique. Préfixez `_` pour en faire un itinéraire de tracé sans chemin (pas de segment URL). Les modèles utilisent `flatRoutes()` — le fichier de notation par points ci-dessus est principal ; le formulaire de dossier imbriqué `inbox/route.tsx` fonctionne également.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## Ajout d'une nouvelle page {#adding-a-page}
+
+Créez le fichier et exportez un composant par défaut :
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+C'est tout – Le routeur React le récupère automatiquement, aucune inscription n'est nécessaire.
+
+## Paramètres dynamiques {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## Navigation {#navigation}
+
+Utilisez `<Link>` pour la navigation côté client et `useNavigate()` pour la navigation par programmation :
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## Quelle est la prochaine étape
+
+- [**Client**](/docs/client) — les hooks et utilitaires de navigateur natifs de l'agent
+- [**Server**](/docs/server) — routes de serveur basées sur des fichiers et espace de noms `/_agent-native/`

package/docs/content/locales/fr-FR/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "Adaptateurs"
+description: "Les deux adaptateurs du framework : les adaptateurs sandbox échangent le backend qui exécute l'outil d'exécution de code de l'agent, et les adaptateurs CLI donnent à l'agent un accès structuré aux outils de ligne de commande."
+search: "adaptateurs adaptateur sandbox adaptateur cli code d'exécution SandboxAdapter CliAdapter ShellCliAdapter exécuteur durable sandbox edge sans serveur child_process"
+---
+
+# Adaptateurs
+
+> **À qui s'adresse-t-il :** les auteurs d'hôtes qui étendent le runtime. Les développeurs d'applications rarement
+> j'en ai besoin – les valeurs par défaut fonctionnent immédiatement.
+
+Agent-Native est doté de deux coutures d'adaptateur qui éliminent un problème derrière un étroit,
+interface remplaçable :
+
+- **Les adaptateurs Sandbox** échangent le backend qui exécute l'outil `run-code` de l'agent —
+  un processus enfant local par défaut, ou un exécuteur Docker/distant/durable.
+- **Les adaptateurs CLI** donnent à l'agent un accès structuré aux outils de ligne de commande
+  (`gh`, `ffmpeg`, `stripe`) avec découverte, contrôles de disponibilité et
+  forme de résultat cohérente.
+
+Les deux partagent une contrainte d'exécution : ils s'appuient sur les liaisons système Node.js et le font
+ne s'exécute pas sur les environnements d'exécution Edge/Worker – voir [Edge and serverless](#edge-serverless).
+
+## Quel document de codage je veux ? {#which-doc}
+
+| Vous voulez…                                                                             | Utiliser                                     |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------- |
+| Échangez le backend qui exécute l'**outil `run-code`** de l'agent                        | **Adaptateurs Sandbox** (cette page)         |
+| Encapsuler un outil CLI (`gh`, `ffmpeg`) pour que l'agent appelle                        | **Adaptateurs CLI** (cette page)             |
+| Afficher un **espace de travail de codage de style Claude-Code/Codex** UI\*\*            | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Exécutez Claude Code / Codex / Pi **en tant qu'agent**, avec leur propre boucle + outils | [Harness Agents](/docs/harness-agents)       |
+
+# Adaptateurs Sandbox
+
+L'outil `run-code` exécute le JavaScript fourni par l'agent dans un environnement isolé. Les **adaptateurs Sandbox** prennent en compte le problème d'_exécution_ de cet outil afin que le backend puisse être échangé (un processus enfant local par défaut, ou un exécuteur Docker/distant/durable) sans toucher à la boucle d'agent, à `run-code.ts`, au pont localhost, au nettoyage d'environnement ou au formatage de sortie.
+
+## Pourquoi une couture {#why}
+
+Le backend par défaut génère un processus enfant de nœud local verrouillé. Cela est limité par le processus d'hébergement : sur la plate-forme hébergée, il partage le plafond d'exécution souple de la boucle d'agent (~ 40 s avant l'expiration du délai d'attente/la poursuite). Un adaptateur distant ou durable est le levier permettant de dépasser ce plafond : il exécute des tâches de données volumineuses jusqu'à leur achèvement indépendamment du cycle de vie de la demande.
+
+En gardant le contrat étroit, un adaptateur distant hérite de la même posture de sécurité. Le processus parent conserve la propriété de tout ce qui porte secret : il construit le module sandbox, exécute le pont localhost (qui contient le contexte de la demande et applique les listes autorisées d'hôtes + les gardes SSRF), nettoie l'environnement et formate la sortie. Un adaptateur reçoit uniquement une source de module **non secrète** déjà préparée ainsi que les limites de ressources — il est uniquement responsable de son _exécution_ et de la capture de l'état stdout/stderr/exit.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## L'interface {#interface}
+
+La couture réside dans le noyau de `packages/core/src/coding-tools/sandbox/` : `adapter.ts` (le contrat), `index.ts` (sélection : `getSandboxAdapter()` / `registerSandboxAdapter()`) et `local-child-process-adapter.ts` (la valeur par défaut). Il est câblé dans l'emballage par `run-code.ts` ; un hôte connecte un backend différent via l'assistant d'enregistrement `index.ts` (ou, pour un backend Docker, via le [blueprint](/docs/blueprint-installer) qui édite directement ces fichiers).
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+Chaque backend implémente `SandboxAdapter` :
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+La requête et le résultat sont volontairement petits et opaques :
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## Par défaut : `LocalChildProcessAdapter` {#default}
+
+Prêt à l'emploi, `getSandboxAdapter()` renvoie `LocalChildProcessAdapter` (`id: "local-child-process"`). Il préserve le comportement historique du `run-code` octet par octet :
+
+- La source du module préparée est écrite dans un nouveau répertoire temporaire.
+- L'enfant s'exécute avec l'environnement nettoyé (sans secrets), avec `TMPDIR`/`TEMP`/`TMP` pointé à l'intérieur du répertoire sandbox.
+- Lorsque le modèle d'autorisation de nœud est disponible (`--permission` ou `--experimental-permission` sur le nœud 20), l'enfant se voit refuser l'accès au système de fichiers en dehors de son répertoire temporaire, ainsi qu'aux processus enfants, aux travailleurs et aux modules complémentaires natifs. Le réseau sortant n'est _pas_ bloqué par le modèle d'autorisation — mais le nettoyage d'environnement signifie que de telles requêtes ne comportent aucune information d'identification et que tous les appels authentifiés passent par le pont de bouclage du parent.
+- Un timeout envoie `SIGTERM`, puis `SIGKILL` après un délai de grâce de 2 s.
+- Les fichiers temporaires sont nettoyés au mieux après l'exécution.
+
+> [!WARNING]
+> L'adaptateur par défaut utilise `node:child_process`, qui n'existe pas sur les environnements d'exécution Edge/Worker. Exécutez `run-code` dans un environnement Node.js standard ou enregistrez un adaptateur distant – voir [Edge and serverless](#edge-serverless).
+
+## Sélection d'un adaptateur {#selection}
+
+Ordre de résolution : un adaptateur explicitement enregistré gagne ; sinon, la variable env sélectionne un élément intégré ; sinon, la valeur locale par défaut est utilisée :
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### Variable d'environnement `AGENT_NATIVE_SANDBOX` {#env}
+
+Sélectionne un adaptateur intégré par identifiant. Actuellement, seul le `local` (valeur par défaut) est câblé ; les valeurs inconnues reviennent au niveau local plutôt que d'échouer l'exécution.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+Un processus hôte remplace le backend pour tous les appels `run-code` ultérieurs via le `index.ts` de la couture — par exemple, pour exécuter chaque appel dans un conteneur distant :
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## La couture pour un coureur durable {#durable}
+
+Cette interface est délibérément le joint d'un futur bac à sable distant/durable. Un adaptateur distant ou durable (Docker, un exécuteur de type Vercel-Sandbox ou un travailleur en arrière-plan en file d'attente) :
+
+1. Implémentez `SandboxAdapter.run` sur un environnement d'exécution hors processus.
+2. Tunnelez le pont de bouclage (ou le pont proxy rappelle le parent).
+3. Laissez les tâches de données volumineuses s'exécuter jusqu'à leur terme indépendamment du cycle de vie de la demande, en dépassant le plafond d'exécution de code hébergé d'environ 40 s qui limite l'adaptateur de processus enfant local.
+
+Enregistrez-le sous une nouvelle valeur `AGENT_NATIVE_SANDBOX` (par exemple `remote`) et/ou via `registerSandboxAdapter()`. La boucle d'agent et `run-code.ts` ne changent jamais.
+
+> [!TIP]
+> Le plan `agent-native add sandbox docker` émet une recette complète et autonome pour implémenter un adaptateur Docker contre cette couture. Voir [Blueprint Installer](/docs/blueprint-installer).
+
+# Adaptateurs CLI
+
+L'autre joint d'adaptateur enveloppe un seul outil de ligne de commande (`gh`, `ffmpeg`, `stripe`, `aws`) afin que l'agent puisse le découvrir, vérifier s'il est installé et l'exécuter avec un résultat stdout/stderr/exit-code cohérent. Chaque adaptateur CLI implémente `CliAdapter` :
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+Pour la plupart des CLI, `ShellCliAdapter` encapsule n'importe quel binaire avec des valeurs par défaut raisonnables, et `CliRegistry` collecte des adaptateurs pour la découverte du runtime :
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+Enveloppez un appel CLI dans `defineAction` pour l'exposer sur la surface d'action. Consultez la référence rapide [CLI Adapters](/docs/cli-adapters) pour les options `ShellCliAdapter`, les adaptateurs personnalisés et le modèle d'encapsulage d'action.
+
+## Edge et sans serveur {#edge-serverless}
+
+> [!WARNING]
+> Les deux coutures d'adaptateur reposent sur les fixations du système Node.js. Les adaptateurs sandbox `LocalChildProcessAdapter` et CLI (`ShellCliAdapter` et adaptateurs personnalisés) utilisent `node:child_process` (`execFile` / `spawn`), qui **n'existe pas** sur les environnements d'exécution Edge/Worker tels que Cloudflare Workers ou Netlify Edge Functions. Si vous déployez des routes de serveur vers ces préréglages Edge, l'exécution de ces adaptateurs génère une exception d'exécution. Exécutez les points de terminaison et les tâches de l'adaptateur dans un environnement Node.js standard (conteneurs de serveur traditionnels ou fonctions de nœud sans serveur) ou, pour la couture sandbox, enregistrez un adaptateur distant qui expédie le travail hors processus.
+
+## Quelle est la prochaine étape
+
+- [**CLI Adapters**](/docs/cli-adapters) — la référence rapide pour la couture CLI
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` imprime une recette d'adaptateur Docker
+- [**Agent Teams**](/docs/agent-teams) — déléguer des tâches lourdes à des sous-agents
+- [**Security**](/docs/security) – la posture de nettoyage d'environnement et de liste d'autorisation de pont