create-leafmesh 2.7.0__tar.gz → 2.7.1__tar.gz

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: create-leafmesh
-Version: 2.7.0
+Version: 2.7.1
 Summary: Project scaffolding + cloud-deploy tool for LeafMesh
 License-Expression: MIT
 Requires-Python: >=3.10

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/__init__.py

@@ -1,3 +1,3 @@
 """create-leafmesh — Project scaffolding + cloud-deploy tool for LeafMesh."""
 
-__version__ = "2.7.0"
+__version__ = "2.7.1"

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/_inspire/env

@@ -73,23 +73,36 @@ LEAFMESH_ENV_TOKEN=your-env-token-here
 # Webhook hardening (HMAC + replay protection).
 # Set to 1 to keep accepting body-only HMAC during a migration window.
 # LEAFMESH_WEBHOOK_ALLOW_LEGACY_HMAC=0
-# LEAFMESH_WEBHOOK_REPLAY_SKEW_S=300
-# LEAFMESH_WEBHOOK_RATE_LIMIT_MAX=60
-# LEAFMESH_WEBHOOK_RATE_LIMIT_WINDOW_S=60
-# LEAFMESH_WEBHOOK_MAX_PAYLOAD_BYTES=1048576    # 1 MiB
-
-# Knowledge ingest / query caps.
-# LEAFMESH_KNOWLEDGE_MAX_DOCS_PER_INGEST=1000
-# LEAFMESH_KNOWLEDGE_MAX_DOC_BYTES=2097152      # 2 MiB
-# LEAFMESH_KNOWLEDGE_MAX_INGEST_TOTAL_BYTES=52428800  # 50 MiB
-# LEAFMESH_KNOWLEDGE_QUERY_RATE_LIMIT_MAX=120
-# LEAFMESH_KNOWLEDGE_QUERY_RATE_LIMIT_WINDOW_S=60
-
-# LLM hard timeout — prevents a stuck provider from pinning an agent slot.
-# LEAFMESH_LLM_HARD_TIMEOUT_S=300
-
-# Cron min-interval (seconds). Default 60s — schedules below this are rejected.
-# LEAFMESH_CRON_MIN_INTERVAL_SECONDS=60
+#
+# ── The tuning knobs below are NOT environment variables any more ──
+# 2.4.131 moved them into configs/config.yaml, where they round-trip and
+# show up in Studio. Setting them here does nothing at all — no error, no
+# effect. Put them in the config instead:
+#
+#   limits:
+#     webhook_replay_skew_s: 300
+#     webhook_rate_limit_max: 60
+#     webhook_rate_limit_window_s: 60
+#     webhook_max_payload_bytes: 1048576      # 1 MiB
+#     knowledge_max_ingest_total_bytes: 52428800   # 50 MiB
+#     knowledge_query_rate_limit_max: 120
+#     knowledge_query_rate_limit_window_s: 60
+#     max_session_history_bytes: 1048576
+#     max_parallel_tool_calls: 8
+#
+#   timeouts:
+#     llm_hard_timeout_s: 300     # stops a stuck provider pinning an agent slot
+#
+#   scheduler:
+#     cron_min_interval_seconds: 60   # schedules below this are rejected
+#     misfire_grace_s: 60
+#
+#   runtime:
+#     lease_seconds: 30           # raise to ~120 on a flaky remote Redis
+#     lease_heartbeat_s: 10
+#
+# (knowledge_max_docs_per_ingest and knowledge_max_doc_bytes were removed
+#  outright — there is no replacement for those two.)
 
 # MCP subprocess allowlist (comma-separated absolute paths or basenames).
 # Empty = warn-only at startup. Set to "*" for "any command" with explicit
@@ -100,8 +113,8 @@ LEAFMESH_ENV_TOKEN=your-env-token-here
 # behind a tunnel (production must wire a Bot Framework JWT validator).
 # LEAFMESH_TEAMS_ALLOW_UNVERIFIED=0
 
-# Conversation history hard byte cap (per session).
-# LEAFMESH_MAX_SESSION_HISTORY_BYTES=5242880    # 5 MiB
+# Conversation history hard byte cap (per session) — moved to config in
+# 2.4.131:  limits.max_session_history_bytes: 5242880   # 5 MiB
 
 # Security headers.
 # LEAFMESH_HSTS_ENABLED=1

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/_inspire/requirements.txt

@@ -1,7 +1,7 @@
 # {{project_name}} — Dependencies
 
 # LeafMesh SDK (includes all providers + connectors)
-leafmesh>=2.4.0
+leafmesh>=2.4.263
 
 # Scheduler (enables wake_up cron in YAML)
 apscheduler>=3.10.0

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/ai-dev-squad/main.py

@@ -34,10 +34,8 @@ async def main():
     leafmesh.event_bus.subscribe(EventType.MANAGER_INTERVENTION, _on_manager_intervention)
     leafmesh.event_bus.subscribe(EventType.INTERVENTION_NEEDED,  _on_intervention_needed)
     leafmesh.event_bus.subscribe(EventType.HUMAN_INPUT_TIMEOUT,  _on_human_input_timeout)
-    try:
-        await leafmesh.enable_self_healing()
-    except AttributeError:
-        pass
+    # Self-healing is automatic — the SDK enables it during start() on
+    # every operator-facing mesh. No call is needed.
     logger.info("{{project_name}} — AI Dev Squad running. API: http://127.0.0.1:18820/docs")
     stop = asyncio.Event(); loop = asyncio.get_running_loop()
     if sys.platform != "win32":

{create_leafmesh-2.7.0/create_leafmesh/templates/bench-management → create_leafmesh-2.7.1/create_leafmesh/templates/ai-dev-squad}/requirements.txt

