@strands-agents/sdk 1.3.0 → 1.5.0

package/dist/src/agent/agent.js

@@ -1,55 +1,3 @@
-var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
-    if (value !== null && value !== void 0) {
-        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
-        var dispose, inner;
-        if (async) {
-            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
-            dispose = value[Symbol.asyncDispose];
-        }
-        if (dispose === void 0) {
-            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
-            dispose = value[Symbol.dispose];
-            if (async) inner = dispose;
-        }
-        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
-        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
-        env.stack.push({ value: value, dispose: dispose, async: async });
-    }
-    else if (async) {
-        env.stack.push({ async: true });
-    }
-    return value;
-};
-var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
-    return function (env) {
-        function fail(e) {
-            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
-            env.hasError = true;
-        }
-        var r, s = 0;
-        function next() {
-            while (r = env.stack.pop()) {
-                try {
-                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
-                    if (r.dispose) {
-                        var result = r.dispose.call(r.value);
-                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
-                    }
-                    else s |= 1;
-                }
-                catch (e) {
-                    fail(e);
-                }
-            }
-            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
-            if (env.hasError) throw env.error;
-        }
-        return next();
-    };
-})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
-    var e = new Error(message);
-    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
-});
 import { AgentResult, } from '../types/agent.js';
 import { BedrockModel } from '../models/bedrock.js';
 import { contentBlockFromData, Message, TextBlock, ToolResultBlock, ToolUseBlock, } from '../types/messages.js';
@@ -66,12 +14,18 @@ import { AgentPrinter, getDefaultAppender } from './printer.js';
 import { InterventionRegistry } from '../interventions/registry.js';
 import { PluginRegistry } from '../plugins/registry.js';
 import { SlidingWindowConversationManager } from '../conversation-manager/sliding-window-conversation-manager.js';
+import { SummarizingConversationManager } from '../conversation-manager/summarizing-conversation-manager.js';
 import { NullConversationManager } from '../conversation-manager/null-conversation-manager.js';
 import { ConversationManager } from '../conversation-manager/conversation-manager.js';
+import { ContextOffloader } from '../vended-plugins/context-offloader/plugin.js';
+import { InMemoryStorage } from '../vended-plugins/context-offloader/storage.js';
 import { HookRegistryImplementation } from '../hooks/registry.js';
+import { MiddlewareRegistry, InvokeModelStage, ExecuteToolStage, AgentStreamStage } from '../middleware/index.js';
 import { InitializedEvent, AfterInvocationEvent, AfterModelCallEvent, AfterToolCallEvent, AfterToolsEvent, BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent, BeforeToolsEvent, HookableEvent, MessageAddedEvent, ModelStreamUpdateEvent, ContentBlockEvent, ModelMessageEvent, ToolResultEvent, AgentResultEvent, ToolStreamUpdateEvent, InterruptEvent, } from '../hooks/events.js';
 import { StructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME } from '../tools/structured-output-tool.js';
 import { AgentAsTool } from './agent-as-tool.js';
+import { ToolCaller } from './tool-caller.js';
+import { MemoryManager } from '../memory/memory-manager.js';
 import { SessionManager } from '../session/session-manager.js';
 import { Tracer } from '../telemetry/tracer.js';
 import { Meter } from '../telemetry/meter.js';
@@ -79,13 +33,69 @@ import { logger } from '../logging/logger.js';
 import { CancelledError } from '../errors.js';
 import { DefaultModelRetryStrategy } from '../retry/default-model-retry-strategy.js';
 import { warnOnDuplicateRetryStrategyTypes } from '../retry/retry-strategy.js';
-import { InterruptError, InterruptState, interruptFromAgent } from '../interrupt.js';
+import { Interrupt, InterruptError, InterruptState, interruptFromAgent } from '../interrupt.js';
 import { isInterruptResponseContent } from '../types/interrupt.js';
 import { takeSnapshot as takeSnapshotInternal, loadSnapshot as loadSnapshotInternal } from './snapshot.js';
+import { defaultSandbox } from '../sandbox/default.js';
+/** Benchmark-validated token threshold for offloading tool results. */
+const CONTEXT_MANAGER_MAX_RESULT_TOKENS = 1_500;
+/** Benchmark-validated preview token count for offloaded results. */
+const CONTEXT_MANAGER_PREVIEW_TOKENS = 750;
+/** Benchmark-validated ratio of messages to summarize on overflow. */
+const CONTEXT_MANAGER_SUMMARY_RATIO = 0.3;
+/** Benchmark-validated context window ratio that triggers proactive compression. */
+const CONTEXT_MANAGER_COMPRESSION_THRESHOLD = 0.85;
+/**
+ * Resolve the contextManager facade into a concrete ConversationManager.
+ *
+ * When contextManager is undefined, falls back to the default SlidingWindowConversationManager.
+ * When "auto", uses SummarizingConversationManager with benchmark-validated defaults,
+ * unless the user already provided a conversationManager.
+ */
+function resolveConversationManager(contextManager, conversationManager) {
+    if (contextManager !== undefined && contextManager !== 'auto') {
+        throw new Error(`Unsupported contextManager value: "${contextManager}". Supported values: "auto"`);
+    }
+    if (contextManager === 'auto') {
+        return (conversationManager ??
+            new SummarizingConversationManager({
+                summaryRatio: CONTEXT_MANAGER_SUMMARY_RATIO,
+                proactiveCompression: { compressionThreshold: CONTEXT_MANAGER_COMPRESSION_THRESHOLD },
+            }));
+    }
+    return conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+}
 /** Default name assigned to agents when none is provided. */
 const DEFAULT_AGENT_NAME = 'Strands Agent';
 /** Default identifier assigned to agents when none is provided. */
 const DEFAULT_AGENT_ID = 'agent';
