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

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

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

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

{create_leafmesh-2.6.7 → 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 |

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

@@ -293,6 +293,48 @@ 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 |
@@ -307,6 +349,7 @@ same turn as local tools, in parallel or in sequence.
 | 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.7 → 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.7
+Version: 2.6.8
 Summary: Project scaffolding + cloud-deploy tool for LeafMesh
 License-Expression: MIT
 Requires-Python: >=3.10

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

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