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

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

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

{create_leafmesh-2.6.6 → 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.6"
+__version__ = "2.6.7"

{create_leafmesh-2.6.6 → create_leafmesh-2.6.7}/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.7}/create_leafmesh/templates/claude_skills/leafmesh/agent-config-fields.md

@@ -745,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.
 
@@ -772,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`).

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

@@ -257,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 |
@@ -271,3 +307,6 @@ 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) |
+| 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.7}/create_leafmesh.egg-info/PKG-INFO

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

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

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