@strands-agents/sdk 1.3.0 → 1.5.0

package/dist/src/agent/__tests__/agent.context-manager.test.js

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { Agent } from '../agent.js';
+import { MockMessageModel } from '../../__fixtures__/mock-message-model.js';
+import { SlidingWindowConversationManager } from '../../conversation-manager/sliding-window-conversation-manager.js';
+import { SummarizingConversationManager } from '../../conversation-manager/summarizing-conversation-manager.js';
+import { ContextOffloader } from '../../vended-plugins/context-offloader/plugin.js';
+import { InMemoryStorage } from '../../vended-plugins/context-offloader/storage.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function internals(agent) {
+    return agent;
+}
+function getConversationManager(agent) {
+    return internals(agent)._conversationManager;
+}
+function getPending(agent) {
+    return internals(agent)._pluginRegistry._pending;
+}
+describe('Agent contextManager', () => {
+    describe('when undefined (default)', () => {
+        it('uses SlidingWindowConversationManager', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model });
+            expect(getConversationManager(agent)).toBeInstanceOf(SlidingWindowConversationManager);
+        });
+        it('does not add ContextOffloader plugin', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model });
+            const pending = getPending(agent);
+            expect(pending.find((p) => p.name === 'strands:context-offloader')).toBeUndefined();
+        });
+    });
+    describe('when "auto"', () => {
+        it('uses SummarizingConversationManager', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model, contextManager: 'auto' });
+            expect(getConversationManager(agent)).toBeInstanceOf(SummarizingConversationManager);
+        });
+        it('sets summaryRatio to 0.3', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model, contextManager: 'auto' });
+            const conversationManager = getConversationManager(agent);
+            expect(conversationManager._summaryRatio).toBe(0.3);
+        });
+        it('enables proactive compression at 0.85', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model, contextManager: 'auto' });
+            const conversationManager = getConversationManager(agent);
+            expect(conversationManager._compressionThreshold).toBe(0.85);
+        });
+        it('adds ContextOffloader plugin with benchmark defaults', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const agent = new Agent({ model, contextManager: 'auto' });
+            const pending = getPending(agent);
+            const offloader = pending.find((p) => p.name === 'strands:context-offloader');
+            expect(offloader).toBeDefined();
+            expect(offloader._maxResultTokens).toBe(1500);
+            expect(offloader._previewTokens).toBe(750);
+            expect(offloader._storage).toBeInstanceOf(InMemoryStorage);
+        });
+    });
+    describe('coexistence with conversationManager', () => {
+        it('respects user-provided conversationManager', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const userCm = new SlidingWindowConversationManager({ windowSize: 20 });
+            const agent = new Agent({ model, contextManager: 'auto', conversationManager: userCm });
+            expect(getConversationManager(agent)).toBe(userCm);
+        });
+        it('still adds ContextOffloader when user provides conversationManager', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const userCm = new SlidingWindowConversationManager({ windowSize: 20 });
+            const agent = new Agent({ model, contextManager: 'auto', conversationManager: userCm });
+            const pending = getPending(agent);
+            expect(pending.find((p) => p.name === 'strands:context-offloader')).toBeDefined();
+        });
+        it('does not add duplicate ContextOffloader if user provides one', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            const userOffloader = new ContextOffloader({
+                storage: new InMemoryStorage(),
+                maxResultTokens: 3000,
+                previewTokens: 1000,
+            });
+            const agent = new Agent({ model, contextManager: 'auto', plugins: [userOffloader] });
+            const pending = getPending(agent);
+            const offloaders = pending.filter((p) => p.name === 'strands:context-offloader');
+            expect(offloaders).toHaveLength(1);
+            expect(offloaders[0]._maxResultTokens).toBe(3000);
+        });
+    });
+    describe('stateful model', () => {
+        it('throws when used with a stateful model', () => {
+            class StatefulModel extends MockMessageModel {
+                get stateful() {
+                    return true;
+                }
+            }
+            const model = new StatefulModel().addTurn({ type: 'textBlock', text: 'hi' });
+            expect(() => new Agent({ model, contextManager: 'auto' })).toThrow('stateful model');
+        });
+    });
+    describe('unsupported value', () => {
+        it('throws for invalid contextManager value', () => {
+            const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'hi' });
+            expect(() => new Agent({ model, contextManager: 'manual' })).toThrow('Unsupported contextManager value');
+        });
+    });
+});
+//# sourceMappingURL=agent.context-manager.test.js.map

package/dist/src/agent/__tests__/agent.context-manager.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.context-manager.test.js","sourceRoot":"","sources":["../../../../src/agent/__tests__/agent.context-manager.test.ts"],"names":[],"mappings":"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"}

package/dist/src/agent/__tests__/agent.test.js

