@strands-agents/sdk 1.2.0 → 1.4.0

package/dist/src/vended-interventions/hitl/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Human-in-the-loop intervention for Strands Agents.
+ *
+ * Pauses agent execution before tool calls to request human approval.
+ * Defaults to interrupt/resume mode for stateless deployments.
+ * Pass `ask: 'stdio'` for CLI prompting or a custom `ask` function for other UIs.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { HumanInTheLoop } from '@strands-agents/sdk/vended-interventions/hitl'
+ *
+ * const agent = new Agent({
+ *   tools: [deleteTool, readTool],
+ *   interventions: [new HumanInTheLoop({ allowedTools: ['readTool'] })],
+ * })
+ *
+ * // Default: agent pauses with stopReason 'interrupt', caller resumes with response
+ * const result = await agent.invoke('Delete the file')
+ * ```
+ */
+export { HumanInTheLoop } from './hitl.js';
+export type { HumanInTheLoopConfig } from './hitl.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/vended-interventions/hitl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/vended-interventions/hitl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA"}

package/dist/src/vended-interventions/hitl/index.js

@@ -0,0 +1,23 @@
+/**
+ * Human-in-the-loop intervention for Strands Agents.
+ *
+ * Pauses agent execution before tool calls to request human approval.
+ * Defaults to interrupt/resume mode for stateless deployments.
+ * Pass `ask: 'stdio'` for CLI prompting or a custom `ask` function for other UIs.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { HumanInTheLoop } from '@strands-agents/sdk/vended-interventions/hitl'
+ *
+ * const agent = new Agent({
+ *   tools: [deleteTool, readTool],
+ *   interventions: [new HumanInTheLoop({ allowedTools: ['readTool'] })],
+ * })
+ *
+ * // Default: agent pauses with stopReason 'interrupt', caller resumes with response
+ * const result = await agent.invoke('Delete the file')
+ * ```
+ */
+export { HumanInTheLoop } from './hitl.js';
+//# sourceMappingURL=index.js.map

package/dist/src/vended-interventions/hitl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vended-interventions/hitl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA"}

package/dist/src/vended-interventions/steering/__tests__/handler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handler.test.d.ts.map

package/dist/src/vended-interventions/steering/__tests__/handler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.test.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/__tests__/handler.test.ts"],"names":[],"mappings":""}