@@ -1,4 +1,4 @@
-leafmesh>=2.4.131
+leafmesh>=2.4.263
 
 # Scheduler (enables wake_up cron in YAML)
 apscheduler>=3.10.0

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/bd-proposals/main.py

@@ -30,8 +30,8 @@ async def main():
     leafmesh.event_bus.subscribe(EventType.MANAGER_INTERVENTION, _on_manager_intervention)
     leafmesh.event_bus.subscribe(EventType.INTERVENTION_NEEDED, _on_intervention_needed)
     leafmesh.event_bus.subscribe(EventType.HUMAN_INPUT_TIMEOUT, _on_human_input_timeout)
-    try: await leafmesh.enable_self_healing()
-    except AttributeError: pass
+    # Self-healing is automatic — the SDK enables it during start() on
+    # every operator-facing mesh. No call is needed.
     logger.info("{{project_name}} — BD Proposals mesh running")
 
     stop = asyncio.Event(); loop = asyncio.get_running_loop()

{create_leafmesh-2.7.0/create_leafmesh/templates/customer-support → create_leafmesh-2.7.1/create_leafmesh/templates/bd-proposals}/requirements.txt

@@ -1,4 +1,4 @@
-leafmesh>=2.4.131
+leafmesh>=2.4.263
 
 # Scheduler (enables wake_up cron in YAML)
 apscheduler>=3.10.0

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/bench-management/PRD.md

@@ -235,7 +235,7 @@ dual→dual — verified 0 dual warnings at load); the `mcp:` block is commented
 empty `${VAR:}` url); `max_tool_calls_per_message: 15` on the tool-chaining
 agents; every llm agent fn is `async def f(llm_response, input_data, context)`;
 `super_agent` is dict form; `timeouts.llm_hard_timeout_s` lands with the 2.4.131
-floor. `requirements.txt` is core-only (`leafmesh>=2.4.131` + `apscheduler>=3.10`).
+floor. `requirements.txt` is core-only (`leafmesh>=2.4.263` + `apscheduler>=3.10`).
 
 ## Config pointer
 

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/bench-management/README.md

@@ -83,7 +83,7 @@ against the seed store:
 cp env .env && pip install -r requirements.txt && python validate_config.py && python main.py
 ```
 
-`requirements.txt` pins `leafmesh>=2.4.131` + `apscheduler>=3.10` (for the weekly
+`requirements.txt` pins `leafmesh>=2.4.263` + `apscheduler>=3.10` (for the weekly
 `wake_up` cron). Do **not** install `leafmesh[all]` on Python 3.12+ — it pulls
 `cchardet`, which has no wheel there; add only the specific extras you wire.
 

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/bench-management/main.py

@@ -50,8 +50,8 @@ async def main():
     leafmesh.event_bus.subscribe(EventType.MANAGER_INTERVENTION, _on_manager_intervention)
     leafmesh.event_bus.subscribe(EventType.INTERVENTION_NEEDED, _on_intervention_needed)
     leafmesh.event_bus.subscribe(EventType.HUMAN_INPUT_TIMEOUT, _on_human_input_timeout)
-    try: await leafmesh.enable_self_healing()
-    except AttributeError: pass
+    # Self-healing is automatic — the SDK enables it during start() on
+    # every operator-facing mesh. No call is needed.
     logger.info("{{project_name}} — Bench Management mesh running")
 
     stop = asyncio.Event(); loop = asyncio.get_running_loop()

{create_leafmesh-2.7.0/create_leafmesh/templates/ai-dev-squad → create_leafmesh-2.7.1/create_leafmesh/templates/bench-management}/requirements.txt

@@ -1,4 +1,4 @@
-leafmesh>=2.4.131
+leafmesh>=2.4.263
 
 # Scheduler (enables wake_up cron in YAML)
 apscheduler>=3.10.0

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/claude_skills/leafmesh/SKILL.md

@@ -44,6 +44,8 @@ You are an expert at building multi-agent orchestration systems with the LeafMes
 - [Command Center (the business board)](#command-center-the-business-board) · [Image generation](#image-generation)
 - [STRICT — fields by `agent_type`](#strict--fields-by-agent_type) · [STRICT — `human_interface` rules](#strict--human_interface-rules)
 - [Human-in-the-Loop (HITL)](#human-in-the-loop-hitl)
+- [**THE ROOM RULES**](#the-room-rules--get-these-wrong-and-the-mesh-is-rude-or-deaf) — when a channel message is ours, and which conversation it joins
+- [Credentials — `connection:`, never a literal](#credentials--connection-never-a-literal) · [Per-seat channel fields](#per-seat-channel-fields-worth-knowing) · [Inbox vs connector seats](#inbox-seats-vs-connector-seats)
 - [YAML Agent Config (All Fields)](#yaml-agent-config-all-fields) · [Condition Syntax](#condition-syntax-can_call-conditions)
 - [Decorators — Making an Agent Self-Reliant](#decorators--making-an-agent-self-reliant)
 - [Communication Types](#communication-types) · [Fan-In Patterns (`wait_for`)](#fan-in-patterns-wait_for) · [Tools](#tools)
@@ -72,7 +74,11 @@ You are an expert at building multi-agent orchestration systems with the LeafMes
 | "Add Skills" / "give this agent reusable playbooks" | Add `skills: {sourceName: "...", enabled: true, names: [...]}` on the agent. **Local `.md` files are NOT auto-loaded** — the default source is hosted (Redis). For filesystem skills, register a source via `POST /api/skills/sources` first. See [Skills System](#skills-system) section |
 | "Retry when X fails" / "loop back to re-do upstream work" | NEVER write an unbounded retry back-edge. Add a per-session exhaustion counter in the agent's Python, yield a `*_retry_exhausted` boolean, gate the back-edge on it, add a terminal route. See [Rule 3](#rule-3--bound-every-retry-back-edge) |
 | "Use Grok or Mistral as the model" | Set `model: "grok-2"` (or `grok-3`, `grok-beta`) and `XAI_API_KEY` env var; or `model: "mistral-large"` (or `mistral-small`, `mixtral-8x22b`, `codestral-latest`) and `MISTRAL_API_KEY` env var. Both are native providers — no Bedrock/Vertex routing needed |
-| "Send / receive email from an agent" | Add Email channel adapter: `channels: {email: {smtp_host, smtp_port, smtp_user, smtp_password, imap_host, imap_user, imap_password}}`. Outbound via SMTP/Mailgun/SendGrid/Postmark; inbound via IMAP with talon reply-stripping. Use for customer support, partner notifications, internal escalations |
+| "Put this agent on Slack/Teams/Discord/Telegram/Cliq/WhatsApp" | `human_interface: "webhook"` + a `channels:` block. Credentials come from a **connection**, never a literal — the mesh refuses to boot on an inline provider credential. Then read [THE ROOM RULES](#the-room-rules--get-these-wrong-and-the-mesh-is-rude-or-deaf): in a shared room a bare message is IGNORED, a mention opens a NEW conversation, and a thread reply continues one. |
+| "Slack but we have no public URL" | Socket Mode. Put an app-level (`xapp-`) token in the connection and it turns itself on — inbound arrives over an outbound WebSocket. Without it a local/NAT'd mesh can post but will never hear anything. |
+| "Only our staff should answer this seat" | `operators_only: true` on the channel block, plus an `operators` map. Off by default, because a customer-facing seat must accept strangers. Refused senders are logged with the reason. |
+| "Where do credentials go?" | A connection on the Infra page; config references it by name (`connection: "slack-workspace"`). One connection holds the provider's whole credential set. `${ENV_VAR}` also works. A literal token makes the mesh REFUSE TO BOOT (2.4.180). |
+| "Send / receive email from an agent" | Add the Email channel: `channels: {email: {connection, provider, smtp_host, smtp_port, smtp_username, from_address, inbound_domain}}`. Outbound over SMTP; inbound is the **provider's webhook** (Mailgun/SendGrid/Postmark) — there is **no IMAP**, so a mesh with no public URL cannot receive mail. The field is `smtp_username`, not `smtp_user`. |
 
 ## Current project config
 !`cat configs/config.yaml 2>/dev/null | head -30`
@@ -658,7 +664,9 @@ manager:
     enabled: true
     design_after_runs: 3     # runs to observe before designing (1–50)
     max_metrics: 24
-    model: null              # defaults to the manager's model
+    model: null              # falls back to the SUMMARIZER's model
+                             # (use_model = model or summarizer.config.model);
+                             # if neither has one the design is skipped
 ```
 
 What this means when you are building an agency:
