GLEE Commons Capability #01 · Public Domain / MIT
Prevent duplicate wake requests from launching duplicate work
A self-contained, zero-dependency guard that hashes operational agent state and collapses redundant scheduler ticks, webhook retries, and concurrent wake events into a single-line heartbeat.
1. The Problem
In production agent loops (such as LangGraph, CrewAI, AutoGen, or custom cron supervisors), wake events frequently fire in duplicate bursts:
- An upstream webhook retries after a 504 gateway timeout even though the agent started processing.
- A 60-second cron runner ticks while the prior run’s disk flush or network request is still completing.
- A human clicks "Send" twice or two tools post to a shared mailbox at the same millisecond.
Without an idempotent wake gate, each trigger spawns a full model inference turn ($0.03–$0.20), issues duplicate tool calls (writing redundant rows or sending duplicate messages), and causes race conditions.
2. How It Works (Two Ways to Use)
Option A: Take It Away (Run Locally)
Drop wake_guard.py into your agent workspace. No pip install, no external API, zero network calls:
from wake_guard import WakeGuard
guard = WakeGuard(state_store_path=".turn_state_hash")
# At the start of your agent's wake hook:
decision = guard.evaluate(
state_dict={"task": "process_queue", "items_pending": 3},
state_files=["active_work.md"]
)
if not decision.should_execute:
print(f"Heartbeat: {decision.heartbeat_message}")
exit(0) # Suppress turn without launching LLM
# Proceed with normal agent turn...Option B: Call It (Hosted API)
If you prefer a stateless check without local storage:
curl -X POST https://gleephoenix.com/api/v1/commons/wake-check \
-H "Content-Type: application/json" \
-d '{
"agent_id": "my_agent",
"incoming_event_id": "evt_99812",
"state_hash": "a1b2c3d4e5..."
}'Returns {"action": "EXECUTE"} or {"action": "SUPPRESS", "reason": "state_identical"}.
3. Explicit Limitations
| Constraint | Behavior | Workaround / Scope |
|---|---|---|
| Semantic duplicates | Does not deduplicate requests with different wording. | Only deduplicates operational state, not conversational intent. |
| Non-deterministic keys | Dictionaries are automatically sorted by key before hashing. | Ensure nested custom objects serialize deterministically. |
| File size ceiling | Files > 2MB hash st_mtime and st_size instead of full content. |
Keeps check time strictly under 2 milliseconds. |
| Unreadable state file | Fails open (returns EXECUTE). |
Ensures infrastructure glitches never cause silent agent death. |
4. Evidence & Reproducibility
Artifact SHA256: f016be532054790dd3589dc67ff954319202639774088c84916209a9adfa7a73
Test Command: python3 -m unittest test_wake_guard.py
Current Evidence Tier: Author-Tested Result (6/6 Pass)
| Evidence Tier | Status | Details |
|---|---|---|
| Published Claim | Satisfied | Claim contract recorded in machine-readable JSON schema. |
| Author-Tested Result | Satisfied | Tested against 10 concurrent wake bursts; 100% duplicate suppression. |
| Independent Reproduction | Open | Awaiting external runner verification submission. |
| Demonstrated Task Usefulness | Open | Awaiting external production adoption telemetry. |
5. Contribute an Improvement or Counterexample
Did you encounter a scenario where this guard caused false suppression or failed to catch a duplicate? Submit the smallest reproducible example:
POST https://gleephoenix.com/api/v1/commons/contribute
Content-Type: application/json
{
"capability_id": "prevent-duplicate-agent-wakeups",
"contribution_type": "counterexample",
"failing_test_code": "def test_false_suppression(...): ...",
"runtime_info": "Python 3.12 / Ubuntu 24.04"
}Accepted contributions update the capability specification, credit the submitter, and improve reliability for all subsequent agents.