zwarm 1.3.2__tar.gz → 1.3.3__tar.gz

{zwarm-1.3.2 → zwarm-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zwarm
-Version: 1.3.2
+Version: 1.3.3
 Summary: Multi-Agent CLI Orchestration Research Platform
 Requires-Python: <3.14,>=3.13
 Requires-Dist: python-dotenv>=1.0.0
@@ -136,12 +136,17 @@ state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
   enabled: true
+  message_role: user            # Role for nudge messages: user | assistant | system
   watchers:
     - name: progress
     - name: budget
       config:
         max_steps: 50
         max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10           # Nudge after N consecutive non-delegation calls
+        lookback: 30            # How many messages to check
     - name: scope
       config:
         keywords: []
@@ -217,28 +222,38 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
 | `delegation` | Ensures orchestrator delegates instead of writing code directly |
+| `delegation_reminder` | Nudges after many consecutive non-delegation tool calls (default: 10) |
 
 ### Enabling Watchers
 
 ```yaml
 # config.yaml
 watchers:
-  enabled:
-    - progress
-    - budget
-    - scope
-  config:
-    progress:
-      stuck_threshold: 5      # Flag after 5 similar steps
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords:
-        - "refactor"
-        - "rewrite"
+  enabled: true
+  message_role: user              # How nudges appear: user | assistant | system
+  watchers:
+    - name: progress
+      config:
+        max_same_calls: 3         # Flag after 3 identical tool calls
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10             # Nudge after 10 non-delegation calls
+    - name: scope
+      config:
+        avoid_keywords:
+          - "refactor everything"
+          - "rewrite"
 ```
 
+The `message_role` setting controls how watcher nudges are injected:
+- `user` (default): Appears as a user message - strong nudge, agent must respond
+- `assistant`: Appears as a previous assistant thought - softer, agent can continue
+- `system`: Appears as system instruction - authoritative guidance
+
 ### Watcher Actions
 
 Watchers can return different actions:

{zwarm-1.3.2 → zwarm-1.3.3}/README.md

@@ -124,12 +124,17 @@ state_dir: .zwarm             # State directory for sessions/events
 
 watchers:
   enabled: true
+  message_role: user            # Role for nudge messages: user | assistant | system
   watchers:
     - name: progress
     - name: budget
       config:
         max_steps: 50
         max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10           # Nudge after N consecutive non-delegation calls
+        lookback: 30            # How many messages to check
     - name: scope
       config:
         keywords: []
@@ -205,28 +210,38 @@ Watchers are composable guardrails that monitor agent behavior and can intervene
 | `pattern` | Custom regex pattern matching |
 | `quality` | Code quality checks |
 | `delegation` | Ensures orchestrator delegates instead of writing code directly |
+| `delegation_reminder` | Nudges after many consecutive non-delegation tool calls (default: 10) |
 
 ### Enabling Watchers
 
 ```yaml
 # config.yaml
 watchers:
-  enabled:
-    - progress
-    - budget
-    - scope
-  config:
-    progress:
-      stuck_threshold: 5      # Flag after 5 similar steps
-    budget:
-      max_steps: 50
-      max_sessions: 10
-    scope:
-      keywords:
-        - "refactor"
-        - "rewrite"
+  enabled: true
+  message_role: user              # How nudges appear: user | assistant | system
+  watchers:
+    - name: progress
+      config:
+        max_same_calls: 3         # Flag after 3 identical tool calls
+    - name: budget
+      config:
+        max_steps: 50
+        max_sessions: 10
+    - name: delegation_reminder
+      config:
+        threshold: 10             # Nudge after 10 non-delegation calls
+    - name: scope
+      config:
+        avoid_keywords:
+          - "refactor everything"
+          - "rewrite"
 ```
 
+The `message_role` setting controls how watcher nudges are injected:
+- `user` (default): Appears as a user message - strong nudge, agent must respond
+- `assistant`: Appears as a previous assistant thought - softer, agent can continue
+- `system`: Appears as system instruction - authoritative guidance
+
 ### Watcher Actions
 
 Watchers can return different actions:

{zwarm-1.3.2 → zwarm-1.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zwarm"
-version = "1.3.2"
+version = "1.3.3"
 description = "Multi-Agent CLI Orchestration Research Platform"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{zwarm-1.3.2 → zwarm-1.3.3}/src/zwarm/cli/main.py

@@ -672,7 +672,7 @@ def init(
     # Gather settings
     weave_project = ""
     adapter = "codex_mcp"
-    watchers_enabled = ["progress", "budget", "delegation"]
+    watchers_enabled = ["progress", "budget", "delegation", "delegation_reminder"]
     create_project_config = with_project
     project_description = ""
     project_context = ""
@@ -696,10 +696,10 @@ def init(
 
         # Watchers
         console.print("\n  [bold]Watchers[/] (trajectory aligners)")
-        available_watchers = ["progress", "budget", "delegation", "scope", "pattern", "quality"]
+        available_watchers = ["progress", "budget", "delegation", "delegation_reminder", "scope", "pattern", "quality"]
         watchers_enabled = []
         for w in available_watchers:
-            default = w in ["progress", "budget", "delegation"]
+            default = w in ["progress", "budget", "delegation", "delegation_reminder"]
             if typer.confirm(f"    Enable {w}?", default=default):
                 watchers_enabled.append(w)
 

{zwarm-1.3.2 → zwarm-1.3.3}/src/zwarm/core/config.py

@@ -86,7 +86,13 @@ class WatchersConfig:
     watchers: list[WatcherConfigItem] = field(default_factory=lambda: [
         WatcherConfigItem(name="progress"),
         WatcherConfigItem(name="budget"),
+        WatcherConfigItem(name="delegation_reminder"),
     ])
+    # Role for watcher nudge messages: "user" | "assistant" | "system"
+    # "user" (default) - Appears as if user sent the message, strong nudge
+    # "assistant" - Appears as previous assistant thought, softer nudge
+    # "system" - Appears as system instruction, authoritative
+    message_role: str = "user"
 
 
 @dataclass
@@ -122,13 +128,14 @@ class ZwarmConfig:
                 ],
             )
         else:
-            # Full format: watchers: {enabled: true, watchers: [...]}
+            # Full format: watchers: {enabled: true, watchers: [...], message_role: "user"}
             watchers_config = WatchersConfig(
                 enabled=watchers_data.get("enabled", True),
                 watchers=[
                     WatcherConfigItem(name=w) if isinstance(w, str) else WatcherConfigItem(**w)
                     for w in watchers_data.get("watchers", [])
                 ] or WatchersConfig().watchers,
+                message_role=watchers_data.get("message_role", "user"),
             )
 
         # Build orchestrator config with nested compaction
@@ -180,6 +187,7 @@ class ZwarmConfig:
                     {"name": w.name, "enabled": w.enabled, "config": w.config}
                     for w in self.watchers.watchers
                 ],
+                "message_role": self.watchers.message_role,
             },
             "state_dir": self.state_dir,
         }