package/dist/src/vended-interventions/steering/__tests__/handler.test.js

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Agent } from '../../../agent/agent.js';
+import { HookRegistryImplementation } from '../../../hooks/registry.js';
+import { AfterModelCallEvent, BeforeToolCallEvent } from '../../../hooks/events.js';
+import { Interrupt, InterruptState } from '../../../interrupt.js';
+import { confirm, guide } from '../../../interventions/actions.js';
+import { Message, TextBlock } from '../../../types/messages.js';
+import { SteeringHandler } from '../handlers/handler.js';
+function getHookRegistry(agent) {
+    return agent._hooksRegistry;
+}
+describe('SteeringHandler', () => {
+    const toolUse = { name: 'searchWeb', toolUseId: 'tu-1', input: { q: 'hi' } };
+    function makeBeforeToolCallEvent(agent) {
+        return new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
+    }
+    function makeAfterModelCallEvent(agent) {
+        return new AfterModelCallEvent({
+            agent,
+            model: {},
+            invocationState: {},
+            attemptCount: 0,
+            stopData: {
+                message: new Message({ role: 'assistant', content: [new TextBlock('response')] }),
+                stopReason: 'endTurn',
+            },
+        });
+    }
+    it('routes beforeToolCall to subclass override with the event', async () => {
+        const seen = {};
+        class Spy extends SteeringHandler {
+            name = 'spy';
+            async beforeToolCall(event) {
+                seen.agent = event.agent;
+                seen.toolUse = event.toolUse;
+                return guide('try again');
+            }
+        }
+        const agent = new Agent({ interventions: [new Spy()] });
+        await agent.initialize();
+        const event = makeBeforeToolCallEvent(agent);
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(seen.agent).toBe(agent);
+        expect(seen.toolUse).toEqual(toolUse);
+        expect(event.cancel).toContain('GUIDANCE:');
+        expect(event.cancel).toContain('try again');
+    });
+    it('routes afterModelCall to subclass override with the event', async () => {
+        const seen = {};
+        class Spy extends SteeringHandler {
+            name = 'spy';
+            async afterModelCall(event) {
+                if (!event.stopData)
+                    return { type: 'proceed' };
+                seen.message = event.stopData.message;
+                seen.stopReason = event.stopData.stopReason;
+                return guide('be terser');
+            }
+        }
+        const agent = new Agent({ interventions: [new Spy()] });
+        await agent.initialize();
+        const event = makeAfterModelCallEvent(agent);
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(seen.message).toBeDefined();
+        expect(seen.stopReason).toBe('endTurn');
+        expect(event.retry).toBe(true);
+    });
+    it('exposes provider context to subclasses via getSteeringContext', async () => {
+        const fakeProvider = {
+            name: 'fake',
+            observeAgent() { },
+            get context() {
+                return { type: 'fake', tokens: 42 };
+            },
+        };
+        let observedContext;
+        class ContextReader extends SteeringHandler {
+            name = 'context-reader';
+            async beforeToolCall() {
+                observedContext = this.getSteeringContext();
+                return { type: 'proceed' };
+            }
+        }
+        const agent = new Agent({ interventions: [new ContextReader({ contextProviders: [fakeProvider] })] });
+        await agent.initialize();
+        await getHookRegistry(agent).invokeCallbacks(makeBeforeToolCallEvent(agent));
+        expect(observedContext).toEqual([{ type: 'fake', tokens: 42 }]);
+    });
+    it('siblings with distinct names can coexist on one agent', () => {
+        class A extends SteeringHandler {
+            name = 'steer:tool';
+        }
+        class B extends SteeringHandler {
+            name = 'steer:model';
+        }
+        expect(() => new Agent({ interventions: [new A(), new B()] })).not.toThrow();
+    });
+    it('does not invoke afterModelCall body when stopData is missing', async () => {
+        const called = vi.fn();
+        class Spy extends SteeringHandler {
+            name = 'spy';
+            async afterModelCall(event) {
+                if (event.stopData)
+                    called();
+                return { type: 'proceed' };
+            }
+        }
+        const agent = new Agent({ interventions: [new Spy()] });
+        await agent.initialize();
+        const event = new AfterModelCallEvent({
+            agent,
+            model: {},
+            invocationState: {},
+            attemptCount: 0,
+        });
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(called).not.toHaveBeenCalled();
+    });
+    it('confirm decision flows through the interrupt system on resume (approved)', async () => {
+        class Approver extends SteeringHandler {
+            name = 'approver';
+            async beforeToolCall() {
+                return confirm('approve searchWeb?');
+            }
+        }
+        const agent = new Agent({ interventions: [new Approver()] });
+        await agent.initialize();
+        // Preload an approval response so event.interrupt() returns it instead of pausing
+        const interruptId = `hook:beforeToolCall:${toolUse.toolUseId}:approver`;
+        const interruptState = agent._interruptState;
+        interruptState.interrupts[interruptId] = new Interrupt({
+            id: interruptId,
+            name: 'approver',
+            response: 'yes',
+            source: 'hook',
+        });
+        const event = makeBeforeToolCallEvent(agent);
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(event.cancel).toBe(false);
+    });
+    it('confirm decision sets cancel when human denies', async () => {
+        class Approver extends SteeringHandler {
+            name = 'approver';
+            async beforeToolCall() {
+                return confirm('approve searchWeb?');
+            }
+        }
+        const agent = new Agent({ interventions: [new Approver()] });
+        await agent.initialize();
+        const interruptId = `hook:beforeToolCall:${toolUse.toolUseId}:approver`;
+        const interruptState = agent._interruptState;
+        interruptState.interrupts[interruptId] = new Interrupt({
+            id: interruptId,
+            name: 'approver',
+            response: 'no',
+            source: 'hook',
+        });
+        const event = makeBeforeToolCallEvent(agent);
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(event.cancel).toBe('CONFIRMATION_FAILED: approve searchWeb?');
+    });
+});
+//# sourceMappingURL=handler.test.js.map

package/dist/src/vended-interventions/steering/__tests__/handler.test.js.map

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

package/dist/src/vended-interventions/steering/__tests__/llm.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llm.test.d.ts.map

package/dist/src/vended-interventions/steering/__tests__/llm.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.test.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/__tests__/llm.test.ts"],"names":[],"mappings":""}