+/**
+ * Creates a non-mutating interrupt function for middleware contexts.
+ * Reads existing responses from state (resume case) but never writes to it.
+ * On first run (no response), throws InterruptError with a locally-created Interrupt.
+ *
+ * @param interruptState - The agent's interrupt state (read-only access)
+ * @param idPrefix - Prefix for the interrupt ID (e.g., 'middleware:agentStream')
+ */
+function createMiddlewareInterrupt(interruptState, idPrefix) {
+    return (params) => {
+        const interruptId = `${idPrefix}:${params.name}`;
+        const existing = interruptState.interrupts[interruptId];
+        if (existing?.response !== undefined) {
+            return { response: existing.response };
+        }
+        if (params.response !== undefined) {
+            return { response: params.response };
+        }
+        const interrupt = new Interrupt({
+            id: interruptId,
+            name: params.name,
+            ...(params.reason !== undefined && { reason: params.reason }),
+            source: 'middleware',
+        });
+        throw new InterruptError(interrupt);
+    };
+}
 /**
  * Orchestrates the interaction between a model, a set of tools, and MCP clients.
  * The Agent is responsible for managing the lifecycle of tools and clients
@@ -132,7 +142,22 @@ export class Agent {
      * The session manager for saving and restoring agent sessions, if configured.
      */
     sessionManager;
+    /**
+     * The memory manager for cross-session memory retrieval and storage, if configured.
+     */
+    memoryManager;
+    _sandbox;
+    /**
+     * Execution environment for running commands, code, and file operations.
+     *
+     * @throws DefaultNotConfiguredError if no sandbox is configured for this
+     * environment (e.g. browsers, where no host default is registered).
+     */
+    get sandbox() {
+        return this._sandbox || defaultSandbox.get();
+    }
     _hooksRegistry;
+    _middlewareRegistry;
     _pluginRegistry;
     _interventionRegistry;
     _toolRegistry;
