@animalabs/agent-framework 0.6.4 → 0.6.5

package/dist/test/overbudget-drain-breaker.test.js

@@ -0,0 +1,157 @@
+/**
+ * OverBudget deadlock breaker (PR #58, 15befaa): when compile throws
+ * context-manager's OverBudgetError, the compression drain never runs — it is
+ * driven by successful activity, which the over-budget state prevents. A
+ * closed loop with no internal exit (field data 2026-07-10: 36 minutes
+ * hard-down, zero self-rescue). noteInferenceExhausted breaks it by kicking
+ * the strategy drain (cm.tick()) directly.
+ *
+ * The trigger is the classified errorType 'over_budget' (err.name ===
+ * 'OverBudgetError' — CM does not export the class, so no cross-package
+ * instanceof; the message-prose match is only a fallback). These tests pin
+ * that classification so a CM message rewording cannot silently kill the
+ * breaker.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { AgentFramework } from '../src/framework.js';
+import { MembraneError } from '@animalabs/membrane';
+function makeHarness(tick) {
+    const cm = {
+        addMessage: () => 'marker-id',
+        tick,
+    };
+    const fw = Object.create(AgentFramework.prototype);
+    fw.consecutiveInferenceFailures = new Map();
+    fw.exhaustionRewinds = new Map();
+    fw.rewindEpisode = new Map();
+    fw.lastInferenceAt = new Map();
+    fw.overBudgetDrainInFlight = new Set();
+    fw.opsAlertLastSent = new Map();
+    fw.pendingRequests = [];
+    fw.traceListeners = [];
+    fw.inferenceFailureEscalationThreshold = 3;
+    fw.agents = new Map([['cairn', {
+                name: 'cairn',
+                refusalHandling: { maxRewinds: 3 },
+                getContextManager: () => cm,
+            }]]);
+    const errs = [];
+    const orig = console.error;
+    console.error = (...a) => { errs.push(a.join(' ')); };
+    const restore = () => { console.error = orig; };
+    return { fw, errs, restore };
+}
+/** Let the fire-and-forget drain IIFE's microtask chain run to quiescence. */
+async function settle(rounds = 3) {
+    for (let i = 0; i < rounds; i++)
+        await new Promise((r) => setImmediate(r));
+}
+const OVER_BUDGET_REASON = 'Compile plan would exceed hard budget: head=41200 tail=8100 middle=62000 budget=100000';
+test('classification: err.name OverBudgetError → over_budget, regardless of message wording', () => {
+    const fw = Object.create(AgentFramework.prototype);
+    // The load-bearing pin: classification must NOT depend on CM's message
+    // prose, which CM can reword without knowing AF gates a breaker on it.
+    const reworded = new Error('context plan no longer fits (reworded in some future CM)');
+    reworded.name = 'OverBudgetError';
+    assert.deepEqual(fw.classifyInferenceError(reworded), { errorType: 'over_budget' });
+    // Membrane errors keep their own typed classification.
+    const membraneErr = new MembraneError({
+        type: 'invalid_request',
+        message: '400 bad request',
+        retryable: false,
+        rawError: null,
+    });
+    assert.deepEqual(fw.classifyInferenceError(membraneErr), { retryable: false, errorType: 'invalid_request' });
+    // Anything else stays unclassified.
+    assert.deepEqual(fw.classifyInferenceError(new Error('boom')), {});
+});
+test('errorType over_budget kicks the drain: 8 ticks, honest success log', async () => {
+    let ticks = 0;
+    const { fw, errs, restore } = makeHarness(async () => { ticks++; });
+    try {
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        await settle(20);
+    }
+    finally {
+        restore();
+    }
+    assert.equal(ticks, 8);
+    assert.ok(errs.some((e) => e.includes('drain kicked for cairn') && e.includes('8 ticks')), `success log with real tick count, got: ${errs.join(' | ')}`);
+});
+test('message fallback: "exceed hard budget" prose kicks even without errorType', async () => {
+    let ticks = 0;
+    const { fw, restore } = makeHarness(async () => { ticks++; });
+    try {
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, undefined);
+        await settle(20);
+    }
+    finally {
+        restore();
+    }
+    assert.equal(ticks, 8);
+});
+test('unrelated failures never kick the drain', async () => {
+    let ticks = 0;
+    const { fw, restore } = makeHarness(async () => { ticks++; });
+    try {
+        fw.noteInferenceExhausted('cairn', '529 overloaded', true, 'server');
+        fw.noteInferenceExhausted('cairn', '400 invalid request', false, 'invalid_request');
+        fw.noteInferenceExhausted('cairn', 'weird transport error', undefined, undefined);
+        await settle(20);
+    }
+    finally {
+        restore();
+    }
+    assert.equal(ticks, 0);
+});
+test('overlapping kicks are suppressed: one drain per agent at a time', async () => {
+    let started = 0;
+    const gates = [];
+    const { fw, errs, restore } = makeHarness(() => { started++; return new Promise((r) => { gates.push(r); }); });
+    try {
+        // The scenario the breaker exists for: every activation fails, repeatedly.
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        await settle();
+        // Only ONE kick started; its first tick is still in flight.
+        assert.equal(started, 1);
+        // Release ticks one at a time — exactly 8 run, then the drain finishes.
+        for (let i = 0; i < 8; i++) {
+            gates[i]();
+            await settle();
+        }
+        assert.equal(started, 8, 'exactly one drain worth of ticks, not three');
+        assert.equal(errs.filter((e) => e.includes('drain kicked for cairn')).length, 1);
+        // The in-flight flag was cleared: a NEW failure kicks again.
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        await settle();
+        assert.equal(started, 9);
+    }
+    finally {
+        restore();
+    }
+});
+test('a failing tick is logged with the real count and clears the in-flight flag', async () => {
+    let calls = 0;
+    const { fw, errs, restore } = makeHarness(async () => {
+        calls++;
+        if (calls === 3)
+            throw new Error('strategy exploded');
+    });
+    try {
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        await settle(20);
+        assert.ok(errs.some((e) => e.includes('drain kick failed for cairn after 2 ticks')));
+        assert.equal(fw.overBudgetDrainInFlight.size, 0, 'flag cleared on failure');
+        // Recovery: the next failure can kick again.
+        fw.noteInferenceExhausted('cairn', OVER_BUDGET_REASON, undefined, 'over_budget');
+        await settle(20);
+        assert.ok(calls > 3, 'subsequent kick ran');
+    }
+    finally {
+        restore();
+    }
+});
+//# sourceMappingURL=overbudget-drain-breaker.test.js.map

package/dist/test/overbudget-drain-breaker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overbudget-drain-breaker.test.js","sourceRoot":"","sources":["../../test/overbudget-drain-breaker.test.ts"],"names":[],"mappings":"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"}