create-leafmesh 2.6.5__tar.gz → 2.6.7__tar.gz

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/PKG-INFO

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

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/__init__.py

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

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/_inspire/configs/config.yaml

@@ -5,29 +5,31 @@ environment: "development"                # "development" or "production"
 debug: true
 log_level: "INFO"
 
-redis:
-  host: "${REDIS_HOST:localhost}"
-  port: ${REDIS_PORT:6379}
-  db: 0
-  password: "${REDIS_PASSWORD:}"
-  auto_storage: true
-  decode_responses: true               # Decode Redis byte responses to strings
-  default_ttl: 3600                    # Default key TTL in seconds
-  session_ttl: 7200                    # Session TTL in seconds
-  # cluster_mode: true                   # Enable Redis cluster mode
-  # cluster_nodes:                        # Cluster node addresses
-  #   - "redis-node1:6379"
-  #   - "redis-node2:6379"
-  #   - "redis-node3:6379"
-
-  # TLS / encryption-in-transit
-  # Enable when your Redis server requires TLS (rediss://).
-  # ssl: true
-  # ssl_cert_reqs: required              # required | optional | none
-  # ssl_ca_certs: /etc/ssl/certs/redis-ca.crt
-  # ssl_certfile: /etc/ssl/certs/redis-client.crt   # mTLS, optional
-  # ssl_keyfile: /etc/ssl/private/redis-client.key  # mTLS, optional
-  # ssl_check_hostname: true
+persistence:
+  backend: redis
+  redis:
+    host: "${REDIS_HOST:localhost}"
+    port: ${REDIS_PORT:6379}
+    db: 0
+    password: "${REDIS_PASSWORD:}"
+    auto_storage: true
+    decode_responses: true               # Decode Redis byte responses to strings
+    default_ttl: 3600                    # Default key TTL in seconds
+    session_ttl: 7200                    # Session TTL in seconds
+    # cluster_mode: true                   # Enable Redis cluster mode
+    # cluster_nodes:                        # Cluster node addresses
+    #   - "redis-node1:6379"
+    #   - "redis-node2:6379"
+    #   - "redis-node3:6379"
+
+    # TLS / encryption-in-transit
+    # Enable when your Redis server requires TLS (rediss://).
+    # ssl: true
+    # ssl_cert_reqs: required              # required | optional | none
+    # ssl_ca_certs: /etc/ssl/certs/redis-ca.crt
+    # ssl_certfile: /etc/ssl/certs/redis-client.crt   # mTLS, optional
+    # ssl_keyfile: /etc/ssl/private/redis-client.key  # mTLS, optional
+    # ssl_check_hostname: true
 
 # ═══════════════════════════════════════════════════
 # API — HTTP server (CORS, etc.)
@@ -59,7 +61,6 @@ auto_discover:
 # The Manager never calls an LLM — it acts on the Summarizer's analysis.
 # ═══════════════════════════════════════════════════
 manager:
-  enabled: true
   model: "gpt-4o-mini"              # Used by Summarizer for LLM analysis
   domain: "generic"                  # Summarizer domain: "generic" | "ecommerce" | "data_analysis"
   # ── Learning-based routing (BRD-008) ──

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/ai-dev-squad/configs/config.yaml

@@ -14,15 +14,17 @@ environment: "development"
 debug: true
 log_level: "INFO"
 
-redis:
-  host: "${REDIS_HOST:localhost}"
-  port: ${REDIS_PORT:6379}
-  db: 0
-  password: "${REDIS_PASSWORD:}"
-  auto_storage: true
-  decode_responses: true
-  default_ttl: 86400
-  session_ttl: 1209600          # 14d — tickets are long-lived
+persistence:
+  backend: redis
+  redis:
+    host: "${REDIS_HOST:localhost}"
+    port: ${REDIS_PORT:6379}
+    db: 0
+    password: "${REDIS_PASSWORD:}"
+    auto_storage: true
+    decode_responses: true
+    default_ttl: 86400
+    session_ttl: 1209600          # 14d — tickets are long-lived
 
 # ─────────────────────────────────────────────────────────────────────
 # EVENT BROKERS — where Jira pushes events the squad listens to.
@@ -51,7 +53,6 @@ auto_discover:
   recursive: false
 
 manager:
-  enabled: true
   model: "gpt-4o-mini"
   domain: "generic"
   can_intervene: true

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/bd-proposals/configs/config.yaml

