intermesh 0.3.0__tar.gz → 0.4.0__tar.gz

{intermesh-0.3.0 → intermesh-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intermesh
-Version: 0.3.0
+Version: 0.4.0
 Summary: Universal coordination protocol for AI agents — E2E encrypted, cross-language, federated
 Author: InterMesh Protocol Authors
 License: Apache-2.0
@@ -26,6 +26,8 @@ Description-Content-Type: text/markdown
 Requires-Dist: websockets>=12.0
 Requires-Dist: PyJWT>=2.8.0
 Requires-Dist: cryptography>=42.0.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
 
 # InterMesh — Python SDK
 

{intermesh-0.3.0 → intermesh-0.4.0}/intermesh/__init__.py

@@ -53,4 +53,4 @@ try:
 except ImportError:
     pass
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{intermesh-0.3.0 → intermesh-0.4.0}/intermesh/admin.py

@@ -57,6 +57,8 @@ MUTATING = {
     "task.retry",
     "apikey.create",
     "apikey.revoke",
+    "approval.approve",
+    "approval.deny",
     "guardrails.set_policy",
     "escrow.grant",
     "escrow.release",
@@ -93,7 +95,14 @@ class AdminContext:
         asimov_engine: Any = None,
         escrow_manager: Any = None,
         snapshot_dir: Any = None,
+        pending_approvals: Any = None,
+        finalize_task: Callable | None = None,
     ):
+        # Tâches retenues en attente d'arbitrage humain, et le moyen de les
+        # relâcher. `finalize_task` est le même chemin que celui d'une
+        # soumission ordinaire : approuver ne doit pas livrer autrement.
+        self.pending_approvals = pending_approvals if pending_approvals is not None else {}
+        self.finalize_task = finalize_task
         self.snapshot_dir = snapshot_dir
         self.agents = agents
         self.identity_registry = identity_registry
@@ -274,6 +283,7 @@ def _tasks_list(ctx: AdminContext, params: dict) -> dict:
             {
                 "task_id": t.task_id,
                 "title": t.title,
+                "summary": t.summary,
                 "orchestrator": t.orchestrator,
                 "assignee": t.assignee,
                 "status": t.status.value,
@@ -694,6 +704,91 @@ def _snapshot_restore(ctx: AdminContext, params: dict) -> dict:
     }
 
 
+def _pending_in_scope(ctx: AdminContext, entry: dict) -> bool:
+    if not ctx.scoped:
+        return True
+    task = entry.get("task") or {}
+    return ctx.caller_org in (_org_of(entry.get("submitter")), _org_of(task.get("assignee")))
+
+
+def _approvals_list(ctx: AdminContext, params: dict) -> dict:
+    """Tâches en attente d'un arbitrage humain.
+
+    La charge utile de la tâche n'est pas renvoyée : elle peut contenir les
+    données mêmes que l'organisation ne veut pas voir circuler. Ce qui est
+    montré est ce qu'il faut pour décider — qui demande, pour qui, et la
+    raison écrite dans la règle.
+    """
+    out = []
+    for task_id, entry in ctx.pending_approvals.items():
+        if not _pending_in_scope(ctx, entry):
+            continue
+        task = entry.get("task") or {}
+        out.append({
+            "task_id": task_id,
+            "title": task.get("title"),
+            "submitter": entry.get("submitter"),
+            "assignee": task.get("assignee"),
+            "rule": entry.get("rule"),
+            "reason": entry.get("reason"),
+            "estimated_cost": task.get("estimated_cost"),
+            "submitted_at": entry.get("submitted_at"),
+        })
+    out.sort(key=lambda e: e.get("submitted_at") or 0)
+    return {"pending": out, "count": len(out)}
+
+
+def _pop_pending(ctx: AdminContext, params: dict) -> tuple[str, dict]:
+    task_id = params.get("task_id")
+    entry = ctx.pending_approvals.get(task_id)
+    if entry is None:
+        raise AdminError("Aucune tâche en attente d'approbation sous cet identifiant.")
+    if not _pending_in_scope(ctx, entry):
+        raise AdminError("Cette tâche est hors de votre organisation.")
+    return task_id, ctx.pending_approvals.pop(task_id)
+
+
+async def _approval_approve(ctx: AdminContext, params: dict) -> dict:
+    """Relâche une tâche retenue, par le même chemin qu'une soumission normale.
+
+    Le séquestre est constitué maintenant, pas au moment de la soumission :
+    rien n'aura été immobilisé pendant l'attente. Le revers est qu'il peut
+    échouer ici, faute de fonds — l'erreur est alors renvoyée à
+    l'approbateur plutôt que masquée.
+    """
+    task_id, entry = _pop_pending(ctx, params)
+    approver = params.get("_approver") or "admin"
+
+    if ctx.finalize_task is None:
+        raise AdminError("Ce Hub ne sait pas relâcher une tâche approuvée.")
+
+    err = await ctx.finalize_task(entry["task"], entry["submitter"], entry.get("token"))
+    if err:
+        # La tâche ressort de la file : elle n'a pas été livrée, et la
+        # remettre en attente laisse une chance de réapprouver une fois le
+        # solde reconstitué, au lieu de la perdre.
+        ctx.pending_approvals[task_id] = entry
+        raise AdminError(f"Approuvée, mais non livrée : {err}")
+
+    ctx.audit_log.log("APPROVAL_GRANTED", approver, entry["task"].get("assignee"), {
+        "task_id": task_id, "rule": entry.get("rule"), "submitter": entry.get("submitter"),
+    })
+    return {"task_id": task_id, "status": "approved"}
+
+
+def _approval_deny(ctx: AdminContext, params: dict) -> dict:
+    """Refuse une tâche retenue. Aucun séquestre n'existe, rien à défaire."""
+    task_id, entry = _pop_pending(ctx, params)
+    approver = params.get("_approver") or "admin"
+    note = params.get("note") or ""
+
+    ctx.audit_log.log("APPROVAL_DENIED", approver, entry["task"].get("assignee"), {
+        "task_id": task_id, "rule": entry.get("rule"),
+        "submitter": entry.get("submitter"), "note": note,
+    })
+    return {"task_id": task_id, "status": "denied", "note": note}
+
+
 HANDLERS: dict[str, Callable[..., Any]] = {
     "hub.info": _hub_info,
     "agents.list": _agents_list,
@@ -706,6 +801,9 @@ HANDLERS: dict[str, Callable[..., Any]] = {
     "apikeys.list": _apikeys_list,
     "apikey.create": _apikey_create,
     "apikey.revoke": _apikey_revoke,
+    "approvals.list": _approvals_list,
+    "approval.approve": _approval_approve,
+    "approval.deny": _approval_deny,
     "guardrails.policy": _guardrails_policy,
     "guardrails.set_policy": _guardrails_set_policy,
     "escrow.balance": _escrow_balance,

{intermesh-0.3.0 → intermesh-0.4.0}/intermesh/agent.py

@@ -136,12 +136,34 @@ class InterMeshAgent:
             if "org_id" in res.content:
                 self.identity.org_id = res.content["org_id"]
                 self.org_id = res.content["org_id"]
+            self._learn_siblings(res.content.get("cluster_hubs"))
             print(f"✅ [{self.qualified_name}] Connecté sur {url} | E2E: {'🔒 ON' if self.encrypt else '🔓 OFF'}")
         elif res.type == MessageType.ERROR:
             print(f"❌ [{self.name}] Refusé : {res.content}")
             await ws.close()
             raise PermissionError(res.content)
 
+    def _learn_siblings(self, urls) -> None:
+        """Ajoute les Hubs frères annoncés par le Hub à la liste de repli.
+
+        Un agent ne connaît que l'adresse qu'on lui a donnée. Si ce Hub
+        meurt, la boucle de reconnexion rejoue indéfiniment la même adresse
+        morte, alors qu'un frère de la même grappe l'accepterait — c'est
+        mesurable, et c'était le comportement avant ceci.
+
+        Les énumérer à la main dans chaque agent serait possible, mais ne
+        survivrait pas à l'ajout d'un Hub : la liste vieillirait en silence,
+        ce qui revient à ne pas l'avoir. Le Hub, lui, sait qui est vivant.
+
+        Les adresses reçues sont *ajoutées*, jamais substituées : celle que
+        l'exploitant a écrite reste la première essayée.
+        """
+        if not isinstance(urls, list):
+            return
+        for candidate in urls:
+            if isinstance(candidate, str) and candidate and candidate not in self._hub_candidates:
+                self._hub_candidates.append(candidate)
+
     async def connect(self):
         """
         Connexion initiale. Avec plusieurs URLs de Hub, essaie chacune dans
@@ -311,6 +333,35 @@ class InterMeshAgent:
             try: return json.loads(encrypted_content)
             except json.JSONDecodeError: return encrypted_content
 
+    async def _respond_to_request(self, msg) -> None:
+        """Exécute le gestionnaire de requêtes et renvoie la réponse.
+
+        Séparée de la boucle d'écoute pour que celle-ci reste disponible :
+        le chiffrement de la réponse a besoin d'un aller-retour WHO_IS, que
+        la boucle doit pouvoir traiter pendant que cette tâche l'attend.
+        """
+        try:
+            handler = self._request_handler
+            reply = await handler(msg) if inspect.iscoroutinefunction(handler) else handler(msg)
+            reply = self._apply_egress(msg.sender, reply)
+            if self.encrypt:
+                pk = await self._fetch_public_key(msg.sender)
+                if pk:
+                    reply = self._encrypt_content(pk, reply)
+                else:
+                    # Sans clé, la réponse partirait en clair alors que
+                    # l'appelant a demandé le chiffrement. Le dire est le
+                    # minimum : une dégradation silencieuse vers le clair
+                    # est pire qu'une erreur.
+                    print(f"⚠️  [{self.qualified_name}] Clé publique de "
+                          f"{msg.sender} introuvable : réponse NON chiffrée.")
+            await self.ws.send(InterMeshMessage(
+                type=MessageType.RESPONSE, sender=self.qualified_name, to=msg.sender,
+                reply_to=msg.id, content=reply, token=self.token,
+            ).to_json())
+        except Exception as exc:
+            print(f"⚠️  [{self.qualified_name}] Réponse impossible : {exc}")
+
     async def _listen_loop(self):
         try:
             async for raw in self.ws:
@@ -348,12 +399,15 @@ class InterMeshAgent:
                         content = self._decrypt_content(content)
                     msg.content = content
                     if self._request_handler:
-                        reply = await self._request_handler(msg) if inspect.iscoroutinefunction(self._request_handler) else self._request_handler(msg)
-                        reply = self._apply_egress(msg.sender, reply)
-                        if self.encrypt:
-                            pk = await self._fetch_public_key(msg.sender)
-                            if pk: reply = self._encrypt_content(pk, reply)
-                        await self.ws.send(InterMeshMessage(type=MessageType.RESPONSE, sender=self.qualified_name, to=msg.sender, reply_to=msg.id, content=reply, token=self.token).to_json())
+                        # Hors de la boucle, comme TASK_ASSIGN. Répondre ici
+                        # même conduisait à un interblocage : chiffrer la
+                        # réponse exige la clé publique du demandeur, obtenue
+                        # par un WHO_IS dont la réponse ne peut être traitée
+                        # que par cette boucle — alors bloquée à l'attendre.
+                        # Le WHO_IS expirait donc systématiquement (3 s par
+                        # requête) et, faute de clé, la réponse repartait en
+                        # clair alors que le chiffrement était demandé.
+                        asyncio.create_task(self._respond_to_request(msg))
 
                 elif msg.type == MessageType.MESSAGE:
                     content = msg.content
@@ -408,9 +462,13 @@ class InterMeshAgent:
             if self.encrypt:
                 pk = await self._fetch_public_key(task.orchestrator)
                 if pk: encrypted_output = self._encrypt_content(pk, encrypted_output)
-            task.update_status(TaskStatus.COMPLETED, output_data=encrypted_output)
+            # task.summary peut avoir été renseigné par le handler (en clair,
+            # contrairement à output_data qui peut être chiffré) : sinon on
+            # retombe sur un résumé générique pour la page de résumés.
+            summary = task.summary or f"Tâche « {task.title} » terminée par {self.qualified_name}."
+            task.update_status(TaskStatus.COMPLETED, output_data=encrypted_output, summary=summary)
         except Exception as e:
-            task.update_status(TaskStatus.FAILED, error_message=str(e))
+            task.update_status(TaskStatus.FAILED, error_message=str(e), summary=task.summary or f"Échec de « {task.title} » : {e}")
 
         await self.ws.send(InterMeshMessage(type=MessageType.TASK_UPDATE, sender=self.qualified_name, content=task.to_dict(), token=self.token).to_json())
         print(f"✅ [{self.qualified_name}] Tâche terminée: {task.status.value.upper()}")

intermesh-0.4.0/intermesh/approval.py

@@ -0,0 +1,186 @@
+"""
+Validation humaine : les tâches qu'un agent n'a pas le droit de lancer seul.
+
+Les garde-fous Asimov répondent à « cette tâche est-elle légitime ? » et
+refusent celles qui ne le sont pas. Ils ne répondent pas à « celle-ci est
+légitime, mais quelqu'un doit-il la regarder avant ? ». Signer un contrat,
+virer de l'argent, supprimer une base : ce sont des actions qu'un agent
+peut vouloir légitimement, et qu'une organisation veut néanmoins tenir
+sous décision humaine.
+
+C'est la différence entre un refus et une suspension. Une règle qui
+correspond ici ne rejette rien : elle met la tâche en attente jusqu'à ce
+qu'une personne tranche.
+
+Politique vide par défaut. Rien n'est suspendu tant que rien n'est
+déclaré — un système qui met en attente ce qu'on ne lui a pas demandé de
+retenir est un système qu'on désactive.
+
+Portée : ce module décide *si* une tâche doit être approuvée. Il ne dit
+rien de *qui* approuve — cette autorisation relève des rôles admin, au
+même titre que les autres commandes d'administration.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+ANY = "*"
+
+
+@dataclass
+class ApprovalRule:
+    """Une règle de mise en attente.
+
+    Tous les critères renseignés doivent correspondre — ils se cumulent au
+    lieu de s'additionner. Une règle sans aucun critère correspondrait à
+    toutes les tâches, ce que `__post_init__` refuse : le plus probable est
+    qu'on ait oublié de la remplir, pas qu'on veuille tout suspendre.
+
+    `reason` n'est pas décoratif : c'est le texte que lit la personne à qui
+    l'on demande de trancher. Sans lui, elle voit une tâche en attente sans
+    savoir ce qui l'y a mise.
+    """
+
+    name: str
+    reason: str
+    assignees: list[str] = field(default_factory=lambda: [ANY])
+    capabilities: list[str] = field(default_factory=lambda: [ANY])
+    pattern: str | None = None
+    min_cost: float | None = None
+    cross_org_only: bool = False
+
+    def __post_init__(self):
+        if not self.name:
+            raise ValueError("une règle d'approbation doit avoir un `name`")
+        if not self.reason:
+            raise ValueError(f"règle '{self.name}' : `reason` est obligatoire — "
+                             "c'est ce que lit la personne qui approuve")
+        specific = (
+            self.assignees != [ANY]
+            or self.capabilities != [ANY]
+            or self.pattern is not None
+            or self.min_cost is not None
+            or self.cross_org_only
+        )
+        if not specific:
+            raise ValueError(
+                f"règle '{self.name}' : aucun critère, elle suspendrait toutes les "
+                "tâches. Précisez au moins assignees, capabilities, pattern, "
+                "min_cost ou cross_org_only."
+            )
+        self._compiled = re.compile(self.pattern, re.IGNORECASE) if self.pattern else None
+
+    def matches(
+        self,
+        assignee: str,
+        capabilities: list[str],
+        payload_text: str,
+        estimated_cost: float,
+        is_cross_org: bool,
+    ) -> bool:
+        if self.cross_org_only and not is_cross_org:
+            return False
+        if self.assignees != [ANY] and assignee not in self.assignees:
+            return False
+        if self.capabilities != [ANY] and not any(c in self.capabilities for c in capabilities):
+            return False
+        if self.min_cost is not None and estimated_cost < self.min_cost:
+            return False
+        if self._compiled is not None and not self._compiled.search(payload_text or ""):
+            return False
+        return True
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "ApprovalRule":
+        return cls(
+            name=raw["name"],
+            reason=raw["reason"],
+            assignees=raw.get("assignees", [ANY]),
+            capabilities=raw.get("capabilities", [ANY]),
+            pattern=raw.get("pattern"),
+            min_cost=raw.get("min_cost"),
+            cross_org_only=bool(raw.get("cross_org_only", False)),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "reason": self.reason,
+            "assignees": self.assignees,
+            "capabilities": self.capabilities,
+            "pattern": self.pattern,
+            "min_cost": self.min_cost,
+            "cross_org_only": self.cross_org_only,
+        }
+
+
+@dataclass
+class ApprovalPolicy:
+    name: str = "empty"
+    rules: list[ApprovalRule] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.rules
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "ApprovalPolicy":
+        return cls(
+            name=raw.get("name", "unnamed"),
+            rules=[ApprovalRule.from_dict(r) for r in raw.get("rules", [])],
+        )
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "rules": [r.to_dict() for r in self.rules]}
+
+    @classmethod
+    def load(cls, path: str | Path) -> "ApprovalPolicy":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))
+
+
+def _payload_text(task: dict) -> str:
+    """Texte sur lequel `pattern` est évalué.
+
+    Le titre et les données d'entrée sont concaténés : une règle qui
+    cherche « contrat » doit correspondre que le mot soit dans l'intitulé
+    ou dans la charge utile.
+    """
+    parts = [str(task.get("title") or "")]
+    data = task.get("input_data")
+    if data is not None:
+        parts.append(data if isinstance(data, str) else json.dumps(data, ensure_ascii=False))
+    return "\n".join(parts)
+
+
+def requires_approval(
+    task: dict,
+    policy: ApprovalPolicy | None,
+    *,
+    capabilities: list[str] | None = None,
+    is_cross_org: bool = False,
+) -> ApprovalRule | None:
+    """Retourne la première règle qui met cette tâche en attente, sinon None.
+
+    La première suffit : une tâche est suspendue ou ne l'est pas, et c'est
+    le motif de cette règle qui sera montré à la personne qui tranche.
+    """
+    if policy is None or policy.is_empty:
+        return None
+
+    assignee = str(task.get("assignee") or "")
+    try:
+        cost = float(task.get("estimated_cost") or 0.0)
+    except (TypeError, ValueError):
+        cost = 0.0
+    text = _payload_text(task)
+    caps = capabilities or []
+
+    for rule in policy.rules:
+        if rule.matches(assignee, caps, text, cost, is_cross_org):
+            return rule
+    return None