v0.2.0

agent-loop-guard v0.2.0

v0.2.0 focuses on the two things 0.1.0 users hit first: loops that consecutive-repeat detection can't see (such as interleaved $A \rightarrow B \rightarrow A$ loops), and integrations where beforeCall() and afterCall() drift apart.

Backward Compatibility: 100% backward compatible with 0.1.0 — every new option defaults to previous behavior. The only change to existing decision objects is an added warnings array, which is empty unless a threshold is being approached.

🚀 What's New in v0.2.0

1. One-Call Integration & Error Stagnation

• guard.run(toolName, args, executor): Wraps beforeCall() → executor() → afterCall() / afterError() in a single awaited call, returning a structured RunOutcome instead of managing two separate decisions manually. Re-throws executor errors with error.loopGuardDecision attached.
• guard.afterError(toolName, args, error): Records a thrown error the way afterCall() records a result, ensuring a tool that keeps failing identically triggers STAGNANT_RESULT instead of burning through the whole run budget. Custom signatures configurable via options.errorSignature.

2. Enhanced Detection & Granular Budgets

• Sliding Window Repeat Detection (windowSize, maxRepeatsInWindow): Catches the same call recurring within a recent sliding window even when other calls are interleaved (REPEATED_CALL_IN_WINDOW).
• Per-Tool Budgets (maxCallsPerTool): Set call limits per tool (e.g. { search: 4 }). Reaching a tool's limit flags TOOL_BUDGET_EXHAUSTED without stopping the rest of the agent run.
• Wall-Clock Timeouts (maxDurationMs): Enforce wall-clock ceilings (TIME_BUDGET_EXHAUSTED). The timer begins at the first tool call, with an injectable now clock hook for deterministic testing.
• Non-Blocking Early Warnings (decision.warnings): Emits proactive warnings one step before limits block (APPROACHING_BUDGET, APPROACHING_TOOL_BUDGET, APPROACHING_REPEAT_LIMIT, APPROACHING_STAGNATION), allowing the agent to self-correct before being stopped. Controlled by warn and budgetWarnAt.

3. State Persistence & Observability

• State Persistence (toJSON() & LoopGuard.fromJSON()): Snapshot run state to survive process restarts or serverless pauses. Elapsed time is stored as duration, resuming accurately against any new system clock.
• Plain-Text Status Reporting (report()): Generates a compact, model-readable plain-text summary suitable for inserting into prompt context as a system note.
• Enriched summary(): Now includes blockedCalls, elapsedMs, callsByTool, and decisionsByCode.

4. Developer Experience & Packaging

• Full TypeScript Definitions: Shipped in src/index.d.ts covering RunOutcome, GuardWarning, WarningCode, LoopGuardState, LoopGuardSummary, and all block codes.
• Runnable Example: Added examples/agent-loop.mjs demonstrating the complete workflow.
• Automated Provenance: Releases are cryptographically signed with Sigstore provenance.

📦 Installation

npm install agent-loop-guard@0.2.0

Full Changelog: v0.1.0...v0.2.0

v0.1.0

agent-loop-guard v0.1.0

Initial public release of agent-loop-guard.

A lightweight, framework-independent guard for detecting runaway LLM agent loops before they waste execution time, tokens, and API budget.

Compatibility

• Node.js 18, 20, 22, and 24
• Modern TypeScript ESM / NodeNext projects