@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "Processeurs en boucle"
+description: "Crochets d'observateur/garde-corps internes à la boucle qui surveillent la sortie diffusée en continu du modèle et les appels d'outils à mi-exécution et peuvent l'interrompre : la couture pour les garde-corps en temps réel et les portes de validation."
+---
+
+# Processeurs en boucle
+
+Un `Processor` est un **observateur/garde-corps** interne à la boucle pour l'exécution de l'agent. Il surveille la sortie diffusée en continu du modèle et l'outil l'appelle _au fur et à mesure que l'exécution progresse_, conserve son propre état de travail et peut **abandonner** l'exécution avant qu'un « terminé » ne soit revendiqué. Il s'agit de la condition structurelle préalable aux garde-fous en temps réel (bloquer les sorties interdites à mi-parcours) et à une porte de preuve de réalisation/de couverture (inspecter ce que le modèle est sur le point de faire et l'arrêter).
+
+```an-diagram title="Where the three hooks fire in the run" summary="processOutputStream watches every chunk, processOutputStep gates tool calls per response, processOutputResult records a verdict at the end. Any hook can abort with a TripWire."
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — gate tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — verdict</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> Un processeur est une **configuration**, pas un outil, pas une action, ni une création DSL. Les processeurs observent et modifient uniquement leur propre état de flux et `abort()`. Ils ne définissent jamais le comportement de l'application, ne remplacent jamais actions et n'apparaissent jamais dans le modèle. Les opérations d'application appartiennent à [actions](/docs/actions).
+
+## Les crochets {#hooks}
+
+Un processeur implémente n'importe quel sous-ensemble de trois hooks de cycle de vie facultatifs (la forme est empruntée aux processeurs de sortie de Mastra) :
+
+| Crochet               | Feux…                                                                        | Utilisez-le pour…                                                                      |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `processOutputStream` | par morceau diffusé (texte/deltas de réflexion) pendant que le modèle génère | réagir à la sortie avant l'arrivée du tour complet                                     |
+| `processOutputStep`   | une fois par réponse du modèle, autour de l'exécution de l'outil             | inspectez les appels de l'outil, le modèle est sur le point de s'exécuter ; portez-les |
+| `processOutputResult` | une fois à la fin de l'exécution, avec le texte final de l'assistant         | enregistrer un verdict/une preuve de réussite sur la réponse complétée                 |
+
+Chaque processeur obtient son propre objet `state` mutable, à portée d'exécution, qui persiste dans chacun de ses appels de hook au cours d'une seule exécution et est **isolé** de l'état des autres processeurs.
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## Abandon avec `TripWire` {#tripwire}
+
+Un hook arrête l'exécution en appelant `abort(reason, meta?)`, qui renvoie un **`TripWire`**. La boucle l'attrape, émet un seul événement **`tripwire`**, s'arrête proprement et fait apparaître la raison comme message final de l'assistant.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+L'événement `tripwire` porte :
+
+| Champ       | Tapez    | Remarques                                                         |
+| ----------- | -------- | ----------------------------------------------------------------- |
+| `reason`    | `string` | Raison lisible par l'homme transmise à `abort`.                   |
+| `processor` | `string` | Nom du processeur qui a abandonné, lorsqu'il a déclaré un `name`. |
+
+`TripWire` comporte également un `meta` structuré facultatif et le nom d'origine `processor` pour les consommateurs programmatiques qui le vérifient par `instanceof`. Parce qu'un arrêt est gracieux, `processOutputResult` se déclenche toujours sur le texte final (arrêté) afin qu'un processeur de preuve de réalisation puisse enregistrer son verdict même lorsque l'exécution a été interrompue.
+
+## Processeurs de câblage {#wiring}
+
+Les processeurs sont configurés en code via le tableau `processors` sur `runAgentLoop` :
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**Zéro surcharge lorsqu'il n'est pas utilisé.** La boucle construit la chaîne de processeurs uniquement lorsqu'au moins un processeur est fourni ; lorsque `processors` est omis ou vide, aucun des codes de couture ne s'exécute et la boucle reste inchangée octet par octet. Les hooks s'exécutent dans l'ordre d'enregistrement et peuvent être synchronisés ou asynchrones.
+
+> [!NOTE]
+> La couture au niveau de la boucle est le livrable aujourd'hui et peut être appelée directement par les sous-agents, A2A, MCP et les tests. Faire passer `processors` via le gestionnaire de discussion HTTP (afin qu'un résolveur par requête puisse les configurer sans appeler directement `runAgentLoop`) est une plomberie pratique qui n'est pas encore câblée : configurez les processeurs sur le site d'appel `runAgentLoop` pour l'instant.
+
+## Connexe
+
+- [**Durable Resume**](/docs/durable-resume) — comment la boucle survit aux interruptions sans réexécuter les effets secondaires terminés.
+- [**Custom Agents & Teams**](/docs/agent-teams) — les sous-agents exécutent la même boucle et peuvent transporter leurs propres processeurs.
+- [**Observability**](/docs/observability) : enregistre les verdicts du processeur ainsi que les traces d'exécution.

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

@@ -0,0 +1,199 @@
+---
+title: "Progrès"
+description: "Signal de progression en direct pour les tâches d'agent de longue durée : démarrage, mise à jour, achèvement"
+---
+
+# Progrès
+
+Les tâches longues des agents ne doivent pas se cacher derrière une roulette. `progress_runs` donne à l'agent un moyen d'annoncer _"Je travaille là-dessus, j'ai terminé à 45 %, voici l'étape en cours"_ — que le UI affiche sous la forme d'un plateau d'exécutions flottant avec une barre de pourcentage.
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+Préoccupation distincte de [notifications](/docs/notifications) : les notifications se déclenchent une fois ("X s'est produit"_), la progression est continue (_"X est terminé à 45 %"\_). Les deux compositions - `completeRun` suivi de `notify(..., severity: "info")` indiquent à l'utilisateur quand le travail est terminé, même s'il ne regardait pas le plateau.
+
+## Le cycle de vie {#lifecycle}
+
+| Statut      | Transition                      |
+| ----------- | ------------------------------- |
+| `running`   | Initial — défini par `startRun` |
+| `succeeded` | Terminal Happy Path             |
+| `failed`    | Terminal d'erreur               |
+| `cancelled` | Utilisateur interrompu          |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Les états des terminaux sont définis `completed_at`. Le bac UI affiche uniquement les lignes `running` ; les lignes complétées restent dans la base de données pour les requêtes `action=list`.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+Créez une course. Renvoie le `AgentRun` complet avec un identifiant généré.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+Émet `run.progress.started` sur le bus d'événements.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+Corrigez n'importe quel champ d'une exécution en cours. Tout champ omis reste inchangé.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+Émet `run.progress.updated` sur le bus d'événements. Renvoie le `AgentRun` mis à jour, ou `null` si l'exécution n'existe pas ou n'appartient pas à l'appelant.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+Transition vers un statut de terminal. `succeeded` définit implicitement `percent=100`.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+Émet également `run.progress.updated` avec l'état du terminal.
+
+### Liste {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+Monté sur `/_agent-native/runs/*` par le plugin core-routes. **Lecture seule sur HTTP** : les écritures passent par les outils de l'agent puisque l'agent est l'écrivain canonique. Toutes les routes sont limitées au propriétaire.
+
+| Méthode  | Chemin                            |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## Composant UI {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+Widget d'en-tête intégré : installez-le à côté de la cloche de notifications. Affiche une icône de rotation + un badge de comptage lorsque les exécutions sont actives ; un clic ouvre une liste déroulante avec une barre de pourcentage en direct par exécution. Masque entièrement le déclencheur lorsqu’aucun actif n’est exécuté. Interroge `/_agent-native/runs?active=true` tous les `pollMs` (par défaut 3 s). Utilise des jetons sémantiques shadcn, s'adapte aux thèmes clairs et sombres.
+
+## Outil d'agent {#agent-tool}
+
+Un seul outil `manage-progress` est enregistré dans chaque modèle. Le paramètre `action` sélectionne l'opération :
+
+| Actions    | Objectif                                                             |
+| ---------- | -------------------------------------------------------------------- |
+| `start`    | Appel en début de tâche longue. Renvoie un runId.                    |
+| `update`   | Appelez périodiquement pendant la tâche avec `percent` et/ou `step`. |
+| `complete` | Terminal : un parmi `succeeded`, `failed`, `cancelled`.              |
+| `list`     | Inspecter les exécutions récentes (filtrer par `active=true`).       |
+
+### Quand démarrer une course {#when-to-start}
+
+- À utiliser pour tout ce qui dépasse > ~5 secondes. Un spinner sans contexte semble figé.
+- Mise à jour aux points de contrôle naturels, pas à chaque itération. Chaque 5 à 10 % est suffisant.
+- **Toujours** appeler `manage-progress` avec `action=complete`, y compris dans les chemins d'erreur. Une ligne `running` orpheline est pire que pas de ligne.
+- Associez-le à `notify` une fois terminé afin que l'utilisateur voie le résultat lorsqu'il ne regarde pas activement le plateau.
+
+## Bus d'événements {#event-bus}
+
+Deux événements émettent sur le [event bus](/docs/automations#event-bus) :
+
+| Événement              | Charge utile                       |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) peut s'y abonner — par exemple, *"si une course dure plus de 5 minutes, prévenez-moi"* :
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## Comment ça marche {#internals}
+
+- **Portée du propriétaire** : chaque ligne comporte une colonne `owner` ; chaque requête filtre dessus. Les utilisateurs voient uniquement leurs propres courses.
+- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client) s'invalident automatiquement sans aucun câblage supplémentaire.
+- **Nom de la table** — le framework dispose également d'une table `agent_runs` pour le suivi interne du cycle de vie des tours de discussion des agents. La primitive de progression utilise `progress_runs` pour séparer les deux préoccupations.
+- **Pourcentage de serrage** : les valeurs sont limitées à `[0, 100]` et arrondies à un nombre entier lors de l'écriture.
+
+## Quelle est la prochaine étape
+
+- [**Notifications**](/docs/notifications) : associez-le à `manage-progress` (`action=complete`) pour indiquer à l'utilisateur la fin du travail
+- [**Automations**](/docs/automations) – fonctionnement lent du chien de garde via `run.progress.updated`
+- [**Client**](/docs/client) — `useDbSync` pour l'invalidation du cache en temps réel

package/corpus/core/docs/content/locales/fr-FR/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "Applications Pure-Agent"
+description: "Applications dans lesquelles l'agent représente l'ensemble du produit : la boucle application-agent est la porte d'entrée et UI n'est ajouté que lorsque les humains en ont besoin."
+---
+
+# Applications Pure-Agent
+
+Une application purement agent est la fin minimale de l'agent natif : la boucle application-agent est la
+produit, pas un tableau de bord. Vous envoyez une requête depuis le terminal, Slack, email, un
+tâche planifiée, un autre agent ou Chat – "résumer mes e-mails non lus", "publier le
+mesures quotidiennes vers Slack" — et l'agent agit et renvoie le résultat où qu'il soit
+appartient. C'est toujours une vraie application : actions, sessions, état de l'application, historique,
+les paramètres, les informations d'identification et les enregistrements de partage sont tous présents dans SQL.
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+Atteignez cette forme lorsque le travail s'exécute en arrière-plan, la sortie quitte le
+, le domaine est unique ou vous êtes en train de créer un prototype. L'agent a toujours besoin d'un UI —
+pas un tableau de bord, mais un endroit où les humains peuvent le superviser, le configurer et le piloter —
+c'est pourquoi même les applications purement agents montent généralement le shell Chat intégré.
+
+Il s'agit de la forme du produit **sans tête**. Le guide de décision complet, ce qui est livré
+la boîte, l'échafaudage, l'accès au dépôt et le partage d'exécution se trouvent désormais au même endroit :
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## Quelle est la prochaine étape
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) – le guide de décision complet sans tête et les API
+- [**Getting Started**](/docs/getting-started) : créez d'abord une application de chat ou un agent sans tête
+- [**Dispatch**](/docs/template-dispatch) : le modèle d'espace de travail qui constitue un excellent point de départ pour les agents purs
+- [**Messaging the agent**](/docs/messaging) : comment les utilisateurs parlent à l'agent sur le Web, Slack, Telegram, e-mail
+- [**Recurring Jobs**](/docs/recurring-jobs) : invites planifiées que l'agent exécute tout seul
+- [**Actions**](/docs/actions) — les outils que votre agent pur appellera