@@ -883,29 +891,107 @@ agents:
         post_channel: "${SLACK_POST_CHANNEL}"
       telegram:
         bot_token: "${TELEGRAM_BOT_TOKEN}"
-      email:                              # v2.3.x — BRD-020
-        # Outbound — SMTP, or provider API (Mailgun / SendGrid / Postmark)
-        smtp_host: "${SMTP_HOST}"
+      email:
+        connection: "email-support"       # holds smtp_password + signing_secret
+        # Outbound — SMTP
+        provider: "mailgun"               # mailgun | sendgrid | postmark
+        smtp_host: "smtp.mailgun.org"     # optional for mailgun: defaults by region
         smtp_port: 587
-        smtp_user: "${SMTP_USER}"
-        smtp_password: "${SMTP_PASSWORD}"
+        smtp_username: "postmaster@mg.example.com"   # NOT smtp_user
         from_address: "support@example.com"
-        # Inbound — IMAP (talon reply-stripping is automatic)
-        imap_host: "${IMAP_HOST}"
-        imap_port: 993
-        imap_user: "${IMAP_USER}"
-        imap_password: "${IMAP_PASSWORD}"
-        imap_folder: "INBOX"
-        # Optional — DKIM signing
-        dkim_private_key: "${DKIM_PRIVATE_KEY}"
-        # Optional — provider API mode (skip SMTP)
-        # provider: "mailgun" | "sendgrid" | "postmark"
-        # provider_api_key: "${MAILGUN_API_KEY}"
+        reply_to_address: "support@example.com"
+        # Inbound — the PROVIDER'S WEBHOOK, not IMAP. The adapter registers a
+        # route and verifies the provider's signature; there is no IMAP client.
+        inbound_domain: "mg.example.com"
+        inbound_local_part_filter: ["support"]   # optional; accept only these
+        threading: "references_first"     # or reply_to_token
+        auto_reply_drop: true             # ignore vacation autoresponders
 ```
 
 The HITL flow works identically across all channels -- the SDK handles transport, the agent handles routing. With multiple channels configured, the SDK tries each in order; if all fail, it falls back to `webhook_config.outbound_url` (when set).
 
-**Email channel specifics (BRD-020, v2.3.x).** Email is **asymmetric** — outbound goes via SMTP (or provider API), inbound goes via IMAP. Threading is automatic via `Message-ID` / `In-Reply-To` / `References` headers, matching the same session-reconstruction pattern Slack uses with `thread_ts`. Reply / signature stripping uses `talon` (Mailgun's MIT-licensed library, used by Front / Help Scout / Intercom) so the LLM sees only the user's new message, not quoted history. Bounces and complaints publish `email.bounce` / `email.complaint` events to the Redis Stream — operators can suppress the recipient or mark the session for human review.
+**Email channel specifics.** Email is **asymmetric** — outbound goes over SMTP, inbound arrives as the PROVIDER'S WEBHOOK (Mailgun, SendGrid or Postmark), whose signature the adapter verifies. The email CHANNEL has no IMAP client, so a mesh with no public URL cannot receive mail through it — for that case use the separate **IMAP broker** (`brokers: {name: {type: "imap", host, user, password, folder, poll_interval_s}}`), which polls a mailbox and feeds `listen_events` instead. Threading uses `In-Reply-To` / `References`, and for clients that strip those the adapter sets a plus-addressed `Reply-To` token so a reply still finds its conversation. Reply and signature stripping uses `talon` when it is installed, with a regex fallback when it is not. **Email is direct but NOT continuous:** a reply continues its conversation, a brand-new mail starts a new one — unlike a DM, where every message is one running chat.
+
+### Credentials — `connection:`, never a literal
+
+**The mesh REFUSES TO BOOT if it finds a provider credential written literally
+in config** (2.4.180). Name a connection made on the Infra page instead:
+
+```yaml
+    channels:
+      slack:
+        connection: "slack-workspace"   # the vault holds the secret
+        post_channel: "C0123456789"
+```
+
+`${ENV_VAR}` still passes — the secret is in the environment, not the file.
+A literal `"xoxb-…"` does not. One connection carries the provider's WHOLE
+credential set (Slack: `bot_token` + `signing_secret` + `app_token`), so you
+reference it once and every field it holds comes with it.
+
+Connections made while the mesh is running are adopted live — for Slack that
+includes opening Socket Mode from the app token, so inbound starts working
+without a restart.
+
+### Per-seat channel fields worth knowing
+
+| field | what it does |
+|---|---|
+| `operators` | logical operator id → that channel's user handle, so a step can address a named person |
+| `operators_only` | refuse anyone not in `operators`. **Off by default** — a customer-facing seat must accept strangers. Turn it on for a staff-only seat. |
+| `socket_mode` | Slack: receive events over an outbound WebSocket — **no public URL needed**. Turns itself on when the connection holds an `xapp-` token. |
+| `listen_channels` | channel ids to accept inbound from; empty means all |
+
+### THE ROOM RULES — get these wrong and the mesh is rude or deaf
+
+Two questions on every inbound: **is this for us**, then **which conversation**.
+
+**Is it addressed to the mesh?**
+
+```
+DIRECT (a DM, or mail to the mesh's address)   → always ours, no mention needed
+SHARED ROOM
+  ├── @mentions the mesh / names an agent / slash command  → ours
+  ├── posted inside a thread the mesh opened               → ours
+  └── anything else                                        → IGNORED
+```
+
+A bare message in a room is people talking to each other. Having spoken to the
+mesh before does NOT make later messages its business — that is how a "yes, go
+ahead" meant for a colleague gets eaten as an answer to a pending request.
+The mesh also never answers its own messages, on any channel.
+
+**Which conversation does it join?**
+
+```
+Addressed the mesh (@mention / named agent / slash command)
+    → a NEW conversation, EVEN IF a question is open.
+      Nobody @-mentions a bot to answer its question; you just type.
+
+Reply inside a thread
+    ├── something pending → answers THAT message, same session
+    └── nothing pending   → runs the flow again, SAME session (the Inbox rule)
+
+New email (no In-Reply-To, no reply token)
+    → a new conversation. A reply stays in its own.
+```
+
+Threads exist on **slack, teams, discord, email**. **telegram, cliq, whatsapp**
+have none — there each person has one continuous conversation, and a question
+asked in a Cliq room can only be answered by naming the mesh or in a DM.
+
+**When you design a seat:** if it takes work from strangers, leave
+`operators_only` off and expect mentions. If it is an approval seat for staff,
+turn it on. If the mesh has no public URL, Slack needs `socket_mode` (an
+`xapp-` token) or it will never hear anything.
+
+### Inbox seats vs connector seats
+
+A seat is **either** an Inbox seat (the hosted console) **or** a connector seat
+(slack/teams/…), never both. Declaring `channels:` makes it a connector seat
+and it gets no Inbox door. Ownership is the login's platform role
+(`operator_role: owner|admin`), and `operator_ids` are the assigned operators;
+a stranger sees no tab at all.
 
 ## YAML Agent Config (All Fields)
 
@@ -916,7 +1002,11 @@ agents:
     name: my_agent
     agent_type: "llm"              # llm | human | programmatic | external
     description: "What this agent does"
-    model: "gpt-4o-mini"           # Any supported model
+    model: "gpt-4o-mini"           # REQUIRED — no default since 2.4.135.
+                                   # The SDK never picks one for you: boot names
+                                   # every LLM agent missing one, and the call
+                                   # raises ModelNotConfiguredError.
+                                   # Non-LLM agents need no model.
     prompt: "You are a helpful..." # System prompt
     temperature: 0.1
     max_tokens: 800
@@ -1118,7 +1208,7 @@ rather than being manufactured as `false`/`""`. Two consequences:
   final answer share one turn) and is wasted on agents with ≤ 1 yields
   field — both warn.
 - **`reasoning: true` on a non-reasoning-capable model warns** — you
-  probably meant `thinking: true` (see [reasoning vs thinking](#reasoning-vs-thinking)).
+  probably meant `thinking: true` (see [reasoning vs thinking](agent-config-fields.md#reasoning-vs-thinking)).
 - **Unknown names warn at load**: `can_call` / `wait_for` referencing
   an agent that doesn't exist, and circular *unconditional* `can_call`
   edges. `entry_points` targets are stricter — a typo'd target raises
@@ -1344,7 +1434,9 @@ def format_md(items: list) -> str:
 manager:
   # on by default — omit `enabled` (set `enabled: false` only to kill
   # coordination + the summarizer entirely; rare)
-  model: "gpt-4o-mini"          # Summarizer model
+  model: "gpt-4o-mini"          # Summarizer model — REQUIRED for supervision.
+                                # Without it the manager/summarizer are INERT and
+                                # boot says so; nothing is guessed.
   domain: "generic"              # generic | ecommerce | data_analysis
   routing:
     mode: "learning"             # static | learning (adaptive routing)

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/claude_skills/leafmesh/agent-config-fields.md

@@ -294,7 +294,7 @@ These fields are used when `agent_type` is `"llm"`. Ignored for other types.
 
 | Field | Type | Default | Accepted Values | Description |
 |-------|------|---------|-----------------|-------------|
-| `model` | string | `"gpt-4o-mini"` | see [Model List](#model-list) below | LLM model name |
+| `model` | string | **none — declare it** | see [Model List](#model-list) below | LLM model name. No default since 2.4.135 — the SDK never picks one for you. Non-LLM agents need none. **Read the note below: nothing stops you booting without it.** |
 | `prompt` | string | `null` | any string (multiline supported) | System prompt |
 | `temperature` | float | `0.1` | `0.0` – `2.0` | LLM temperature (creativity/randomness) |
 | `max_tokens` | int | `800` | 1 – model max | Max output tokens (legacy models) |
@@ -329,6 +329,24 @@ These fields are used when `agent_type` is `"llm"`. Ignored for other types.
 | `output_modality` | string | `"text"` | `"text"`, `"image"` | (declared field since 2.4.121) Output type for the agent. Pair `"image"` with an image-capable model and `image_options`. |
 | `image_options` | dict | `null` | provider image opts | (2.4.104, fixed 2.4.108) Options for image generation when `output_modality: "image"` (size, quality, etc.). **≥2.4.108 required** — earlier versions ran image models as TEXT turns on the mesh path (full token bill, empty content, yields failure). |
 
+> **⚠️ A missing `model` is NOT caught where you would expect, and the two
+> validators disagree.** Verified against `leafmesh==2.4.263`:
+>
+> | What you run | LLM agent with no `model` |
+> |---|---|
+> | `load_yaml_config(path)` | **loads fine** — `agent.model` is `None` |
+> | `validate_config(cfg)` | **`valid: True`** — it does not check agent models at all |
+> | Studio / `POST /api/yaml/validate` | **error:** `LLM agent 'x' has no model configured` |
+> | Boot | **starts** — nothing refuses |
+> | The agent's first LLM call | **`ModelNotConfiguredError`** naming the agent and the field |
+>
+> So a template can pass `validate_config` green, boot green, and then fail at
+> the first real message — in front of a user. `validate_config` is NOT a
+> sufficient gate for this; check every LLM agent has a model yourself, or
+> validate through the API path. What 2.4.135 changed is that there is no
+> longer a default to fall back on: before, a missing model silently spent the
+> customer's money on a model they never chose.
+
 > **⚠️ Tune Super-Agent with the DICT form — not flat keys.** As of **2.4.123** `super_agent:` accepts either a bool (`true` = on with defaults) **or a dict** of tuning keys, and as of **2.4.131 the dict is the ONLY way to tune it** (the three `LEAFMESH_SUPER_AGENT_*` env vars are dead). The old **flat** keys — `super_agent_cost_ceiling`, `super_agent_step_cap`, `super_agent_reflection_budget`, `super_agent_wall_clock`, `synth_max_tokens_floor/ceiling` — were **never wired** (accepted only as `extra='allow'` and ignored); **do not use them.** Allowed **dict** keys and defaults:
 >
 > | Dict key | Default | Governs |
@@ -1149,7 +1167,7 @@ Used inside `webhook_config` for human agents.
 | `response_mapping` | dict | `{}` | Field mapping for webhook response transformation |
 | `max_retries` | int | `3` | Max retry attempts for failed outbound webhooks |
 | `retry_delay` | int | `5` | Delay between retries (seconds) |
-| `operators` | dict | *(no schema default)* | Declared field (verified in `leafmesh.core.agent_config`). Per-operator routing map (operator name → external address/ID) for directing a human agent's outbound to a specific person. |
+| `operators` | dict | `{}` | Declared field (verified in `leafmesh.core.agent_config`). Per-operator routing map (operator name → external address/ID) for directing a human agent's outbound to a specific person. |
 
 ---
 
@@ -1159,24 +1177,37 @@ Used inside `channels` dict for human agents. Keys are provider names.
 
 ### Supported Provider Keys
 
-| Key | Provider |
-|-----|----------|
-| `slack` | Slack Bot API |
-| `telegram` | Telegram Bot API |
-| `discord` | Discord Bot API |
-| `whatsapp` | WhatsApp Business API (Meta Cloud API) |
-| `teams` | Microsoft Teams Bot Framework |
+| Key | Provider | Threads? |
+|-----|----------|----------|
+| `slack` | Slack Bot API | yes |
+| `teams` | Microsoft Teams Bot Framework | yes |
+| `discord` | Discord Bot API | yes |
+| `email` | SMTP/IMAP, or Mailgun / SendGrid / Postmark | yes (In-Reply-To / References) |
+| `telegram` | Telegram Bot API | no |
+| `cliq` | Zoho Cliq | no |
+| `whatsapp` | WhatsApp Business API (Meta Cloud API) | no |
+
+"Threads?" decides how a reply finds its conversation, and whether a question
+the mesh asks in a shared room can be answered there at all — see THE ROOM
+RULES in SKILL.md. A channel without threads gives each person one continuous
+conversation.
 
 ### Fields Per Channel
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `bot_token` | string | `null` | Bot/API token for the provider (see per-provider notes below) |
-| `signing_secret` | string | `null` | Request verification secret (see per-provider notes below) |
+| `connection` | string | `null` | **Preferred.** Names a connection held in the mesh's vault, carrying the provider's WHOLE credential set. A LITERAL credential in any field below makes the mesh REFUSE TO BOOT (2.4.180); `${ENV_VAR}` is fine. |
+| `bot_token` | string | `null` | Bot/API token. Prefer `connection:`. |
+| `signing_secret` | string | `null` | Request verification secret. Prefer `connection:`. |
+| `app_token` | string | `null` | **Slack only** — app-level (`xapp-`) token. Its presence turns Socket Mode on: inbound arrives over an outbound WebSocket, so **no public URL is needed**. Essential for a local or NAT'd mesh. |
+| `socket_mode` | bool | auto | **Slack only** — defaults to true when an `app_token` exists. Set `false` to force the webhook route on a mesh that has a public URL. |
+| `operators` | dict | `{}` | Logical operator id → that channel's user handle, so a step can address a named person. Read in reverse on inbound, so the same person is recognised across channels. |
+| `operators_only` | bool | `false` | Refuse anyone not listed in `operators` — checked BEFORE addressing, so it holds in a DM too. Off by default: a customer-facing seat must accept strangers. An empty `operators` map with this on fails CLOSED. |
+| `service_url` | string | `null` | **Teams only** — the Bot Framework endpoint, needed when the mesh SPEAKS FIRST (nothing inbound has arrived to learn it from). Use the global `https://smba.trafficmanager.net/teams/`; Microsoft warns against region-specific URLs. |
 | `listen_channels` | list | `[]` | Channel/chat IDs to accept inbound messages from (empty = all) |
 | `post_channel` | string | `null` | Default channel/chat ID for outbound messages (see per-provider notes below) |
 | `verify_token` | string | `null` | Webhook verification token — **WhatsApp only** (`hub.verify_token`) |
-| `operators` | dict | *(no schema default)* | Declared field (v2.2.44+). Per-operator routing map: operator name → provider address/ID (e.g. Slack user ID for a DM). Used to route a human agent's message to a specific person. See the example below. |
+| `operators` | dict | `{}` | Declared field (v2.2.44+). Per-operator routing map: operator name → provider address/ID (e.g. Slack user ID for a DM). Used to route a human agent's message to a specific person. See the example below. |
 
 **Note:** `ChannelConfig` allows extra fields (`extra="allow"`) for any provider-specific config.
 
@@ -1560,7 +1591,7 @@ escalation:
 | Field | Type | Default | Accepted Values | Description |
 |-------|------|---------|-----------------|-------------|
 | `enabled` | bool | `true` | `true`, `false` | Enable manager + summarizer |
-| `model` | string | `"gpt-4o-mini"` | same as [Model List](#model-list) | LLM model for Summarizer analysis |
+| `model` | string | **none — declare it** | same as [Model List](#model-list) | LLM model for Summarizer analysis. No default since 2.4.135 (`ManagerConfig.model` and `SummarizerConfig.model` both default to `None`). With `enabled: true` and no model, `validate_config` DOES flag this one — `"Manager model is required for analysis when enabled"` — unlike a plain agent's missing model, which it lets through. |
 | `domain` | string | `"generic"` | `generic`, `ecommerce`, `data_analysis` | Summarizer domain specialization |
 | `prompt` | string | `null` | any string (multiline supported) | **Evaluation criteria** — tell the Manager what success looks like, what to escalate on, and what patterns to watch. Injected into every Summarizer analysis call as an `EVALUATION CRITERIA` section, alongside the domain prompt. |
 | `can_intervene` | bool | `true` | `true`, `false` | Allow manager interventions (false = read-only) |
@@ -1575,7 +1606,7 @@ escalation:
 | `max_tokens` | int | `800` | 1 – model max | Max output tokens for the Manager analysis call. |
 | `analysis_style` | string | `"coordination"` | e.g. `coordination` | Style/persona applied to the Summarizer's analysis. |
 | `omnipresent_mode` | bool | `true` | `true`, `false` | When true, the Manager observes every agent turn; false narrows its attention. |
-| `triggers` | dict | `{}` | arbitrary | Declarative triggers for Manager intervention. |
+| `triggers` | dict | `null` | arbitrary | Declarative triggers for Manager intervention. |
 | `yields` | dict | `null` | yield contract | Optional yields contract for the Manager's own output. |
 | `super_agent` | bool | `false` | `true`, `false` | Wrap the Manager's analysis in the Super-Agent orchestrator. |
 | `knowledge` | bool \| object | `false` | `false`, or see [Knowledge Config](#knowledge-config) | Knowledge/RAG config available to the Manager. Defaults to `false` (off); set an object to enable. |
@@ -1770,10 +1801,28 @@ mesh:
   reply_stream: false           # default false; always ON in workers mode regardless
 ```
 
-**Dead env vars (no longer read — migrate to the blocks above):** `LEAFMESH_LLM_HARD_TIMEOUT_S`, `LEAFMESH_CRON_MIN_INTERVAL_SECONDS`, `LEAFMESH_WEBHOOK_{MAX_PAYLOAD_BYTES,RATE_LIMIT_MAX,RATE_LIMIT_WINDOW_S,REPLAY_SKEW_S}`, `LEAFMESH_MAX_SESSION_HISTORY_BYTES`, `LEAFMESH_MAX_PARALLEL_TOOL_CALLS`, `LEAFMESH_KNOWLEDGE_*` (all), `LEAFMESH_MESH_REPLY_STREAM`, `LEAFMESH_SUPER_AGENT_*` (→ per-agent `super_agent:` dict), `LEAFMESH_MANAGER_*_TAIL`.
+**Dead env vars — no longer read. If you find one set anywhere, here is what it became:**
+
+| Dead env var | Now |
+|---|---|
+| `LEAFMESH_LLM_HARD_TIMEOUT_S` | `timeouts.llm_hard_timeout_s` |
+| `LEAFMESH_CRON_MIN_INTERVAL_SECONDS` | `scheduler.cron_min_interval_seconds` |
+| `LEAFMESH_WEBHOOK_{MAX_PAYLOAD_BYTES,RATE_LIMIT_MAX,RATE_LIMIT_WINDOW_S,REPLAY_SKEW_S}` | `limits.webhook_*` |
+| `LEAFMESH_MAX_SESSION_HISTORY_BYTES` | `limits.max_session_history_bytes` |
+| `LEAFMESH_MAX_PARALLEL_TOOL_CALLS` | `limits.max_parallel_tool_calls` |
+| `LEAFMESH_KNOWLEDGE_QUERY_RATE_LIMIT_*` | `limits.knowledge_query_rate_limit_*` |
+| `LEAFMESH_KNOWLEDGE_MAX_INGEST_TOTAL_BYTES` | `limits.knowledge_max_ingest_total_bytes` |
+| `LEAFMESH_KNOWLEDGE_MAX_DOCS_PER_INGEST` | per-provider `settings.max_docs_per_ingest` |
+| `LEAFMESH_KNOWLEDGE_MAX_DOC_BYTES` | per-provider `settings.max_doc_bytes` |
+| `LEAFMESH_MESH_REPLY_STREAM` | `mesh.reply_stream` |
+| `LEAFMESH_SUPER_AGENT_*` | per-agent `super_agent:` dict |
+| `LEAFMESH_MANAGER_*_TAIL` | `manager:` block |
+
+Setting any of these produces no error and no effect — the mesh runs on the
+default and nothing tells you.
 **Still legitimately env:** `LEAFMESH_LICENSE_KEY`, `LEAFMESH_ENV_TOKEN`, `WEBHOOK_SECRET`, `INTERNAL_API_KEY`, `API_URL`/`API_PORT`, `EVOLUTION_API_PORT`, `SSE_COOKIE_SAMESITE`, `WORKERS`(_MODE), `OTEL_REDACT_PII`, `DISABLE_PROMPT_GUARDRAIL`, `WEBHOOK_ALLOW_LEGACY_HMAC`, `MCP_COMMAND_ALLOWLIST`, `TEAMS_ALLOW_UNVERIFIED`, `YAML_ENV_BLOCKLIST(_EXTRA)`, `HSTS_ENABLED`, `REFERRER_POLICY`, `CSP`, `LEAFMESH_SKILLS_DIR`, `LEAFMESH_SKILLS_EAGER`.
 
-> ⚠️ **The `timeouts` block is REJECTED by ≤2.4.130** (`from_yaml` raises `ConfigError`) — it is only valid on **2.4.131+**. Ship these blocks only when the template floor is `leafmesh>=2.4.131`.
+> ⚠️ **The `timeouts` block is REJECTED by ≤2.4.130** (`from_yaml` raises `ConfigError`) — it is only valid on **2.4.131+**. Ship these blocks only when the template floor is `leafmesh>=2.4.131` or higher (the shipped templates now floor at 2.4.263).
 
 ---
 
@@ -1821,7 +1870,7 @@ Top-level `api:` block Configures the SDK's HTTP server.
 | `mutation_rate` | float | `0.1` | 0.0 – 1.0 | Mutation probability |
 | `crossover_rate` | float | `0.7` | 0.0 – 1.0 | Crossover probability |
 | `elite_size` | int | `2` | 1+ | Elite genomes to preserve per generation |
-| `mutation_types` | list | `["prompt_variation", "temperature_adjustment", "tool_selection"]` | `prompt_variation`, `temperature_adjustment`, `tool_selection` | Mutation types |
+| `mutation_types` | list | all six below | `agent_connections`, `communication_patterns`, `agent_parameters`, `workflow_sequences`, `resource_allocation`, `timeout_settings` | Mutation types. **This is a `Literal` list — any other value is REJECTED at load**, so the three names this table used to list (`prompt_variation`, `temperature_adjustment`, `tool_selection`) do not exist and will fail validation. Evolution mutates the mesh's *shape* (wiring, timeouts, allocation), not an agent's prompt or temperature. |
 | `fitness_function` | string | `"task_completion_rate"` | free text | Fitness evaluation function |
 | `selection_method` | string | `"tournament"` | free text | Selection method |
 | `test_scenarios` | list | `[]` | list of scenario dicts — see below | Weighted test scenarios for fitness evaluation |

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/claude_skills/leafmesh/building-agents-thoroughly.md

@@ -415,7 +415,7 @@ accept and negotiate an intent is the rare exception that joins as a member.)
 
 | The user has… | Wire it as |
 |---|---|
-| Outlook / Gmail / mailbox | native email channel (SMTP/IMAP) or Graph/MCP connector |
+| Outlook / Gmail / mailbox | native email channel (SMTP out, provider webhook in) — or the **IMAP broker** when there is no public URL — or a Graph/MCP connector |
 | Slack / Teams / WhatsApp / Telegram | native `channels:` adapter on the human agent |
 | A SaaS with an API (CRM/ERP/WMS, Box, Jira, SharePoint) | `integration: mcp` / `n8n` connector agent, shaped by `@sdk.intelligence` |
 | A webhook-only system | `programmatic` agent + `connector_config.webhook_url` (n8n), or `/callback/{agent}` |

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/claude_skills/leafmesh/nuances-and-gotchas.md

@@ -324,7 +324,7 @@ agents:
   "Run time of job … was missed by H:MM:SS" warnings on wake. That is
   by design: a 9 AM "assign the day's tasks" run firing at 5 PM is
   worse than not firing. If you WANT one catch-up run on wake, set
-  `LEAFMESH_SCHEDULER_MISFIRE_GRACE_S=none` (ops env knob; coalesce
+  ``scheduler.misfire_grace_s`=none` (ops env knob; coalesce
   guarantees at most ONE catch-up per schedule).
 
 ## 14. Conditions FAIL CLOSED on missing fields — and `not` does NOT rescue them
@@ -404,7 +404,7 @@ output contract so the contract is always satisfiable.
   `LEAFMESH_*` env vars into the `timeouts`/`scheduler`/`runtime`/`limits`/
   `connectors` YAML blocks (see agent-config-fields.md). The SDK does **not** warn
   — a still-set env var is simply ignored and the default applies. Notably
-  `LEAFMESH_LLM_HARD_TIMEOUT_S` → `timeouts.llm_hard_timeout_s`, and the default
+  ``timeouts.llm_hard_timeout_s`` → `timeouts.llm_hard_timeout_s`, and the default
   dropped **300s → 90s**. The `timeouts` block is **rejected by ≤2.4.130**, so it
   must land *with* the 2.4.131 floor, never before.
 - **`pip install leafmesh` is core + LLM providers only.** Channels, listeners,

{create_leafmesh-2.7.0 → create_leafmesh-2.7.1}/create_leafmesh/templates/claude_skills/leafmesh/reference.md

@@ -195,20 +195,34 @@ entry_points:
 # agents.<name>.skills.sourceName. See SKILL.md → Skills System.
 
 # ── Brokers (v2.3.x — BRD-021 Event Listeners) ──
+# A broker holds ONLY how to REACH the system. What to read from it —
+# topic, consumer group, folder, qos — belongs on the agent's
+# `listen_events`, because two agents may read different topics from one
+# broker. Every broker model is extra="forbid", so putting them here is a
+# load error, not a warning.
 brokers:
   order_events_kafka:                    # name referenced from agents.<name>.listen_events
     type: "kafka"
-    bootstrap_servers: "kafka.internal:9092"
-    topic: "orders.created"
-    consumer_group: "leafmesh-order-processor"
+    bootstrap_servers: ["kafka.internal:9092"]   # a LIST, not a string
   support_inbox_imap:
     type: "imap"
     host: "imap.example.com"
     port: 993
-    user: "support@example.com"
+    username: "support@example.com"      # `username`, not `user`
     password: "${IMAP_PASSWORD}"
-    folder: "INBOX"
-    poll_interval_s: 30
+
+# …and the agent says what it wants from them:
+#
+# agents:
+#   order_processor:
+#     listen_events:
+#       - broker: order_events_kafka
+#         topic: "orders.created"
+#         consumer_group: "leafmesh-order-processor"
+#       - broker: support_inbox_imap
+#         folder: "INBOX"
+#         poll_interval_s: 30
+#         unseen_only: true
 
 # ── Agents ──
 agents:
@@ -589,15 +603,15 @@ Each feed post contains:
 | `COMPOSIO_API_KEY` | For Composio | Composio key |
 | `XAI_API_KEY` | For Grok models | xAI API key |
 | `MISTRAL_API_KEY` | For Mistral models | Mistral API key |
-| ~~`LEAFMESH_LLM_HARD_TIMEOUT_S`~~ | **DEAD (2.4.131)** | Moved to YAML `timeouts.llm_hard_timeout_s` (default **90**s; timed-out calls retry **once**, then fail; super-agent phases get 600s). The env var is **no longer read** — set the YAML block. Raise for long-running agents with big outputs |
+| ~~``timeouts.llm_hard_timeout_s``~~ | **DEAD (2.4.131)** | Moved to YAML `timeouts.llm_hard_timeout_s` (default **90**s; timed-out calls retry **once**, then fail; super-agent phases get 600s). The env var is **no longer read** — set the YAML block. Raise for long-running agents with big outputs |
 | `LEAFMESH_SKILLS_DIR` | No | Root dir for `filesystem` skill sources when no `config.root` is set (default `./skills/`) |
 | `LEAFMESH_API_PORT` | No | Mesh API port (default **18820**) |
-| ~~`LEAFMESH_MAX_PARALLEL_TOOL_CALLS`~~ | **DEAD (2.4.131)** | Moved to YAML `limits.max_parallel_tool_calls` (default **8**). Env var no longer read |
-| ~~`LEAFMESH_SUPER_AGENT_STEP_CONCURRENCY`~~ | **DEAD (2.4.131)** | Now a per-agent super-agent dict key: `super_agent: {step_concurrency: N}` (default **4**). Env var no longer read |
+| ~~``limits.max_parallel_tool_calls``~~ | **DEAD (2.4.131)** | Moved to YAML `limits.max_parallel_tool_calls` (default **8**). Env var no longer read |
+| ~~`super_agent: {step_concurrency: N} on the agent`~~ | **DEAD (2.4.131)** | Now a per-agent super-agent dict key: `super_agent: {step_concurrency: N}` (default **4**). Env var no longer read |
 | `LEAFMESH_WORKERS_MODE` | No | `1` enables workers/HA mode — required for running more than one instance against one Redis (exactly-once events, singleton runners, cross-instance locks) |
 | `LEAFMESH_WORKERS` | No | Number of worker processes in workers mode |
-| `LEAFMESH_LEASE_SECONDS` | No | Singleton-runner lease window (default **30**). Raise (e.g. `120`) when Redis is remote over a flaky link so connectivity blips shorter than the window never flap leased runners; heartbeat auto-scales to a third of the window (2.4.107) |
-| `LEAFMESH_LEASE_HEARTBEAT` | No | Explicit lease heartbeat interval override (must be < lease window) |
+| ``runtime.lease_seconds`` | No | Singleton-runner lease window (default **30**). Raise (e.g. `120`) when Redis is remote over a flaky link so connectivity blips shorter than the window never flap leased runners; heartbeat auto-scales to a third of the window (2.4.107) |
+| ``runtime.lease_heartbeat_s`` | No | Explicit lease heartbeat interval override (must be < lease window) |
 
 ## Webhook HMAC Authentication