{zwarm-1.3.2 → zwarm-1.3.3}/src/zwarm/orchestrator.py

@@ -352,10 +352,15 @@ Review what was accomplished in the previous session and delegate new tasks as n
 
         # Handle watcher result
         if result.action == WatcherAction.NUDGE and result.guidance:
-            # Inject guidance as a system message
+            # Inject guidance as a message with configurable role
+            message_role = self.config.watchers.message_role
+            # Validate role (default to user if invalid)
+            if message_role not in ("user", "assistant", "system"):
+                message_role = "user"
+
             self.messages.append(
                 {
-                    "role": "user",
+                    "role": message_role,
                     "content": f"[WATCHER: {result.metadata.get('triggered_by', 'unknown')}] {result.guidance}",
                 }
             )

{zwarm-1.3.2 → zwarm-1.3.3}/src/zwarm/prompts/orchestrator.py

@@ -43,6 +43,24 @@ Your primary tools are for delegation and verification:
 
 ---
 
+# Watchers
+
+Your execution is monitored by "watchers" - automated systems that observe your trajectory and provide guidance when you may be going off course. Watchers are designed to help you stay aligned with best practices and catch common pitfalls.
+
+When you see a message prefixed with `[WATCHER: ...]`, pay attention. These are interventions from the watcher system indicating that your current approach may need adjustment. Watchers might notice:
+
+- You're doing direct work (bash commands) when you should be delegating to executors
+- You're spinning or repeating the same actions without making progress
+- You're approaching resource limits (steps, sessions)
+- You're drifting from the original task scope
+- You're making changes without corresponding tests
+
+Watcher guidance is not optional advice - treat it as an important course correction. If a watcher tells you to delegate instead of doing work directly, delegate. If a watcher says you're stuck, step back and try a different approach. If a watcher warns about budget limits, prioritize and wrap up.
+
+The watchers are on your side. They exist to help you succeed, not to criticize. Heed their guidance promptly.
+
+---
+
 # Sync vs Async: Choosing the Right Mode
 
 The mode you choose for delegation significantly affects how work proceeds.

