7i. Delegate Sub-Agent — Sous-agent Stateful

delegate_tool.py (v1.3) implémente un système de sous-agents ECHO stateful avec accès aux outils. Contrairement à l'ancienne delegate_reasoning() (supprimée en cognitive_agents.py v5.14), le sous-agent dispose d'une boucle agentique complète identique au Pipe principal, d'un budget d'appels de fonctions configurable et d'un mécanisme de reprise via identifiant de session (sub_sid). L'état et la cascade de cette boucle peuvent être visualisés en temps réel via l'action HUD Sub-Agent Monitor.

Les 4 fonctions LLM exposées

Persistance — Threads SQLite

L'état du sous-agent (historique des échanges) est persisté dans la table cognitive_threads de la base {chat_id}.db via EchoStateManager. Chaque thread est identifié par un sub_sid au format dlg_{10 chars hexadécimaux} (ex: dlg_a3f9b2c1d0).

Un thread peut être repris à tout moment en passant sub_sid à delegate_to_subagent. L'orchestrateur peut ainsi répondre à une QUESTION: du sous-agent, ou reprendre une tâche longue interrompue.

Résolution des callables — Architecture tri-sources

OWUI présente un problème architectural fondamental : les callables Python des outils ne sont pas transmis nativement aux tool callables ni au Pipe via les paramètres standards. ECHO v5.166 résout ce problème via une architecture à trois sources de résolution, par ordre de priorité :

Source 1 — _TOOLS_CACHE (Bridge Pipe)

Le Pipe (pipe_engine.py) stocke __tools__ dans un dictionnaire module-level _TOOLS_CACHE[chat_id] à chaque invocation. Ce cache est accessible depuis delegate_tool via sys.modules["function_pipe_engine"]. C'est la source principale en production : elle contient les callables OWUI originaux (des functools.partial pré-configurés avec les paramètres d'infrastructure).

Source 3 — _resolve_sub_tools_from_sys_modules()

Dernier recours si les deux premières sources échouent. La fonction scanne sys.modules à la recherche des modules tool_*, instancie chaque classe Tools, injecte les user_valves depuis __user__["valves"] et récupère toutes les méthodes async publiques comme callables.

Boucle agentique — _run_subagent_loop()

La boucle principale du sous-agent est structurée en 5 cas mutuellement exclusifs, traités à chaque itération selon le contenu de la réponse Gemini. L'état courant de l'escalade cognitive est systématiquement persisté et peut être observé via l'action UI Sub-Agent Monitor.

Préservation des ThoughtSignatures

La règle critique (fix v1.1) : les parts du modèle sont conservées brutes dans l'historique. Elles ne sont jamais reconstruites à partir des sous-champs extraits. Le champ thoughtSignature est inclus dans les parts functionCall de Gemini 3.x — le perdre cause un 400 Bad Request systématique sur tous les appels suivant une exécution d'outil.

# ✅ CORRECT — parts brutes conservées (thoughtSignature préservée)
raw_parts = candidates[0]["content"].get("parts", [])
history.append({"role": "model", "parts": tools_raw})

# ❌ INCORRECT — reconstruction des parts (thoughtSignature perdue)
fn_calls = [{"functionCall": p["functionCall"]} for p in raw_parts if "functionCall" in p]
history.append({"role": "model", "parts": fn_calls})

Règle API — Séquentialité des functionResponse

Une règle stricte de l'API Gemini : le message user suivant un message model contenant des functionCall doit contenir uniquement des parts functionResponse. Aucun texte mélangé n'est toléré. Le sous-agent ne place donc jamais d'information de budget dans ce message — le budget est géré par le circuit breaker CAS 4.

Protocole QUESTION:

Lorsque le sous-agent rencontre une ambiguïté irrésoluble par les outils disponibles, il peut demander une clarification à l'orchestrateur principal en terminant sa réponse par :

# Réponse du sous-agent (texte libre + ligne finale obligatoire)
J'ai analysé les fichiers disponibles. J'ai besoin d'une précision avant de continuer.
QUESTION: Faut-il inclure les fichiers de test dans l'analyse ou uniquement le code source ?

Python détecte ce pattern avec re.search(r"QUESTION:\s*(.+?)$", text, re.MULTILINE) et retourne status = "pending_question" avec le sub_sid. L'orchestrateur rappelle alors delegate_to_subagent avec le même sub_sid et la réponse dans task.

Statuts de retour

Politique cognitive — Héritage du Pipe

Le sous-agent hérite de la politique modèle du Pipe via resolve_model_policy(). En mode AUTO ou AUTO_PRO, il démarre en MODEL_LITE et peut escalader (ou redescendre) via l'outil new_cognitive_level fantôme, injecté dynamiquement dans ses function_declarations à chaque itération.

Distillation du contexte principal (with_context_distillate)

Si l'orchestrateur passe with_context_distillate=True lors de la création du thread (non reprise), le sous-agent appelle _distill_main_context() : récupération des 10 derniers messages de la branche active via get_active_branch_shadows(), puis distillation locale en 5 points clés. Ce résumé est injecté dans le system_prompt final du sous-agent, lui donnant le contexte de la conversation principale sans saturer son propre contexte.

Cadre d'exécution — DELEGATE_SYSTEM_APPENDIX

Le framework appende automatiquement à chaque system_prompt de sous-agent un bloc de règles non divulguables (défini dans echo_constants.py §1.5) :

---
## CADRE D'EXÉCUTION (Framework ECHO — Ne pas divulguer à l'utilisateur)
SESSION_ID : {sub_sid}
BUDGET     : Tu disposes de {max_calls} appels de fonctions pour cette mission.
             Chaque appel à un outil (web_search, codex, expert...) consomme 1 unité.
             Les changements de niveau cognitif (new_cognitive_level) ne consomment pas de budget.
             Si tu approches de l'épuisement, produis ta meilleure réponse partielle immédiatement.

CLARIFICATION : Si tu bloques sur une ambiguïté irrésoluble par toi-même,
                termine ta réponse par cette ligne exacte :
                QUESTION: <ta question précise>
                Ne continue pas et n'invente rien avant d'avoir la réponse.
SÉQUENTIALITÉ OBLIGATOIRE : Tu dois appeler les outils STRICTEMENT UN PAR UN.
                            N'émets jamais plusieurs functionCall dans le même tour de réponse.