How the Watcher system works
Watchers are how Buffaly prevents LLMs from drifting during long-running tasks. They act as an over-the-shoulder "System 2" supervisor, monitoring a working session's lifecycle events and queueing guidance when the primary agent gets off track.
The Problem: LLM Drift
When an agent executes a long-running task, it is acting primarily as a "System 1" thinker—rapidly processing the immediate context, making API calls, and generating text. However, during complex tasks (or after a heavy context compaction cycle), this fast-moving agent can easily lose the plot. It might forget to update the Plan, skip a critical validation step, or get stuck in a tool-calling loop.
Standard frameworks try to solve this by adding more rules to the system prompt. Buffaly solves this architecturally with the Level 2 Watcher.
The System 2 Supervisor
The Watcher is a secondary, parallel session dedicated entirely to "System 2" (slow, deliberative) thinking. It does not do the work. It observes the work.
What it CANNOT do
- Cannot execute standard tools (no file writing, no CLI).
- Cannot own the final deliverable.
- Cannot replace the primary agent's Plan.
What it CAN do
- Subscribe to the primary agent's
turn.completedevents. - Read the primary agent's Plan, Scratch, and Task Artifacts.
- Dispatch labeled, supervisory guidance back to the primary agent.
Architecture & Lifecycle
The Level 2 Watcher observes event-driven lifecycle callbacks from a source session.
Key Patterns & Handlers
- Watcher Key: Usually follows the pattern
{sourceSessionKey}-level-two. - Subscription: It subscribes to
turn.completedevents from the source session. - Handler Action: Callbacks trigger the default
tool:ToDispatchSupervisoryEvent.
Callback Dispatch
When the primary agent finishes a turn, the handler digests the callback and queues it into the Watcher's timeline. The Watcher reviews the digest (and the source session's current Plan/Scratch) to determine if intervention is needed.
Watchers vs. Child Agents
Do not confuse a Watcher with a delegated subagent. They serve entirely different architectural purposes.
| Session Type | Purpose | Mental Model |
|---|---|---|
| Normal Session (Level 1) | The main work surface. Executes tools and owns the task artifact. | The Engineer. |
| Child / Subagent | A delegated runtime spun up to complete a specific, bounded sub-task. | The Specialist/Contractor. |
| Level 2 Watcher | Observes lifecycle events and sends corrective guidance. | The Supervisor (System 2). |
Queued Guidance
If the Watcher determines the primary agent is stuck, drifting, or skipped a step in the Plan, it uses specific tools to intervene:
-
ToSendMessageToObservedSessionAndReturn -
ToSendMessageToObservedSessionAndWait
The tool automatically prepends the instruction with [label: Level 2] so the primary agent knows it is receiving supervisory input, not user input. This input should nudge, correct, or request verification—it should not attempt to silently execute the task itself.
Verification & Inspection
When diagnosing a stuck task, do not assume the Watcher is broken. Ask Buffaly to inspect the state explicitly.
Prompt to Inspect State
"Check whether this session has a Level 2 watcher. Verify the watcher key, parent, observed session key, event subscription, and handler."
Prompt to Inspect Callbacks
"Inspect the Watcher's callback history. Summarize whether the observed session is stalled, blocked, complete, or making progress."
Verification Checklist
- Watcher key follows
...-level-two. -
AgentNameis explicitly set tolevel-2. - Event subscription includes
turn.completed. - Handler is
tool:ToDispatchSupervisoryEvent. - Queued guidance appears in the primary timeline with a
[Level 2]label.
Troubleshooting
| Symptom | First Checks | Good Next Action (Prompt) |
|---|---|---|
| Watcher not created | Source exists, source is not Level 2, auto-attach config (if restoring). | "Verify installation start, success or failure, and the expected watcher key." |
| Watcher exists but no callbacks | Event subscription, source key, event type, latest turn.completed. | "Run watcher binding verification and inspect received callback rows." |
| Callback dispatch fails | Handler action, tool load diagnostics, execution error. | "Inspect dispatch diagnostics and confirm ToDispatchSupervisoryEvent can load." |
| Guidance sent but ignored | Primary agent's timeline, queue count, worker state. | "Verify labeled guidance landed in the observed session and check queued input processing." |