@aws/nx-plugin-mcp 1.0.0-rc.55 → 1.0.0-rc.57

package/docs/guides/nx-migration.mdx

@@ -75,7 +75,7 @@ export default async function migration(
 }
 ```
 
-- **`nextSteps`** — workspace-wide notes surfaced to the user after `nx migrate` runs. Use these to report files you skipped (see the guardrails below) or manual follow-up the migration couldn't perform.
+- **`nextSteps`** — the follow-up actions Nx prints for the user after `nx migrate` runs. Every entry should be something they need to do by hand: reconcile a file you skipped (see the guardrails below), or finish something beyond the migration's reach, like an install to refresh a lock file. They aren't a log of what you changed — when a transform applies cleanly, add nothing, otherwise the entries that do need action get buried.
 - **`agentContext`** (hybrid only) — a summary of what the codemod changed, passed to the paired `prompt` when it runs under Nx's agentic flow so the agent can focus on the user-owned parts.
 
 For some example operations you can perform in your migration (generating files, modifying existing files using GritQL, reading and updating JSON), refer to the <Link path="/guides/nx-generator">Nx Generator guide</Link>.
@@ -86,6 +86,7 @@ Migrations run against workspaces you don't control, so it is recommended to adh
 
 - **Transform source code with GritQL.** Use the <Link path="/guides/nx-generator">GritQL helpers</Link> (`applyGritQL`, `matchGritQL`) to edit source rather than regexes or string replacements. GritQL matches the AST, so one pattern holds across the formatting, whitespace and quoting a user's copy may have drifted into, where text matching quietly misses equivalent code or corrupts the file. Use `updateJson` for JSON and the matching parser for other structured config.
 - **Pattern-match before writing.** If a target file has diverged from the shape your generators produce, skip it and report it via `nextSteps`, or consider a hybrid migration, rather than clobbering the user's changes. `matchGritQL` is a convenient way to make that check.
+- **Report only what's left to do.** `nextSteps` is for work the user has to pick up, not a record of the edits you made — those are already in their `git diff`.
 - **Idempotent.** Re-running the migration must be a no-op. Guard GritQL rewrites that inject code with a `where { ... <: not contains ... }` clause so a second run doesn't append a duplicate.
 - **Format what you write.** Finish with `formatFilesInSubtree(tree)` so the files your migration wrote are formatted correctly.
 

package/docs/guides/ts-agent.mdx

@@ -60,6 +60,7 @@ The generator will add the following files to your existing TypeScript project.
         - init.ts tRPC initialization
         - router.ts tRPC router with agent procedures
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - client.ts Vended client for invoking your agent
         - agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
@@ -79,6 +80,7 @@ The entry point uses the [Strands A2A Express Server](https://strandsagents.com/
       - agent/ (or custom name if specified)
         - index.ts A2A Express server entry point
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and Express dependencies
     - project.json Updated with agent serve targets
@@ -96,6 +98,7 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
       - agent/ (or custom name if specified)
         - index.ts AG-UI server entry point (Express + SSE)
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and AG-UI dependencies
     - project.json Updated with agent serve targets
@@ -185,7 +188,7 @@ const letterCounter = tool({
 });
 
 // Add tools to your agent
-export const getAgent = async (sessionId: string) => {
+export const getAgent = async () => {
   return new Agent({
     systemPrompt: 'You are a helpful assistant with access to various tools.',
     tools: [letterCounter],
@@ -347,6 +350,29 @@ Your agent is automatically configured with observability using the [AWS Distro
 You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
 
 For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).
+
+### Session Management
+
+The `session` option controls how your agent persists conversation state (message history, tool state, etc.) across invocations, using the Strands SDK's [SessionManager](https://strandsagents.com/docs/user-guide/concepts/agents/session-management/):
+
+- **`s3`** (default): The CDK/Terraform infrastructure provisions a dedicated S3 bucket for session data, encrypted with a dedicated KMS key and with all public access blocked; server access logs are delivered to a CloudWatch Logs log group via the same key. The agent's IAM role is granted read/write/list/delete access to the bucket and decrypt/generate-data-key access to the key, and the bucket name is registered alongside the agent's ARN in AppConfig runtime configuration.
+- **`in-memory`**: No bucket is provisioned. Conversation state is kept in memory only for the lifetime of the running process and does not survive restarts or scale-in.
+
+This is implemented in the generated `session.ts`, which exports a `getSessionManager()` function resolving a `SessionManager` for the current session.
+
+<OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI session wiring">
+Since AG-UI clones a template agent per conversation thread, `getSessionManager` is wired in as a `sessionManagerProvider` on the `StrandsAgent` config in `index.ts`, so a fresh `SessionManager` is resolved for each thread rather than baked into the shared template agent.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: ['http', 'a2a'] }} description="HTTP/A2A session wiring">
+Since `withSessionId` already caches one `Agent` instance per session, `getSessionManager` is called directly inside `getAgent`'s `new Agent({ sessionManager: await getSessionManager() })` call in `agent.ts`.
+</OptionFilter>
+
+The session ID itself comes from the AgentCore Runtime session (propagated via the `x-amzn-bedrock-agentcore-runtime-session-id` header for A2A/AG-UI, or the WebSocket connection context for HTTP/tRPC) and is bound to an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)-based context so `getCurrentSessionId()` can resolve it anywhere in the request — including in any downstream MCP or A2A clients wired up via the <Link path="/guides/connection">`connection` generator</Link>, so the whole call chain shares a consistent session.
+
+:::note[Local Development]
+When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target), session data is always stored on disk under `tmp/agents/strands/<agent-name>` at the workspace root, regardless of the configured `session` option, for convenience.
+:::
 </OptionFilter>
 
 ## Invoking your Agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.55",
+  "version": "1.0.0-rc.57",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/py/agent/schema.json

@@ -60,6 +60,14 @@
       "default": "agentcore",
       "x-priority": "important"
     },
+    "session": {
+      "type": "string",
+      "description": "The storage used to persist session for your Agent. Only 'in-memory' is currently supported for Python agents.",
+      "x-prompt": "How would you like to persist session for your Agent?",
+      "enum": ["in-memory"],
+      "default": "in-memory",
+      "x-priority": "important"
+    },
     "preferInstallDependencies": {
       "type": "boolean",
       "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",

package/src/ts/agent/schema.json

@@ -60,6 +60,14 @@
       "default": "agentcore",
       "x-priority": "important"
     },
+    "session": {
+      "type": "string",
+      "description": "The storage used to persist session for your Agent.",
+      "x-prompt": "How would you like to persist session for your Agent?",
+      "enum": ["s3", "in-memory"],
+      "default": "s3",
+      "x-priority": "important"
+    },
     "preferInstallDependencies": {
       "type": "boolean",
       "description": "Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.",