@mostajs/chatbot 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
 
+## 0.3.0 — 2026-06-11
+- **Agent assignable (générique)** : l'assistant devient un **acteur de 1ʳᵉ classe**. Nouveau `src/agent.ts` —
+  `AgentIdentity {id,name,kind:"assistant"}` (config `createChatbot({agent:{id?,name?}})`, défaut `assistant`/`Assistant`)
+  + **`AssignableAgentPort`** (contrat d'**injection** : l'app hôte fournit la liaison de SON domaine — CRM→Employee/commande,
+  race-event→un autre acteur). `createChatbot` accepte `agent?`/`assignable?` et expose `agent()`, `isAgent(id)`,
+  `ensureAssignable()`, `assignableLabel(id)`. Le module reste **agnostique** (aucune notion d'« Employee »). Compat **100 %**
+  (options additives). Exports : `DEFAULT_AGENT`, `resolveAgent`, types `AgentIdentity`/`AgentConfig`/`AssignableAgentPort`.
+
 ## 0.2.0 — 2026-06-10
 - **Extraction en modules (façon @mostajs/orm)** : la couche LLM et la boucle/routeur quittent le chatbot.
   - **`@mostajs/llm`** : dialectes (1 par IA) + registre + types function-calling (déplacés depuis `src/dialects/`).

package/README.md

@@ -4,17 +4,18 @@
 
 Assistant / copilote / agent conversationnel **générique et réutilisable** pour les apps `@mostajs/*`.
 **Activable/désactivable** et **entièrement piloté par `.env`**. Backends pluggables (`scripted` sans IA,
-`ai` avec LLM), **providers LLM pluggables avec fallback** (`anthropic`/`claude-opus-4-8`, `deepseek`),
-ancrage **tool-use** sur les données de l'app, **recherche web** optionnelle. Registres façon dialectes ORM.
+`ai` avec LLM, `router` hybride), **providers LLM pluggables avec fallback** (`anthropic`/`claude-opus-4-8`,
+`deepseek`), ancrage **tool-use** sur les données de l'app, **recherche web** optionnelle, et l'assistant
+peut devenir un **membre du personnel assignable** dans votre domaine. Registres façon dialectes ORM.
 
-> Statut : **0.0.1 (scaffold)**. Livrables DEVRULES #1-#3 dans `docs/`. Voir `llms.txt` pour l'API complète.
+> Statut : **0.3.0**. Voir `llms.txt` pour l'API dense et `CHANGELOG.md` pour l'historique.
 
 ## Configuration (`.env` — tout par config)
 ```
 CHATBOT_ENABLED=1                       # interrupteur maître (défaut 0)
 CHATBOT_ROLES=admin,employe             # vide = tous
 CHATBOT_MODE=assistant                  # assistant | agent
-CHATBOT_BACKEND=ai                      # scripted (défaut) | ai
+CHATBOT_BACKEND=router                  # scripted (défaut) | ai | router (hybride : intents sans IA, IA en repli)
 CHATBOT_PROVIDERS=deepseek,anthropic    # liste priorité + fallback
 CHATBOT_MODEL=                          # vide ⇒ défaut du provider
 ANTHROPIC_API_KEY=...                   # provider anthropic
@@ -24,27 +25,127 @@ CHATBOT_WEB_SEARCH=0                    # recherche web (anthropic)
 CHATBOT_EFFORT=high
 ```
 