{zwarm-1.3.2 → zwarm-1.3.3}/src/zwarm/watchers/builtin.py

@@ -340,3 +340,85 @@ class QualityWatcher(Watcher):
                 )
 
         return WatcherResult.ok()
+
+
+@register_watcher("delegation_reminder")
+class DelegationReminderWatcher(Watcher):
+    """
+    Reminds the orchestrator to delegate work instead of doing it directly.
+
+    Counts consecutive non-delegation tool calls (bash commands that aren't
+    delegation-related). When the count exceeds a threshold, nudges the
+    orchestrator to consider delegating to executors instead.
+
+    This is a softer reminder than the DelegationWatcher - it doesn't detect
+    specific code-writing patterns, just notices when the orchestrator seems
+    to be doing a lot of direct work that could potentially be delegated.
+    """
+
+    name = "delegation_reminder"
+    description = "Reminds orchestrator to delegate after many direct tool calls"
+
+    # Tools that count as delegation-related (don't count against threshold)
+    DELEGATION_TOOLS = {
+        "delegate",
+        "converse",
+        "check_session",
+        "end_session",
+        "list_sessions",
+        "chat",  # Talking to user is not direct work
+    }
+
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        config = self.config
+        threshold = config.get("threshold", 10)  # Max consecutive non-delegation calls
+        lookback = config.get("lookback", 30)  # How many messages to check
+
+        # Count consecutive non-delegation tool calls from the end
+        consecutive_non_delegation = 0
+
+        # Look through recent messages in reverse order
+        for msg in reversed(ctx.messages[-lookback:]):
+            if msg.get("role") != "assistant":
+                continue
+
+            tool_calls = msg.get("tool_calls", [])
+            if not tool_calls:
+                # Text-only response doesn't reset counter, but doesn't add to it
+                continue
+
+            # Check each tool call in this message
+            has_delegation = False
+            has_non_delegation = False
+
+            for tc in tool_calls:
+                func = tc.get("function", {})
+                name = func.get("name", "")
+
+                if name in self.DELEGATION_TOOLS:
+                    has_delegation = True
+                elif name:  # Any other tool call
+                    has_non_delegation = True
+
+            if has_delegation:
+                # Found a delegation tool - stop counting
+                break
+            elif has_non_delegation:
+                # Add to consecutive count (one per message, not per tool call)
+                consecutive_non_delegation += 1
+
+        # Check if threshold exceeded
+        if consecutive_non_delegation >= threshold:
+            return WatcherResult.nudge(
+                guidance=(
+                    f"You've made {consecutive_non_delegation} consecutive direct tool calls "
+                    "without delegating to an executor. Remember: as the orchestrator, your role "
+                    "is to delegate coding work to executors, not do it yourself via bash. "
+                    "Consider whether the work you're doing could be delegated to an executor "
+                    "using delegate(). Executors can write code, run tests, and handle complex "
+                    "file operations more effectively than direct bash commands."
+                ),
+                reason=f"Consecutive non-delegation calls: {consecutive_non_delegation}",
+            )
+
+        return WatcherResult.ok()