@@ -15,15 +15,17 @@ environment: "development"
 debug: true
 log_level: "INFO"
 
-redis:
-  host: "${REDIS_HOST:localhost}"
-  port: ${REDIS_PORT:6379}
-  db: 0
-  password: "${REDIS_PASSWORD:}"
-  auto_storage: true
-  decode_responses: true
-  default_ttl: 86400
-  session_ttl: 2592000
+persistence:
+  backend: redis
+  redis:
+    host: "${REDIS_HOST:localhost}"
+    port: ${REDIS_PORT:6379}
+    db: 0
+    password: "${REDIS_PASSWORD:}"
+    auto_storage: true
+    decode_responses: true
+    default_ttl: 86400
+    session_ttl: 2592000
 
 auto_discover:
   directory: "./agency"
@@ -31,7 +33,6 @@ auto_discover:
   recursive: false
 
 manager:
-  enabled: true
   model: "gpt-4o-mini"
   domain: "generic"
   can_intervene: true

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/bench-management/configs/config.yaml

@@ -35,15 +35,17 @@ environment: "development"
 debug: true
 log_level: "INFO"
 
-redis:
-  host: "${REDIS_HOST:localhost}"
-  port: ${REDIS_PORT:6379}
-  db: 0
-  password: "${REDIS_PASSWORD:}"
-  auto_storage: true
-  decode_responses: true
-  default_ttl: 86400
-  session_ttl: 2592000
+persistence:
+  backend: redis
+  redis:
+    host: "${REDIS_HOST:localhost}"
+    port: ${REDIS_PORT:6379}
+    db: 0
+    password: "${REDIS_PASSWORD:}"
+    auto_storage: true
+    decode_responses: true
+    default_ttl: 86400
+    session_ttl: 2592000
 
 auto_discover:
   directory: "./agency"
@@ -51,7 +53,6 @@ auto_discover:
   recursive: false
 
 manager:
-  enabled: true
   model: "gpt-4o-mini"
   domain: "generic"
   can_intervene: true

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/claude_skills/leafmesh/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash
 
 You are an expert at building multi-agent orchestration systems with the LeafMesh SDK.
 
-> **SDK baseline: 2.4.104.** Before wiring or debugging agents, read
+> **SDK baseline: 2.4.107.** Before wiring or debugging agents, read
 > **[nuances-and-gotchas.md](nuances-and-gotchas.md)** — the 10 non-obvious rules
 > that cause almost every "my agent silently does nothing / the handoff looks
 > empty / Gemini behaves differently" report. The top three that bite hardest:
