agentcore-cli 0.31.1__py3-none-any.whl

agentcore/assets/python/mcp/standalone/base/main.py

@@ -0,0 +1,83 @@
+{{#if needsOs}}
+import os
+{{/if}}
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("{{ name }}", host="0.0.0.0", stateless_http=True)
+
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
+
+def _safe_resolve(path: str) -> str:
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
+    return resolved
+
+@mcp.tool()
+def file_read(path: str) -> str:
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+@mcp.tool()
+def file_write(path: str, content: str) -> str:
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+@mcp.tool()
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
+    try:
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{path}': {e.strerror}"
+
+{{/if}}
+
+
+@mcp.tool()
+def add_numbers(a: int, b: int) -> int:
+    """Add two numbers together"""
+    return a + b
+
+
+@mcp.tool()
+def multiply_numbers(a: int, b: int) -> int:
+    """Multiply two numbers together"""
+    return a * b
+
+
+@mcp.tool()
+def greet_user(name: str) -> str:
+    """Greet a user by name"""
+    return f"Hello, {name}! Nice to meet you."
+
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")

agentcore/assets/python/mcp/standalone/base/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore MCP Server"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp >= 1.28.1, < 2.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

agentcore/assets/typescript/http/strands/base/README.md

@@ -0,0 +1,42 @@
+This is a project generated by the AgentCore CLI!
+
+# Layout
+
+The generated application code lives at the agent root directory. At the root, there is a `.gitignore` file, an
+`agentcore/` folder which represents the configurations and state associated with this project. Other `agentcore`
+commands like `deploy`, `dev`, and `invoke` rely on the configuration stored here.
+
+## Agent Root
+
+The main entrypoint to your app is defined in `main.ts`. Using the AgentCore SDK `BedrockAgentCoreApp`, this file
+defines an HTTP server that streams tokens from your chosen Agent framework SDK.
+
+`model/load.ts` instantiates your chosen model provider.
+
+## Input Validation
+
+The generated Zod request schema keeps plain prompts typed as strings before forwarding them to Strands. Retain this
+validation when extending the request shape, and pass only prompt text to the agent.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+{{#if hasIdentity}}| `{{identityProviders.[0].envVarName}}` | Yes | {{modelProvider}} API key (local) or Identity provider name (deployed) |
+{{/if}}| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, `node_modules/` is already populated with dependencies.
+
+`agentcore dev` will start a local server using `npx tsx watch main.ts` for hot reload. The port is logged to the terminal (default `8080`).
+
+In a new terminal, you can invoke that server with:
+
+`agentcore invoke --dev "What can you do"`
+
+# Deployment
+
+After providing credentials, `agentcore deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Use `agentcore invoke` to invoke your deployed agent.

agentcore/assets/typescript/http/strands/base/gitignore.template

@@ -0,0 +1,22 @@
+# Environment variables
+.env
+.env.*
+
+# Node
+node_modules/
+dist/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

agentcore/assets/typescript/http/strands/base/main.ts

@@ -0,0 +1,149 @@
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { Agent, McpClient, tool, type ToolList } from '@strands-agents/sdk';
+import { z } from 'zod';
+import { loadModel } from './model/load.js';
+import { getStreamableHttpMcpClient } from './mcp_client/client.js';
+{{#if hasMemory}}
+import { getActorId, getOrCreateMemoryManager } from './memory/memory.js';
+{{/if}}
+
+// Define a collection of MCP clients (filter out anything that failed to initialize)
+const mcpClients: McpClient[] = [getStreamableHttpMcpClient()].filter(
+  (client): client is McpClient => Boolean(client)
+);
+
+// Define a collection of tools used by the model
+const tools: ToolList = [];
+
+// Define a simple function tool — the Zod schema gives us type inference and runtime validation for free
+const addNumbers = tool({
+  name: 'add_numbers',
+  description: 'Return the sum of two numbers',
+  inputSchema: z.object({
+    a: z.number(),
+    b: z.number(),
+  }),
+  callback: async ({ a, b }) => a + b,
+});
+tools.push(addNumbers);
+
+// Add MCP clients to tools
+tools.push(...mcpClients);
+
+const SYSTEM_PROMPT = `
+You are a helpful assistant. Use tools when appropriate.
+`;
+
+const requestSchema = z.object({
+  prompt: z.string().default(''),
+});
+
+{{#if hasMemory}}
+const agentCache = new Map<string, Agent>();
+
+async function getOrCreateAgent(sessionId: string, actorId: string): Promise<Agent> {
+  const key = `${actorId}:${sessionId}`;
+  let agent = agentCache.get(key);
+  if (agent) return agent;
+
+  const model = await loadModel();
+  agent = new Agent({
+    model,
+    systemPrompt: SYSTEM_PROMPT,
+    tools,
+    memoryManager: getOrCreateMemoryManager(sessionId, actorId) ?? undefined,
+  });
+  agentCache.set(key, agent);
+  return agent;
+}
+{{else}}
+const AGENT_CACHE_LIMIT = 128;
+
+// 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);
+  }
+  const model = await loadModel();
+  const agent = new Agent({
+    model,
+    systemPrompt: SYSTEM_PROMPT,
+    tools,
+  });
+  agentCache.set(sessionId, agent);
+  return agent;
+}
+{{/if}}
+
+const app = new BedrockAgentCoreApp({
+  invocationHandler: {
+    requestSchema,
+    async *process(payload, context) {
+      {{#if hasMemory}}
+      const sessionId = context?.sessionId ?? 'default-session';
+      const actorId = getActorId(payload, context);
+      const agent = await getOrCreateAgent(sessionId, actorId);
+      {{else}}
+      const sessionId = context?.sessionId ?? 'default-session';
+      const agent = await getOrCreateAgent(sessionId);
+      {{/if}}
+
+      {{#if hasMemory}}
+      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 };
+          }
+        }
+      } finally {
+        // Drain in-flight createEvent calls before the runtime can reclaim
+        // the session microVM. flush() is the durability mechanism — without
+        // it, an idle reclamation can lose the tail of the conversation.
+        await agent.memoryManager?.flush();
+      }
+      {{else}}
+      // 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}}
+    },
+  },
+});
+
+app.run({ port: parseInt(process.env.PORT ?? '8080') });

agentcore/assets/typescript/http/strands/base/mcp_client/client.ts

@@ -0,0 +1,11 @@
+import { McpClient } from '@strands-agents/sdk';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+// ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
+const EXAMPLE_MCP_ENDPOINT = 'https://mcp.exa.ai/mcp';
+
+export function getStreamableHttpMcpClient(): McpClient {
+  // to use an MCP server that supports bearer authentication, add a headers() callback to requestInit
+  const transport = new StreamableHTTPClientTransport(new URL(EXAMPLE_MCP_ENDPOINT));
+  return new McpClient({ transport });
+}

agentcore/assets/typescript/http/strands/base/model/load.ts

@@ -0,0 +1,102 @@
+{{#if (eq modelProvider "Bedrock")}}
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+
+export function loadModel(): BedrockModel {
+  return new BedrockModel({ modelId: 'global.anthropic.claude-sonnet-4-5-20250929-v1:0' });
+}
+{{/if}}
+{{#if (eq modelProvider "Anthropic")}}
+import { AnthropicModel } from '@strands-agents/sdk/models/anthropic';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or ANTHROPIC_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: AnthropicModel | undefined;
+
+export async function loadModel(): Promise<AnthropicModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new AnthropicModel({
+      apiKey,
+      modelId: 'claude-sonnet-4-5-20250929',
+      maxTokens: 5000,
+    });
+  }
+  return _model;
+}
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+import { OpenAIModel } from '@strands-agents/sdk/models/openai';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or OPENAI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: OpenAIModel | undefined;
+
+export async function loadModel(): Promise<OpenAIModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new OpenAIModel({
+      api: 'chat',
+      apiKey,
+      modelId: 'gpt-4.1',
+    });
+  }
+  return _model;
+}
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+import { GoogleModel } from '@strands-agents/sdk/models/google';
+import { withApiKey } from 'bedrock-agentcore/identity';
+
+const IDENTITY_PROVIDER_NAME = '{{identityProviders.[0].name}}';
+const IDENTITY_ENV_VAR = '{{identityProviders.[0].envVarName}}';
+
+async function getApiKey(): Promise<string> {
+  if (process.env.LOCAL_DEV === '1') {
+    const apiKey = process.env[IDENTITY_ENV_VAR] ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error(`${IDENTITY_ENV_VAR} or GEMINI_API_KEY not found. Add your key to agentcore/.env.local`);
+    }
+    return apiKey;
+  }
+  return withApiKey({ providerName: IDENTITY_PROVIDER_NAME })(async (apiKey: string) => apiKey)();
+}
+
+let _model: GoogleModel | undefined;
+
+export async function loadModel(): Promise<GoogleModel> {
+  if (!_model) {
+    const apiKey = await getApiKey();
+    _model = new GoogleModel({
+      apiKey,
+      modelId: 'gemini-2.5-flash',
+    });
+  }
+  return _model;
+}
+{{/if}}

agentcore/assets/typescript/http/strands/base/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "description": "AgentCore Runtime Application using Strands TypeScript SDK",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/main.js",
+    "dev": "tsx watch main.ts"
+  },
+  "dependencies": {
+    {{#if (eq modelProvider "Anthropic")}}
+    "@anthropic-ai/sdk": "^0.71.2",
+    {{/if}}
+    {{#if (eq modelProvider "OpenAI")}}
+    "openai": "^6.7.0",
+    {{/if}}
+    {{#if (eq modelProvider "Gemini")}}
+    "@google/genai": "^1.40.0",
+    {{/if}}
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@opentelemetry/api": "^1.9.0",
+    "@strands-agents/sdk": "^1.5.0",
+    "bedrock-agentcore": "^0.3.0",
+    "tsx": "^4.19.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "overrides": {
+    "bedrock-agentcore": {
+      "@strands-agents/sdk": "$@strands-agents/sdk"
+    }
+  }
+}

agentcore/assets/typescript/http/strands/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

agentcore/assets/typescript/http/strands/capabilities/memory/memory.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { MemoryManager } from '@strands-agents/sdk';
+import { createAgentCoreMemoryStores } from 'bedrock-agentcore/experimental/memory/strands';
+
+const MEMORY_ID = process.env.{{memoryProviders.[0].envVarName}};
+
+const CUSTOM_ACTOR_ID_HEADER = 'x-amzn-bedrock-agentcore-runtime-custom-actor-id';
+
+export function getActorId(payload: any, context: any): string {
+  const raw =
+    context?.headers?.[CUSTOM_ACTOR_ID_HEADER] ||
+    payload?.userId ||
+    context?.sessionId;
+  return typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : randomUUID();
+}
+
+const memoryManagerCache = new Map<string, MemoryManager>();
+
+export function getOrCreateMemoryManager(sessionId: string, actorId: string): MemoryManager | null {
+  if (!MEMORY_ID) return null;
+
+  const key = `${actorId}:${sessionId}`;
+  let manager = memoryManagerCache.get(key);
+  if (manager) return manager;
+
+  const stores = createAgentCoreMemoryStores({
+    memoryId: MEMORY_ID,
+    actorId,
+    sessionId,
+    namespaces: [
+{{#if (includes memoryProviders.[0].strategies "SEMANTIC")}}
+      { namespace: '/users/{actorId}/facts' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "USER_PREFERENCE")}}
+      { namespace: '/users/{actorId}/preferences' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "EPISODIC")}}
+      { namespace: '/episodes/{actorId}/{sessionId}' },
+{{/if}}
+{{#if (includes memoryProviders.[0].strategies "SUMMARIZATION")}}
+      { namespace: '/summaries/{actorId}/{sessionId}' },
+{{/if}}
+    ],
+    // readMode defaults to 'per-namespace' (one retrieve call per namespace).
+    // Switch to 'subtree' to consolidate to a single hierarchical recall call.
+    extraction: true,
+  });
+
+  manager = new MemoryManager({ stores });
+  memoryManagerCache.set(key, manager);
+  return manager;
+}

agentcore/assets/typescript/http/vercelai/base/README.md

@@ -0,0 +1,42 @@
+This is a project generated by the AgentCore CLI!
+
+# Layout
+
+The generated application code lives at the agent root directory. At the root, there is a `.gitignore` file, an
+`agentcore/` folder which represents the configurations and state associated with this project. Other `agentcore`
+commands like `deploy`, `dev`, and `invoke` rely on the configuration stored here.
+
+## Agent Root
+
+The main entrypoint to your app is defined in `main.ts`. Using the AgentCore SDK `BedrockAgentCoreApp`, this file
+defines an HTTP app that streams tokens using the Vercel AI SDK's `streamText` API.
+
+`model/load.ts` instantiates your chosen model provider.
+
+## Input Validation
+
+The generated Zod request schema keeps plain prompts typed as strings before forwarding them to the agent framework.
+Retain this validation when extending the request shape, and pass only prompt text to the agent.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+{{#if hasIdentity}}| `{{identityProviders.[0].envVarName}}` | Yes | {{modelProvider}} API key (local) or Identity provider name (deployed) |
+{{/if}}| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, `node_modules/` is already populated with dependencies.
+
+`agentcore dev` will start a local server using `npx tsx watch main.ts` for hot reload. The port is logged to the terminal (default `8080`).
+
+In a new terminal, you can invoke that server with:
+
+`agentcore invoke --dev "What can you do"`
+
+# Deployment
+
+After providing credentials, `agentcore deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Use `agentcore invoke` to invoke your deployed agent.

agentcore/assets/typescript/http/vercelai/base/gitignore.template

@@ -0,0 +1,22 @@
+# Environment variables
+.env
+.env.*
+
+# Node
+node_modules/
+dist/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

agentcore/assets/typescript/http/vercelai/base/main.ts

@@ -0,0 +1,70 @@
+import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
+import { streamText, type ModelMessage } from 'ai';
+import { z } from 'zod';
+import { loadModel } from './model/load.js';
+
+const SYSTEM_PROMPT = `You are a helpful assistant.`;
+
+const requestSchema = z.object({
+  prompt: z.string().default(''),
+});
+
+const HISTORY_LIMIT = 128;
+
+// Keeps one message history per sessionId so each session remembers its own
+// turns (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, persist messages to an external store.
+const histories = new Map<string, ModelMessage[]>();
+
+function getHistory(sessionId: string): ModelMessage[] {
+  const existing = histories.get(sessionId);
+  if (existing) {
+    histories.delete(sessionId);
+    histories.set(sessionId, existing);
+    return existing;
+  }
+  if (histories.size >= HISTORY_LIMIT) {
+    const oldest = histories.keys().next().value;
+    if (oldest !== undefined) histories.delete(oldest);
+  }
+  const fresh: ModelMessage[] = [];
+  histories.set(sessionId, fresh);
+  return fresh;
+}
+
+const app = new BedrockAgentCoreApp({
+  invocationHandler: {
+    requestSchema,
+    async *process(payload, context) {
+      const sessionId = context?.sessionId ?? 'default-session';
+      const history = getHistory(sessionId);
+      const userMessage: ModelMessage = { role: 'user', content: payload.prompt };
+
+      const model = await loadModel();
+      const result = streamText({
+        model,
+        system: SYSTEM_PROMPT,
+        messages: [...history, userMessage],
+      });
+
+      let assistant = '';
+      for await (const chunk of result.textStream) {
+        assistant += chunk;
+        yield { data: chunk };
+      }
+
+      // Commit the exchange to history only after a non-empty reply. On a failed
+      // or empty stream the turn is dropped instead of leaving a dangling user
+      // (or empty assistant) message — consecutive same-role or empty-content
+      // messages would otherwise be rejected on the next turn for this session.
+      if (assistant.length > 0) {
+        history.push(userMessage, { role: 'assistant', content: assistant });
+      }
+    },
+  },
+});
+
+app.run({ port: parseInt(process.env.PORT ?? '8080') });