-## Usage (Next.js)
+## 1. Intégrer le chatbot dans n'importe quelle application
+
+L'app fournit son **profil métier** (`domain`), ses **outils** (`tools`) et, en option, ses **intents**
+déterministes. Le module route vers le backend configuré (`.env`).
+
 ```ts
-// serveur
-import { createChatbot, registerTool } from "@mostajs/chatbot";
-registerTool({ name:"orders_by_state", description:"Compter les commandes par état",
-  schema:{ type:"object", properties:{ state:{type:"string"} }, required:["state"] },
-  permission:"order.read", run: async ({state}, actor) => /* requête dépôt */ 0 });
-const bot = createChatbot({ domain:{ appName:"CRM TRADING",
-  description:"Société de négoce : commandes, fournisseurs, proformats.", locale:"fr" } });
-if (bot.enabled()) { const answer = await bot.ask([{role:"user",content:"aide"}], actor); }
+// serveur (un seul endroit) — lib/chatbot.ts
+import { createChatbot } from "@mostajs/chatbot";
+
+const bot = createChatbot({
+  domain: {
+    appName: "Mon App",
+    description: "Décrit le métier → injecté dans le prompt système.",
+    locale: "fr",
+    rules: ["Toujours demander confirmation avant une action.", "Ne jamais exposer de secret."],
+  },
+  // ...tools / intents : voir §3
+});
+
+// Server action consommée par le widget
+export async function askAction(text: string): Promise<string> {
+  const actor = await getActor();                       // { id, role, permissions }
+  if (!bot.enabled()) return "Assistant désactivé.";
+  return bot.ask([{ role: "user", content: text }], actor);
+}
 ```
 ```tsx
-// client (widget)
+// client (widget bulle + panneau)
 import { Chatbot } from "@mostajs/chatbot/client";
-<Chatbot send={askServerAction} title="Assistant TRADING" />
+<Chatbot send={askAction} title="Assistant" greeting="Bonjour 👋" />
+```
+
+> Le widget est `"use client"`. Importez `createChatbot` (serveur) à part et passez-lui un `send()` (server action).
+
+## 2. Faire de l'assistant un **membre du personnel** (agent assignable)
+
+L'assistant est un **acteur de première classe** : il a une **identité** (`agent`) et, via le contrat
+d'injection **`AssignableAgentPort`**, l'app le **branche comme acteur assignable de SON domaine** — un
+employé qu'on assigne à une tâche, un opérateur, un agent de traitement… Le module reste **agnostique** :
+il ne connaît ni « employé », ni « commande » ; **vous** fournissez la liaison.
+
+```ts
+import { createChatbot, type AssignableAgentPort } from "@mostajs/chatbot";
+
+// L'adaptateur de VOTRE domaine : ici, l'agent est matérialisé comme un "employé" assignable.
+// (Une autre app le brancherait sur une autre entité — ou pas du tout.)
+const staffAgent: AssignableAgentPort = {
+  // seed idempotent → renvoie l'id de l'agent côté hôte (apparaît alors dans vos listes d'assignation)
+  ensure: async () => upsertEmployee({ email: "assistant@app.bot", name: "🤖 Assistant" }),
+  // cet id d'acteur est-il l'agent ?
+  isAgent: async (id) => (await getEmployee(id))?.email === "assistant@app.bot",
+  label: () => "🤖 Assistant",
+};
+
+const bot = createChatbot({
+  domain: { appName: "Mon App", description: "…", locale: "fr" },
+  agent: { id: "assistant", name: "🤖 Assistant" },   // identité (défaut: { id:"assistant", name:"Assistant" })
+  assignable: staffAgent,                               // liaison au domaine
+  // tools/intents…
+});
+
+await bot.ensureAssignable();        // garantit que l'agent existe comme acteur assignable (au boot)
+bot.agent();                         // { id:"assistant", name:"🤖 Assistant", kind:"assistant" }
+await bot.isAgent(someActorId);      // true si cet acteur EST l'assistant
+bot.assignableLabel(someActorId);    // libellé d'affichage côté hôte
 ```
 