package/dist/src/vended-interventions/steering/__tests__/llm.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Agent } from '../../../agent/agent.js';
+import { BeforeToolCallEvent } from '../../../hooks/events.js';
+import { HookRegistryImplementation } from '../../../hooks/registry.js';
+import { MockMessageModel } from '../../../__fixtures__/mock-message-model.js';
+import { LLMSteeringHandler } from '../handlers/llm.js';
+function getHookRegistry(agent) {
+    return agent._hooksRegistry;
+}
+function structuredOutputModel(decision) {
+    return new MockMessageModel().addTurn({
+        type: 'toolUseBlock',
+        name: 'strands_structured_output',
+        toolUseId: 'inner-1',
+        input: decision,
+    });
+}
+describe('LLMSteeringHandler', () => {
+    const toolUse = { name: 'searchWeb', toolUseId: 'tu-1', input: { q: 'hi' } };
+    it("defaults to the parent agent's model when none is configured", async () => {
+        const model = structuredOutputModel({ type: 'proceed', reason: 'no concerning patterns' });
+        const streamSpy = vi.spyOn(model, 'stream');
+        const handler = new LLMSteeringHandler({
+            systemPrompt: 'You are a steering agent.',
+            contextProviders: [],
+        });
+        const agent = new Agent({ model, interventions: [handler] });
+        await agent.initialize();
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(streamSpy).toHaveBeenCalledTimes(1);
+        expect(event.cancel).toBe(false);
+    });
+    it('uses the configured model in preference to the agent model', async () => {
+        const agentModel = new MockMessageModel().addTurn({ type: 'textBlock', text: 'unused' });
+        const configuredModel = structuredOutputModel({ type: 'proceed', reason: 'ok' });
+        const agentStreamSpy = vi.spyOn(agentModel, 'stream');
+        const configuredStreamSpy = vi.spyOn(configuredModel, 'stream');
+        const handler = new LLMSteeringHandler({
+            systemPrompt: 'You are a steering agent.',
+            model: configuredModel,
+            contextProviders: [],
+        });
+        const agent = new Agent({ model: agentModel, interventions: [handler] });
+        await agent.initialize();
+        const event = new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
+        await getHookRegistry(agent).invokeCallbacks(event);
+        expect(configuredStreamSpy).toHaveBeenCalledTimes(1);
+        expect(agentStreamSpy).not.toHaveBeenCalled();
+    });
+    it('throws when no model is configured and the handler has no parent agent', async () => {
+        const handler = new LLMSteeringHandler({
+            systemPrompt: 'You are a steering agent.',
+            contextProviders: [],
+        });
+        // Detached: never attached to an agent, never observed.
+        await expect(handler.beforeToolCall({ toolUse })).rejects.toThrow(/no model/i);
+    });
+});
+//# sourceMappingURL=llm.test.js.map

package/dist/src/vended-interventions/steering/__tests__/llm.test.js.map

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

package/dist/src/vended-interventions/steering/__tests__/tool-ledger.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-ledger.test.d.ts.map

package/dist/src/vended-interventions/steering/__tests__/tool-ledger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-ledger.test.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/__tests__/tool-ledger.test.ts"],"names":[],"mappings":""}

