@strands-agents/sdk 1.3.0 → 1.5.0

package/dist/src/middleware/registry.js

@@ -0,0 +1,107 @@
+/** Compose layering: input (outermost) → output → wrap (innermost). Execution order: input → wrap → output. */
+const PHASE_ORDER = { input: 0, output: 1, wrap: 2 };
+/**
+ * Registry that stores middleware handlers keyed by stage tokens
+ * and composes them into execution chains with phase ordering.
+ */
+export class MiddlewareRegistry {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _handlers;
+    constructor() {
+        this._handlers = new Map();
+    }
+    /**
+     * Register a middleware handler for a given stage (Wrap phase).
+     * Handlers are stored in registration order within their phase.
+     *
+     * @param stage - The stage token to register the handler for
+     * @param handler - The middleware handler function
+     */
+    add(stage, handler) {
+        const handlers = this._handlers.get(stage) ?? [];
+        handlers.push({ phase: 'wrap', handler });
+        this._handlers.set(stage, handlers);
+    }
+    /**
+     * Register an Input phase handler. Transforms context before the Wrap chain runs.
+     * Multiple Input handlers compose in registration order (each sees the previous handler's output).
+     * Returns the adapted handler for cleanup purposes.
+     */
+    addInput(phase, handler) {
+        const stage = phase._stage;
+        const handlers = this._handlers.get(stage) ?? [];
+        const adapted = async function* (context, next) {
+            const transformed = await handler(context);
+            return yield* next(transformed);
+        };
+        handlers.push({ phase: 'input', handler: adapted });
+        this._handlers.set(stage, handlers);
+        return adapted;
+    }
+    /**
+     * Register an Output phase handler. Transforms result after the Wrap chain completes.
+     * Multiple Output handlers compose in registration order (each sees the previous handler's output).
+     * Returns the adapted handler for cleanup purposes.
+     */
+    addOutput(phase, handler) {
+        const stage = phase._stage;
+        const handlers = this._handlers.get(stage) ?? [];
+        const adapted = async function* (context, next) {
+            const result = yield* next(context);
+            return await handler(result);
+        };
+        handlers.push({ phase: 'output', handler: adapted });
+        this._handlers.set(stage, handlers);
+        return adapted;
+    }
+    /**
+     * Remove a previously registered middleware handler for a given stage.
+     * Removes the first occurrence of the handler (by reference equality on the adapted handler).
+     *
+     * @param stage - The stage token to remove the handler from
+     * @param handler - The middleware handler function to remove
+     */
+    remove(stage, handler) {
+        const handlers = this._handlers.get(stage);
+        if (!handlers)
+            return;
+        const idx = handlers.findIndex((h) => h.handler === handler);
+        if (idx !== -1)
+            handlers.splice(idx, 1);
+    }
+    /**
+     * Compose all registered handlers for a stage into a single middleware chain.
+     * Handlers are ordered by phase (input → output → wrap), then by registration order within phase.
+     * First in the composed chain = outermost.
+     *
+     * @param stage - The stage token to compose handlers for
+     * @param terminal - The innermost function that performs actual stage execution
+     * @returns A single function representing the full middleware chain
+     */
+    compose(stage, terminal) {
+        const tagged = (this._handlers.get(stage) ?? []);
+        // Stable sort by phase: input first, output second, wrap last (closest to terminal)
+        const sorted = [...tagged].sort((a, b) => PHASE_ORDER[a.phase] - PHASE_ORDER[b.phase]);
+        let current = terminal;
+        for (let i = sorted.length - 1; i >= 0; i--) {
+            const handler = sorted[i].handler;
+            const next = current;
+            current = (context) => handler(context, next);
+        }
+        return current;
+    }
+    /**
+     * Compose and invoke the middleware chain for a stage in one call.
+     * Equivalent to `compose(stage, terminal)(context)` but reads more clearly at call sites.
+     *
+     * @param stage - The stage token to invoke
+     * @param context - The context to pass into the chain
+     * @param terminal - The innermost function that performs actual stage execution
+     * @returns An async generator yielding events and returning the stage result
+     */
+    invoke(stage, context, terminal) {
+        const chain = this.compose(stage, terminal);
+        return chain(context);
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/middleware/registry.js.map

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

package/dist/src/middleware/stages.d.ts

@@ -0,0 +1,138 @@
+import type { MiddlewareStage } from './types.js';
+import type { LocalAgent, AgentStreamEvent, InvocationState, InvokeArgs, InvokeOptions, AgentResult } from '../types/agent.js';
+import type { Message, SystemPrompt, ToolResultBlock } from '../types/messages.js';
+import type { ToolSpec, ToolChoice } from '../tools/types.js';
+import type { StateStore } from '../state-store.js';
+import type { StreamAggregatedResult } from '../models/model.js';
+import type { ToolUseData } from '../hooks/events.js';
+import type { Tool } from '../tools/tool.js';
+import type { InterruptParams } from '../types/interrupt.js';
+import type { JSONValue } from '../types/json.js';
+/**
+ * Result returned by `interrupt()` in middleware contexts.
+ * Returns an object to allow future extension (e.g., cached data, metadata)
+ * without a breaking change to callers.
+ */
+export interface MiddlewareInterruptResult<T = JSONValue> {
+    /**
+     * The resolved response value from the interrupt.
+     * The generic `T` is a caller assertion — the actual value is whatever the user
+     * passed in `InterruptResponseContent.response` (a `JSONValue`). No runtime
+     * validation is performed; callers are responsible for ensuring the shape matches.
+     */
+    response: T;
+}
+/**
+ * Interface for middleware contexts that support interrupts.
+ * Unlike the hook/tool `Interruptible`, middleware interrupts return a wrapper
+ * object to allow non-breaking additions in the future.
+ */
+export interface MiddlewareInterruptible {
+    /**
+     * Request a human-in-the-loop interrupt.
+     *
+     * On first execution (no prior response), throws `InterruptError` to halt the agent.
+     * On resume (after the user provides a response), returns the response wrapped in
+     * `MiddlewareInterruptResult`.
+     *
+     * @param params - Interrupt parameters (name, optional reason, optional preemptive response)
+     * @returns The user's response wrapped in `{ response: T }`
+     * @throws InterruptError when no response has been provided yet
+     */
+    interrupt<T = JSONValue>(params: InterruptParams): MiddlewareInterruptResult<T>;
+}
+/**
+ * Creates a new middleware stage token with Input/Wrap/Output phase sub-tokens.
+ * The returned object is frozen and used as a Map key by the registry.
+ *
+ * @param name - Human-readable name for debugging/logging
+ * @returns A frozen MiddlewareStage object carrying the Context/Event/Result type parameters
+ */
+export declare function createStage<TContext, TResult, TEvent>(name: string): MiddlewareStage<TContext, TResult, TEvent>;
+/**
+ * Context passed to model-stage middleware.
+ * All inputs to the model call are explicit — middleware can inspect and transform
+ * any of them by passing a modified context to next().
+ */
+export interface InvokeModelContext {
+    /** The agent instance (escape hatch for advanced use cases). */
+    readonly agent: LocalAgent;
+    /** The messages to send to the model. */
+    readonly messages: readonly Message[];
+    /** System prompt to guide the model's behavior. */
+    readonly systemPrompt?: SystemPrompt;
+    /** Tool specifications available to the model. */
+    readonly toolSpecs: readonly ToolSpec[];
+    /** Controls how the model selects tools. */
+    readonly toolChoice?: ToolChoice;
+    /** Runtime state for stateful model providers. */
+    readonly modelState: StateStore;
+    /** Per-invocation state shared across hooks and tools. */
+    readonly invocationState: InvocationState;
+}
+/**
+ * Result from model-stage middleware.
+ * The return value of the async generator.
+ */
+export interface InvokeModelResult {
+    /** The aggregated result from the model stream. */
+    readonly result: StreamAggregatedResult;
+}
+/**
+ * Context passed to tool-stage middleware.
+ * Contains everything needed to understand and potentially modify the tool call.
+ */
+export interface ExecuteToolContext extends MiddlewareInterruptible {
+    /** The agent instance (escape hatch for advanced use cases). */
+    readonly agent: LocalAgent;
+    /** The resolved tool implementation, or undefined if not found. */
+    readonly tool: Tool | undefined;
+    /** The tool use request (name, toolUseId, input). */
+    readonly toolUse: ToolUseData;
+    /** Per-invocation state shared across hooks and tools. */
+    readonly invocationState: InvocationState;
+}
+/**
+ * Result from tool-stage middleware.
+ * The return value of the async generator.
+ */
+export interface ExecuteToolResult {
+    /** The tool result block from execution. */
+    readonly result: ToolResultBlock;
+}
+/**
+ * Context passed to agent-stream-stage middleware.
+ * Wraps the entire agent output stream at the outermost interception point.
+ */
+export interface AgentStreamContext extends MiddlewareInterruptible {
+    /** The agent instance (escape hatch for advanced use cases). */
+    readonly agent: LocalAgent;
+    /** The invocation arguments passed to agent.stream(). */
+    readonly args: InvokeArgs;
+    /** Per-invocation options (cancel signal, structured output, etc.). */
+    readonly options?: InvokeOptions;
+}
+/**
+ * Result from agent-stream-stage middleware.
+ * The return value of the async generator.
+ */
+export interface AgentStreamResult {
+    /** The final agent result from the stream. */
+    readonly result: AgentResult;
+}
+/**
+ * Built-in stage wrapping core model invocation.
+ * Middleware registered for this stage can rate-limit, cache, or transform model inputs.
+ */
+export declare const InvokeModelStage: MiddlewareStage<InvokeModelContext, InvokeModelResult, AgentStreamEvent>;
+/**
+ * Built-in stage wrapping individual tool execution.
+ * Middleware registered for this stage can add telemetry, validate inputs, or mock responses.
+ */
+export declare const ExecuteToolStage: MiddlewareStage<ExecuteToolContext, ExecuteToolResult, AgentStreamEvent>;
+/**
+ * Built-in stage wrapping the entire agent output stream.
+ * Middleware registered for this stage can filter, transform, or inject events.
+ */
+export declare const AgentStreamStage: MiddlewareStage<AgentStreamContext, AgentStreamResult, AgentStreamEvent>;
+//# sourceMappingURL=stages.d.ts.map

package/dist/src/middleware/stages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.d.ts","sourceRoot":"","sources":["../../../src/middleware/stages.ts"],"names":[],"mappings":"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"}

package/dist/src/middleware/stages.js

@@ -0,0 +1,31 @@
+/**
+ * Creates a new middleware stage token with Input/Wrap/Output phase sub-tokens.
+ * The returned object is frozen and used as a Map key by the registry.
+ *
+ * @param name - Human-readable name for debugging/logging
+ * @returns A frozen MiddlewareStage object carrying the Context/Event/Result type parameters
+ */
+export function createStage(name) {
+    // Partially constructed; all required fields are assigned via Object.assign before Object.freeze below.
+    const stage = { name };
+    const input = Object.freeze({ _phase: 'input', _stage: stage });
+    const wrap = Object.freeze({ _phase: 'wrap', _stage: stage });
+    const output = Object.freeze({ _phase: 'output', _stage: stage });
+    return Object.freeze(Object.assign(stage, { Input: input, Wrap: wrap, Output: output }));
+}
+/**
+ * Built-in stage wrapping core model invocation.
+ * Middleware registered for this stage can rate-limit, cache, or transform model inputs.
+ */
+export const InvokeModelStage = createStage('invokeModel');
+/**
+ * Built-in stage wrapping individual tool execution.
+ * Middleware registered for this stage can add telemetry, validate inputs, or mock responses.
+ */
+export const ExecuteToolStage = createStage('executeTool');
+/**
+ * Built-in stage wrapping the entire agent output stream.
+ * Middleware registered for this stage can filter, transform, or inject events.
+ */
+export const AgentStreamStage = createStage('agentStream');
+//# sourceMappingURL=stages.js.map

package/dist/src/middleware/stages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stages.js","sourceRoot":"","sources":["../../../src/middleware/stages.ts"],"names":[],"mappings":"AAqDA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAA4B,IAAY;IACjE,wGAAwG;IACxG,MAAM,KAAK,GAAG,EAAE,IAAI,EAAgD,CAAA;IACpE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IACxE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAe,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IACtE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAA;AAC1F,CAAC;AA+ED;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAA0D,aAAa,CAAC,CAAA;AAEnH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAA0D,aAAa,CAAC,CAAA;AAEnH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAA0D,aAAa,CAAC,CAAA"}

package/dist/src/middleware/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A stage token that identifies a middleware interception point.
+ * Stages are created via `createStage()` and carry their Context/Event/Result types
+ * as generics, enabling full type inference at registration sites.
+ *
+ * Third parties can create custom stages — the SDK does not maintain a closed set.
+ */
+export interface MiddlewareStage<TContext, TResult, TEvent> {
+    /** Human-readable name for debugging and logging. */
+    readonly name: string;
+    /** @internal Phantom field for type inference. Never accessed at runtime. */
+    readonly _types?: {
+        context: TContext;
+        event: TEvent;
+        result: TResult;
+    };
+    /** Phase sub-token: transform context before execution. */
+    readonly Input: MiddlewareInputPhase<TContext, TResult, TEvent>;
+    /** Phase sub-token: full async generator wrap (before + call next + after). */
+    readonly Wrap: MiddlewareWrapPhase<TContext, TResult, TEvent>;
+    /** Phase sub-token: transform result after execution. */
+    readonly Output: MiddlewareOutputPhase<TContext, TResult, TEvent>;
+}
+/** Phase ordering. Compose layering: input (outermost) → output → wrap (innermost). Execution order: input → wrap → output. */
+export type MiddlewarePhaseKind = 'input' | 'wrap' | 'output';
+/** Phase sub-token for Input handlers. */
+export interface MiddlewareInputPhase<TContext, TResult, TEvent> {
+    /** @internal */
+    readonly _phase: 'input';
+    /** @internal Back-reference to parent stage. */
+    readonly _stage: MiddlewareStage<TContext, TResult, TEvent>;
+}
+/** Phase sub-token for Wrap handlers. */
+export interface MiddlewareWrapPhase<TContext, TResult, TEvent> {
+    /** @internal */
+    readonly _phase: 'wrap';
+    /** @internal Back-reference to parent stage. */
+    readonly _stage: MiddlewareStage<TContext, TResult, TEvent>;
+}
+/** Phase sub-token for Output handlers. */
+export interface MiddlewareOutputPhase<TContext, TResult, TEvent> {
+    /** @internal */
+    readonly _phase: 'output';
+    /** @internal Back-reference to parent stage. */
+    readonly _stage: MiddlewareStage<TContext, TResult, TEvent>;
+}
+/** Union of all phase sub-tokens. */
+export type MiddlewarePhase<TContext, TResult, TEvent> = MiddlewareInputPhase<TContext, TResult, TEvent> | MiddlewareWrapPhase<TContext, TResult, TEvent> | MiddlewareOutputPhase<TContext, TResult, TEvent>;
+/**
+ * The `next` function passed to middleware.
+ * Returns an async generator that yields events of type TEvent and returns the stage result.
+ * Middleware can choose not to call `next` to short-circuit execution.
+ */
+export type MiddlewareNext<TContext, TResult, TEvent> = (context: TContext) => AsyncGenerator<TEvent, TResult, undefined>;
+/**
+ * A middleware handler function (Wrap phase).
+ * Receives the context and a `next` function to call the next layer.
+ * Must be an async generator that yields TEvent and returns TResult.
+ * Middleware can yield its own events, forward events from next, or suppress them.
+ */
+export type MiddlewareHandler<TContext, TResult, TEvent> = (context: TContext, next: MiddlewareNext<TContext, TResult, TEvent>) => AsyncGenerator<TEvent, TResult, undefined>;
+/** Handler for Input phase — transforms context before execution. */
+export type MiddlewareInputHandler<TContext> = (context: TContext) => TContext | Promise<TContext>;
+/** Handler for Output phase — transforms result after execution. */
+export type MiddlewareOutputHandler<TResult> = (result: TResult) => TResult | Promise<TResult>;
+/**
+ * Extracts the `MiddlewareHandler` type from a stage token.
+ * Use this to type middleware methods or properties without repeating the generic parameters.
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin implements Plugin {
+ *   private _handler: MiddlewareHandlerOf<typeof InvokeModelStage> = async function* (context, next) { ... }
+ * }
+ * ```
+ */
+export type MiddlewareHandlerOf<S> = S extends MiddlewareStage<infer C, infer R, infer E> ? MiddlewareHandler<C, R, E> : never;
+/**
+ * Extracts the `MiddlewareNext` type from a stage token.
+ * Use this to type the `next` parameter in standalone middleware methods.
+ *
+ * @example
+ * ```typescript
+ * private async *_handler(context: ..., next: MiddlewareNextOf<typeof AgentStreamStage>) { ... }
+ * ```
+ */
+export type MiddlewareNextOf<S> = S extends MiddlewareStage<infer C, infer R, infer E> ? MiddlewareNext<C, R, E> : never;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/types.ts"],"names":[],"mappings":"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"}

package/dist/src/middleware/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/middleware/types.ts"],"names":[],"mappings":""}

package/dist/src/models/__tests__/anthropic.test.js

@@ -4,7 +4,7 @@ import { isNode } from '../../__fixtures__/environment.js';
 import { AnthropicModel } from '../anthropic.js';
 import { ContextWindowOverflowError, ModelThrottledError } from '../../errors.js';
 import { collectIterator } from '../../__fixtures__/model-test-helpers.js';
-import { Message, TextBlock, CachePointBlock, GuardContentBlock, ToolResultBlock, JsonBlock, } from '../../types/messages.js';
+import { Message, TextBlock, CachePointBlock, GuardContentBlock, ToolResultBlock, JsonBlock, ReasoningBlock, } from '../../types/messages.js';
 import { ImageBlock, DocumentBlock, VideoBlock } from '../../types/media.js';
 import { warnOnce } from '../../logging/warn-once.js';
 /**
@@ -303,17 +303,32 @@ describe('AnthropicModel', () => {
             const messages = [new Message({ role: 'user', content: [new TextBlock('Hi')] })];
             await expect(collectIterator(provider.stream(messages))).rejects.toThrow('API Error');
         });
+        it('maps overload error to ContextWindowOverflowError', async () => {
+            const mockClient = createMockClient(async function* () {
+                yield { type: 'ping' }; // Satisfy linter require-yield
+                throw new Error('prompt is too long');
+            });
+            const provider = new AnthropicModel({ client: mockClient });
+            const messages = [new Message({ role: 'user', content: [new TextBlock('Hi')] })];
+            await expect(collectIterator(provider.stream(messages))).rejects.toThrow(ContextWindowOverflowError);
+        });
         it.each([
-            'PROMPT IS TOO LONG: request exceeds context window',
-            'max_tokens exceeded',
-            'input too long',
             'input is too long',
             'input length exceeds context window',
             'input and output tokens exceed your context limit',
-        ])('maps context overflow error "%s" to ContextWindowOverflowError', async (message) => {
+        ])('maps overflow phrase %p to ContextWindowOverflowError', async (phrase) => {
             const mockClient = createMockClient(async function* () {
-                yield { type: 'ping' }; // Satisfy linter require-yield
-                throw new Error(message);
+                yield { type: 'ping' };
+                throw new Error(phrase);
+            });
+            const provider = new AnthropicModel({ client: mockClient });
+            const messages = [new Message({ role: 'user', content: [new TextBlock('Hi')] })];
+            await expect(collectIterator(provider.stream(messages))).rejects.toThrow(ContextWindowOverflowError);
+        });
+        it('matches overflow phrases case-insensitively', async () => {
+            const mockClient = createMockClient(async function* () {
+                yield { type: 'ping' };
+                throw new Error('PROMPT IS TOO LONG: 200000 tokens');
             });
             const provider = new AnthropicModel({ client: mockClient });
             const messages = [new Message({ role: 'user', content: [new TextBlock('Hi')] })];
@@ -384,6 +399,21 @@ describe('AnthropicModel', () => {
             });
             expect(captured.request.tool_choice).toEqual({ type: 'auto' });
         });
+        it('formats a signature-only reasoning block', async () => {
+            const { captured, mockClient } = setupCapture();
+            const provider = new AnthropicModel({ client: mockClient });
+            const messages = [
+                new Message({
+                    role: 'assistant',
+                    content: [new ReasoningBlock({ signature: 'sig-abc' }), new TextBlock('answer')],
+                }),
+            ];
+            await collectIterator(provider.stream(messages));
+            expect(captured.request.messages[0].content).toEqual([
+                { type: 'thinking', thinking: '', signature: 'sig-abc' },
+                { type: 'text', text: 'answer' },
+            ]);
+        });
         describe('Prompt Caching (Lookahead logic)', () => {
             it('attaches cache control to message content block followed by cache point', async () => {
                 const { captured, mockClient } = setupCapture();