@ag-ui/aws-strands 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# AWS Strands Integration for AG-UI (TypeScript)
+
+This package exposes a lightweight wrapper that lets any `@strands-agents/sdk` `Agent` speak the AG-UI protocol. It mirrors the developer experience of the other integrations: give us a Strands agent instance, plug it into `StrandsAgent`, and wire it to Express via `createStrandsApp` (or `addStrandsExpressEndpoint`).
+
+## Prerequisites
+
+- Node.js 18+
+- `pnpm` (recommended) or `npm`
+- A Strands-compatible model key (e.g., AWS credentials for Bedrock, `OPENAI_API_KEY` for OpenAI)
+
+## Quick Start
+
+The `examples/` package ships a "dojo" server that mounts every demo on a
+single port, plus seven standalone servers — one per feature — that you can
+run independently.
+
+```bash
+# from the repo root
+pnpm install
+pnpm --filter @ag-ui/aws-strands build
+
+cd integrations/aws-strands/typescript/examples
+pnpm dojo                       # all examples at http://localhost:8022
+```
+
+Or run any single example on its own port (default `8000`):
+
+```bash
+pnpm agentic-chat
+pnpm agentic-chat-reasoning
+pnpm agentic-chat-multimodal
+pnpm backend-tool-rendering
+pnpm shared-state
+pnpm agentic-generative-ui
+pnpm human-in-the-loop
+```
+
+The dojo exposes:
+
+| Route                      | Description                                                              |
+| -------------------------- | ------------------------------------------------------------------------ |
+| `/agentic-chat`            | Baseline chat; frontend tools auto-registered from `RunAgentInput.tools` |
+| `/agentic-chat-reasoning`  | Reasoning / thinking event streaming                                     |
+| `/agentic-chat-multimodal` | Multimodal image / document analysis                                     |
+| `/backend-tool-rendering`  | Backend-executed tools (`get_weather`, `render_chart`)                   |
+| `/shared-state`            | Shared recipe state (`stateFromArgs`)                                    |
+| `/agentic-generative-ui`   | Async-generator tool streams `STATE_SNAPSHOT`s + `PredictState`          |
+| `/human-in-the-loop`       | Frontend proxy tool with halt-after-call                                 |
+
+Each standalone file under `examples/server/api/*.ts` follows the same pattern: build a Strands `Agent`, wrap it in a `StrandsAgent`, hand it to `createStrandsApp`, listen.
+
+## Architecture Overview
+
+The integration has three main layers:
+
+- **StrandsAgent** – wraps `Agent.stream()` from `@strands-agents/sdk`. It translates Strands streaming events into AG-UI events (text chunks, tool calls, PredictState, snapshots, reasoning/thinking, multi-agent steps, etc.).
+- **Configuration** – `StrandsAgentConfig` + `ToolBehavior` + `PredictStateMapping` let you describe tool-specific quirks declaratively (skip message snapshots, emit state, stream args, etc.).
+- **Transport helpers** – `createStrandsApp` and `addStrandsExpressEndpoint` expose the agent via SSE. They are thin shells over the shared `@ag-ui/encoder` `EventEncoder`. Imported from `@ag-ui/aws-strands/server` — kept off the main entry so client-side bundlers (Next.js, Vite) don't pull Express into the browser graph.
+
+See [../ARCHITECTURE.md](../ARCHITECTURE.md) for diagrams and a deeper dive.
+
+## Key Files
+
+| File                       | Description                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `src/agent.ts`             | Core wrapper translating Strands streams into AG-UI events                      |
+| `src/config.ts`            | Config primitives (`StrandsAgentConfig`, `ToolBehavior`, `PredictStateMapping`) |
+| `src/server.ts`            | `createStrandsApp` + Express transport (subpath: `@ag-ui/aws-strands/server`)   |
+| `src/endpoint.ts`          | Express endpoint helpers (used by `server.ts`)                                  |
+| `src/utils.ts`             | Multimodal content conversion                                                   |
+| `src/client-proxy-tool.ts` | Dynamic frontend tool registration/deregistration                               |
+| `examples/server/api/*.ts` | Ready-to-run demo apps                                                          |
+
+## Amazon Bedrock AgentCore Considerations
+
+If you are planning to deploy your agent into Amazon Bedrock AgentCore (AC), please note that AC expects the following:
+
+- The server is running on port 8080.
+- The path `/invocations - POST` is implemented and can be used for interacting with the agent.
+- The path `/ping - GET` is implemented and can be used for verifying that the agent is operational and ready to handle requests.
+
+To implement the paths mentioned above, you can use the helper function `createStrandsApp` and pass the agent interaction path and the ping path as shown below:
+
+```ts
+const app = await createStrandsApp(aguiAgent, {
+  path: "/invocations",
+  pingPath: "/ping",
+});
+app.listen(8080);
+```
+
+You can also use the helper functions `addStrandsExpressEndpoint` and `addPing` for adding the mentioned paths to an Express app that you are creating separately:
+
+```ts
+import express from "express";
+import cors from "cors";
+import { addStrandsExpressEndpoint, addPing } from "@ag-ui/aws-strands/server";
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: "50mb" }));
+addStrandsExpressEndpoint(app, aguiAgent, { path: "/invocations" });
+addPing(app, "/ping");
+app.listen(8080);
+```
+
+Requests to the AC endpoint must be authenticated. You can configure your agent runtime to accept JWT bearer tokens (via Amazon Cognito) or use SigV4. See [Set up authentication](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html) in the AgentCore documentation.
+
+For details on how AgentCore handles AG-UI requests, event streaming, and error formatting, see the [AG-UI protocol contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui-protocol-contract.html).
+
+To deploy, use the [AgentCore Starter Toolkit](https://github.com/awslabs/bedrock-agentcore-starter-toolkit):
+
+```bash
+pip install bedrock-agentcore-starter-toolkit
+agentcore configure -e my_agui_server.ts --protocol AGUI
+agentcore deploy
+```
+
+For the complete deployment walkthrough, see [Deploy AG-UI servers in AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html).
+
+## Supported AG-UI Events
+
+The integration supports the following AG-UI event families:
+
+- **Lifecycle**: `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
+- **Text streaming**: `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` (optionally collapsed into `TEXT_MESSAGE_CHUNK` via `StrandsAgentConfig.emitChunkEvents`)
+- **Reasoning**: `REASONING_*` events for models with extended thinking (`REASONING_MESSAGE_CHUNK` when `emitChunkEvents` is on)
+- **Tool calls**: `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT` (or `TOOL_CALL_CHUNK` with `emitChunkEvents`)
+- **State management**: `STATE_SNAPSHOT`
+- **Multi-agent**: `STEP_STARTED`, `STEP_FINISHED`, and `MultiAgentHandoff` custom events
+- **Generative UI**: `PredictState` custom events for optimistic UI updates
+- **Multimodal**: Image, document, and video content in user messages (converted to Strands ContentBlock format)
+
+The adapter advertises its full event / feature matrix at GET
+`/capabilities` (enabled by default; override via `createStrandsApp({ capabilitiesPath, capabilities })` or mount manually with `addCapabilities(app, path, overrides)`).
+
+## Passing tools to the Agent
+
+The adapter clones the template `Agent`'s `tools` array onto every per-thread
+clone. That means whatever the Strands SDK has resolved into `agent.tools` at
+construction time is what the model sees — including for `McpClient`
+instances. If you pass an **unconnected** `McpClient` directly, its tools
+won't be in the resolved list and the model can't call them.
+
+Connect MCP clients first and spread the resolved tools into `tools`:
+
+```ts
+import { Agent } from "@strands-agents/sdk";
+import { McpClient } from "@strands-agents/sdk/mcp";
+
+const spellbook = new McpClient({
+  /* transport config */
+});
+await spellbook.connect();
+const mcpTools = await spellbook.listTools();
+
+const agent = new Agent({
+  model: "anthropic.claude-sonnet-4-5-20250929-v1:0",
+  tools: [...mcpTools, myLocalTool],
+});
+
+const aguiAgent = new StrandsAgent({ agent });
+```
+
+The adapter logs a warning at construction time if it spots an entry in
+`tools` that looks like an unconnected client (has a `.connect()` method but
+no `.name`).
+
+## Human-in-the-loop interrupts
+
+Two complementary patterns are supported:
+
+- **Frontend tools.** The `/human-in-the-loop` example declares
+  `generate_task_steps` on the frontend via `useHumanInTheLoop` — the adapter
+  auto-registers it as a proxy tool, halts the run after the proxy resolves,
+  and hands control back to the UI for approval.
+- **Native Strands interrupts (SDK 1.1.0+).** Backend hooks and tools can call
+  `event.interrupt(...)` / `context.interrupt(...)` to raise a
+  `stopReason: 'interrupt'`. The adapter forwards the outstanding interrupts
+  on `RUN_FINISHED`:
+
+  ```json
+  {
+    "type": "RUN_FINISHED",
+    "outcome": {
+      "type": "interrupt",
+      "interrupts": [
+        { "id": "...", "reason": "...", "metadata": { "strandsName": "..." } }
+      ]
+    }
+  }
+  ```
+
+  The next `RunAgentInput` carries `resume[]` entries keyed by those `id`s.
+  The adapter converts each entry into a Strands `InterruptResponseContent`
+  (forwarding `payload` for `resolved` and `{ status: "cancelled" }` for
+  `cancelled`) and hands them straight to `agent.stream(...)`. Unknown
+  `interruptId`s still short-circuit with
+  `RUN_ERROR { code: "UNKNOWN_INTERRUPT" }` per
+  [interrupts.mdx rule 4](https://docs.ag-ui.com/concepts/interrupts).
+
+## Reasoning / extended thinking
+
+The `/agentic-chat-reasoning` demo only emits `REASONING_*` events when the
+underlying Strands model is configured with thinking / reasoning params. The
+default `BedrockModel(...)` without `additional_request_fields` returns plain
+text; for Claude extended thinking, configure the model like so:
+
+```ts
+import { BedrockModel } from "@strands-agents/sdk/models/bedrock";
+
+const model = new BedrockModel({
+  modelId: "global.anthropic.claude-sonnet-4-6",
+  additionalRequestFields: {
+    thinking: { type: "enabled", budget_tokens: 5000 },
+  },
+});
+```
+
+## Install
+
+```bash
+pnpm add @ag-ui/aws-strands @strands-agents/sdk @ag-ui/core @ag-ui/encoder
+# Server-side helpers (createStrandsApp / addStrandsExpressEndpoint) require express + cors:
+pnpm add express cors
+pnpm add -D @types/express @types/cors
+# @modelcontextprotocol/sdk is loaded unconditionally by @strands-agents/sdk
+# — required at runtime even for agents that don't use MCP:
+pnpm add @modelcontextprotocol/sdk
+```
+
+## Server: Expose a Strands Agent via AG-UI
+
+```ts
+import { Agent } from "@strands-agents/sdk";
+import { StrandsAgent } from "@ag-ui/aws-strands";
+import { createStrandsApp } from "@ag-ui/aws-strands/server";
+
+// `model` accepts either a Bedrock model ID string or a constructed
+// Model instance (e.g. BedrockModel / AnthropicModel / OpenAIResponsesModel).
+// Omitting it uses Strands' current Bedrock default.
+const strandsAgent = new Agent({
+  systemPrompt: "You are a helpful assistant.",
+  tools: [],
+});
+
+const aguiAgent = new StrandsAgent({
+  agent: strandsAgent,
+  name: "MyAgent",
+  description: "A Strands agent exposed via AG-UI",
+});
+
+const app = await createStrandsApp(aguiAgent, { path: "/invocations" });
+app.listen(8000);
+```
+
+## Configuration
+
+```ts
+import {
+  StrandsAgent,
+  type StrandsAgentConfig,
+  type ToolBehavior,
+} from "@ag-ui/aws-strands";
+
+const config: StrandsAgentConfig = {
+  toolBehaviors: {
+    set_recipe: {
+      stateFromArgs: async (ctx) => ({ recipe: ctx.toolInput }),
+      predictState: [
+        { stateKey: "recipe", tool: "set_recipe", toolArgument: "data" },
+      ],
+    },
+    render_chart: {
+      stopStreamingAfterResult: true,
+    },
+  },
+  sessionManagerProvider: async (input) => {
+    // Optional: vend a SessionManager per-thread from your own state store.
+    return undefined;
+  },
+  stateContextBuilder: (input, prompt) => {
+    // Optional: decorate the outgoing prompt with any server-side state.
+    return prompt;
+  },
+};
+
+const agent = new StrandsAgent({ agent: strandsAgent, name: "x", config });
+```
+
+## Low-Level Transport
+
+If you have an existing Express app, mount the endpoint directly instead of
+using `createStrandsApp`:
+
+```ts
+import express from "express";
+import cors from "cors";
+import { addStrandsExpressEndpoint, addPing } from "@ag-ui/aws-strands/server";
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: "50mb" }));
+addStrandsExpressEndpoint(app, aguiAgent, { path: "/invocations" });
+addPing(app, "/ping");
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```

package/dist/agent-B2EYZvns.d.ts

@@ -0,0 +1,310 @@
+import { Agent, AgentConfig, Plugin, SessionManager } from "@strands-agents/sdk";
+import { BaseEvent, Message, RunAgentInput } from "@ag-ui/core";
+
+//#region src/logger.d.ts
+/**
+ * Injectable logger for the AWS Strands adapter.
+ *
+ * The Python sibling uses `logging.getLogger(__name__)` and emits warnings /
+ * errors to stderr at `WARNING` and up, with `DEBUG` opt-in. This module
+ * mirrors that behaviour: by default the adapter is silent below `warn`,
+ * surfaces warnings via `console.warn`, and lets callers redirect output by
+ * passing a `Logger` in `StrandsAgentConfig.logger`.
+ *
+ * Signature `(message: string, ...args: unknown[])` intentionally matches the
+ * `console` method shape so existing `vi.spyOn(console, "warn")` test
+ * scaffolding keeps working with the default logger in place, and so wiring
+ * in pino / winston / bunyan is a one-liner.
+ */
+interface Logger {
+  debug(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+//#endregion
+//#region src/config.d.ts
+type StatePayload = Record<string, unknown>;
+/**
+ * Free-form key/value map carried on `RunAgentInput.context[]` and
+ * `RunAgentInput.forwardedProps`. Exposed on hook contexts so behaviors can
+ * react to e.g. per-request auth tokens or locale without re-parsing
+ * `inputData`.
+ *
+ * TypeScript-only: the Python adapter passes `input_data` directly to hooks
+ * and callers pull these fields off themselves.
+ */
+interface ToolCallContextExtras {
+  /**
+   * `RunAgentInput.context[]` flattened by `description` → `value`.
+   * Duplicates: later entries overwrite earlier ones. Keys `__proto__`,
+   * `constructor`, and `prototype` are dropped to prevent prototype-pollution
+   * surprises in downstream `Object.assign(target, ctx.context)` usage.
+   */
+  context: Readonly<Record<string, string>>;
+  /**
+   * `RunAgentInput.forwardedProps` as an opaque record. Shape is defined by
+   * the frontend; the adapter does not introspect it.
+   */
+  forwardedProps: Readonly<Record<string, unknown>>;
+}
+/** Context passed to tool call hooks. */
+interface ToolCallContext extends ToolCallContextExtras {
+  inputData: RunAgentInput;
+  toolName: string;
+  toolUseId: string;
+  toolInput: unknown;
+  argsStr: string;
+}
+/** Context passed to tool result hooks. */
+interface ToolResultContext extends ToolCallContext {
+  resultData: unknown;
+  messageId: string;
+}
+type MaybePromise<T> = T | Promise<T>;
+type ArgsStreamer = (ctx: ToolCallContext) => AsyncIterable<string>;
+type StateFromArgs = (ctx: ToolCallContext) => MaybePromise<StatePayload | null | undefined>;
+type StateFromResult = (ctx: ToolResultContext) => MaybePromise<StatePayload | null | undefined>;
+type CustomResultHandler = (ctx: ToolResultContext) => AsyncIterable<BaseEvent | null | undefined>;
+type StateContextBuilder = (inputData: RunAgentInput, prompt: string, /** Convenience view over `inputData.context[]` + `inputData.forwardedProps`. */
+
+extras?: ToolCallContextExtras) => string;
+type SessionManagerProvider = (inputData: RunAgentInput) => MaybePromise<SessionManager | null | undefined>;
+/** Declarative mapping telling the UI how to predict state from tool args. */
+interface PredictStateMapping {
+  stateKey: string;
+  tool: string;
+  toolArgument: string;
+}
+/** Declarative configuration for tool-specific handling. */
+interface ToolBehavior {
+  /**
+   * Suppress the `MessagesSnapshotEvent` that would normally follow this
+   * tool's `TOOL_CALL_END` / `TOOL_CALL_RESULT`. Useful when
+   * `customResultHandler` emits its own snapshot.
+   */
+  skipMessagesSnapshot?: boolean;
+  /** Keep the stream alive after emitting a frontend tool call. */
+  continueAfterFrontendCall?: boolean;
+  /** Close text streaming and halt the agent after a tool result arrives. */
+  stopStreamingAfterResult?: boolean;
+  /** `PredictStateMapping[]` that inform the UI how to project tool args into state. */
+  predictState?: PredictStateMapping | Iterable<PredictStateMapping>;
+  /** Async generator controlling how tool arguments are streamed to the frontend. */
+  argsStreamer?: ArgsStreamer;
+  /** Derive a `StateSnapshotEvent` from the tool call arguments. */
+  stateFromArgs?: StateFromArgs;
+  /** Derive a `StateSnapshotEvent` from the tool result. */
+  stateFromResult?: StateFromResult;
+  /** Async iterator that can emit arbitrary AG-UI events in response to a result. */
+  customResultHandler?: CustomResultHandler;
+}
+/** Top-level configuration for the Strands agent adapter. */
+interface StrandsAgentConfig {
+  /** Per-tool overrides keyed by the Strands tool name. */
+  toolBehaviors?: Record<string, ToolBehavior>;
+  /** Callable that enriches the outgoing prompt with the current shared state. */
+  stateContextBuilder?: StateContextBuilder;
+  /**
+   * Optional factory for creating per-thread `SessionManager` instances.
+   *
+   * Called exactly once per `threadId` the first time that thread is seen.
+   * Subsequent requests on the same thread reuse the cached agent (and its
+   * SessionManager). If the provider depends on per-request data (e.g. auth
+   * tokens in `forwardedProps`), only the first request's data is used.
+   *
+   * If the provider throws, the run yields `RUN_ERROR` and returns early;
+   * the thread is NOT cached so the provider will be retried on the next
+   * request.
+   *
+   * If the provider returns `null` or `undefined`, a warning is logged and
+   * the agent runs without session persistence; the thread IS cached.
+   */
+  sessionManagerProvider?: SessionManagerProvider;
+  /**
+   * Emit `MessagesSnapshotEvent` at lifecycle boundaries (after the initial
+   * `STATE_SNAPSHOT`, after each `TOOL_CALL_END` / `TOOL_CALL_RESULT`, and
+   * after each terminal `TEXT_MESSAGE_END`).
+   *
+   * Required for CopilotKit v2 frontends; set to `false` for raw AG-UI
+   * consumers that reconstruct messages themselves. Default: `true`.
+   */
+  emitMessagesSnapshot?: boolean;
+  /**
+   * When `true` (and the cached Strands agent has no `sessionManager`),
+   * reconcile the per-thread `Agent.messages` list with
+   * `RunAgentInput.messages` before invoking `stream()`.
+   *
+   * Prevents the LLM from re-firing frontend tools every turn because
+   * Strands' internal history was missing the tool result the frontend
+   * produced. Disable only if you manage Strands history yourself.
+   * Default: `true`.
+   */
+  replayHistoryIntoStrands?: boolean;
+  /**
+   * Emit the self-expanding AG-UI chunk events (`TEXT_MESSAGE_CHUNK`,
+   * `TOOL_CALL_CHUNK`, `REASONING_MESSAGE_CHUNK`) instead of the explicit
+   * `*_START` / `*_CONTENT` / `*_END` triples. Halves the event count on
+   * high-frequency deltas; useful for bandwidth-constrained transports.
+   * TypeScript-only. Default: `false`.
+   */
+  emitChunkEvents?: boolean;
+  /**
+   * Optional injectable logger. Mirrors the Python adapter's
+   * `logging.getLogger("ag_ui_strands")`: the default surfaces `warn` / `error`
+   * via the `console` and drops `debug`, matching Python's stdlib default
+   * (WARNING-and-up to stderr). Pass `{ debug: console.debug, warn:
+   * console.warn, error: console.error }` to enable verbose traces, `{ debug()
+   * {}, warn() {}, error() {} }` to silence everything, or wire in pino /
+   * winston / bunyan directly — the `Logger` shape matches the `console`
+   * methods.
+   *
+   * Debug messages match the Python adapter's message strings field-for-field
+   * (modulo camelCase / snake_case) so cross-SDK log diffs are straightforward.
+   */
+  logger?: Logger;
+}
+/**
+ * Flatten `RunAgentInput.context[]` into a plain key/value record and ensure
+ * `forwardedProps` is a record. Exported so hook implementations can call it
+ * when they have an `inputData` but not a fully-populated hook context.
+ */
+declare function buildContextExtras(inputData: RunAgentInput): ToolCallContextExtras;
+//#endregion
+//#region src/agent.d.ts
+/**
+ * Structural interface for a Strands multi-agent orchestrator (Graph/Swarm).
+ * TypeScript-only: the Python SDK currently has no orchestrator equivalent.
+ */
+interface StrandsOrchestrator {
+  readonly id?: string;
+  stream(input: string): AsyncGenerator<unknown, unknown, unknown>;
+}
+/**
+ * Convert ``RunAgentInput.messages`` to AG-UI message objects.
+ *
+ * Used to seed the running ``MessagesSnapshotEvent`` payload so each snapshot
+ * carries the full thread history.
+ */
+declare function buildSnapshotMessages(input_messages: Message[]): Message[];
+/** Options accepted by `StrandsAgent`. */
+interface StrandsAgentOptions {
+  /**
+   * Either an `Agent` (the template — adapter clones it per thread and syncs
+   * proxy tools) OR a multi-agent orchestrator (`Graph`, `Swarm`).
+   * Orchestrators are stateless per invocation so the same instance serves
+   * every thread.
+   */
+  agent: Agent | StrandsOrchestrator;
+  name: string;
+  description?: string;
+  config?: StrandsAgentConfig;
+  /**
+   * Plugins forwarded to every per-thread Strands agent created by this
+   * adapter (observability, loop caps, policy checks, ...). Mirrors the
+   * Python adapter's `hooks=` kwarg. Ignored when `agent` is a multi-agent
+   * orchestrator.
+   */
+  plugins?: Plugin[];
+}
+/** AWS Strands Agent wrapper for AG-UI integration. */
+declare class StrandsAgent {
+  readonly name: string;
+  readonly description: string;
+  readonly config: StrandsAgentConfig;
+  private readonly _templateFields;
+  /**
+   * Hook providers forwarded to each per-thread StrandsAgentCore.
+   *
+   * Taken directly from the caller rather than read off the template because
+   * Strands' `Agent.hooks` is a `HookRegistry` containing only registered
+   * callbacks — the original list of provider objects is not retained, and
+   * the registry also contains callbacks bound to internal Strands objects
+   * that must not be cross-wired into per-thread agents.
+   */
+  private readonly _plugins;
+  private readonly _agentsByThread;
+  private readonly _proxyToolNamesByThread;
+  /**
+   * Guards first-time thread initialization. The sessionManagerProvider call
+   * introduces an async yield point between the "is this thread new?" check
+   * and the map assignment, so concurrent requests for the same new threadId
+   * could otherwise both create an agent and one would clobber the other.
+   */
+  private readonly _threadInitLock;
+  /**
+   * Threads with an in-flight run. Strands `Agent.stream()` throws if a
+   * second invocation is started on a busy agent; we detect the collision
+   * up front and emit a protocol-shaped RUN_ERROR/THREAD_BUSY instead.
+   * TypeScript-only: the Python adapter has no equivalent guard.
+   */
+  private readonly _activeRunsByThread;
+  /** Outstanding Strands interrupt IDs per thread, used to validate
+   * incoming `RunAgentInput.resume[]` (interrupts.mdx rule 4). */
+  private readonly _pendingInterruptsByThread;
+  /**
+   * When non-null, the adapter bypasses per-thread cloning and invokes
+   * the orchestrator directly. See `StrandsAgentOptions.agent`.
+   */
+  private readonly _orchestrator;
+  /**
+   * Injectable logger. Defaults to console `warn`/`error` with `debug`
+   * suppressed, matching Python's stdlib `logging.getLogger(__name__)`.
+   */
+  private readonly _log;
+  constructor(options: StrandsAgentOptions);
+  /** Run the Strands agent and yield AG-UI events. */
+  run(inputData: RunAgentInput): AsyncGenerator<BaseEvent, void, void>;
+  protected _runRaw(inputData: RunAgentInput): AsyncGenerator<BaseEvent, void, void>;
+  private _runSingleAgent;
+  /**
+   * Legacy burst path for tool calls — invoked when the Strands SDK delivers
+   * a complete `ToolUseBlock` or when a `ToolBehavior.argsStreamer` takes
+   * over args emission at contentBlockStop.
+   *
+   * The streaming path inside `_runSingleAgent` handles the common case
+   * directly; this helper handles continuation turns and custom streamers.
+   *
+   * Getters/setters surface the caller's local variables because JS closures
+   * capture by reference only for `const` / `let` in scope — an object of
+   * mutable fields would work but would require threading `state` through
+   * `_runSingleAgent`'s long body.
+   */
+  private _emitToolCall;
+  /**
+   * Orchestrator-mode run loop. TypeScript-only: drives a `Graph` or `Swarm`
+   * `.stream()` call and translates multi-agent events. Per-thread caching,
+   * session managers, and proxy-tool sync don't apply.
+   */
+  private _runOrchestrator;
+  private _buildThreadAgentConfig;
+}
+/**
+ * Build the message-history seed handed to `AgentConfig.messages` on
+ * cold-cache agent creation. TypeScript-only: the Python SDK mutates
+ * `Agent.messages` in place after construction via
+ * `_buildStrandsHistory`, whereas the TS SDK consumes a seed at
+ * construction time.
+ *
+ * - Normal run (tail is a `user` turn): seed everything except the final
+ *   user turn; the final turn is passed to `agent.stream(...)` as the
+ *   fresh prompt.
+ * - Continuation run (tail is a `tool` message) or orphan tail: seed the
+ *   entire history so the agent sees its own tool call + result before the
+ *   synthetic continuation prompt fires.
+ *
+ * Returns `undefined` when the resulting seed would be empty or would
+ * start with an `assistant` turn (Bedrock rejects assistant-first history).
+ */
+declare function buildStrandsSeed(messages: Message[], log?: Logger): Promise<AgentConfig["messages"]>;
+/**
+ * Convert AG-UI messages into the `MessageData` shape `AgentConfig.messages`
+ * accepts on cold-cache agent construction. Similar in spirit to
+ * `_buildStrandsHistory` but drops orphan tool turns (Bedrock rejects them).
+ */
+declare function convertMessagesForStrandsSeed(messages: Message[], log?: Logger): Promise<Array<{
+  role: "user" | "assistant";
+  content: unknown[];
+}>>;
+//#endregion
+export { ToolCallContext as _, convertMessagesForStrandsSeed as a, buildContextExtras as b, MaybePromise as c, StateContextBuilder as d, StateFromArgs as f, ToolBehavior as g, StrandsAgentConfig as h, buildStrandsSeed as i, PredictStateMapping as l, StatePayload as m, StrandsAgentOptions as n, ArgsStreamer as o, StateFromResult as p, buildSnapshotMessages as r, CustomResultHandler as s, StrandsAgent as t, SessionManagerProvider as u, ToolCallContextExtras as v, Logger as x, ToolResultContext as y };
+//# sourceMappingURL=agent-B2EYZvns.d.ts.map

package/dist/agent-B2EYZvns.d.ts.map

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