@@ -1425,5 +1425,200 @@ describe('normalizeToolUseNames', () => {
             setterSpy.mockRestore();
         });
     });
+    describe('limits', () => {
+        const toolUseTurn = (toolUseId, usage) => [
+            { type: 'toolUseBlock', name: 'loop', toolUseId, input: {} },
+            { usage },
+        ];
+        const passthroughTool = () => createMockTool('loop', (context) => new ToolResultBlock({
+            toolUseId: context.toolUse.toolUseId,
+            status: 'success',
+            content: [new TextBlock('ok')],
+        }));
+        describe('when limits.turns is reached', () => {
+            it('runs the cycle to completion and bails at top of next iteration', async () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', { inputTokens: 10, outputTokens: 5, totalTokens: 15 }))
+                    .addTurn(...toolUseTurn('tool-2', { inputTokens: 20, outputTokens: 5, totalTokens: 25 }));
+                const agent = new Agent({ model, tools: [passthroughTool()] });
+                const result = await agent.invoke('go', { limits: { turns: 1 } });
+                // Bail after tools — lastMessage is the user toolResult, so we don't
+                // use expectAgentResult (which assumes role 'assistant').
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitTurns',
+                    lastMessage: expect.objectContaining({
+                        role: 'user',
+                        content: expect.arrayContaining([expect.any(ToolResultBlock)]),
+                    }),
+                    metrics: expectLoopMetrics({
+                        cycleCount: 1,
+                        toolNames: ['loop'],
+                        usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+                    }),
+                }));
+            });
+        });
+        describe('when limits is generous', () => {
+            it('does not trip and the model ends naturally', async () => {
+                const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'done' }, { usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 } });
+                const agent = new Agent({ model });
+                const result = await agent.invoke('go', { limits: { turns: 5, outputTokens: 1000, totalTokens: 1000 } });
+                expect(result).toEqual(expectAgentResult({
+                    stopReason: 'endTurn',
+                    messageText: 'done',
+                    cycleCount: 1,
+                    usage: { inputTokens: 5, outputTokens: 5, totalTokens: 10 },
+                }));
+            });
+        });
+        describe('when limits.outputTokens is reached', () => {
+            it('returns limitOutputTokens once cumulative outputTokens hits the cap', async () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', { inputTokens: 10, outputTokens: 60, totalTokens: 70 }))
+                    .addTurn(...toolUseTurn('tool-2', { inputTokens: 10, outputTokens: 60, totalTokens: 70 }));
+                const agent = new Agent({ model, tools: [passthroughTool()] });
+                const result = await agent.invoke('go', { limits: { outputTokens: 100 } });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitOutputTokens',
+                    lastMessage: expect.objectContaining({
+                        role: 'user',
+                        content: expect.arrayContaining([expect.any(ToolResultBlock)]),
+                    }),
+                    metrics: expectLoopMetrics({
+                        cycleCount: 2,
+                        toolNames: ['loop'],
+                        usage: { inputTokens: 20, outputTokens: 120, totalTokens: 140 },
+                    }),
+                }));
+            });
+            it('uses at-most (>=) semantics: stops when count exactly equals the cap', async () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', { inputTokens: 10, outputTokens: 100, totalTokens: 110 }))
+                    .addTurn(...toolUseTurn('tool-2', { inputTokens: 10, outputTokens: 100, totalTokens: 110 }));
+                const agent = new Agent({ model, tools: [passthroughTool()] });
+                const result = await agent.invoke('go', { limits: { outputTokens: 100 } });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitOutputTokens',
+                    metrics: expectLoopMetrics({
+                        cycleCount: 1,
+                        toolNames: ['loop'],
+                        usage: { inputTokens: 10, outputTokens: 100, totalTokens: 110 },
+                    }),
+                }));
+            });
+        });
+        describe('when limits.totalTokens is reached', () => {
+            it('returns limitTotalTokens once cumulative totalTokens hits the cap', async () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', { inputTokens: 200, outputTokens: 100, totalTokens: 300 }))
+                    .addTurn(...toolUseTurn('tool-2', { inputTokens: 200, outputTokens: 100, totalTokens: 300 }));
+                const agent = new Agent({ model, tools: [passthroughTool()] });
+                const result = await agent.invoke('go', { limits: { totalTokens: 500 } });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitTotalTokens',
+                    lastMessage: expect.objectContaining({
+                        role: 'user',
+                        content: expect.arrayContaining([expect.any(ToolResultBlock)]),
+                    }),
+                    metrics: expectLoopMetrics({
+                        cycleCount: 2,
+                        toolNames: ['loop'],
+                        usage: { inputTokens: 400, outputTokens: 200, totalTokens: 600 },
+                    }),
+                }));
+            });
+        });
+        describe('when the model ends naturally on the same turn the limit would trip', () => {
+            it('returns endTurn — the model answer wins', async () => {
+                const model = new MockMessageModel().addTurn({ type: 'textBlock', text: 'final answer' }, { usage: { inputTokens: 300, outputTokens: 300, totalTokens: 600 } });
+                const agent = new Agent({ model });
+                const result = await agent.invoke('go', { limits: { totalTokens: 500 } });
+                expect(result).toEqual(expectAgentResult({
+                    stopReason: 'endTurn',
+                    messageText: 'final answer',
+                    cycleCount: 1,
+                    usage: { inputTokens: 300, outputTokens: 300, totalTokens: 600 },
+                }));
+            });
+        });
+        describe('when multiple limits trip simultaneously', () => {
+            const heavyUsage = { inputTokens: 100, outputTokens: 100, totalTokens: 200 };
+            const buildAgent = () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', heavyUsage))
+                    .addTurn(...toolUseTurn('tool-2', heavyUsage));
+                return new Agent({ model, tools: [passthroughTool()] });
+            };
+            it('prefers turns when all three trip', async () => {
+                const result = await buildAgent().invoke('go', {
+                    limits: { turns: 1, totalTokens: 1, outputTokens: 1 },
+                });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitTurns',
+                    metrics: expectLoopMetrics({ cycleCount: 1, toolNames: ['loop'] }),
+                }));
+            });
+            it('prefers totalTokens over outputTokens', async () => {
+                const result = await buildAgent().invoke('go', { limits: { totalTokens: 1, outputTokens: 1 } });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitTotalTokens',
+                    metrics: expectLoopMetrics({ cycleCount: 1, toolNames: ['loop'] }),
+                }));
+            });
+            it('falls back to outputTokens when no higher-priority cap is set', async () => {
+                const result = await buildAgent().invoke('go', { limits: { outputTokens: 1 } });
+                expect(result).toEqual(expect.objectContaining({
+                    type: 'agentResult',
+                    stopReason: 'limitOutputTokens',
+                    metrics: expectLoopMetrics({ cycleCount: 1, toolNames: ['loop'] }),
+                }));
+            });
+        });
+        describe('when the same agent is reused across invocations', () => {
+            it('scopes the limit to the current invocation, not lifetime', async () => {
+                // Each turn uses 50 output tokens. With limits.outputTokens: 75, a single
+                // invocation tolerates one turn but trips on the second. If the cap
+                // were lifetime-scoped, the second `invoke()` would trip on its first
+                // turn (75 cumulative across both calls).
+                const model = new MockMessageModel()
+                    .addTurn({ type: 'textBlock', text: 'first' }, { usage: { inputTokens: 10, outputTokens: 50, totalTokens: 60 } })
+                    .addTurn({ type: 'textBlock', text: 'second' }, { usage: { inputTokens: 10, outputTokens: 50, totalTokens: 60 } });
+                const agent = new Agent({ model });
+                const r1 = await agent.invoke('go', { limits: { outputTokens: 75 } });
+                expect(r1.stopReason).toBe('endTurn');
+                expect(r1.metrics?.latestAgentInvocation?.cycles.length).toBe(1);
+                const r2 = await agent.invoke('go again', { limits: { outputTokens: 75 } });
+                expect(r2.stopReason).toBe('endTurn');
+                expect(r2.metrics?.latestAgentInvocation?.cycles.length).toBe(1);
+            });
+        });
+        describe('when a limit is invalid', () => {
+            it.each([
+                ['negative', { limits: { turns: -1 } }],
+                ['zero', { limits: { turns: 0 } }],
+                ['NaN', { limits: { outputTokens: NaN } }],
+                ['Infinity', { limits: { totalTokens: Infinity } }],
+            ])('rejects %s with TypeError', async (_label, options) => {
+                const agent = new Agent({ model: new MockMessageModel().addTurn({ type: 'textBlock', text: 'never reached' }) });
+                await expect(agent.invoke('go', options)).rejects.toThrow(TypeError);
+            });
+        });
+        describe('when invoked via stream()', () => {
+            it('returns limitTurns as the generator return value', async () => {
+                const model = new MockMessageModel()
+                    .addTurn(...toolUseTurn('tool-1', { inputTokens: 10, outputTokens: 5, totalTokens: 15 }))
+                    .addTurn(...toolUseTurn('tool-2', { inputTokens: 10, outputTokens: 5, totalTokens: 15 }));
+                const agent = new Agent({ model, tools: [passthroughTool()] });
+                const { result } = await collectGenerator(agent.stream('go', { limits: { turns: 1 } }));
+                expect(result).toEqual(expect.objectContaining({ type: 'agentResult', stopReason: 'limitTurns' }));
+            });
+        });
+    });
 });
 //# sourceMappingURL=agent.test.js.map