+Schéma : **le module possède le *concept*** (identité + `AssignableAgentPort`), **votre app possède la
+*liaison*** (l'adaptateur ci-dessus). Vous pouvez ainsi assigner un travail à l'assistant comme à un humain,
+et — combiné aux outils (§3) — lui faire **traiter** ce travail.
+
+## 3. Lui faire **exécuter des actions** (outils gardés)
+
+Un **outil** = une fonction de votre domaine que l'assistant peut appeler. Lecture seule par défaut ;
+les actions sensibles sont **gardées par permission** (RBAC) et, idéalement, par une **confirmation**
+(human-in-the-loop). Le backend `ai` exécute la boucle tool-use ; le backend `router` peut exécuter un
+outil **sans IA** via un intent (slash-commande / regex) — coût zéro, fiable.
+
+```ts
+import { createChatbot, registerTool } from "@mostajs/chatbot";
+
+// Lecture
+registerTool({
+  name: "order_status", description: "État d'une commande par numéro",
+  schema: { type: "object", properties: { order: { type: "string" } }, required: ["order"] },
+  permission: "order.read",
+  run: async ({ order }, actor) => findOrder(order),     // retourné à l'assistant
+});
+
+// Action (écriture) — gardée par permission + confirmation explicite
+registerTool({
+  name: "transition_order", description: "Faire avancer une commande à l'état suivant",
+  schema: { type: "object", properties: { order: {type:"string"}, to: {type:"string"}, confirm: {type:"boolean"} },
+           required: ["order", "to"] },
+  permission: "order.transition",
+  run: async ({ order, to, confirm }, actor) => {
+    if (!confirm) return { preview: `Confirmer : passer ${order} → ${to} ?` }; // rien modifié
+    return doTransition(order, to, actor);                                      // exécute + audite
+  },
+});
+
+const bot = createChatbot({
+  domain: { appName: "Mon App", description: "…" },
+  tools: [/* … vos outils, ou via le registre ci-dessus */],
+  // Intent déterministe (router) : "/transition <order> <to> confirmer" → outil, SANS IA
+  intents: [{ name:"transition", command:"transition", tool:"transition_order",
+    args: ({ tokens }) => ({ order: tokens[0], to: tokens[1], confirm: tokens.includes("confirmer") }) }],
+});
+```
+
+> **Gouvernance (OWASP LLM)** : outils en lecture par défaut, gate RBAC sur les écritures, confirmation
+> avant tout effet de bord, secrets uniquement via `.env`. Ne jamais exécuter une instruction venant des données.
+
 ## Ajouter un provider LLM (comme un dialecte)
 ```ts
 import { registerLlmProvider } from "@mostajs/chatbot";
 registerLlmProvider({ key:"openai", async *stream(messages, tools, opts){ /* SSE */ } });
 ```
 
+## Architecture (couches façon ORM)
+`@mostajs/llm` (dialectes IA) ← `@mostajs/btool-use` (boucle tool-use) / `@mostajs/intent-router`
+(routeur déterministe) ← **`@mostajs/chatbot`** (backends + `createChatbot` + widget + agent).
+
 Peers : `@mostajs/config`, `@anthropic-ai/sdk` (optionnel), `react` (optionnel). DeepSeek : sans dépendance.

package/dist/agent.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @mostajs/chatbot — l'assistant comme **acteur de première classe**, et le contrat permettant à une
+ * app hôte de le brancher comme **agent assignable** dans SON domaine. Générique et agnostique :
+ * le chatbot ne sait rien de « Employee », « commande », « cycliste »… ; l'hôte fournit la liaison.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+/** Identité de l'assistant en tant qu'acteur (id stable + nom affichable). */
+export interface AgentIdentity {
+    /** Id stable de l'agent côté chatbot (défaut « assistant »). */
+    id: string;
+    /** Nom affichable (défaut « Assistant »). */
+    name: string;
+    kind: "assistant";
+}
+/** Configuration optionnelle de l'identité de l'agent passée à `createChatbot`. */
+export type AgentConfig = {
+    id?: string;
+    name?: string;
+};
+/**
+ * Contrat d'**injection** : comment l'app hôte matérialise l'agent comme **acteur assignable** dans
+ * son propre domaine (CRM → Employee assigné aux commandes ; race-event → un autre acteur ; etc.).
+ * Le module possède le *concept* ; l'hôte possède la *liaison*. Toutes les méthodes sont optionnelles
+ * à fournir côté hôte sauf `ensure`/`isAgent`.
+ */
+export interface AssignableAgentPort {
+    /** Seed idempotent de l'agent comme acteur assignable de l'hôte ; renvoie son id côté hôte. */
+    ensure(): Promise<string>;
+    /** Cet id d'acteur (côté hôte) est-il l'agent-assistant ? */
+    isAgent(id: string | undefined): boolean | Promise<boolean>;
+    /** Libellé d'affichage optionnel de l'agent côté hôte (ex. « 🤖 Assistant TRADING »). */
+    label?(id: string): string;
+}
+/** Identité par défaut si l'app n'en fournit aucune. */
+export declare const DEFAULT_AGENT: AgentIdentity;
+/** Résout l'identité de l'agent depuis la config (valeurs par défaut sûres). */
+export declare function resolveAgent(cfg?: AgentConfig): AgentIdentity;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,14 @@
+/**
+ * @mostajs/chatbot — l'assistant comme **acteur de première classe**, et le contrat permettant à une
+ * app hôte de le brancher comme **agent assignable** dans SON domaine. Générique et agnostique :
+ * le chatbot ne sait rien de « Employee », « commande », « cycliste »… ; l'hôte fournit la liaison.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
+ */
+/** Identité par défaut si l'app n'en fournit aucune. */
+export const DEFAULT_AGENT = { id: "assistant", name: "Assistant", kind: "assistant" };
+/** Résout l'identité de l'agent depuis la config (valeurs par défaut sûres). */
+export function resolveAgent(cfg) {
+    return { id: cfg?.id ?? DEFAULT_AGENT.id, name: cfg?.name ?? DEFAULT_AGENT.name, kind: "assistant" };
+}
+//# sourceMappingURL=agent.js.map

package/dist/client.d.ts

@@ -1,6 +1,14 @@
-export declare function Chatbot({ send, title, greeting }: {
+interface Msg {
+    role: "user" | "assistant";
+    content: string;
+}
+export declare function Chatbot({ send, title, greeting, loadHistory, onExport, onReset }: {
     send: (text: string) => Promise<string>;
     title?: string;
     greeting?: string;
+    loadHistory?: () => Promise<Msg[]>;
+    onExport?: (format: "html" | "pdf") => Promise<string | void>;
+    onReset?: () => Promise<void>;
 }): import("react").JSX.Element;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -1,17 +1,31 @@
 /**
- * @mostajs/chatbot/client — widget React minimal (bulle + panneau). L'app fournit `send(text)`
- * (qui appelle son endpoint serveur → createChatbot). Styles : classes `cbot-*` côté hôte.
- * (0.0.1 : non-streaming. Streaming SSE en 0.3.)
+ * @mostajs/chatbot/client — widget React (bulle + panneau). L'app fournit `send(text)` (→ endpoint
+ * serveur → createChatbot). Optionnel : `loadHistory` (reprend le fil à la 1ʳᵉ ouverture), `onExport`
+ * (exporte la conversation, ouvre l'URL renvoyée), `onReset` (nouvelle conversation). Styles `cbot-*` côté hôte.
  * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later
  */
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-export function Chatbot({ send, title = "Assistant", greeting = "Bonjour 👋" }) {
+export function Chatbot({ send, title = "Assistant", greeting = "Bonjour 👋", loadHistory, onExport, onReset }) {
     const [open, setOpen] = useState(false);
     const [msgs, setMsgs] = useState([{ role: "assistant", content: greeting }]);
     const [val, setVal] = useState("");
     const [busy, setBusy] = useState(false);
+    const [loaded, setLoaded] = useState(false);
+    async function toggle() {
+        const willOpen = !open;
+        setOpen(willOpen);
+        if (willOpen && !loaded && loadHistory) {
+            setLoaded(true);
+            try {
+                const h = await loadHistory();
+                if (h && h.length)
+                    setMsgs([{ role: "assistant", content: greeting }, ...h]);
+            }
+            catch { /* ignore */ }
+        }
+    }
     const submit = async (e) => {
         e.preventDefault();
         const t = val.trim();
@@ -29,6 +43,27 @@ export function Chatbot({ send, title = "Assistant", greeting = "Bonjour 👋" }
         }
         setBusy(false);
     };
-    return (_jsxs("div", { className: "cbot", children: [open ? (_jsxs("div", { className: "cbot-panel", role: "dialog", children: [_jsxs("div", { className: "cbot-head", children: [_jsx("span", { children: title }), _jsx("button", { className: "cbot-x", onClick: () => setOpen(false), "aria-label": "Fermer", children: "\u00D7" })] }), _jsxs("div", { className: "cbot-msgs", children: [msgs.map((m, i) => _jsx("div", { className: `cbot-msg ${m.role}`, children: m.content }, i)), busy ? _jsx("div", { className: "cbot-msg assistant cbot-typing", children: "\u2026" }) : null] }), _jsxs("form", { className: "cbot-form", onSubmit: submit, children: [_jsx("input", { value: val, onChange: (e) => setVal(e.target.value), placeholder: "Votre question\u2026" }), _jsx("button", { className: "cbot-send", type: "submit", disabled: busy, children: "\u27A4" })] })] })) : null, _jsx("button", { className: "cbot-fab", onClick: () => setOpen((v) => !v), "aria-label": title, children: "\uD83E\uDD16" })] }));
+    async function doExport(fmt) {
+        if (!onExport || busy)
+            return;
+        setBusy(true);
+        try {
+            const url = await onExport(fmt);
+            if (typeof url === "string" && url)
+                window.open(url, "_blank");
+        }
+        catch { /* ignore */ }
+        setBusy(false);
+    }
+    async function doReset() {
+        if (!onReset)
+            return;
+        try {
+            await onReset();
+        }
+        catch { /* ignore */ }
+        setMsgs([{ role: "assistant", content: greeting }]);
+    }
+    return (_jsxs("div", { className: "cbot", children: [open ? (_jsxs("div", { className: "cbot-panel", role: "dialog", children: [_jsxs("div", { className: "cbot-head", children: [_jsx("span", { children: title }), _jsxs("span", { style: { display: "flex", gap: 4, alignItems: "center" }, children: [onReset ? _jsx("button", { className: "cbot-x", title: "Nouvelle conversation", onClick: doReset, children: "\uD83D\uDD04" }) : null, onExport ? _jsx("button", { className: "cbot-x", title: "Exporter (HTML)", onClick: () => doExport("html"), children: "\u2913" }) : null, onExport ? _jsx("button", { className: "cbot-x", title: "Exporter (PDF)", style: { fontSize: ".7rem" }, onClick: () => doExport("pdf"), children: "PDF" }) : null, _jsx("button", { className: "cbot-x", onClick: () => setOpen(false), "aria-label": "Fermer", children: "\u00D7" })] })] }), _jsxs("div", { className: "cbot-msgs", children: [msgs.map((m, i) => _jsx("div", { className: `cbot-msg ${m.role}`, children: m.content }, i)), busy ? _jsx("div", { className: "cbot-msg assistant cbot-typing", children: "\u2026" }) : null] }), _jsxs("form", { className: "cbot-form", onSubmit: submit, children: [_jsx("input", { value: val, onChange: (e) => setVal(e.target.value), placeholder: "Votre question\u2026" }), _jsx("button", { className: "cbot-send", type: "submit", disabled: busy, children: "\u27A4" })] })] })) : null, _jsx("button", { className: "cbot-fab", onClick: toggle, "aria-label": title, children: "\uD83E\uDD16" })] }));
 }
 //# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -16,19 +16,34 @@ import "./backends/scripted.js";
 import "./backends/ai.js";
 import "./backends/router.js";
 import type { ChatChunk, ChatMessage, ChatActor, DomainProfile, ChatTool, ChatIntent } from "./types.js";
+import { type AgentConfig, type AgentIdentity, type AssignableAgentPort } from "./agent.js";
 export interface ChatbotOptions {
     domain: DomainProfile;
     tools?: ChatTool[];
     intents?: ChatIntent[];
+    /** Identité de l'assistant comme acteur (id/nom) — défaut `{ id:"assistant", name:"Assistant" }`. */
+    agent?: AgentConfig;
+    /** Liaison (DI) rendant l'agent **assignable** dans le domaine de l'app hôte (cf. `AssignableAgentPort`). */
+    assignable?: AssignableAgentPort;
 }
 export declare function createChatbot(options: ChatbotOptions): {
     enabled: () => boolean;
     stream: (messages: ChatMessage[], actor: ChatActor) => AsyncIterable<ChatChunk>;
     ask: (messages: ChatMessage[], actor: ChatActor) => Promise<string>;
+    /** Identité de l'assistant (acteur de 1ʳᵉ classe). */
+    agent: () => AgentIdentity;
+    /** Cet id d'acteur (côté hôte) est-il l'agent ? Délègue au port d'assignation s'il est fourni. */
+    isAgent: (id?: string) => Promise<boolean>;
+    /** Garantit (seed idempotent) l'agent comme acteur assignable de l'hôte → renvoie son id côté hôte. */
+    ensureAssignable: () => Promise<string>;
+    /** Libellé d'affichage de l'agent côté hôte (si le port en fournit un). */
+    assignableLabel: (id: string) => string | undefined;
 };
 export type { ChatbotOptions as Options };
 export type { AskContext, ChatChunk, ChatMessage, ChatActor, DomainProfile, ChatTool, ChatIntent, IChatBackend, ILlmProvider, ILlmDialect, ToolCall, LlmMessage, LlmTurn, ChatbotMode, LlmStreamOpts, } from "./types.js";
 export { registerBackend, getBackend, listBackends, registerTool, getTool, listTools } from "./registry.js";
+export { DEFAULT_AGENT, resolveAgent } from "./agent.js";
+export type { AgentIdentity, AgentConfig, AssignableAgentPort } from "./agent.js";
 export { registerLlmProvider, getLlmProvider, listLlmProviders, registerDialect, getDialect, listDialects, getSupportedDialects, AbstractLlmDialect, OpenAiDialect, DeepSeekDialect, MistralDialect, GroqDialect, OllamaDialect, AnthropicDialect, } from "@mostajs/llm";
 export { runToolLoop } from "@mostajs/btool-use";
 export { matchIntent, runIntent } from "@mostajs/intent-router";

package/dist/index.js

@@ -17,7 +17,10 @@ import "./backends/ai.js";
 import "./backends/router.js";
 import { getBackend } from "./registry.js";
 import { chatbotEnabled, chatbotBackend, chatbotAllowsRole, chatbotMode } from "./config.js";
+import { resolveAgent } from "./agent.js";
 export function createChatbot(options) {
+    const agent = resolveAgent(options.agent);
+    const assignable = options.assignable;
     async function* stream(messages, actor) {
         if (!chatbotAllowsRole(actor.role)) {
             yield { type: "error", text: "Assistant désactivé pour votre profil." };
@@ -34,9 +37,23 @@ export function createChatbot(options) {
                 out += c.text;
         return out;
     }
-    return { enabled: () => chatbotEnabled(), stream, ask };
+    return {
+        enabled: () => chatbotEnabled(),
+        stream,
+        ask,
+        /** Identité de l'assistant (acteur de 1ʳᵉ classe). */
+        agent: () => agent,
+        /** Cet id d'acteur (côté hôte) est-il l'agent ? Délègue au port d'assignation s'il est fourni. */
+        isAgent: async (id) => (assignable ? !!(await assignable.isAgent(id)) : id === agent.id),
+        /** Garantit (seed idempotent) l'agent comme acteur assignable de l'hôte → renvoie son id côté hôte. */
+        ensureAssignable: async () => (assignable ? assignable.ensure() : agent.id),
+        /** Libellé d'affichage de l'agent côté hôte (si le port en fournit un). */
+        assignableLabel: (id) => assignable?.label?.(id),
+    };
 }
 export { registerBackend, getBackend, listBackends, registerTool, getTool, listTools } from "./registry.js";
+// Agent : l'assistant comme acteur assignable (générique ; l'app hôte fournit la liaison de domaine).
+export { DEFAULT_AGENT, resolveAgent } from "./agent.js";
 // Réexports de la couche LLM (compat : ces symboles vivaient dans @mostajs/chatbot avant l'extraction).
 export { registerLlmProvider, getLlmProvider, listLlmProviders, registerDialect, getDialect, listDialects, getSupportedDialects, AbstractLlmDialect, OpenAiDialect, DeepSeekDialect, MistralDialect, GroqDialect, OllamaDialect, AnthropicDialect, } from "@mostajs/llm";
 export { runToolLoop } from "@mostajs/btool-use";

package/llms.txt

@@ -10,9 +10,11 @@ défaut, RBAC) ; le module route vers le **backend** configuré et, en mode `ai`
 (avec fallback). Aucune logique d'une app particulière dans le module (réutilisable partout : CRM, santé, …).
 
 ## EXPORTS
-- `.` (serveur-safe) : `createChatbot({domain,tools})` → `{enabled(), stream(messages,actor), ask(messages,actor)}` ;
+- `.` (serveur-safe) : `createChatbot({domain,tools,intents?,agent?,assignable?})` → `{enabled(), stream, ask,
+  agent(), isAgent(id), ensureAssignable(), assignableLabel(id)}` ;
   `registerBackend/getBackend/listBackends`, `registerLlmProvider/getLlmProvider/listLlmProviders`,
-  `registerTool/getTool/listTools` ; toute la config (`chatbot*`) ; types.
+  `registerTool/getTool/listTools` ; **agent** : `DEFAULT_AGENT`/`resolveAgent` + types `AgentIdentity`/`AgentConfig`/`AssignableAgentPort` ;
+  toute la config (`chatbot*`) ; types.
 - `./server` : built-ins concrets (`scriptedBackend`, `aiBackend`, `anthropicProvider`, `deepseekProvider`).
 - `./client` (React) : `<Chatbot send=… title? greeting? />` (widget bulle+panneau ; SSE en 0.3).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/chatbot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Assistant / copilote / agent conversationnel générique et réutilisable pour apps @mostajs/* — backends pluggables (scripted | ai), providers LLM pluggables (anthropic/claude-opus-4-8 par défaut), ancrage tool-use, recherche web optionnelle. Activable/désactivable par .env.",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",