package/dist/src/vended-interventions/steering/__tests__/tool-ledger.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { Agent } from '../../../agent/agent.js';
+import { AfterToolCallEvent, BeforeToolCallEvent } from '../../../hooks/events.js';
+import { TextBlock, ToolResultBlock } from '../../../types/messages.js';
+import { ToolLedgerProvider } from '../providers/tool-ledger.js';
+describe('ToolLedgerProvider', () => {
+    const toolUse = { name: 'searchWeb', toolUseId: 'tu-1', input: { q: 'hi' } };
+    function setupAgent(provider) {
+        const agent = new Agent();
+        const hookRegistry = agent._hooksRegistry;
+        provider.observeAgent(agent);
+        return { agent, hookRegistry };
+    }
+    function makeBefore(agent) {
+        return new BeforeToolCallEvent({ agent, toolUse, tool: undefined, invocationState: {} });
+    }
+    function makeAfter(agent, status = 'success', error) {
+        return new AfterToolCallEvent({
+            agent,
+            toolUse,
+            tool: undefined,
+            result: new ToolResultBlock({
+                toolUseId: toolUse.toolUseId,
+                status,
+                content: [new TextBlock('result text')],
+                ...(error !== undefined && { error }),
+            }),
+            invocationState: {},
+            ...(error !== undefined && { error }),
+        });
+    }
+    it('records pending entry on beforeToolCall', async () => {
+        const provider = new ToolLedgerProvider();
+        const { agent, hookRegistry } = setupAgent(provider);
+        expect(provider.context.type).toBe('toolLedger');
+        expect(provider.context.calls).toEqual([]);
+        await hookRegistry.invokeCallbacks(makeBefore(agent));
+        const calls = provider.context.calls;
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toMatchObject({
+            id: 'tu-1',
+            name: 'searchWeb',
+            args: { q: 'hi' },
+            status: 'pending',
+        });
+    });
+    it('flips pending to success after afterToolCall', async () => {
+        const provider = new ToolLedgerProvider();
+        const { agent, hookRegistry } = setupAgent(provider);
+        await hookRegistry.invokeCallbacks(makeBefore(agent));
+        await hookRegistry.invokeCallbacks(makeAfter(agent, 'success'));
+        const calls = provider.context.calls;
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toMatchObject({
+            id: 'tu-1',
+            name: 'searchWeb',
+            args: { q: 'hi' },
+            status: 'success',
+            error: null,
+            endTime: expect.any(String),
+        });
+    });
+    it('records error status and message', async () => {
+        const provider = new ToolLedgerProvider();
+        const { agent, hookRegistry } = setupAgent(provider);
+        await hookRegistry.invokeCallbacks(makeBefore(agent));
+        await hookRegistry.invokeCallbacks(makeAfter(agent, 'error', new Error('boom')));
+        const calls = provider.context.calls;
+        expect(calls[0]).toMatchObject({
+            id: 'tu-1',
+            name: 'searchWeb',
+            args: { q: 'hi' },
+            status: 'error',
+            error: 'boom',
+            endTime: expect.any(String),
+        });
+    });
+    it('drops oldest entries when ledger exceeds maxEntries', async () => {
+        const provider = new ToolLedgerProvider({ maxEntries: 2 });
+        const { agent, hookRegistry } = setupAgent(provider);
+        for (const id of ['a', 'b', 'c']) {
+            await hookRegistry.invokeCallbacks(new BeforeToolCallEvent({
+                agent,
+                toolUse: { name: 't', toolUseId: id, input: {} },
+                tool: undefined,
+                invocationState: {},
+            }));
+        }
+        const calls = provider.context.calls;
+        expect(calls).toHaveLength(2);
+        expect(calls.map((c) => c.id)).toEqual(['b', 'c']);
+    });
+});
+//# sourceMappingURL=tool-ledger.test.js.map

package/dist/src/vended-interventions/steering/__tests__/tool-ledger.test.js.map

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