@@ -29,6 +29,7 @@ You are an expert at building multi-agent orchestration systems with the LeafMes
 - [Rule 3 — Bound every retry back-edge](#rule-3--bound-every-retry-back-edge)
 - [How This Project Works](#how-this-project-works) · [Core SDK Pattern](#core-sdk-pattern) · [User-Facing APIs](#user-facing-apis)
 - [Agent Types](#agent-types) · [Super-Agent v3](#super-agent-v3) · [Skills System](#skills-system)
+- [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)
 - [YAML Agent Config (All Fields)](#yaml-agent-config-all-fields) · [Condition Syntax](#condition-syntax-can_call-conditions)
@@ -46,6 +47,7 @@ You are an expert at building multi-agent orchestration systems with the LeafMes
 | "Add a new LLM agent" | 1. Add YAML block in `configs/config.yaml` 2. Create `agency/<name>_agent.py` (optional -- pure YAML works) 3. Wire `can_call` from upstream agents 4. Add entry point if needed |
 | "Add a programmatic agent" | 1. Add YAML block with `agent_type: "programmatic"` 2. If connector-only: add `integration` + `connector_config` (no Python needed) 3. If Python logic: create `agency/<name>_agent.py` 4. Wire `can_call` |
 | "Add an external agent" | 1. Add YAML block with `agent_type: "external"`, `framework`, and `connector_config` (no Python needed) 2. Optionally add `agency/<name>_agent.py` to post-process connector result 3. Wire `can_call` |
+| "Let this agent use an MCP server's tools" | Agent-level `mcp:` block — the server's tools join that agent's tool list. Do **not** re-list them under `tools:`. See [MCP servers as tools](agent-config-fields.md#mcp--mcp-servers-as-tools-the-normal-way) |
 | "Integrate with Zapier/n8n/Composio/MCP" | Programmatic: `integration: "zapier"` + `connector_config`. External: `framework: "n8n"` + `connector_config`. Pre-compose helper: `@pre_compose(context_processor=zapier(...))`. See reference.md for all connector fields. |
 | "Set up HITL / human review" | Pick **one** `human_interface`: `default` (inbox), `webhook` (channels/HTTP), or `api` (Python callback). Each one accepts a *different* set of config fields — see HITL section below. Mixing them (e.g. `default` + `webhook_config`) is rejected at YAML load. |
 | "Connect agents" / "wire routing" | Add `can_call` entries with conditions. Use `calling_agent_response.field` in conditions. |
@@ -182,9 +184,11 @@ How to merge: the surviving agent takes the union of yields, the
 union of responsibilities in its prompt/module (sequenced stages),
 and the union of outbound edges. An LLM role absorbs deterministic
 responsibilities into its module post-processing — never the reverse
-(judgment never moves into a programmatic agent). One `wake_up` per
-agent: cron responsibilities merge only when one schedule can carry
-both.
+(judgment never moves into a programmatic agent). Since 2.4.107 one
+agent can hold MULTIPLE wake_up schedules, each with its own `input`
+({cron, input} list entries) — so cron responsibilities that share an
+agent's role no longer need to share one schedule; distinct schedules
+with distinct inputs beat one overloaded cron.
 
 **What is NEVER merged — roles are not the only thing in a mesh.
 Controls stay separate at any cost:**
@@ -301,7 +305,12 @@ hitl_stub_receiver.py  <- Webhook stub for testing HITL locally
 
 **Auto-discovery**: The SDK matches Python function names to YAML agent names. `greeter_agent()` in `agency/greeter_agent.py` binds to the `greeter_agent:` block in `config.yaml`.
 
-**Execution flow**: Entry point -> agent function runs -> SDK handles mesh communication (can_call), session state, Redis persistence, and observability automatically.
+**Execution flow**: Entry point -> agent function runs -> SDK handles mesh communication (can_call), session state, persistence, and observability automatically.
+
+**Persistence is a deployment choice, not a code one.** The same agency runs on
+Redis or on Postgres — `persistence: backend: redis` (default) or
+`backend: postgres`. Nothing in your agents or YAML changes between them, so
+never write agent code that assumes Redis.
 
 ## Core SDK Pattern
 
@@ -624,6 +633,55 @@ The LLM first calls `load_skill_reference("refund_flow")` for the primary body,
 
 A compromised skill body cannot do more than produce bad text, which the Summarizer + yields contract are designed to catch. A compromised tool can have real-world side effects.
 
+## Command Center (the business board)
+
+The agency designs its own business KPI board by watching what its agents
+actually do. **You do not write the metrics** — that is the whole point. It
+watches a few real runs, infers what this agency exists to achieve, and derives
+the numbers from real outcomes rather than from the config.
+
+```yaml
+manager:
+  command_center:
+    enabled: true
+    design_after_runs: 3     # runs to observe before designing (1–50)
+    max_metrics: 24
+    model: null              # defaults to the manager's model
+```
+
+What this means when you are building an agency:
+
+- **Name yields in business language.** The board is derived from what agents
+  yield and which tools they run. `status: "settled"` and `claim_value` produce
+  a board about claims; `output_1` and `flag_2` produce nothing anyone can read.
+  This is the single biggest thing you control.
+- **Nothing is pre-built.** There is no default metric set to switch on, and no
+  template. An empty-looking board early on means it has not seen enough work
+  yet, not that something is broken.
+- **Work done before the board exists is not lost.** Events are buffered and
+  replayed at their original timestamps once the schema lands.
+- **The board is business, never machinery.** It talks about invoices, tickets
+  and cases — not agents, tokens or queues. Do not try to make it show
+  operational metrics; the dashboards already do that.
+- **Operators can edit, export and re-import it**, and ask for a redesign in
+  plain words when the business changes what matters.
+
+## Image generation
+
+An agent that produces images picks an image model the same way any other agent
+picks a text one. Routing and capability checks are handled for you — an image
+model is never selected for a text agent, or the reverse.
+
+```yaml
+  - name: creative_agent
+    agent_type: llm
+    model: gemini-3-pro-image
+```
+
+Available: `gemini-3-pro-image`, `gemini-2.5-flash-image` (Google);
+`gpt-image-1`, `dall-e-3`, `dall-e-2` (OpenAI); Imagen 3 (Vertex);
+Titan Image Generator v2, Nova Canvas, Stable Diffusion XL (Bedrock).
+
 ## STRICT — fields by `agent_type`
 
 YAML load rejects fields that don't apply to the declared `agent_type`. Set only the fields that match.
@@ -635,7 +693,7 @@ YAML load rejects fields that don't apply to the declared `agent_type`. Set only
 | `external` | `framework` (**required**), `connector_config` |
 | `programmatic` | `integration`; `connector_config` allowed only when `integration` is set |
 
-**Universal fields** (any type): `name`, `description`, `agent_type`, `communication_type`, `parallel`, `max_concurrent`, `wake_up`, `yields`, `inputs`, `can_call`, `narration`, `wait_for`, `wait_for_timeout`, `auto_store_response`, `auto_store_yields`, `enforce_yields`, `enforce_yields_retry`, `memory`, `knowledge`, `skills`, `listen_events`.
+**Universal fields** (any type): `name`, `description`, `agent_type`, `communication_type`, `parallel`, `max_concurrent`, `wake_up`, `wake_up_input`, `yields`, `inputs`, `can_call`, `narration`, `wait_for`, `wait_for_timeout`, `auto_store_response`, `auto_store_yields`, `enforce_yields`, `enforce_yields_retry`, `memory`, `knowledge`, `skills`, `listen_events`.
 
 **Do not set `is_human_powered` manually** — it's auto-derived from `agent_type` and is silently overwritten by the validator.
 
@@ -1271,7 +1329,8 @@ def format_md(items: list) -> str:
 
 ```yaml
 manager:
-  enabled: true
+  # on by default — omit `enabled` (set `enabled: false` only to kill
+  # coordination + the summarizer entirely; rare)
   model: "gpt-4o-mini"          # Summarizer model
   domain: "generic"              # generic | ecommerce | data_analysis
   routing:

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/claude_skills/leafmesh/agent-config-fields.md

@@ -50,11 +50,15 @@ These fields apply to every agent regardless of `agent_type`.
 | `description` | string | `null` | any string | no | Agent description and purpose |
 | `agent_type` | string | `"llm"` | `llm`, `human`, `programmatic`, `external` | no | Agent execution type (see note below) |
 | `communication_type` | string | `"dual"` | `dual`, `chain`, `execute` | no | How agent communicates with the mesh |
-| `parallel` | bool | `false` | `true`, `false` | no | Enable parallel processing |
-| `max_concurrent` | int | `null` | 1 – unlimited | no | Max concurrent calls when `parallel: true` (null = unlimited) |
-| `wake_up` | string | `null` | cron expression (e.g. `"0 9 * * *"`) | no | Schedule for periodic wake-up |
+| `parallel` | bool | `false` | `true`, `false` | no | **Managed concurrency, not acceleration.** With `true`, up to `max_concurrent` sessions execute in this agent simultaneously; overflow calls are QUEUED and drain as slots free (queue actually drains since 2.4.38). WITHOUT it, every arriving call starts immediately — no per-agent cap at this gate. Use it to protect rate limits and cap simultaneous LLM spend on high-traffic agents |
+| `max_concurrent` | int | `5` (when `parallel: true`) | 1+ | no | The teller windows: simultaneous executions before new calls queue. Omitting it does NOT mean unlimited — the default is 5 |
+| `monthly_token_budget` | int | `null` | > 0 | no | Opt-in monthly token cap for this agent (auto-resets each calendar month). The gate pre-estimates each call and refuses BEFORE spending — the cap is never exceeded. Only bites LLM spend |
+| `monthly_cost_budget` | float | `null` | > 0 (USD) | no | Same as above in dollars; either cap trips the gate |
+| `budget_on_exhaust` | string | `graceful` | `graceful`, `escalate` | no | What exhaustion does: `graceful` = the agent stops cleanly with a `budget_exhausted` marker (yields filled with defaults, chain continues, no alarm); `escalate` = routed to the Manager as an error |
+| `wake_up` | string or list | `null` | cron string; OR (2.4.107+) a list of cron strings; OR a list of `{cron, input}` entries | no | Scheduled wake-up(s). Multiple schedules per agent are supported; each entry may carry its own `input` dict merged into that wake's payload |
+| `wake_up_input` | dict | `null` | any JSON object | no | 2.4.107+ — declared input template for scheduled wake-ups. Merged as the BASE of every wake payload (per-schedule `input` overrides it; trigger markers `wake_up_trigger`/`trigger_time` always win). Cron-woken agents receive real input instead of a bare trigger |
 | `listen_events` | list | `[]` | list of `EventListener` entries (see [Event Listeners](#event-listeners--brd-021)) | no | Bind agent to external event sources (Kafka, SQS, MQTT, Redis Streams, IMAP). Each entry references a broker from the top-level `brokers:` block. Parallel to `wake_up` — both are agent-level trigger surfaces |
-| `yields` | dict | `{}` | key: field name, value: type string or nested object | no | Output schema — what agent produces |
+| `yields` | dict | `{}` | key: field name, value: type string or nested object | no | Output schema — what the agent produces. Nested objects: `{type: object, fields: {...}}`; arrays: `{type: array, items: ...}`. Any declaration may add `nullable: true` (2.4.104) to accept an explicit null — declare it instead of leaving legitimately-null fields undeclared |
 | `inputs` | dict | `{}` | key: field name, value: type string or nested object | no | Input schema — what agent expects |
 | `can_call` | list | `[]` | list of `{"agent": "name"}` or `{"agent": "name", "condition": "expr"}` | no | Agents this agent can invoke |
 | `narration` | string | `null` | any string (multiline supported) | no | Plain-English routing hints for the Manager — evaluated by the Summarizer when conditions don't cover everything (see [Narration Routing](#narration-routing)) |
@@ -297,6 +301,10 @@ These fields are used when `agent_type` is `"llm"`. Ignored for other types.
 | `reasoning_budget` | int | `null` | 1024 – 32768 (tokens) | Max native reasoning tokens. Provider defaults apply when omitted. |
 | `thinking_budget` | int | `null` | 1024 – 32768 (tokens) | Legacy budget field, still **its own declared `AgentConfig` field** in 2.4.33 (not removed). Prefer `reasoning_budget`; set only one to avoid ambiguity. |
 | `enable_prompt_caching` | bool | `false` | `true`, `false` | Enable provider-native prompt caching for cost reduction (see below) |
+| `cache` | bool | `null` | `true`, `false` | LLM-text cache opt-out (2.4.107). The SDK cache reuses ONLY the model's text on identical requests — your function/@chain/@compose always run fresh (side effects re-execute). `false` disables even that reuse for agents that need a fresh model call every time |
+| `strict_tools` | bool | `false` | `true`, `false` | Provider-native strict tool schemas (`strict: true`): the model cannot pass hallucinated or extra arguments to tools. Turn on when tool-arg discipline matters more than model flexibility |
+| `memory_strategy` | string | `null` | `recency`, `relevant`, `hybrid` | How prior activity is selected for recall when `memory` is enabled: newest-first, similarity-ranked, or blended |
+| `knowledge_strategy` | string | `null` | (provider-dependent) | Selection strategy for knowledge/RAG retrieval when `knowledge` is enabled |
 | `response_format` | dict | *(accepted extra — not a declared field)* | JSON Schema object | Structured output — forces LLM to respond with valid JSON matching this schema. **Not a declared `AgentConfig` field**; it is accepted via `extra='allow'` and consumed by the provider layer (works, but has no schema-level default/validation). |
 | `optimization_strategy` | string | `null` | `performance`, `cost`, `speed` | Per-agent model selection strategy |
 | `context_parts` | dict | `null` | see below | Optional context parts |
@@ -737,7 +745,16 @@ Connects to an external AutoGen Studio or custom AutoGen API service via HTTP.
 | `max_poll_seconds` | float | `300.0` | no | — | Max total polling time (seconds) |
 | `http_timeout` | float | `30.0` | no | — | HTTP request timeout (seconds) |
 
-#### mcp
+#### mcp (as a connector — one tool, one agent)
+
+> **Read this first — there are two ways to use MCP, and this is the older,
+> narrower one.** What follows describes MCP as a *connector*: the whole agent
+> becomes a single call to a single remote tool, named by `tool_name`.
+>
+> If what you want is "this agent can use the tools that server offers", you
+> want the **agent-level `mcp:` block** instead — see *MCP servers as tools*
+> below. That is the right default. Reach for the connector form only when the
+> agent genuinely *is* one remote call and nothing else.
 
 MCP supports two transport modes. `tool_name` is always required.
 
@@ -764,6 +781,59 @@ MCP supports two transport modes. `tool_name` is always required.
 | `url` | string | `""` | **yes** (http) | MCP server HTTP/SSE endpoint |
 | `auth_token` | string | `""` | no | Bearer token |
 
+---
+
+### `mcp:` — MCP servers as tools (the normal way)
+
+**This is the one you almost always want.** An agent declares the MCP servers it
+may reach, and every tool those servers publish joins the tool list its model
+already sees. No separate registration, and you do **not** name the tools again
+under `tools:`.
+
+```yaml
+agents:
+  - name: research_agent
+    agent_type: llm
+    model: gpt-4o-mini
+    mcp:
+      - url: https://mcp.example.com/sse
+        token: ${MCP_SEARCH_TOKEN}
+        use: [search_docs, fetch_page]   # omit to expose every tool
+      - transport: stdio                  # a server you launch yourself
+        command: python
+        args: [./servers/inventory.py]
+        name: inventory
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport` | string | `"http"` | `"http"` for a hosted server, `"stdio"` for one you launch |
+| `url` | string | `""` | Endpoint — **required** for `http` |
+| `command` | string | `""` | Executable — **required** for `stdio` |
+| `args` | list | `[]` | Arguments for the stdio command |
+| `token` | string | `""` | Auth token — keep it in an env var: `${MY_TOKEN}` |
+| `use` | list | `[]` | Only expose these tools; empty means all of them |
+| `name` | string | derived | Namespace prefix; derived from the server when unset |
+| `timeout` | float | `30.0` | Per-call timeout in seconds |
+
+**Things that will bite you if you don't know them:**
+
+- **Tools are namespaced.** A tool arrives as `<server>_<tool>` — `inventory_search`,
+  not `search` — so two servers can both publish `search` without colliding.
+- **`tools:` is a positive allowlist for LOCAL tools only.** MCP tools are merged
+  in automatically. An agent whose tools are all remote can omit `tools:`
+  entirely; adding the MCP tool names there does nothing useful.
+- **Scoped to the declaring agent.** Another agent cannot call your server's
+  tools unless it declares the server too. Same rule as local tools.
+- **They run like any other tool** — same permission check, same timeout, same
+  guardrail on tool output, same execution record. A model can call an MCP tool
+  and a local tool in the same turn, in parallel or in sequence.
+- **A server that is down at startup does not stop the agency.** The agent starts
+  without that server's tools and logs a warning.
+- **Set `tool_choice` / `allow_parallel_tool_calls` on the agent as usual** — they
+  apply to MCP tools too (SDK ≥ 2.4.112; earlier builds dropped these settings
+  when saving an agent that had no local `tools:`).
+
 #### zapier
 
 Tool name is built as `{connection}_{action}` (e.g. `google_sheets_create_row`).
@@ -1848,6 +1918,14 @@ Shows which fields are **used** (U), **ignored** (—), or **required** (R) for
 | `integration` | — | — | U | — |
 | `communication_type` | U | U | U | U |
 | `parallel` | U | U | U | U |
+| `monthly_token_budget` | U | U | U | U |
+| `monthly_cost_budget` | U | U | U | U |
+| `budget_on_exhaust` | U | U | U | U |
+| `cache` | ✓ | — | — | — |
+| `strict_tools` | ✓ | — | — | — |
+| `memory_strategy` | ✓ | — | — | — |
+| `knowledge_strategy` | ✓ | — | — | — |
+| `wake_up_input` | U | U | U | U |
 | `max_concurrent` | U | U | U | U |
 | `wake_up` | U | U | U | U |
 | `listen_events` | U | U | U | U |

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/claude_skills/leafmesh/nuances-and-gotchas.md

@@ -1,6 +1,6 @@
 # LeafMesh — Nuances & Gotchas (READ FIRST)
 
-**SDK baseline: 2.4.104.** This file captures the non-obvious rules that cause
+**SDK baseline: 2.4.107.** This file captures the non-obvious rules that cause
 real, hard-to-debug failures. Most "my agent silently does nothing" or "the
 handoff looks empty" or "Gemini behaves differently from GPT" reports trace to
 exactly one item below. Read this before wiring agents.
@@ -109,6 +109,14 @@ worked and are the safe default.
 
 ---
 
+**Nullable fields:** any yields declaration may add `nullable: true` (2.4.104)
+to accept an explicit null. If a field is legitimately null sometimes, DECLARE
+it nullable — do not leave it undeclared, and do not let the prompt mandate
+null for a non-nullable field (the SDK detects that conflict and skips the
+doomed reflection retry, telling you which to fix).
+
+---
+
 ## 4. Structured output is IDENTICAL across providers (2.4.103)
 
 **Trap:** you assume Gemini/Anthropic/Bedrock enforce a hard native schema while
@@ -202,12 +210,18 @@ stripped from API/UI responses; never surface them.
 
 ## 11. `context` is a shared, per-turn pool — and a side channel
 
-Within ONE agent turn, the SAME `context` dict is threaded through every stage:
-`@pre_compose` → your agent function → each `@chain` step → each `@compose`
-shaper. Whatever a stage writes, later stages read. Use it to carry data *within*
-a turn. (To carry data to the NEXT agent, use yields → `upstream_yields`, see #2.
+Within ONE agent turn, the SAME `context` dict is threaded through the
+in-process stages: `@pre_compose` → your agent function → each `@chain` step.
+Whatever a stage writes, later stages read. Use it to carry data *within* a
+turn. (To carry data to the NEXT agent, use yields → `upstream_yields`, see #2.
 `context` is rebuilt every turn; it does NOT travel between agents.)
 
+**`@compose` is the exception (guaranteed-by-test since 2.4.107):** handoff
+shapers run at PUBLISH time in the mesh and receive a fresh minimal ctx
+(`session_id`, `tenant_id`, `from_agent`) — NOT the turn's context. A shaper
+that needs pool-derived data must read it from the RESULT — put it there in
+your function or a `@chain` step.
+
 **The useful pattern — pull a full set, send the LLM a subset, rejoin after:**
 the prompt is built from `input_data` + messages, NOT from arbitrary `context`
 keys. So data parked in `context` under YOUR OWN key never reaches the model:
@@ -243,6 +257,42 @@ above), never one of these.
 
 ---
 
+## 12. MCP tools do NOT go in `tools:` — and there are two different MCPs
+
+Declare the server on the agent and its tools join that agent's tool list:
+
+```yaml
+  - name: research_agent
+    agent_type: llm
+    model: gpt-4o-mini
+    mcp:
+      - url: https://mcp.example.com/sse
+        token: ${MCP_TOKEN}
+        use: [search_docs]        # omit for every tool the server publishes
+```
+
+Three ways people get this wrong:
+
+1. **Re-listing the tools under `tools:`.** `tools:` is a positive allowlist for
+   *locally registered* tools. MCP tools are merged in automatically. Naming
+   them there does nothing — and if that is the only entry, you have written an
+   allowlist that hides your local tools for no gain.
+2. **Expecting the bare tool name.** Tools arrive namespaced as
+   `<server>_<tool>` — `inventory_search`, not `search` — so two servers can
+   publish the same name safely. Conditions and metric filters must use the
+   namespaced name.
+3. **Confusing it with `framework: "mcp"`.** That is the *connector* form, where
+   the whole agent is one call to one remote tool named by `tool_name`. It still
+   exists and is occasionally right, but it is not how you give an agent a set
+   of tools. If you find yourself creating an agent per remote tool, you want
+   the `mcp:` block instead.
+
+A remote tool otherwise behaves exactly like a local one — same permission
+scoping, timeout, output guardrail and execution record, and it can run in the
+same turn as local tools, in parallel or in sequence.
+
+---
+
 ## Quick "why is my agent misbehaving?" checklist
 
 | Symptom | Likely rule |
@@ -254,5 +304,9 @@ above), never one of these.
 | Agent runs as pure-YAML unexpectedly | #7 (discover name mismatch) |
 | Agent schedules itself instead of acting | #8 (schedule_followup misuse) |
 | "Provider X behaves differently from Y" on yields | #4 (they don't — parity since 2.4.103) |
+| A handoff fired that the function's return should have prevented | Upgrade — since 2.4.106 `can_call` and `@compose` evaluate the FUNCTION's return, never the raw LLM yields |
 | Data I stashed for later "leaked" into the LLM prompt | #11 (used a reserved key like `prepared_data`) |
 | Data I put in `context` vanished at the next agent | #11 (`context` is per-turn; use yields for cross-agent) |
+| The model can't see my MCP server's tools | #12 (declare `mcp:` on the agent; don't list them in `tools:`) |
+| MCP tool calls fail with "tool not found" | #12 (tools are namespaced `<server>_<tool>`) |
+| Command Center board looks empty or generic | It designs after `design_after_runs` real runs; and it can only speak the language your yields use |

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/claude_skills/leafmesh/reference.md

@@ -120,9 +120,27 @@ auto_discover:
   pattern: "*_agent.py"
   recursive: false
 
+# ── Persistence backend (`persistence`) — Redis (default) OR Postgres ──
+# Business-logic persistence (sessions, agent state, yields, feed, HITL) can
+# run on either backend. Omit the block entirely for Redis via the `redis:`
+# config. Postgres example:
+persistence:
+  backend: postgres          # redis (default) | postgres
+  host: db.internal          # Postgres connection
+  port: 5432
+  database: leafmesh
+  user: leafmesh_app
+  password: "${PG_PASSWORD}"
+  sslmode: require           # optional
+  default_ttl: 3600          # generic key TTL (seconds)
+  session_ttl: 604800        # session lifetime (7 days)
+  pool_min: 1
+  pool_max: 10
+
 # ── Manager (coordination + summarizer) ──
 manager:
-  enabled: true
+  # on by default — omit `enabled`; set `enabled: false` only to disable
+  # coordination + the summarizer entirely (rare; no interventions, no feed)
   model: "gpt-4o-mini"                 # Model for summarizer LLM calls
   domain: "generic"                     # Summarizer domain specialization
   can_intervene: true                   # Allow automatic interventions
@@ -516,6 +534,19 @@ Source fields by broker type:
 
 Delivery: **at-least-once**, idempotency on `(listener_name, message_id)`. After retries exhaust → DLQ if configured, otherwise dropped + logged.
 
+## Notable Stream Events (observability)
+
+| Event | When |
+|-------|------|
+| `llm.cost.tracked` | Token + USD cost, recorded once per provider call at the gate |
+| `llm.cache.hit` | Model text reused (agent function/decorators still ran fresh) |
+| `media.generated` | Image-generation call produced media (metadata only) |
+| `reflection.doomed_skipped` | Reflection skipped — null-vs-schema conflict; fix `nullable: true` or the prompt |
+| `session.result_dropped` | Completed work discarded (session already escalated) — loud, with the discarded keys |
+| `dispatch.dedup_suppressed` | Duplicate work unit suppressed (exactly-once) |
+| `manager.degradation` | Super-agent finished degraded; Manager reviewed without re-running |
+| `budget.exhausted` | Per-agent monthly budget tripped before spend |
+
 ## Feed Post Structure
 
 Each feed post contains:
@@ -560,6 +591,13 @@ Each feed post contains:
 | `MISTRAL_API_KEY` | For Mistral models | Mistral API key |
 | `LEAFMESH_LLM_HARD_TIMEOUT_S` | No | Hard ceiling on a single LLM provider call (default **90**s; timed-out calls are retried **once** with the same ceiling, then fail; super-agent phases get 600s automatically). Raise for long-running agents that legitimately produce 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` | No | Cap on tool calls executed concurrently within one LLM step (default **8**) |
+| `LEAFMESH_SUPER_AGENT_STEP_CONCURRENCY` | No | Cap on super-agent plan steps running concurrently when the `depends_on` DAG allows it (default **4**) |
+| `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) |
 
 ## Webhook HMAC Authentication
 

{create_leafmesh-2.6.5 → create_leafmesh-2.6.7}/create_leafmesh/templates/customer-success/configs/config.yaml

@@ -69,15 +69,17 @@ log_level: "INFO"
 # ═══════════════════════════════════════════════════════════════════
 # REDIS — health-score cache, customer context, save-play history
 # ═══════════════════════════════════════════════════════════════════
-redis:
-  host: "${REDIS_HOST:localhost}"
-  port: ${REDIS_PORT:6379}
-  db: 0
-  password: "${REDIS_PASSWORD:}"
-  auto_storage: true
-  decode_responses: true
-  default_ttl: 86400              # keep customer state for a day across signals
-  session_ttl: 604800             # 7 days — long enough for save-play follow-through
+persistence:
+  backend: redis
+  redis:
+    host: "${REDIS_HOST:localhost}"
+    port: ${REDIS_PORT:6379}
+    db: 0
+    password: "${REDIS_PASSWORD:}"
+    auto_storage: true
+    decode_responses: true
+    default_ttl: 86400              # keep customer state for a day across signals
+    session_ttl: 604800             # 7 days — long enough for save-play follow-through
 
 # ═══════════════════════════════════════════════════════════════════
 # AUTO-DISCOVER
@@ -91,7 +93,6 @@ auto_discover:
 # MANAGER — supervisor, watches for save-play patterns + escalations
 # ═══════════════════════════════════════════════════════════════════
 manager:
-  enabled: true
   model: "gpt-4o-mini"
   domain: "generic"
   can_intervene: true