@@ -151,6 +176,8 @@ export class Agent {
     _interruptState;
     /** Strategy for executing tool calls from a single assistant turn. */
     _toolExecutor;
+    /** Direct tool caller — created via {@link ToolCaller.create} factory. */
+    _toolCaller;
     /**
      * Creates an instance of the Agent.
      * @param config - The configuration for the agent.
@@ -165,6 +192,13 @@ export class Agent {
         if (config?.description !== undefined)
             this.description = config.description;
         this.sessionManager = config?.sessionManager;
+        this.memoryManager =
+            config?.memoryManager instanceof MemoryManager
+                ? config.memoryManager
+                : config?.memoryManager
+                    ? new MemoryManager(config.memoryManager)
+                    : undefined;
+        this._sandbox = config?.sandbox;
         if (typeof config?.model === 'string') {
             this.model = new BedrockModel({ modelId: config.model });
         }
@@ -173,14 +207,13 @@ export class Agent {
         }
         // Validate and assign conversation manager
         if (this.model.stateful) {
-            if (config?.conversationManager) {
-                throw new Error('Cannot use a conversationManager with a stateful model. The model manages conversation state server-side.');
+            if (config?.conversationManager || config?.contextManager) {
+                throw new Error('contextManager and conversationManager cannot be used with a stateful model. The model manages conversation state server-side.');
             }
             this._conversationManager = new NullConversationManager();
         }
         else {
-            this._conversationManager =
-                config?.conversationManager ?? new SlidingWindowConversationManager({ windowSize: 40 });
+            this._conversationManager = resolveConversationManager(config?.contextManager, config?.conversationManager);
         }
         const { tools, mcpClients } = flattenTools(config?.tools ?? []);
         this._toolRegistry = new ToolRegistry(tools);
@@ -188,6 +221,8 @@ export class Agent {
         // Initialize hooks registry
         this._hooksRegistry = new HookRegistryImplementation();
         this._interventionRegistry = new InterventionRegistry(config?.interventions ?? [], this._hooksRegistry);
+        // Initialize middleware registry
+        this._middlewareRegistry = new MiddlewareRegistry();
         // `undefined` (omitted) → install the default; `null`/`[]` → explicit opt-out.
         const retryStrategies = config?.retryStrategy === null
             ? []
@@ -205,10 +240,21 @@ export class Agent {
         // - Retry-strategy ordering is not load-bearing for correctness: `DefaultModelRetryStrategy`
         //   guards on `event.retry`, so a user hook that already set it short-circuits
         //   the strategy regardless of registration order.
+        const hasOffloader = (config?.plugins ?? []).some((p) => p.name === 'strands:context-offloader');
         this._pluginRegistry = new PluginRegistry([
             this._conversationManager,
             ...retryStrategies,
             ...(config?.plugins ?? []),
+            ...(config?.contextManager === 'auto' && !hasOffloader
+                ? [
+                    new ContextOffloader({
+                        storage: new InMemoryStorage(),
+                        maxResultTokens: CONTEXT_MANAGER_MAX_RESULT_TOKENS,
+                        previewTokens: CONTEXT_MANAGER_PREVIEW_TOKENS,
+                    }),
+                ]
+                : []),
+            ...(this.memoryManager ? [this.memoryManager] : []),
             ...(config?.sessionManager ? [config.sessionManager] : []),
             new ModelPlugin(this.model),
         ]);
@@ -229,6 +275,9 @@ export class Agent {
         // Initialize interrupt state for human-in-the-loop workflows
         this._interruptState = new InterruptState();
         this._toolExecutor = config?.toolExecutor ?? 'concurrent';
+        // Pass a private helper into ToolCaller so message append + hook firing
+        // remains an internal concern of Agent (not exposed as a public method).
+        this._toolCaller = ToolCaller.create(this, (message, invocationState) => this._appendMessageAndFireHooks(message, invocationState));
         this._initialized = false;
     }
     /**
@@ -254,6 +303,33 @@ export class Agent {
     addHook(eventType, callback, options) {
         return this._hooksRegistry.addCallback(eventType, callback, options);
     }
+    addMiddleware(stageOrPhase, handler) {
+        if ('_phase' in stageOrPhase) {
+            const phase = stageOrPhase;
+            const stage = phase._stage;
+            switch (phase._phase) {
+                case 'input': {
+                    const adapted = this._middlewareRegistry.addInput(stageOrPhase, handler);
+                    return () => this._middlewareRegistry.remove(stage, adapted);
+                }
+                case 'output': {
+                    const adapted = this._middlewareRegistry.addOutput(stageOrPhase, handler);
+                    return () => this._middlewareRegistry.remove(stage, adapted);
+                }
+                case 'wrap': {
+                    const wrapHandler = handler;
+                    this._middlewareRegistry.add(stage, wrapHandler);
+                    return () => this._middlewareRegistry.remove(stage, wrapHandler);
+                }
+                default:
+                    throw new Error(`Unknown middleware phase: ${phase._phase}`);
+            }
+        }
+        const stage = stageOrPhase;
+        const wrapHandler = handler;
+        this._middlewareRegistry.add(stage, wrapHandler);
+        return () => this._middlewareRegistry.remove(stage, wrapHandler);
+    }
     async initialize() {
         if (this._initialized) {
             return;
@@ -267,24 +343,44 @@ export class Agent {
                 this._toolRegistry.addOrReplace(newTools);
             };
         }));
+        // Register tools vended by an explicitly-configured sandbox, applying the sandbox's
+        // toolPrefix to names (like MCP's prefix for server-vended tools).
+        if (this._sandbox) {
+            const prefix = this._sandbox.toolPrefix;
+            for (const tool of this._sandbox.getTools()) {
+                const prefixed = prefix
+                    ? Object.create(tool, {
+                        name: { value: `${prefix}_${tool.name}` },
+                        toolSpec: { value: { ...tool.toolSpec, name: `${prefix}_${tool.name}` } },
+                    })
+                    : tool;
+                if (this._toolRegistry.get(prefixed.name)) {
+                    logger.debug(`tool_name=<${prefixed.name}> | sandbox-vended tool skipped, user has already registered tool with this name`);
+                }
+                else {
+                    this._toolRegistry.add(prefixed);
+                }
+            }
+        }
         await this._pluginRegistry.initialize(this);
+        for (const handler of this._interventionRegistry.handlers) {
+            const observer = handler;
+            if (typeof observer.observeAgent === 'function') {
+                await observer.observeAgent(this);
+            }
+        }
         await this._hooksRegistry.invokeCallbacks(new InitializedEvent({ agent: this }));
         this._initialized = true;
     }
     /**
-     * Acquires a lock to prevent concurrent invocations.
-     * Returns a Disposable that releases the lock when disposed.
+     * Acquires the invocation lock. Throws if an invocation is already in progress.
+     * Callers must release via try/finally with `this._isInvoking = false`.
      */
     acquireLock() {
         if (this._isInvoking) {
             throw new ConcurrentInvocationError('Agent is already processing an invocation. Wait for the current invoke() or stream() call to complete before invoking again.');
         }
         this._isInvoking = true;
-        return {
-            [Symbol.dispose]: () => {
-                this._isInvoking = false;
-            },
-        };
     }
     /**
      * Throws {@link CancelledError} if cancellation has been requested.
@@ -295,6 +391,63 @@ export class Agent {
             throw new CancelledError();
         }
     }
+    /**
+     * Validates the per-invocation budget caps in {@link InvokeOptions.limits}.
+     * Called once at the top of `_stream` so bad inputs fail fast with a clear
+     * error instead of silently no-op'ing (`NaN`, `Infinity`) or tripping
+     * pathologically (zero swallows the user input; negative trips immediately).
+     *
+     * Each cap, when set, must be a positive finite number. Fractional values
+     * are accepted — harmless, and useful for token budgets derived from
+     * arithmetic.
+     */
+    _validateLimits(options) {
+        if (!options?.limits)
+            return;
+        const assertPositive = (name, value) => {
+            if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+                throw new TypeError(`${name} must be a positive finite number, got ${value}`);
+            }
+        };
+        assertPositive('limits.turns', options.limits.turns);
+        assertPositive('limits.outputTokens', options.limits.outputTokens);
+        assertPositive('limits.totalTokens', options.limits.totalTokens);
+    }
+    /**
+     * Evaluates the per-invocation budget caps in {@link InvokeOptions.limits}
+     * against the current invocation's metrics. Called at the top of each
+     * agent-loop iteration, after `_throwIfCancelled` and before `startCycle`.
+     *
+     * Reads from {@link AgentMetrics.latestAgentInvocation} (scoped to the
+     * current invocation) — not `cycleCount` / `accumulatedUsage`, which are
+     * lifetime accumulators that would cause caps to fire prematurely on the
+     * second `invoke()` call against a reused agent.
+     *
+     * Priority on simultaneous trip: turns → totalTokens → outputTokens.
+     *
+     * Returns the {@link StopReason} the loop should terminate with, or
+     * `undefined` if every configured cap is still within budget.
+     */
+    _checkLimits(options) {
+        const limits = options?.limits;
+        if (!limits)
+            return undefined;
+        const invocation = this._meter.metrics.latestAgentInvocation;
+        if (!invocation)
+            return undefined;
+        const cycleCount = invocation.cycles.length;
+        const { outputTokens, totalTokens } = invocation.usage;
+        if (limits.turns !== undefined && cycleCount >= limits.turns) {
+            return 'limitTurns';
+        }
+        if (limits.totalTokens !== undefined && totalTokens >= limits.totalTokens) {
+            return 'limitTotalTokens';
+        }
+        if (limits.outputTokens !== undefined && outputTokens >= limits.outputTokens) {
+            return 'limitOutputTokens';
+        }
+        return undefined;
+    }
     /**
      * The tools this agent can use.
      */