package/dist/src/vended-interventions/steering/handlers/handler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Steering handler base class for providing contextual guidance to agents.
+ *
+ * Subclass {@link SteeringHandler} and override {@link beforeToolCall} and/or
+ * {@link afterModelCall}. These carry a narrowed steering contract
+ * (Proceed | Guide | Confirm for tool calls, Proceed | Guide for model output)
+ * — the wider intervention vocabulary (Deny, Transform) is excluded by the
+ * return type, so out-of-contract actions are caught at compile time.
+ *
+ * @example
+ * ```typescript
+ * class MySteeringHandler extends SteeringHandler {
+ *   override readonly name = 'my-steering'
+ *
+ *   override async beforeToolCall(event) {
+ *     if (event.toolUse.name === 'dangerous_tool') {
+ *       return guide('This tool requires extra caution.')
+ *     }
+ *     return proceed()
+ *   }
+ * }
+ *
+ * const agent = new Agent({ tools: [...], interventions: [new MySteeringHandler()] })
+ * ```
+ */
+import type { AfterModelCallEvent, BeforeToolCallEvent } from '../../../hooks/events.js';
+import { InterventionHandler, type Awaitable } from '../../../interventions/handler.js';
+import type { LifecycleObserver } from '../../../types/lifecycle-observer.js';
+import { type Confirm, type Guide, type Proceed } from '../../../interventions/actions.js';
+import type { LocalAgent } from '../../../types/agent.js';
+import type { SteeringContextData, SteeringContextProvider } from '../providers/context-provider.js';
+/**
+ * Configuration shared by all steering handlers.
+ */
+export interface SteeringHandlerConfig {
+    /** Providers that supply evaluation context. */
+    contextProviders?: SteeringContextProvider[];
+}
+/**
+ * Base class for steering handlers that provide contextual guidance to agents.
+ *
+ * Steering handlers accept context providers that observe agent activity, and
+ * use the accumulated context to make guidance decisions. The handler is an
+ * {@link InterventionHandler} — pass it via `interventions:` on the agent.
+ *
+ * Subclasses must declare a `name` (inherited as `abstract` from
+ * {@link InterventionHandler}). When attaching multiple steering handlers to
+ * one agent, ensure their names are distinct — `InterventionRegistry` rejects
+ * duplicates.
+ */
+export declare abstract class SteeringHandler extends InterventionHandler implements LifecycleObserver {
+    abstract readonly name: string;
+    private readonly _contextProviders;
+    constructor(config?: SteeringHandlerConfig);
+    beforeToolCall(_event: BeforeToolCallEvent): Awaitable<Proceed | Guide | Confirm>;
+    afterModelCall(_event: AfterModelCallEvent): Awaitable<Proceed | Guide>;
+    observeAgent(agent: LocalAgent): Promise<void>;
+    /**
+     * Collect context from all registered providers. Subclasses (and tests)
+     * may call this to inspect the accumulated provider snapshots.
+     */
+    getSteeringContext(): SteeringContextData[];
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/src/vended-interventions/steering/handlers/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/handlers/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACxF,OAAO,EAAE,mBAAmB,EAAE,KAAK,SAAS,EAAE,MAAM,mCAAmC,CAAA;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,OAAO,EAAW,KAAK,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,mCAAmC,CAAA;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAA;AAEpG;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,uBAAuB,EAAE,CAAA;CAC7C;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,eAAgB,SAAQ,mBAAoB,YAAW,iBAAiB;IAC5F,kBAA2B,IAAI,EAAE,MAAM,CAAA;IAEvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2B;gBAEjD,MAAM,CAAC,EAAE,qBAAqB;IASjC,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,CAAC,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAIjF,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;IAQ1E,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;;OAGG;IACH,kBAAkB,IAAI,mBAAmB,EAAE;CAG5C"}

package/dist/src/vended-interventions/steering/handlers/handler.js

@@ -0,0 +1,71 @@
+/**
+ * Steering handler base class for providing contextual guidance to agents.
+ *
+ * Subclass {@link SteeringHandler} and override {@link beforeToolCall} and/or
+ * {@link afterModelCall}. These carry a narrowed steering contract
+ * (Proceed | Guide | Confirm for tool calls, Proceed | Guide for model output)
+ * — the wider intervention vocabulary (Deny, Transform) is excluded by the
+ * return type, so out-of-contract actions are caught at compile time.
+ *
+ * @example
+ * ```typescript
+ * class MySteeringHandler extends SteeringHandler {
+ *   override readonly name = 'my-steering'
+ *
+ *   override async beforeToolCall(event) {
+ *     if (event.toolUse.name === 'dangerous_tool') {
+ *       return guide('This tool requires extra caution.')
+ *     }
+ *     return proceed()
+ *   }
+ * }
+ *
+ * const agent = new Agent({ tools: [...], interventions: [new MySteeringHandler()] })
+ * ```
+ */
+import { InterventionHandler } from '../../../interventions/handler.js';
+import { proceed } from '../../../interventions/actions.js';
+/**
+ * Base class for steering handlers that provide contextual guidance to agents.
+ *
+ * Steering handlers accept context providers that observe agent activity, and
+ * use the accumulated context to make guidance decisions. The handler is an
+ * {@link InterventionHandler} — pass it via `interventions:` on the agent.
+ *
+ * Subclasses must declare a `name` (inherited as `abstract` from
+ * {@link InterventionHandler}). When attaching multiple steering handlers to
+ * one agent, ensure their names are distinct — `InterventionRegistry` rejects
+ * duplicates.
+ */
+export class SteeringHandler extends InterventionHandler {
+    _contextProviders;
+    constructor(config) {
+        super();
+        this._contextProviders = config?.contextProviders ?? [];
+    }
+    // ---------------------------------------------------------------------------
+    // Steering moments — narrowed return types reject out-of-contract actions.
+    // ---------------------------------------------------------------------------
+    beforeToolCall(_event) {
+        return proceed();
+    }
+    afterModelCall(_event) {
+        return proceed();
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle observer — forward to providers so they can self-register hooks.
+    // ---------------------------------------------------------------------------
+    async observeAgent(agent) {
+        for (const provider of this._contextProviders) {
+            await provider.observeAgent(agent);
+        }
+    }
+    /**
+     * Collect context from all registered providers. Subclasses (and tests)
+     * may call this to inspect the accumulated provider snapshots.
+     */
+    getSteeringContext() {
+        return this._contextProviders.map((provider) => provider.context);
+    }
+}
+//# sourceMappingURL=handler.js.map

package/dist/src/vended-interventions/steering/handlers/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../../../src/vended-interventions/steering/handlers/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,mBAAmB,EAAkB,MAAM,mCAAmC,CAAA;AAEvF,OAAO,EAAE,OAAO,EAA0C,MAAM,mCAAmC,CAAA;AAYnG;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,eAAgB,SAAQ,mBAAmB;IAG9C,iBAAiB,CAA2B;IAE7D,YAAY,MAA8B;QACxC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,iBAAiB,GAAG,MAAM,EAAE,gBAAgB,IAAI,EAAE,CAAA;IACzD,CAAC;IAED,8EAA8E;IAC9E,2EAA2E;IAC3E,8EAA8E;IAErE,cAAc,CAAC,MAA2B;QACjD,OAAO,OAAO,EAAE,CAAA;IAClB,CAAC;IAEQ,cAAc,CAAC,MAA2B;QACjD,OAAO,OAAO,EAAE,CAAA;IAClB,CAAC;IAED,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAE9E,KAAK,CAAC,YAAY,CAAC,KAAiB;QAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC9C,MAAM,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAA;QACpC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,kBAAkB;QAChB,OAAO,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;IACnE,CAAC;CACF"}

package/dist/src/vended-interventions/steering/handlers/llm.d.ts

@@ -0,0 +1,72 @@
+/**
+ * LLM-based steering handler that uses an LLM to provide contextual guidance.
+ */
+import { type Confirm, type Guide, type Proceed } from '../../../interventions/actions.js';
+import type { Model } from '../../../models/model.js';
+import type { ContentBlock, SystemPrompt } from '../../../types/messages.js';
+import type { ToolUse } from '../../../tools/types.js';
+import type { BeforeToolCallEvent } from '../../../hooks/events.js';
+import type { LocalAgent } from '../../../types/agent.js';
+import type { SteeringContextData, SteeringContextProvider } from '../providers/context-provider.js';
+import { SteeringHandler } from './handler.js';
+/**
+ * Builds the evaluation prompt sent to the steering LLM.
+ * Return a string for simple prompts, or ContentBlock[] to use cache points.
+ */
+export type PromptBuilder = (context: SteeringContextData[], toolUse?: ToolUse) => string | ContentBlock[];
+/**
+ * Configuration for the LLMSteeringHandler.
+ */
+export interface LLMSteeringHandlerConfig {
+    /** System prompt defining the steering guidance rules. */
+    systemPrompt: SystemPrompt;
+    /** Model for steering evaluation. Defaults to the parent agent's model. */
+    model?: Model;
+    /** Custom prompt builder for evaluation prompts. Defaults to defaultPromptBuilder. */
+    promptBuilder?: PromptBuilder;
+    /**
+     * Context providers for populating steering context.
+     * Defaults to [new ToolLedgerProvider()] if undefined. Pass an empty array to disable.
+     */
+    contextProviders?: SteeringContextProvider[];
+    /**
+     * Identifier for this handler instance. Defaults to `'strands:llm-steering-handler'`.
+     * Override when attaching multiple LLM steering handlers to the same agent.
+     */
+    name?: string;
+}
+/**
+ * Steering handler that uses an LLM to provide contextual guidance.
+ *
+ * Uses natural language prompts to evaluate tool calls and produce an
+ * intervention action.
+ *
+ * Only `beforeToolCall` is implemented — model-output steering is not
+ * delegated to the LLM. Subclass and override `afterModelCall` (which
+ * carries the narrowed `Proceed | Guide` return) to add LLM-driven
+ * evaluation of model responses.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { LLMSteeringHandler } from '@strands-agents/sdk/vended-interventions/steering'
+ *
+ * const handler = new LLMSteeringHandler({
+ *   systemPrompt: `You ensure emails maintain a cheerful, positive tone.`,
+ * })
+ *
+ * const agent = new Agent({ tools: [sendEmail], interventions: [handler] })
+ * ```
+ */
+export declare class LLMSteeringHandler extends SteeringHandler {
+    readonly name: string;
+    private readonly _promptBuilder;
+    private readonly _configuredModel;
+    private _agentModel;
+    private readonly _systemPrompt;
+    constructor(config: LLMSteeringHandlerConfig);
+    observeAgent(agent: LocalAgent): Promise<void>;
+    beforeToolCall(event: BeforeToolCallEvent): Promise<Proceed | Guide | Confirm>;
+    private _invoke;
+}
+//# sourceMappingURL=llm.d.ts.map