Files
waggle-os/packages/agent/src/loop-guard.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

205 lines
6.9 KiB
TypeScript

import { createHash } from 'node:crypto';
export interface LoopGuardConfig {
maxRepeats?: number;
/** Size of the rolling window for oscillation detection (default: 10) */
windowSize?: number;
/** Number of times a hash can appear in the window before flagging a loop (default: 4) */
windowThreshold?: number;
/** T1 — identical tool+args calls (any outcome) before a "result already returned" block (default: 5) */
identicalCallLimit?: number;
/** T2 — identical consecutive FAILURES before a block (default: 3) */
identicalFailureLimit?: number;
/** T4 — same-tool (any-args) consecutive FAILURES before a block (default: 6) */
sameToolFailureLimit?: number;
/** T3 — same-tool consecutive FAILURES before a HARD ABORT (default: 8) */
criticalFailureLimit?: number;
/** Cap on the retained (toolName, argsHash, success) history (default: 50) */
historyCap?: number;
}
/** One recorded tool execution outcome (feeds the graduated tiers). */
interface CallRecord {
toolName: string;
argsHash: string;
success: boolean;
}
/**
* Graduated verdict from {@link LoopGuard.checkTiered}. `block` results are
* surfaced as first-party tool-result nudges; `abort` is a hard stop that the
* agent loop turns into a user-facing give-up message and run termination.
*/
export type LoopGuardVerdict =
| { action: 'allow' }
| { action: 'block'; tier: 'T1' | 'T2' | 'T4'; reason: string }
| { action: 'abort'; tier: 'T3'; reason: string };
export class LoopGuard {
private maxRepeats: number;
private lastHash: string | null = null;
private consecutiveCount = 0;
/** Rolling window of recent call hashes for oscillation detection */
private window: string[] = [];
private windowSize: number;
private windowThreshold: number;
/** Graduated-tier state: outcome history of attempted executions. */
private history: CallRecord[] = [];
private identicalCallLimit: number;
private identicalFailureLimit: number;
private sameToolFailureLimit: number;
private criticalFailureLimit: number;
private historyCap: number;
constructor(config: LoopGuardConfig = {}) {
this.maxRepeats = config.maxRepeats ?? 3;
this.windowSize = config.windowSize ?? 10;
this.windowThreshold = config.windowThreshold ?? 4;
this.identicalCallLimit = config.identicalCallLimit ?? 5;
this.identicalFailureLimit = config.identicalFailureLimit ?? 3;
this.sameToolFailureLimit = config.sameToolFailureLimit ?? 6;
this.criticalFailureLimit = config.criticalFailureLimit ?? 8;
this.historyCap = config.historyCap ?? 50;
}
check(toolName: string, args: Record<string, unknown>): boolean {
const hash = createHash('sha256')
.update(toolName + ':' + JSON.stringify(args))
.digest('hex');
// Consecutive repeat detection (existing behavior)
if (hash === this.lastHash) {
this.consecutiveCount++;
} else {
this.lastHash = hash;
this.consecutiveCount = 1;
}
if (this.consecutiveCount > this.maxRepeats) {
return false;
}
// Rolling window oscillation detection
this.window.push(hash);
if (this.window.length > this.windowSize) {
this.window.shift();
}
// Count occurrences of current hash in the window
let count = 0;
for (const h of this.window) {
if (h === hash) count++;
}
if (count >= this.windowThreshold) {
return false;
}
return true;
}
/**
* Record the outcome of an attempted execution. The tool-executor feeds
* pass/fail from its try/catch; blocked (never-executed) calls are NOT
* recorded so a block never feeds the failure tiers.
*/
record(toolName: string, args: Record<string, unknown>, success: boolean): void {
this.history.push({ toolName, argsHash: this.hashArgs(args), success });
if (this.history.length > this.historyCap) {
this.history.splice(0, this.history.length - this.historyCap);
}
}
/**
* Graduated stops layered on top of {@link check}. Evaluated in the order
* T3 → T1 → T2 → T4 so the hard-abort wins over the same-tool block when a
* failure streak crosses both thresholds. All scans read the recorded history
* from the tail and stop (implicit reset) on the first break condition.
*/
checkTiered(toolName: string, args: Record<string, unknown>): LoopGuardVerdict {
const argsHash = this.hashArgs(args);
// Same-tool consecutive failures (shared by T3 abort + T4 block).
// Break on a different tool or on a success.
let sameToolFailures = 0;
for (let i = this.history.length - 1; i >= 0; i--) {
const e = this.history[i];
if (e.toolName !== toolName || e.success) break;
sameToolFailures++;
}
if (sameToolFailures >= this.criticalFailureLimit) {
return {
action: 'abort',
tier: 'T3',
reason:
`I wasn't able to complete this — the ${toolName} tool failed repeatedly. ` +
`Try rephrasing your request, breaking it into smaller steps, or approaching it a different way.`,
};
}
// T1 — identical tool+args, any outcome. Break on a different call.
let identicalCalls = 0;
for (let i = this.history.length - 1; i >= 0; i--) {
const e = this.history[i];
if (e.toolName !== toolName || e.argsHash !== argsHash) break;
identicalCalls++;
}
if (identicalCalls >= this.identicalCallLimit) {
return {
action: 'block',
tier: 'T1',
reason:
`Error: ${toolName} was already called with these exact arguments and returned the same result. ` +
`Use the result you already have or try a different approach.`,
};
}
// T2 — identical consecutive failures. Break on a different call or a success.
let identicalFailures = 0;
for (let i = this.history.length - 1; i >= 0; i--) {
const e = this.history[i];
if (e.toolName !== toolName || e.argsHash !== argsHash || e.success) break;
identicalFailures++;
}
if (identicalFailures >= this.identicalFailureLimit) {
return {
action: 'block',
tier: 'T2',
reason:
`Error: ${toolName} has failed repeatedly with these exact arguments. ` +
`Change the arguments or try a different approach.`,
};
}
// T4 — same-tool failures below the critical threshold.
if (sameToolFailures >= this.sameToolFailureLimit) {
return {
action: 'block',
tier: 'T4',
reason:
`Error: ${toolName} has failed repeatedly. Try a different tool or a different approach.`,
};
}
return { action: 'allow' };
}
/** Number of retained outcome records (bounded by historyCap). */
get historySize(): number {
return this.history.length;
}
reset(): void {
this.lastHash = null;
this.consecutiveCount = 0;
this.window = [];
this.history = [];
}
private hashArgs(args: Record<string, unknown>): string {
return createHash('sha256').update(JSON.stringify(args)).digest('hex');
}
}