@@ -307,6 +460,32 @@ export class Agent {
     get toolRegistry() {
         return this._toolRegistry;
     }
+    /**
+     * Whether the agent is currently processing an invocation.
+     */
+    get isInvoking() {
+        return this._isInvoking;
+    }
+    /**
+     * Direct tool calling accessor.
+     *
+     * Returns a proxy where each property is a {@link ToolHandle} with
+     * `.invoke()` and `.stream()` methods:
+     * ```typescript
+     * const result = await agent.tool.calculator!.invoke({ a: 5, b: 3 })
+     *
+     * for await (const event of agent.tool.calculator!.stream({ a: 5, b: 3 })) {
+     *   console.log('progress:', event)
+     * }
+     * ```
+     *
+     * Supports underscore-to-hyphen and case-insensitive name resolution.
+     * Results are recorded in message history by default (pass
+     * `{ recordDirectToolCall: false }` to skip).
+     */
+    get tool() {
+        return this._toolCaller;
+    }
     /**
      * The cancellation signal for the current invocation.
      *
@@ -413,97 +592,185 @@ export class Agent {
      * ```
      */
     async *stream(args, options) {
-        const env_1 = { stack: [], error: void 0, hasError: false };
+        this.acquireLock();
         try {
-            const _lock = __addDisposableResource(env_1, this.acquireLock(), false);
             await this.initialize();
+            // Thread the resolved invocationState so all layers share the same reference.
+            const invocationState = options?.invocationState ?? {};
+            const resolvedOptions = options?.invocationState ? options : { ...options, invocationState };
             let currentArgs = args;
-            // Outer loop: re-enters _stream when a hook sets AfterInvocationEvent.resume.
-            // One invocation lock spans the whole resume chain.
             while (true) {
-                // Fresh AbortController per invocation iteration, composed with any external signal.
+                // Fresh AbortController per iteration, composed with any external signal.
                 this._abortController = new AbortController();
-                this._abortSignal = options?.cancelSignal
-                    ? AbortSignal.any([this._abortController.signal, options.cancelSignal])
+                this._abortSignal = resolvedOptions?.cancelSignal
+                    ? AbortSignal.any([this._abortController.signal, resolvedOptions.cancelSignal])
                     : this._abortController.signal;
-                const streamGenerator = this._stream(currentArgs, options);
+                // Process interrupt responses before middleware runs so context.interrupt() can find them
+                const interruptResponses = this._extractInterruptResponses(currentArgs);
+                if (interruptResponses.length > 0) {
+                    this._interruptState.resume(interruptResponses);
+                }
+                // Hooks fire outside middleware — always, even on short-circuit.
+                const beforeInvocationEvent = new BeforeInvocationEvent({ agent: this, invocationState });
+                yield await this._invokeCallbacks(beforeInvocationEvent);
+                if (beforeInvocationEvent.cancel) {
+                    const cancelText = typeof beforeInvocationEvent.cancel === 'string'
+                        ? beforeInvocationEvent.cancel
+                        : 'invocation denied by hook';
+                    const message = new Message({ role: 'assistant', content: [new TextBlock(cancelText)] });
+                    yield this._appendMessage(message, invocationState);
+                    const afterEvent = new AfterInvocationEvent({ agent: this, invocationState });
+                    await this._invokeCallbacks(afterEvent);
+                    yield afterEvent;
+                    return new AgentResult({
+                        stopReason: 'endTurn',
+                        lastMessage: message,
+                        traces: this._tracer.localTraces,
+                        metrics: this._meter.metrics,
+                        invocationState,
+                    });
+                }
+                let result;
                 let caughtError;
-                let lastAfterInvocation;
-                let iterationResult;
+                const afterInvocationEvent = new AfterInvocationEvent({ agent: this, invocationState });
                 try {
-                    iterationResult = await streamGenerator.next();
-                    while (!iterationResult.done) {
-                        try {
-                            const processed = await this._invokeCallbacks(iterationResult.value);
-                            if (processed instanceof AfterInvocationEvent) {
-                                lastAfterInvocation = processed;
-                            }
-                            yield processed;
-                            iterationResult = await streamGenerator.next();
-                        }
-                        catch (error) {
-                            // Throw interrupt errors back into _stream so executeTools can store the
-                            // assistant message as pending execution state for resume.
-                            if (error instanceof InterruptError) {
-                                iterationResult = await streamGenerator.throw(error);
-                            }
-                            else {
-                                throw error;
-                            }
-                        }
-                    }
-                    // Suppress AgentResultEvent for resumed iterations — only the final
-                    // invocation in a resume chain reports an agent result.
-                    if (lastAfterInvocation?.resume === undefined) {
-                        yield await this._invokeCallbacks(new AgentResultEvent({
-                            agent: this,
-                            result: iterationResult.value,
-                            invocationState: iterationResult.value.invocationState,
-                        }));
-                    }
+                    result = yield* this._streamWithMiddleware(currentArgs, resolvedOptions, invocationState);
                 }
                 catch (error) {
                     caughtError = error;
-                    throw error;
                 }
                 finally {
-                    // Drain _stream() so cleanup hooks and printer still fire.
-                    // Yield only on error (consumer may still be iterating); on a consumer
-                    // break, yielding would suspend the generator and leak the lock.
-                    let drainResult = await streamGenerator.return(undefined);
-                    while (!drainResult.done) {
-                        try {
-                            if (caughtError) {
-                                yield await this._invokeCallbacks(drainResult.value);
-                            }
-                            else {
-                                await this._invokeCallbacks(drainResult.value);
-                            }
-                        }
-                        catch (error) {
-                            logger.warn(`event_type=<${drainResult.value.type}>, error=<${error}> | error invoking callbacks during cleanup`);
-                        }
-                        drainResult = await streamGenerator.next();
-                    }
-                    // Reset controller and signal for next iteration / invocation
-                    this._abortController = new AbortController();
-                    this._abortSignal = this._abortController.signal;
+                    // AfterInvocationEvent always fires — even on error or consumer break. Outside middleware.
+                    // Invoke hooks (so .resume can be set) but don't yield in finally (yields in finally
+                    // suspend the generator on consumer break instead of completing cleanup).
+                    await this._invokeCallbacks(afterInvocationEvent);
+                }
+                // Yield outside finally — in JS, a `yield` inside `finally` suspends the generator
+                // mid-cleanup when the consumer breaks, preventing subsequent cleanup code from running.
+                // This line is only reached on normal completion or caught error, never on consumer break.
+                yield afterInvocationEvent;
+                // Re-throw after hooks have fired
+                if (caughtError) {
+                    throw caughtError;
                 }
                 // Resume only on a clean invocation — errors propagate above.
-                if (lastAfterInvocation?.resume !== undefined) {
-                    currentArgs = lastAfterInvocation.resume;
+                if (afterInvocationEvent.resume !== undefined) {
+                    currentArgs = afterInvocationEvent.resume;
                     continue;
                 }
-                return iterationResult.value;
+                // Only emit AgentResultEvent on the final iteration (not on resumed ones).
+                yield await this._invokeCallbacks(new AgentResultEvent({
+                    agent: this,
+                    result: result,
+                    invocationState,
+                }));
+                return result;
+            }
+        }
+        finally {
+            this._isInvoking = false;
+        }
+    }
+    /**
+     * Invokes the AgentStreamStage middleware chain.
+     * Hooks fire outside this method (in stream()'s resume loop).
+     */
+    async *_streamWithMiddleware(args, options, invocationState) {
+        const context = {
+            agent: this,
+            args,
+            ...(options !== undefined && { options }),
+            interrupt: createMiddlewareInterrupt(this._interruptState, 'middleware:agentStream'),
+        };
+        // async function* doesn't bind lexical `this`; capture for the terminal callback.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        try {
+            const { result } = yield* this._middlewareRegistry.invoke(AgentStreamStage, context, async function* (ctx) {
+                const result = yield* self._streamCore(ctx.args, ctx.options);
+                return { result };
+            });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof InterruptError) {
+                for (const interrupt of error.interrupts) {
+                    this._interruptState.registerInterrupt(interrupt);
+                }
+                this._interruptState.activate();
+                for (const interrupt of error.interrupts) {
+                    yield new InterruptEvent({ agent: this, interrupt, invocationState });
+                }
+                return new AgentResult({
+                    stopReason: 'interrupt',
+                    lastMessage: this.messages.length > 0
+                        ? this.messages[this.messages.length - 1]
+                        : new Message({ role: 'assistant', content: [new TextBlock('Interrupted')] }),
+                    traces: this._tracer.localTraces,
+                    metrics: this._meter.metrics,
+                    interrupts: this._interruptState.getUnansweredInterrupts(),
+                    invocationState,
+                });
+            }
+            throw error;
+        }
+    }
+    /**
+     * Single-pass stream through _stream() with event processing.
+     * No resume loop, no lifecycle events — those are handled by stream()'s resume loop.
+     */
+    async *_streamCore(args, options) {
+        const streamGenerator = this._stream(args, options);
+        let caughtError;
+        let iterationResult;
+        try {
+            iterationResult = await streamGenerator.next();
+            while (!iterationResult.done) {
+                try {
+                    const processed = await this._invokeCallbacks(iterationResult.value);
+                    yield processed;
+                    iterationResult = await streamGenerator.next();
+                }
+                catch (error) {
+                    // Throw interrupt errors back into _stream so executeTools can store the
+                    // assistant message as pending execution state for resume.
+                    if (error instanceof InterruptError) {
+                        iterationResult = await streamGenerator.throw(error);
+                    }
+                    else {
+                        throw error;
+                    }
+                }
             }
         }
-        catch (e_1) {
-            env_1.error = e_1;
-            env_1.hasError = true;
+        catch (error) {
+            caughtError = error;
+            throw error;
         }
         finally {
-            __disposeResources(env_1);
+            // Drain _stream() so cleanup hooks and printer still fire.
+            // Yield only on error (consumer may still be iterating); on a consumer
+            // break, yielding would suspend the generator and leak the lock.
+            let drainResult = await streamGenerator.return(undefined);
+            while (!drainResult.done) {
+                try {
+                    if (caughtError) {
+                        yield await this._invokeCallbacks(drainResult.value);
+                    }
+                    else {
+                        await this._invokeCallbacks(drainResult.value);
+                    }
+                }
+                catch (error) {
+                    logger.warn(`event_type=<${drainResult.value.type}>, error=<${error}> | error invoking callbacks during cleanup`);
+                }
+                drainResult = await streamGenerator.next();
+            }
+            // Reset controller and signal for next iteration / invocation
+            this._abortController = new AbortController();
+            this._abortSignal = this._abortController.signal;
         }
+        return iterationResult.value;
     }
     /**
      * Returns a {@link Tool} that wraps this agent, allowing it to be used
@@ -618,6 +885,7 @@ export class Agent {
     async *_stream(args, options) {
         let currentArgs = args;
         let result;
+        this._validateLimits(options);
         // Resolve structured output schema from per-invocation options or constructor config
         const structuredOutputSchema = options?.structuredOutputSchema ?? this._structuredOutputSchema;
         const structuredOutputTool = structuredOutputSchema ? new StructuredOutputTool(structuredOutputSchema) : undefined;
@@ -627,30 +895,14 @@ export class Agent {
         // AgentResult. Mutations by hooks/tools are visible across all recursive
         // agent loop cycles within this invocation.
         const invocationState = options?.invocationState ?? {};
-        // Handle interrupt responses if present in input
+        // Interrupt responses are already consumed in stream() before middleware
+        // runs (so middleware-level interrupt() can find them). Re-extract here
+        // to gate the "non-interrupt input while interrupted" check below.
         const interruptResponses = this._extractInterruptResponses(args);
-        if (interruptResponses.length > 0) {
-            this._interruptState.resume(interruptResponses);
-        }
         // Reject non-interrupt input while in interrupted state
         if (this._interruptState.activated && interruptResponses.length === 0) {
             throw new TypeError('Agent is in an interrupted state. Resume by invoking with interruptResponse content blocks.');
         }
-        const beforeInvocationEvent = new BeforeInvocationEvent({ agent: this, invocationState });
-        yield beforeInvocationEvent;
-        if (beforeInvocationEvent.cancel) {
-            const cancelText = typeof beforeInvocationEvent.cancel === 'string' ? beforeInvocationEvent.cancel : 'invocation denied by hook';
-            const message = new Message({ role: 'assistant', content: [new TextBlock(cancelText)] });
-            yield this._appendMessage(message, invocationState);
-            yield new AfterInvocationEvent({ agent: this, invocationState });
-            return new AgentResult({
-                stopReason: 'endTurn',
-                lastMessage: message,
-                traces: this._tracer.localTraces,
-                metrics: this._meter.metrics,
-                invocationState,
-            });
-        }
         // Normalize input to get the user messages for telemetry
         const inputMessages = this._normalizeInput(args);
         // Start agent trace span
@@ -676,6 +928,17 @@ export class Agent {
             // Main agent loop - continues until model stops without requesting tools
             while (true) {
                 this._throwIfCancelled();
+                const limitStopReason = this._checkLimits(options);
+                if (limitStopReason) {
+                    result = new AgentResult({
+                        stopReason: limitStopReason,
+                        lastMessage: this.messages.at(-1),
+                        traces: this._tracer.localTraces,
+                        metrics: this._meter.metrics,
+                        invocationState,
+                    });
+                    return result;
+                }
                 // Start metrics cycle tracking
                 const { cycleId, startTime: cycleStartTime } = this._meter.startCycle();
                 // Create agent loop cycle span within agent span context
@@ -839,6 +1102,11 @@ export class Agent {
                 return result;
             }
             if (error instanceof InterruptError) {
+                // Handles interrupts from tools/hooks that propagated up through the agent loop.
+                // AgentStreamStage middleware interrupts are caught separately in _streamWithMiddleware().
+                for (const interrupt of error.interrupts) {
+                    this._interruptState.registerInterrupt(interrupt);
+                }
                 // Fan out one event per interrupt. Each event exposes `interrupt.source` so
                 // consumers can filter by origin (tool callback vs hook callback) without
                 // subscribing to separate event types.
@@ -872,8 +1140,6 @@ export class Agent {
             if (structuredOutputTool) {
                 this._toolRegistry.remove(STRUCTURED_OUTPUT_TOOL_NAME);
             }
-            // Always emit final event
-            yield new AfterInvocationEvent({ agent: this, invocationState });
         }
     }
     /**
@@ -1050,26 +1316,10 @@ export class Agent {
                 }
                 return { message, stopReason: 'endTurn' };
             }
-            // Start model span within loop span context
-            const modelId = this.model.modelId;
-            const modelSpan = this._tracer.startModelInvokeSpan({
-                messages: this.messages,
-                ...(modelId && { modelId }),
-                ...(this.systemPrompt !== undefined && { systemPrompt: this.systemPrompt }),
-            });
             try {
-                const result = yield* this._streamFromModel(this.messages, streamOptions, invocationState);
+                const result = yield* this._invokeModelWithMiddleware(invocationState, toolChoice);
                 // Accumulate token usage and model latency metrics
                 this._meter.updateCycle(result.metadata);
-                // End model span with usage
-                const usage = result.metadata?.usage;
-                const metrics = result.metadata?.metrics;
-                this._tracer.endModelInvokeSpan(modelSpan, {
-                    output: result.message,
-                    stopReason: result.stopReason,
-                    ...(usage && { usage }),
-                    ...(metrics && { metrics }),
-                });
                 yield new ModelMessageEvent({
                     agent: this,
                     message: result.message,
@@ -1101,8 +1351,6 @@ export class Agent {
             }
             catch (error) {
                 const modelError = normalizeError(error);
-                // End model span with error
-                this._tracer.endModelInvokeSpan(modelSpan, { error: modelError });
                 // Create error event
                 const errorEvent = new AfterModelCallEvent({
                     agent: this,
@@ -1128,6 +1376,66 @@ export class Agent {
             }
         }
     }
+    /**
+     * Invokes the model through the InvokeModelStage middleware chain.
+     * Builds an InvokeModelContext from current agent state and composes the
+     * middleware chain with a terminal function that calls _streamFromModel
+     * using context fields directly (not re-derived from the agent).
+     *
+     * @param invocationState - Per-invocation state shared across hooks and tools
+     * @param toolChoice - Optional tool choice to force specific tool usage
+     * @returns StreamAggregatedResult from the model (or middleware short-circuit)
+     */
+    async *_invokeModelWithMiddleware(invocationState, toolChoice) {
+        const context = {
+            agent: this,
+            messages: this.messages,
+            ...(this.systemPrompt !== undefined && { systemPrompt: this.systemPrompt }),
+            toolSpecs: this._toolRegistry.list().map((tool) => tool.toolSpec),
+            ...(toolChoice !== undefined && { toolChoice }),
+            modelState: this.modelState,
+            invocationState,
+        };
+        // async function* doesn't bind lexical `this`; capture for the terminal callback.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        const middlewareResult = yield* this._middlewareRegistry.invoke(InvokeModelStage, context, async function* (ctx) {
+            const modelId = self.model.modelId;
+            const modelSpan = self._tracer.startModelInvokeSpan({
+                messages: ctx.messages,
+                ...(modelId && { modelId }),
+                ...(ctx.systemPrompt !== undefined && { systemPrompt: ctx.systemPrompt }),
+            });
+            try {
+                const streamOptions = {
+                    toolSpecs: ctx.toolSpecs,
+                    modelState: ctx.modelState,
+                    ...(ctx.systemPrompt !== undefined && { systemPrompt: ctx.systemPrompt }),
+                    ...(ctx.toolChoice && { toolChoice: ctx.toolChoice }),
+                };
+                const gen = self._streamFromModel(ctx.messages, streamOptions, ctx.invocationState);
+                let iterResult = await gen.next();
+                while (!iterResult.done) {
+                    yield iterResult.value;
+                    iterResult = await gen.next();
+                }
+                const usage = iterResult.value.metadata?.usage;
+                const metrics = iterResult.value.metadata?.metrics;
+                self._tracer.endModelInvokeSpan(modelSpan, {
+                    output: iterResult.value.message,
+                    stopReason: iterResult.value.stopReason,
+                    ...(usage && { usage }),
+                    ...(metrics && { metrics }),
+                });
+                return { result: iterResult.value };
+            }
+            catch (error) {
+                self._tracer.endModelInvokeSpan(modelSpan, { error: normalizeError(error) });
+                throw error;
+            }
+        });
+        return middlewareResult.result;
+    }
     /**
      * Streams events from the model and dispatches appropriate events for each.
      *
@@ -1484,86 +1792,9 @@ export class Agent {
                 }
                 return afterToolCallEvent.result;
             }
-            // Start tool span within loop span context
-            const toolSpan = this._tracer.startToolCallSpan({
-                tool: toolUse,
-            });
-            // Track tool execution time for metrics
-            const toolStartTime = Date.now();
-            let toolResult;
-            let error;
-            if (!effectiveTool) {
-                // Tool not found
-                toolResult = new ToolResultBlock({
-                    toolUseId: toolUse.toolUseId,
-                    status: 'error',
-                    content: [new TextBlock(`Tool '${toolUse.name}' not found in registry`)],
-                });
-            }
-            else {
-                // Execute tool within the tool span context
-                const toolContext = {
-                    toolUse: {
-                        name: toolUse.name,
-                        toolUseId: toolUse.toolUseId,
-                        input: toolUse.input,
-                    },
-                    agent: this,
-                    invocationState,
-                    interrupt: (params) => {
-                        return interruptFromAgent(this, `tool:${toolUseBlock.toolUseId}:${params.name}`, params, 'tool');
-                    },
-                };
-                try {
-                    // Manually iterate tool stream to wrap each ToolStreamEvent in ToolStreamUpdateEvent.
-                    // This keeps the tool authoring interface unchanged — tools construct ToolStreamEvent
-                    // without knowledge of agents or hooks, and we wrap at the boundary.
-                    // Tool execution is ran within the tool span's context so that
-                    // downstream calls (e.g., MCP clients) can propagate trace context
-                    const toolGenerator = this._tracer.withSpanContext(toolSpan, () => effectiveTool.stream(toolContext));
-                    let toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
-                    while (!toolNext.done) {
-                        yield new ToolStreamUpdateEvent({ agent: this, event: toolNext.value, invocationState });
-                        toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
-                    }
-                    const result = toolNext.value;
-                    if (!result) {
-                        // Tool didn't return a result
-                        toolResult = new ToolResultBlock({
-                            toolUseId: toolUse.toolUseId,
-                            status: 'error',
-                            content: [new TextBlock(`Tool '${toolUse.name}' did not return a result`)],
-                        });
-                    }
-                    else {
-                        toolResult = result;
-                        error = result.error;
-                    }
-                }
-                catch (e) {
-                    // Re-throw InterruptError to allow interrupt handling
-                    if (e instanceof InterruptError) {
-                        throw e;
-                    }
-                    // Tool execution failed with error
-                    error = normalizeError(e);
-                    toolResult = new ToolResultBlock({
-                        toolUseId: toolUse.toolUseId,
-                        status: 'error',
-                        content: [new TextBlock(error.message)],
-                        error,
-                    });
-                }
-            }
-            // End tool span with the raw tool result — telemetry reflects what the
-            // tool actually returned, independent of AfterToolCallEvent mutations.
-            this._tracer.endToolCallSpan(toolSpan, { toolResult, ...(error && { error }) });
-            // End tool metrics tracking
-            this._meter.endToolCall({
-                tool: toolUse,
-                duration: Date.now() - toolStartTime,
-                success: toolResult.status === 'success',
-            });
+            // Execute tool core logic through middleware chain
+            const toolResult = yield* this._executeToolWithMiddleware(effectiveTool, toolUse, invocationState);
+            const error = toolResult.error;
             // Single point for AfterToolCallEvent
             const afterToolCallEvent = new AfterToolCallEvent({
                 agent: this,
@@ -1582,6 +1813,110 @@ export class Agent {
             return afterToolCallEvent.result;
         }
     }
+    async *_executeToolWithMiddleware(tool, toolUse, invocationState) {
+        const context = {
+            agent: this,
+            tool,
+            toolUse: {
+                name: toolUse.name,
+                toolUseId: toolUse.toolUseId,
+                input: toolUse.input,
+            },
+            invocationState,
+            interrupt: createMiddlewareInterrupt(this._interruptState, `middleware:executeTool:${toolUse.toolUseId}`),
+        };
+        // async function* doesn't bind lexical `this`; capture for the terminal callback.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        const middlewareResult = yield* this._middlewareRegistry.invoke(ExecuteToolStage, context, async function* (ctx) {
+            const result = yield* self._executeToolCore(ctx.tool, ctx.toolUse, ctx.invocationState);
+            return { result };
+        });
+        return middlewareResult.result;
+    }
+    async *_executeToolCore(effectiveTool, toolUse, invocationState) {
+        // Start tool span within loop span context
+        const toolSpan = this._tracer.startToolCallSpan({
+            tool: toolUse,
+        });
+        // Track tool execution time for metrics
+        const toolStartTime = Date.now();
+        let toolResult;
+        let error;
+        if (!effectiveTool) {
+            // Tool not found
+            toolResult = new ToolResultBlock({
+                toolUseId: toolUse.toolUseId,
+                status: 'error',
+                content: [new TextBlock(`Tool '${toolUse.name}' not found in registry`)],
+            });
+        }
+        else {
+            // Execute tool within the tool span context
+            const toolContext = {
+                toolUse: {
+                    name: toolUse.name,
+                    toolUseId: toolUse.toolUseId,
+                    input: toolUse.input,
+                },
+                agent: this,
+                invocationState,
+                interrupt: (params) => {
+                    return interruptFromAgent(this, `tool:${toolUse.toolUseId}:${params.name}`, params, 'tool');
+                },
+            };
+            try {
+                // Manually iterate tool stream to wrap each ToolStreamEvent in ToolStreamUpdateEvent.
+                // This keeps the tool authoring interface unchanged — tools construct ToolStreamEvent
+                // without knowledge of agents or hooks, and we wrap at the boundary.
+                // Tool execution is ran within the tool span's context so that
+                // downstream calls (e.g., MCP clients) can propagate trace context
+                const toolGenerator = this._tracer.withSpanContext(toolSpan, () => effectiveTool.stream(toolContext));
+                let toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
+                while (!toolNext.done) {
+                    yield new ToolStreamUpdateEvent({ agent: this, event: toolNext.value, invocationState });
+                    toolNext = await this._tracer.withSpanContext(toolSpan, () => toolGenerator.next());
+                }
+                const result = toolNext.value;
+                if (!result) {
+                    // Tool didn't return a result
+                    toolResult = new ToolResultBlock({
+                        toolUseId: toolUse.toolUseId,
+                        status: 'error',
+                        content: [new TextBlock(`Tool '${toolUse.name}' did not return a result`)],
+                    });
+                }
+                else {
+                    toolResult = result;
+                    error = result.error;
+                }
+            }
+            catch (e) {
+                // Re-throw InterruptError to allow interrupt handling
+                if (e instanceof InterruptError) {
+                    throw e;
+                }
+                // Tool execution failed with error
+                error = normalizeError(e);
+                toolResult = new ToolResultBlock({
+                    toolUseId: toolUse.toolUseId,
+                    status: 'error',
+                    content: [new TextBlock(error.message)],
+                    error,
+                });
+            }
+        }
+        // End tool span with the raw tool result — telemetry reflects what the
+        // tool actually returned, independent of AfterToolCallEvent mutations.
+        this._tracer.endToolCallSpan(toolSpan, { toolResult, ...(error && { error }) });
+        // End tool metrics tracking
+        this._meter.endToolCall({
+            tool: toolUse,
+            duration: Date.now() - toolStartTime,
+            success: toolResult.status === 'success',
+        });
+        return toolResult;
+    }
     /**
      * Redacts the last message in the conversation history.
      * Called when guardrails block user input and redaction is enabled.
@@ -1668,6 +2003,17 @@ export class Agent {
         }
         return estimate;
     }
+    /**
+     * Appends a message to the conversation history and fires MessageAddedEvent hooks.
+     *
+     * Used by {@link ToolCaller} (via the helper passed to `ToolCaller.create`) for
+     * direct tool calls that cannot yield events into the agent stream. This stays
+     * private — callers outside the agent should never directly mutate messages.
+     */
+    async _appendMessageAndFireHooks(message, invocationState = {}) {
+        this.messages.push(message);
+        await this._hooksRegistry.invokeCallbacks(new MessageAddedEvent({ agent: this, message, invocationState }));
+    }
     /**
      * Appends a message to the conversation history and returns the event for yielding.
      *