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

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

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

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

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

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

@@ -188,7 +188,10 @@ responsibilities into its module post-processing — never the reverse
 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.
+with distinct inputs beat one overloaded cron. Since 2.4.124 crons
+run in the agent's `timezone:` (default UTC; per-entry `timezone`
+overrides per schedule) — always set it when the schedule means a
+LOCAL time of day.
 
 **What is NEVER merged — roles are not the only thing in a mesh.
 Controls stay separate at any cost:**
@@ -693,7 +696,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`, `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`.
+**Universal fields** (any type): `name`, `description`, `agent_type`, `communication_type`, `parallel`, `max_concurrent`, `wake_up`, `wake_up_input`, `timezone`, `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.
 
@@ -937,6 +940,7 @@ agents:
     parallel: true                 # Parallel execution
     max_concurrent: 3              # Max concurrent invocations
     wake_up: "0 9 * * *"          # Cron schedule
+    timezone: "Asia/Kolkata"       # 2.4.124+ — cron zone; OMIT = UTC (9:00 UTC != 9:00 local!)
     optimization_strategy: "performance"  # performance | cost | speed
 
     # Structured output — force LLM to respond with valid JSON schema

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

@@ -52,11 +52,14 @@ 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 |
-| `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` | string or list | `null` | cron string; OR (2.4.107+) a list of cron strings; OR a list of `{cron, input, timezone}` 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, and (2.4.124+) its own `timezone` overriding the agent-level one for that schedule |
 | `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 |
+| `timezone` | string | `null` (= UTC) | any IANA zone, e.g. `"Asia/Kolkata"` | no | 2.4.124+ — timezone governing this agent's `wake_up` cron schedules. **Without it, crons run in UTC** — `"0 9 * * *"` fires at 14:30 IST, not 9:00. Validated at config load (a fake zone like `Asia/Bangalore` fails boot with a clear error). Studio offers a picker fed by `GET /api/registry?category=timezones` (2.4.125+) |
 | `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 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 |
@@ -1928,6 +1931,7 @@ Shows which fields are **used** (U), **ignored** (—), or **required** (R) for
 | `wake_up_input` | U | U | U | U |
 | `max_concurrent` | U | U | U | U |
 | `wake_up` | U | U | U | U |
+| `timezone` | U | U | U | U |
 | `listen_events` | U | U | U | U |
 | `yields` | U | U | U | U |
 | `inputs` | U | U | U | U |

{create_leafmesh-2.6.7 → create_leafmesh-2.6.9}/create_leafmesh/templates/claude_skills/leafmesh/examples.md

@@ -237,6 +237,7 @@ agents:
   daily_report_agent:
     agent_type: "programmatic"
     wake_up: "0 9 * * *"           # Every day at 9 AM
+    timezone: "Asia/Kolkata"       # …9 AM IST. Omit timezone and this fires at 9 AM UTC (2.4.124+)
     communication_type: "execute"   # Fire-and-forget
 
   hourly_monitor_agent:

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

@@ -293,6 +293,82 @@ same turn as local tools, in parallel or in sequence.
 
 ---
 
+## 13. `wake_up` crons run in UTC unless you declare a `timezone` (2.4.124+)
+
+A cron with no timezone is pinned to **UTC** — deliberately, so a laptop
+and a server never drift apart. The classic failure: an agent written
+with `"0 9 * * *"` expecting a 9 AM local pass actually fires at 14:30
+IST, and the operator concludes "wake-ups don't work".
+
+```yaml
+agents:
+  coordinator:
+    timezone: "Asia/Kolkata"        # governs ALL of this agent's crons
+    wake_up:
+      - cron: "0 9 * * *"
+        input: { run: "assign" }
+      - cron: "0 19 * * *"
+        timezone: "Europe/London"   # per-entry override beats agent-level
+        input: { run: "digest" }
+```
+
+- Validated at config load: a non-IANA name (`Asia/Bangalore` is the
+  classic trap — the real zone is `Asia/Kolkata`) fails boot with a
+  clear error, not silently at fire time.
+- `GET /api/registry?category=timezones` (2.4.125+) returns the exact
+  pickable zone list ({common, all, count}) — Studio's timezone inputs
+  are fed by it.
+- **Missed fires are skipped, not replayed**: if the process (or the
+  laptop) is asleep when a cron comes due, the fire is skipped once it
+  is more than the misfire grace (default 1 hour) late — you'll see
+  "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
+  guarantees at most ONE catch-up per schedule).
+
+## 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 +383,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.9}/create_leafmesh.egg-info/PKG-INFO

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

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

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