create-leafmesh 2.6.6__tar.gz → 2.6.8__tar.gz

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/PKG-INFO

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

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/create_leafmesh/__init__.py

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

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/create_leafmesh/templates/claude_skills/leafmesh/SKILL.md

@@ -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. |
@@ -303,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
 
@@ -626,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.

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/create_leafmesh/templates/claude_skills/leafmesh/agent-config-fields.md

@@ -52,6 +52,8 @@ These fields apply to every agent regardless of `agent_type`.
 | `communication_type` | string | `"dual"` | `dual`, `chain`, `execute` | no | How agent communicates with the mesh |
 | `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 |
+| `instances` | int | `1` | 1–50 | no | **Parallel copies per activation (2.4.118+).** ONE trigger — wake, API request, chain handoff, mesh call, event listener — fans out into N executions of this agent in the SAME session. Each copy's input carries `_instance: {id, of}`; pair with an atomic claim tool so copies split a backlog instead of duplicating work. Distinct from `parallel`: that caps INCOMING calls, `instances` multiplies this agent's own run |
+| `instances_handoff` | string | `"last"` | `last`, `each` | no | What routes downstream when the copies finish. `last` (default): results are COMBINED — lists concatenated in instance order, numbers summed, other fields from the final copy, no field dropped — and the chain continues ONCE; the full per-copy detail also rides on `result._instances` for `@chain`/`@compose` rewrites, and `upstream_yields` carries the same combined payload. `each`: every copy routes its own raw result downstream (N triggers, no combining) |
 | `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 |
@@ -745,7 +747,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.
 
@@ -772,6 +783,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`).

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/create_leafmesh/templates/claude_skills/leafmesh/nuances-and-gotchas.md

@@ -257,6 +257,84 @@ 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.
+
+---
+
+## Parallel instances (`instances: N`, 2.4.118+) — the rules that surprise people
+
+One activation → N parallel copies of the agent, same session, any trigger
+source (wake, request, handoff, mesh call, listener). Two fields only:
+
+```yaml
+finance_agent:
+  instances: 3              # 3 copies per activation
+  instances_handoff: last   # last (default) = COMBINE and route once; each = route N times
+  tools: ["claim_batch"]    # an atomic claim tool splits the backlog between copies
+```
+
+What to know before using it:
+
+- **`last` merges deterministically**: lists concatenate in instance order,
+  numbers SUM, other fields take the final copy's value, and no field any
+  copy produced is dropped. The per-copy detail rides on
+  `result._instances = {count, results: {"1": {...}, ...}, failed: [...]}`,
+  and `upstream_yields` carries the same combined payload downstream.
+- **The number-sum rule cuts both ways.** `item_count` summing is right;
+  `confidence: 0.9` from two copies becomes `1.8` — wrong. Agents whose
+  yields carry ratios/scores should reshape with `@chain`/`@compose`
+  (which receive the combined result + the `_instances` pool).
+- **Without a claim tool, copies duplicate work** — and the merge honestly
+  shows it (two identical items, count 2). That's not a bug; give the
+  copies an atomic claim (`LPOP count` / `UPDATE … SKip LOCKED RETURNING`)
+  so each pulls a disjoint batch.
+- **Don't multiply triggers**: a 3-entry `wake_up` list × `instances: 3`
+  = 9 runs. One cron line is all a fanned agent needs.
+- **`instances` ≠ `parallel`.** `parallel`/`max_concurrent` caps INCOMING
+  calls (a queue at the door); `instances` multiplies this agent's own
+  execution. Fan out with `instances`, protect the shared downstream
+  bottleneck (ERP, DB) with `parallel` on THAT agent.
+- **Conversation/chain history keeps every copy's entry** (by design —
+  the framework doesn't hide work). If the doubling bothers a prompt,
+  reshape via `@compose`.
+- History channels aside, failures stay visible: a dead copy is reported
+  per-instance AND named in `_instances.failed`; the chain still continues
+  once if any copy succeeded.
+
+---
+
 ## Quick "why is my agent misbehaving?" checklist
 
 | Symptom | Likely rule |
@@ -271,3 +349,7 @@ above), never one of these.
 | 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) |
+| Two copies of the same output / doubled counts downstream | `instances` without a claim tool — copies duplicated the work (see Parallel instances) |
+| 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.6 → create_leafmesh-2.6.8}/create_leafmesh.egg-info/PKG-INFO

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

{create_leafmesh-2.6.6 → create_leafmesh-2.6.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "create-leafmesh"
-version = "2.6.6"
+version = "2.6.8"
 description = "Project scaffolding + cloud-deploy tool for LeafMesh"
 readme = "README.md"
 requires-python = ">=3.10"