@aws/agentcore 1.0.0-preview.18 → 1.0.0-preview.19

package/dist/assets/__tests__/googleadk-session-eviction.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Regression test for the GoogleADK session-store LRU eviction (#808, #1639).
+ *
+ * The rendered template bounds InMemorySessionService to 128 sessions via an
+ * OrderedDict whose KEY is the composite (user_id, session_id) tuple. The
+ * eviction must unpack the key tuple from popitem() -- popitem() returns
+ * (key, value), so the value (always True) must be discarded. A previous
+ * bug unpacked `old_user_id, old_session_id = popitem(...)`, which assigned the
+ * tuple key to old_user_id and True to old_session_id, so delete_session() was
+ * called with garbage and the real session was never freed -- growing unbounded.
+ */
+import * as fs from 'fs';
+import Handlebars from 'handlebars';
+import * as path from 'path';
+import { describe, expect, it } from 'vitest';
+
+const MAIN_PATH = path.resolve(__dirname, '..', 'python', 'http', 'googleadk', 'base', 'main.py');
+
+const SESSION_LIMIT = 128;
+const SEP = '::';
+
+/**
+ * Mirror of the rendered template's `get_or_create_session` eviction loop so we
+ * can assert the observable behavior (store cap + correct delete ids) without a
+ * Python runtime. Returns the keys still tracked and the (user_id, session_id)
+ * pairs that delete_session was invoked with, in eviction order.
+ */
+function simulateEviction(sessions: Array<[string, string]>): {
+  tracked: Set<string>;
+  deleted: Array<[string, string]>;
+} {
+  const keys = new Map<string, true>();
+  const deleted: Array<[string, string]> = [];
+
+  for (const [userId, sessionId] of sessions) {
+    const key = `${userId}${SEP}${sessionId}`;
+    if (keys.has(key)) {
+      keys.delete(key);
+      keys.set(key, true);
+      continue;
+    }
+    while (keys.size >= SESSION_LIMIT) {
+      const oldest = keys.keys().next().value as string;
+      keys.delete(oldest);
+      const [oldUser, oldSession] = oldest.split(SEP);
+      deleted.push([oldUser, oldSession]);
+    }
+    keys.set(key, true);
+  }
+
+  return { tracked: new Set(keys.keys()), deleted };
+}
+
+describe('GoogleADK session store LRU eviction', () => {
+  const template = Handlebars.compile(fs.readFileSync(MAIN_PATH, 'utf-8'));
+  const rendered = template({ name: 'evictionagent', needsOs: false, hasGateway: false });
+
+  it('unpacks the composite key tuple from popitem (not key->user_id, value->session_id)', () => {
+    // The load-bearing fix: the key tuple must be destructured, value discarded.
+    expect(rendered).toContain('(old_user_id, old_session_id), _ = _session_keys.popitem(last=False)');
+    // Guard against the buggy form regressing back in.
+    expect(rendered).not.toMatch(/^\s*old_user_id, old_session_id = _session_keys\.popitem/m);
+  });
+
+  it('passes the unpacked ids straight to delete_session', () => {
+    expect(rendered).toContain('user_id=old_user_id, session_id=old_session_id');
+  });
+
+  it('caps the store at 128 and evicts the oldest sessions in order', () => {
+    const sessions: Array<[string, string]> = [];
+    for (let i = 0; i < 200; i++) {
+      sessions.push(['u', `s${i}`]);
+    }
+
+    const { tracked, deleted } = simulateEviction(sessions);
+
+    // Store stays bounded at the limit regardless of how many distinct sessions arrive.
+    expect(tracked.size).toBe(SESSION_LIMIT);
+    // 200 inserts - 128 retained = 72 evictions, oldest first.
+    expect(deleted.length).toBe(200 - SESSION_LIMIT);
+    expect(deleted[0]).toEqual(['u', 's0']);
+    expect(deleted[deleted.length - 1]).toEqual(['u', `s${200 - SESSION_LIMIT - 1}`]);
+    // The most recent session is retained; the first evicted one is gone.
+    expect(tracked.has(`u${SEP}s199`)).toBe(true);
+    expect(tracked.has(`u${SEP}s0`)).toBe(false);
+  });
+});

package/dist/assets/__tests__/summarization-namespace.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Regression test for cross-session SUMMARIZATION recall (issue #665).
+ *
+ * The SUMMARIZATION retrieval namespace must be actor-scoped (`/summaries/{actor_id}`),
+ * not session-scoped. The SDK's namespace_path is a hierarchical prefix match, so a
+ * per-session prefix (`/summaries/{actor_id}/{session_id}`) only ever matches the current
+ * session's own summaries and never surfaces summaries written by prior sessions —
+ * silently breaking cross-session recall. This guards against another silent revert
+ * (see PR #1299, reverted by squash release #1547).
+ */
+import Handlebars from 'handlebars';
+import * as fs from 'fs';
+import * as path from 'path';
+import { describe, expect, it } from 'vitest';
+// Importing render registers the `includes` Handlebars helper used by the template.
+import '../../cli/templates/render.js';
+
+const FLAVORS = ['http', 'agui', 'a2a'] as const;
+
+function renderSessionTemplate(flavor: string): string {
+  const templatePath = path.resolve(
+    __dirname,
+    '..',
+    'python',
+    flavor,
+    'strands',
+    'capabilities',
+    'memory',
+    'session.py'
+  );
+  const content = fs.readFileSync(templatePath, 'utf-8');
+  return Handlebars.compile(content)({
+    memoryProviders: [{ envVarName: 'MEMORY_TEST_ID', strategies: ['SUMMARIZATION'] }],
+  });
+}
+
+describe('SUMMARIZATION retrieval namespace', () => {
+  it.each(FLAVORS)('%s session.py uses an actor-scoped summary namespace', flavor => {
+    const rendered = renderSessionTemplate(flavor);
+    expect(rendered).toContain('f"/summaries/{actor_id}": RetrievalConfig');
+    expect(rendered).not.toContain('/summaries/{actor_id}/{session_id}');
+  });
+});

package/dist/assets/python/a2a/strands/capabilities/memory/session.py

@@ -28,7 +28,7 @@ def get_memory_session_manager(session_id: Optional[str], actor_id: str) -> Opti
         f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
-        f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

package/dist/assets/python/agui/strands/capabilities/memory/session.py

@@ -28,7 +28,7 @@ def get_memory_session_manager(session_id: Optional[str], actor_id: str) -> Opti
         f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
-        f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

package/dist/assets/python/http/autogen/base/main.py

@@ -1,6 +1,7 @@
 {{#if needsOs}}
 import os
 {{/if}}
+from collections import OrderedDict
 from autogen_agentchat.agents import AssistantAgent
 from autogen_core.tools import FunctionTool
 from bedrock_agentcore.runtime import BedrockAgentCoreApp
@@ -91,23 +92,45 @@ You have access to the following mounted filesystems. Use file_read, file_write,
 {{/each}}{{/if}}
 """
 
-@app.entrypoint
-async def invoke(payload, context):
-    log.info("Invoking Agent.....")
+# Reuses one AssistantAgent per session_id so each session keeps its own
+# in-process conversation history (best-effort; resets on cold start). Caches up
+# to 128 active sessions with LRU eviction (least-recently-used is dropped and
+# its history reset).
+_agents = OrderedDict()
 
+
+async def get_or_create_agent(session_id):
+    if session_id in _agents:
+        _agents.move_to_end(session_id)
+        return _agents[session_id]
+    if len(_agents) >= 128:
+        _agents.popitem(last=False)
     # Get MCP Tools
     mcp_tools = await get_streamable_http_mcp_tools()
+    # Re-check after the await: a concurrent first-invocation for the same
+    # session_id may have built and stored the agent while we were awaiting.
+    # Don't overwrite it (that would orphan the agent the other request is using).
+    if session_id not in _agents:
+        _agents[session_id] = AssistantAgent(
+            name="{{ name }}",
+            model_client=load_model(),
+            tools=tools + mcp_tools,
+            system_message=SYSTEM_MESSAGE,
+        )
+    _agents.move_to_end(session_id)
+    return _agents[session_id]
 
-    # Define an AssistantAgent with the model and tools
-    agent = AssistantAgent(
-        name="{{ name }}",
-        model_client=load_model(),
-        tools=tools + mcp_tools,
-        system_message=SYSTEM_MESSAGE,
-    )
+
+@app.entrypoint
+async def invoke(payload, context):
+    log.info("Invoking Agent.....")
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    session_id = getattr(context, "session_id", "default-session")
+
+    # Reuse the per-session agent (preserves conversation history)
+    agent = await get_or_create_agent(session_id)
 
     # Run the agent
     result = await agent.run(task=prompt)

package/dist/assets/python/http/googleadk/base/main.py

@@ -1,6 +1,7 @@
 {{#if needsOs}}
 import os
 {{/if}}
+from collections import OrderedDict
 from google.adk.agents import Agent
 from google.adk.runners import Runner
 from google.adk.sessions import InMemorySessionService
@@ -121,21 +122,57 @@ agent = Agent(
 )
 
 
-# Session and Runner
-async def setup_session_and_runner(user_id, session_id):
-    ensure_credentials_loaded()
-    session_service = InMemorySessionService()
-    session = await session_service.create_session(
+# Module-level session service and runner preserve history across invocations.
+# InMemorySessionService retains every (app_name, user_id, session_id) triple
+# forever, so we bound it to 128 active sessions with LRU eviction (the
+# least-recently-used session is deleted and its history reset) to keep a
+# long-running process from growing without limit. For durable history, swap in
+# a persistent session service (e.g. DatabaseSessionService).
+_SESSION_LIMIT = 128
+_session_service = InMemorySessionService()
+_session_keys = OrderedDict()
+_runner = None
+
+
+def get_or_create_runner():
+    global _runner
+    if _runner is None:
+        ensure_credentials_loaded()
+        _runner = Runner(
+            agent=agent,
+            app_name=APP_NAME,
+            session_service=_session_service,
+        )
+    return _runner
+
+
+async def get_or_create_session(user_id, session_id):
+    key = (user_id, session_id)
+    if key in _session_keys:
+        _session_keys.move_to_end(key)
+    else:
+        while len(_session_keys) >= _SESSION_LIMIT:
+            (old_user_id, old_session_id), _ = _session_keys.popitem(last=False)
+            await _session_service.delete_session(
+                app_name=APP_NAME, user_id=old_user_id, session_id=old_session_id
+            )
+        _session_keys[key] = True
+
+    session = await _session_service.get_session(
         app_name=APP_NAME, user_id=user_id, session_id=session_id
     )
-    runner = Runner(agent=agent, app_name=APP_NAME, session_service=session_service)
-    return session, runner
+    if session is None:
+        session = await _session_service.create_session(
+            app_name=APP_NAME, user_id=user_id, session_id=session_id
+        )
+    return session
 
 
 # Agent Interaction
 async def call_agent_async(query, user_id, session_id):
     content = types.Content(role="user", parts=[types.Part(text=query)])
-    session, runner = await setup_session_and_runner(user_id, session_id)
+    runner = get_or_create_runner()
+    session = await get_or_create_session(user_id, session_id)
     events = runner.run_async(
         user_id=user_id, session_id=session.id, new_message=content
     )

package/dist/assets/python/http/langchain_langgraph/base/main.py

@@ -1,9 +1,11 @@
 {{#if needsOs}}
 import os
 {{/if}}
+from collections import OrderedDict
 from typing import Any
 
 from langchain_core.messages import HumanMessage{{#if hasConfigBundle}}, SystemMessage{{/if}}
+from langgraph.checkpoint.memory import InMemorySaver
 from langgraph.prebuilt import create_react_agent
 from langchain.tools import tool
 {{#if hasConfigBundle}}
@@ -54,6 +56,26 @@ def add_numbers(a: int, b: int) -> int:
 # Define a collection of tools used by the model
 tools = [add_numbers]
 
+# Module-level checkpointer preserves conversation history across invocations.
+# InMemorySaver keeps every thread_id (= session_id) checkpoint in memory
+# forever, so we bound it to 128 active threads with LRU eviction (the
+# least-recently-used thread is deleted and its history reset) to keep a
+# long-running process from growing without limit. For durable history, swap in
+# a persistent checkpointer (e.g. SqliteSaver/AsyncSqliteSaver with a file path).
+_CHECKPOINT_LIMIT = 128
+_checkpointer = InMemorySaver()
+_thread_ids = OrderedDict()
+
+
+def touch_thread(thread_id):
+    if thread_id in _thread_ids:
+        _thread_ids.move_to_end(thread_id)
+        return
+    while len(_thread_ids) >= _CHECKPOINT_LIMIT:
+        evicted, _ = _thread_ids.popitem(last=False)
+        _checkpointer.delete_thread(evicted)
+    _thread_ids[thread_id] = True
+
 {{#if needsOs}}
 _MOUNT_PATHS = [
     {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
@@ -149,29 +171,46 @@ async def invoke(payload, context):
     if mcp_client:
         mcp_tools = await mcp_client.get_tools()
 
-    # Define the agent using create_react_agent
+    # Define the agent using create_react_agent (checkpointer is shared across invocations)
 {{#if hasConfigBundle}}
-    graph = create_react_agent(get_or_create_model(), tools=mcp_tools + tools, prompt=DEFAULT_SYSTEM_PROMPT)
+    graph = create_react_agent(
+        get_or_create_model(),
+        tools=mcp_tools + tools,
+        prompt=DEFAULT_SYSTEM_PROMPT,
+        checkpointer=_checkpointer,
+    )
     callback = ConfigBundleCallback()
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    session_id = getattr(context, "session_id", "default-session")
+    touch_thread(session_id)
     log.info(f"Agent input: {prompt}")
 
-    # Run the agent with config bundle callback
+    # Run the agent with config bundle callback (checkpointer auto-loads/saves history per session)
     result = await graph.ainvoke(
         {"messages": [HumanMessage(content=prompt)]},
-        config={"callbacks": [callback]},
+        config={"callbacks": [callback], "configurable": {"thread_id": session_id}},
     )
 {{else}}
-    graph = create_react_agent(get_or_create_model(), tools=mcp_tools + tools, prompt=DEFAULT_SYSTEM_PROMPT)
+    graph = create_react_agent(
+        get_or_create_model(),
+        tools=mcp_tools + tools,
+        prompt=DEFAULT_SYSTEM_PROMPT,
+        checkpointer=_checkpointer,
+    )
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    session_id = getattr(context, "session_id", "default-session")
+    touch_thread(session_id)
     log.info(f"Agent input: {prompt}")
 
-    # Run the agent
-    result = await graph.ainvoke({"messages": [HumanMessage(content=prompt)]})
+    # Run the agent (checkpointer auto-loads/saves history per session)
+    result = await graph.ainvoke(
+        {"messages": [HumanMessage(content=prompt)]},
+        config={"configurable": {"thread_id": session_id}},
+    )
 {{/if}}
 
     # Return result

package/dist/assets/python/http/openaiagents/base/main.py

@@ -4,7 +4,8 @@ import os
 {{#if hasGateway}}
 from contextlib import AsyncExitStack
 {{/if}}
-from agents import Agent, Runner, function_tool
+from functools import lru_cache
+from agents import Agent, Runner, SQLiteSession, function_tool
 from bedrock_agentcore.runtime import BedrockAgentCoreApp
 from model.load import load_model
 {{#if hasGateway}}
@@ -108,8 +109,16 @@ You have access to the following mounted filesystems. Use file_read, file_write,
 {{/each}}{{/if}}
 """
 
+# Caches up to 128 active sessions; LRU eviction silently resets history for
+# the oldest session. For production use, replace with a durable session store
+# (e.g. SQLiteSession with a file path).
+@lru_cache(maxsize=128)
+def get_session(session_id):
+    return SQLiteSession(session_id)
+
+
 # Define the agent execution
-async def main(query):
+async def main(query, session):
     ensure_credentials_loaded()
     try:
         {{#if hasGateway}}
@@ -128,7 +137,7 @@ async def main(query):
                     tools=tools,
                     mcp_config={"include_server_in_tool_names": True},
                 )
-                result = await Runner.run(agent, query)
+                result = await Runner.run(agent, query, session=session)
                 return result
         else:
             agent = Agent(
@@ -138,7 +147,7 @@ async def main(query):
                 mcp_servers=[],
                 tools=tools
             )
-            result = await Runner.run(agent, query)
+            result = await Runner.run(agent, query, session=session)
             return result
         {{else}}
         if mcp_servers:
@@ -151,7 +160,7 @@ async def main(query):
                     mcp_servers=active_servers,
                     tools=tools
                 )
-                result = await Runner.run(agent, query)
+                result = await Runner.run(agent, query, session=session)
                 return result
         else:
             agent = Agent(
@@ -161,7 +170,7 @@ async def main(query):
                 mcp_servers=[],
                 tools=tools
             )
-            result = await Runner.run(agent, query)
+            result = await Runner.run(agent, query, session=session)
             return result
         {{/if}}
     except Exception as e:
@@ -175,9 +184,11 @@ async def invoke(payload, context):
 
     # Process the user prompt
     prompt = payload.get("prompt", "What can you help me with?")
+    session_id = getattr(context, "session_id", "default-session")
+    session = get_session(session_id)
 
-    # Run the agent
-    result = await main(prompt)
+    # Run the agent (session automatically loads/saves conversation history)
+    result = await main(prompt, session)
 
     # Return result
     return {"result": result.final_output}

package/dist/assets/python/http/strands/base/main.py

@@ -1,4 +1,5 @@
 from typing import Any
+from collections import OrderedDict
 {{#if inlineFunctionTools}}
 import json
 
@@ -434,26 +435,21 @@ def agent_factory():
 get_or_create_agent = agent_factory()
 {{/unless}}
 {{else}}
-{{#if hasConfigBundle}}
-def create_agent({{#if hasSkillsFetcher}}skill_plugins=None{{/if}}):
-    return Agent(
-        model=load_model(),
-        system_prompt=DEFAULT_SYSTEM_PROMPT,
-        tools=tools,
-        conversation_manager=_make_conversation_manager(),
-        {{#if hasSkillsFetcher}}
-        plugins=skill_plugins or None,
-        {{/if}}
-        hooks=[ConfigBundleHook()],
-    )
-{{else}}
 {{#unless hasPayment}}
-_agent = None
-
-def get_or_create_agent({{#if hasSkillsFetcher}}skill_plugins=None{{/if}}):
-    global _agent
-    if _agent is None:
-        _agent = Agent(
+# Reuses one Agent per session_id so each session keeps its own in-process
+# conversation history (best-effort; resets on cold start). The cache is bounded
+# to 128 sessions with LRU eviction (least-recently-used is dropped and its
+# history reset) so a single process serving many sessions cannot leak history
+# between them or grow without limit. For durable history, attach a session manager.
+def agent_factory():
+    cache = OrderedDict()
+    def get_or_create_agent(session_id{{#if hasSkillsFetcher}}, skill_plugins=None{{/if}}):
+        if session_id in cache:
+            cache.move_to_end(session_id)
+            return cache[session_id]
+        if len(cache) >= 128:
+            cache.popitem(last=False)
+        cache[session_id] = Agent(
             model=load_model(),
             system_prompt=DEFAULT_SYSTEM_PROMPT,
             tools=tools,
@@ -473,12 +469,16 @@ def get_or_create_agent({{#if hasSkillsFetcher}}skill_plugins=None{{/if}}):
                     {{#if timeoutSeconds}}timeout_seconds={{timeoutSeconds}},{{/if}}
                 ),
                 {{/if}}
+                {{#if hasConfigBundle}}
+                ConfigBundleHook(),
+                {{/if}}
             ],
         )
-    return _agent
+        return cache[session_id]
+    return get_or_create_agent
+get_or_create_agent = agent_factory()
 {{/unless}}
 {{/if}}
-{{/if}}
 
 
 def _extract_prompt(payload: dict):
@@ -585,11 +585,8 @@ async def invoke(payload, context):
         hooks=[ConfigBundleHook()],{{/if}}
     )
 {{else}}
-{{#if hasConfigBundle}}
-    agent = create_agent({{#if hasSkillsFetcher}}_skill_plugins{{/if}})
-{{else}}
-    agent = get_or_create_agent({{#if hasSkillsFetcher}}_skill_plugins{{/if}})
-{{/if}}
+    session_id = getattr(context, 'session_id', 'default-session')
+    agent = get_or_create_agent(session_id{{#if hasSkillsFetcher}}, _skill_plugins{{/if}})
 {{/if}}
 {{/if}}
 

package/dist/assets/python/http/strands/capabilities/memory/session.py

@@ -28,7 +28,7 @@ def get_memory_session_manager(session_id: Optional[str], actor_id: str) -> Opti
         f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
 {{/if}}
 {{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
-        f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
 {{/if}}
     }
 {{/if}}

package/dist/assets/typescript/http/strands/base/main.ts

@@ -53,18 +53,35 @@ async function getOrCreateAgent(sessionId: string, actorId: string): Promise<Age
   return agent;
 }
 {{else}}
-let cachedAgent: Agent | null = null;
+const AGENT_CACHE_LIMIT = 128;
 
-async function getOrCreateAgent(): Promise<Agent> {
-  if (!cachedAgent) {
-    const model = await loadModel();
-    cachedAgent = new Agent({
-      model,
-      systemPrompt: SYSTEM_PROMPT,
-      tools,
-    });
+// Reuses one Agent per sessionId so each session keeps its own in-process
+// conversation history (best-effort; resets on cold start). A Map preserves
+// insertion order, so it doubles as an LRU bounded to 128 sessions — a local
+// dev process serving many sessions cannot leak history between them or grow
+// without bound. On AgentCore Runtime each microVM serves a single session, so
+// this holds one entry. For durable history, attach memory.
+const agentCache = new Map<string, Agent>();
+
+async function getOrCreateAgent(sessionId: string): Promise<Agent> {
+  const existing = agentCache.get(sessionId);
+  if (existing) {
+    agentCache.delete(sessionId);
+    agentCache.set(sessionId, existing);
+    return existing;
+  }
+  if (agentCache.size >= AGENT_CACHE_LIMIT) {
+    const oldest = agentCache.keys().next().value;
+    if (oldest !== undefined) agentCache.delete(oldest);
   }
-  return cachedAgent;
+  const model = await loadModel();
+  const agent = new Agent({
+    model,
+    systemPrompt: SYSTEM_PROMPT,
+    tools,
+  });
+  agentCache.set(sessionId, agent);
+  return agent;
 }
 {{/if}}
 
@@ -76,7 +93,8 @@ const app = new BedrockAgentCoreApp({
       const actorId = getActorId(payload, context);
       const agent = await getOrCreateAgent(sessionId, actorId);
       {{else}}
-      const agent = await getOrCreateAgent();
+      const sessionId = context?.sessionId ?? 'default-session';
+      const agent = await getOrCreateAgent(sessionId);
       {{/if}}
 
       {{#if hasMemory}}
@@ -97,14 +115,26 @@ const app = new BedrockAgentCoreApp({
         await agent.memoryManager?.flush();
       }
       {{else}}
-      for await (const event of agent.stream(payload.prompt ?? '')) {
-        if (
-          event.type === 'modelStreamUpdateEvent' &&
-          event.event?.type === 'modelContentBlockDeltaEvent' &&
-          event.event.delta?.type === 'textDelta'
-        ) {
-          yield { data: event.event.delta.text };
+      // Snapshot history before streaming so a failed turn can be rolled back.
+      // Agent.stream() appends the user message before invoking the model; on a
+      // mid-stream error that user turn would otherwise linger in the cached
+      // agent, and the next turn for this session would send consecutive user
+      // messages (rejected by providers that require strict role alternation,
+      // e.g. Anthropic). Restoring on error keeps the session reusable.
+      const snapshot = agent.takeSnapshot({ include: ['messages'] });
+      try {
+        for await (const event of agent.stream(payload.prompt ?? '')) {
+          if (
+            event.type === 'modelStreamUpdateEvent' &&
+            event.event?.type === 'modelContentBlockDeltaEvent' &&
+            event.event.delta?.type === 'textDelta'
+          ) {
+            yield { data: event.event.delta.text };
+          }
         }
+      } catch (error) {
+        agent.loadSnapshot(snapshot);
+        throw error;
       }
       {{/if}}
     },