@aws/nx-plugin 1.0.0-rc.9 → 1.0.0-rc.90

package/src/py/agent/generator.js

@@ -1,36 +1,189 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pyAgentGenerator = exports.PY_AGENT_GENERATOR_INFO = void 0;
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-const devkit_1 = require("@nx/devkit");
-const config_1 = require("../../license/config");
-const known_exceptions_1 = require("../../license/known-exceptions");
-const agent_connection_1 = require("../../utils/agent-connection/agent-connection");
-const agent_core_constructs_1 = require("../../utils/agent-core-constructs/agent-core-constructs");
-const bundle_1 = require("../../utils/bundle/bundle");
-const containers_1 = require("../../utils/containers");
-const format_1 = require("../../utils/format");
-const fs_1 = require("../../utils/fs");
-const git_1 = require("../../utils/git");
-const iac_1 = require("../../utils/iac");
-const metrics_1 = require("../../utils/metrics");
-const names_1 = require("../../utils/names");
-const npm_scope_1 = require("../../utils/npm-scope");
-const nx_1 = require("../../utils/nx");
-const nxlv_python_1 = require("../../utils/nxlv-python");
-const object_1 = require("../../utils/object");
-const paths_1 = require("../../utils/paths");
-const port_1 = require("../../utils/port");
-const py_1 = require("../../utils/py");
-const shared_constructs_1 = require("../../utils/shared-constructs");
-const versions_1 = require("../../utils/versions");
-exports.PY_AGENT_GENERATOR_INFO = (0, nx_1.getGeneratorInfo)(__filename);
-const pyAgentGenerator = async (tree, options) => {
-    const project = (0, nx_1.readProjectConfigurationUnqualified)(tree, options.project);
-    const pyProjectPath = (0, devkit_1.joinPathFragments)(project.root, 'pyproject.toml');
+ */ import { generateFiles, joinPathFragments, OverwriteStrategy, updateProjectConfiguration } from "@nx/devkit";
+import { ensureLicenseExceptions } from "../../license/config.js";
+import { AG_UI_LANGGRAPH_EXCEPTIONS } from "../../license/known-exceptions.js";
+import { addPyDependencies, addTsDependencies } from "../../utils/add-dependencies.js";
+import { addAgentChatScripts } from "../../utils/agent-chat/agent-chat.js";
+import { AGENT_CONNECTION_PY_DEPENDENCIES, addPythonFrameworkBase, ensureLangchainS3CheckpointSaver, ensurePythonAgentConnectionProject, getPythonAgentConnectionModuleName, getPythonAgentConnectionProject } from "../../utils/agent-connection/agent-connection.js";
+import { addAgentInfra } from "../../utils/agent-core-constructs/agent-core-constructs.js";
+import { addPythonBundleTarget } from "../../utils/bundle/bundle.js";
+import { resolveContainers } from "../../utils/containers.js";
+import { declareDependencies, ownedElsewhere } from "../../utils/declared-dependencies.js";
+import { addDockerScanTarget, DOCKER_DEPENDENCIES, IMAGE_BUILD_CACHE } from "../../utils/docker.js";
+import { formatFilesInSubtree } from "../../utils/format.js";
+import { FS_DEPENDENCIES, FsCommands } from "../../utils/fs.js";
+import { updateGitIgnore } from "../../utils/git.js";
+import { resolveIac } from "../../utils/iac.js";
+import { installDependencies } from "../../utils/install.js";
+import { addGeneratorMetricsIfApplicable } from "../../utils/metrics.js";
+import { kebabCase, toClassName, toSnakeCase } from "../../utils/names.js";
+import { getNpmScope } from "../../utils/npm-scope.js";
+import { addArtifactDependencyToTargets, addComponentDevTarget, addComponentGeneratorMetadata, addDependencyToTargetIfNotPresent, getGeneratorInfo, normalizeTargetKeyOrder, readProjectConfigurationUnqualified } from "../../utils/nx.js";
+import { sortObjectKeys } from "../../utils/object.js";
+import { openApiCodegenTarget } from "../../utils/open-api-codegen-target.js";
+import { getRelativePathToRootByDirectory, toProjectRelativePath } from "../../utils/paths.js";
+import { assignPort } from "../../utils/port.js";
+import { addWorkspaceDependencyToPyProject } from "../../utils/py.js";
+import { SHARED_CONSTRUCTS_DEPENDENCIES, sharedConstructsGenerator } from "../../utils/shared-constructs.js";
+import { BASE_IMAGES } from "../../utils/versions.js";
+/** Whether the chat CLI signs its requests, which only IAM auth needs. */ const isIam = (m)=>m.auth === 'iam';
+// Each entry names the framework and protocol branch it belongs to, so the same
+// declaration drives both adding and the version sync.
+export const DEPENDENCIES = declareDependencies()({
+    ts: [
+        // The chat CLI, which runs standalone via tsx for every protocol and
+        // resolves the deployed agent from AppConfig. `agent-chat-cli` transitively
+        // bundles the protocol clients (@a2a-js/sdk, @ag-ui/client).
+        {
+            name: 'agent-chat-cli',
+            dev: true,
+            root: true
+        },
+        {
+            name: 'tsx',
+            dev: true,
+            root: true
+        },
+        {
+            name: '@types/node',
+            dev: true,
+            root: true
+        },
+        {
+            name: '@aws-lambda-powertools/parameters',
+            dev: true,
+            root: true
+        },
+        {
+            name: '@aws-sdk/client-appconfigdata',
+            dev: true,
+            root: true
+        },
+        {
+            name: 'aws4fetch',
+            when: isIam,
+            dev: true,
+            root: true
+        },
+        {
+            name: '@aws-sdk/credential-providers',
+            when: isIam,
+            dev: true,
+            root: true
+        },
+        {
+            name: '@a2a-js/sdk',
+            when: (m)=>m.protocol === 'a2a',
+            dev: true,
+            root: true
+        },
+        // Added by the helpers that own the projects they belong to.
+        ...ownedElsewhere(FS_DEPENDENCIES),
+        ...ownedElsewhere(DOCKER_DEPENDENCIES),
+        ...ownedElsewhere(SHARED_CONSTRUCTS_DEPENDENCIES)
+    ],
+    py: [
+        {
+            name: 'aws-lambda-powertools'
+        },
+        {
+            name: 'aws-opentelemetry-distro'
+        },
+        {
+            name: 'bedrock-agentcore'
+        },
+        {
+            name: 'boto3'
+        },
+        {
+            name: 'fastapi'
+        },
+        {
+            name: 'mcp'
+        },
+        // langchain pulls no Strands dependencies — the langchain model binding
+        // plus the per-protocol server adapter: ag-ui-langgraph for AG-UI, a2a-sdk
+        // for A2A, nothing extra for HTTP (FastAPI is added for every agent).
+        {
+            name: 'langchain',
+            when: (m)=>m.framework === 'langchain'
+        },
+        {
+            name: 'langchain-aws',
+            when: (m)=>m.framework === 'langchain'
+        },
+        {
+            name: 'langgraph',
+            when: (m)=>m.framework === 'langchain'
+        },
+        // Local dev uses a SQLite-backed checkpointer for convenience (parity
+        // with the strands framework's local FileSessionManager).
+        {
+            name: 'langgraph-checkpoint-sqlite',
+            when: (m)=>m.framework === 'langchain'
+        },
+        // AsyncSqliteSaver's driver, required alongside langgraph-checkpoint-sqlite.
+        {
+            name: 'aiosqlite',
+            when: (m)=>m.framework === 'langchain'
+        },
+        // Provides DynamoDBSaver (with S3 offloading for large checkpoints).
+        {
+            name: 'langgraph-checkpoint-aws',
+            when: (m)=>m.framework === 'langchain' && m.session === 'dynamodb-s3'
+        },
+        {
+            name: 'ag-ui-protocol',
+            when: (m)=>m.framework === 'langchain' && m.protocol === 'ag-ui'
+        },
+        {
+            name: 'ag-ui-langgraph',
+            when: (m)=>m.framework === 'langchain' && m.protocol === 'ag-ui'
+        },
+        {
+            name: 'a2a-sdk',
+            when: (m)=>m.framework === 'langchain' && m.protocol === 'a2a'
+        },
+        {
+            name: 'strands-agents[a2a]',
+            when: (m)=>m.framework === 'strands' && m.protocol === 'a2a'
+        },
+        {
+            name: 'strands-agents',
+            when: (m)=>m.framework === 'strands' && m.protocol !== 'a2a'
+        },
+        {
+            name: 'strands-agents-tools',
+            when: (m)=>m.framework === 'strands'
+        },
+        // Declared again here so a Strands AG-UI agent lists it in the same order
+        // the generated pyproject.toml had before.
+        {
+            name: 'ag-ui-protocol',
+            when: (m)=>m.framework === 'strands' && m.protocol === 'ag-ui'
+        },
+        {
+            name: 'ag-ui-strands',
+            when: (m)=>m.framework === 'strands' && m.protocol === 'ag-ui'
+        },
+        {
+            name: 'uvicorn'
+        },
+        // `fastapi dev` runs the local server for every protocol.
+        {
+            name: 'fastapi[standard]',
+            group: 'dev'
+        },
+        // The agent-connection helper adds these to its own project.
+        ...ownedElsewhere(AGENT_CONNECTION_PY_DEPENDENCIES)
+    ]
+});
+export const PY_AGENT_GENERATOR_INFO = getGeneratorInfo(import.meta.filename);
+export const pyAgentGenerator = async (tree, options)=>{
+    const project = readProjectConfigurationUnqualified(tree, options.project);
+    const pyProjectPath = joinPathFragments(project.root, 'pyproject.toml');
     // Check if the project has a pyproject.toml file
     if (!pyProjectPath) {
         throw new Error(`Unsupported project ${options.project}. Expected a Python project (with a pyproject.toml)`);
@@ -41,74 +194,124 @@ const pyAgentGenerator = async (tree, options) => {
     // Module name is the last part of the source root,
     const sourceParts = project.sourceRoot.split('/');
     const moduleName = sourceParts[sourceParts.length - 1];
-    const name = (0, names_1.kebabCase)(options.name || `${(0, names_1.kebabCase)(project.name.split('.').pop())}-agent`);
+    const name = kebabCase(options.name || `${kebabCase(project.name.split('.').pop())}-agent`);
     const agentTargetPrefix = options.name ? name : 'agent';
-    const agentNameSnakeCase = (0, names_1.toSnakeCase)(options.name || 'agent');
-    const agentNameClassName = (0, names_1.toClassName)(name);
-    const targetSourceDir = (0, devkit_1.joinPathFragments)(project.sourceRoot, agentNameSnakeCase);
+    const agentNameSnakeCase = toSnakeCase(options.name || 'agent');
+    const agentNameClassName = toClassName(name);
+    const targetSourceDir = joinPathFragments(project.sourceRoot, agentNameSnakeCase);
     const infra = options.infra ?? 'agentcore';
     const protocol = options.protocol ?? 'http';
+    const framework = options.framework ?? 'strands';
+    // Recorded in the metadata below so the version sync can tell a CDK
+    // project from a Terraform one; undefined when no infrastructure was
+    // generated, in which case neither provider's packages were added.
+    const iac = infra !== 'none' ? await resolveIac(tree, options.iac) : undefined;
     if (infra === 'none' && options.auth && options.auth !== 'iam') {
         console.warn('Warning: auth is ignored when no infrastructure is configured (no infrastructure is generated)');
     }
     const auth = options.auth ?? 'iam';
+    // Session backends are framework-specific: Strands' SessionManager only has
+    // an S3-backed implementation here (via strands.session.S3SessionManager),
+    // while LangChain uses dedicated S3 and DynamoDB checkpointer libraries.
+    // 'in-memory' is valid for both.
+    const SESSIONS_BY_FRAMEWORK = {
+        strands: [
+            's3',
+            'in-memory'
+        ],
+        langchain: [
+            's3',
+            'dynamodb-s3',
+            'in-memory'
+        ]
+    };
+    if (options.session && !SESSIONS_BY_FRAMEWORK[framework].includes(options.session)) {
+        throw new Error(`Unsupported combination: session '${options.session}' is not implemented for the ${framework} framework (supported: ${SESSIONS_BY_FRAMEWORK[framework].join(', ')}).`);
+    }
+    const session = options.session ?? 's3';
+    // With infra=none there's no CDK/Terraform construct to provision a bucket
+    // or table or set RUNTIME_CONFIG_APP_ID, so session.py's non-local-dev
+    // branch has nothing to read from AppConfig at runtime — the generated code
+    // still honors `session`, but only works outside local dev if the caller
+    // wires up matching infra/runtime config themselves.
+    if (infra === 'none' && session !== 'in-memory') {
+        console.warn(`Warning: session '${session}' requires infrastructure to configure it automatically (no infrastructure is generated for infra=none) — outside local dev this will fail unless you configure matching runtime config yourself`);
+    }
+    // Local-dev session storage lives at the workspace root
+    // (`tmp/agents/<framework>/<agent-name>`), not inside the project, so each
+    // agent gets its own storage directory — shared by both frameworks
+    // (Strands' FileSessionManager, LangChain's SqliteSaver). The
+    // `-dev`/`-serve` targets run with cwd={projectRoot}, so compute that
+    // directory relative to the project root here rather than resolving it at
+    // runtime.
+    const localSessionsDir = joinPathFragments(getRelativePathToRootByDirectory(project.root), `tmp/agents/${framework}/${name}`);
     // Ensure the shared agent-connection project exists so the server entry
     // point can import `session_id_context` and propagate the AgentCore
     // session ID to any downstream MCP / A2A clients a later connection
     // generator wires into this agent.
-    await (0, agent_connection_1.ensurePythonAgentConnectionProject)(tree);
-    const agentConnectionModuleName = (0, agent_connection_1.getPythonAgentConnectionModuleName)(tree);
-    const agentConnectionPackageName = (0, agent_connection_1.getPythonAgentConnectionPackageName)(tree);
-    (0, py_1.addWorkspaceDependencyToPyProject)(tree, project.root, agentConnectionPackageName);
+    await ensurePythonAgentConnectionProject(tree, DEPENDENCIES);
+    // The agent server imports the framework base helpers (session cache + model
+    // error logging) regardless of whether a connection client is wired in. The
+    // LangChain framework has no base layer (its AG-UI foundation reuses only the
+    // framework-agnostic session context), so this is a no-op for LangChain.
+    await addPythonFrameworkBase(tree, DEPENDENCIES, framework);
+    const agentConnectionModuleName = getPythonAgentConnectionModuleName(tree);
+    addWorkspaceDependencyToPyProject(tree, project, getPythonAgentConnectionProject(tree));
     const templateContext = {
         name,
         agentNameSnakeCase,
         agentNameClassName,
         moduleName,
         agentConnectionModuleName,
+        framework,
+        protocol,
+        session,
+        localSessionsDir
     };
-    // Generate common files shared by both protocols
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', 'common'), targetSourceDir, templateContext, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-    // Generate protocol-specific files
-    (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', protocol.toLowerCase()), targetSourceDir, templateContext, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-    (0, py_1.addDependenciesToPyProjectToml)(tree, project.root, [
-        'aws-lambda-powertools',
-        'aws-opentelemetry-distro',
-        'bedrock-agentcore',
-        'boto3',
-        'fastapi',
-        'mcp',
-        ...(protocol === 'a2a'
-            ? ['strands-agents[a2a]']
-            : protocol === 'ag-ui'
-                ? ['strands-agents', 'ag-ui-protocol', 'ag-ui-strands']
-                : ['strands-agents']),
-        'strands-agents-tools',
-        'uvicorn',
-    ]);
-    (0, py_1.addDependenciesToDependencyGroupInPyProjectToml)(tree, project.root, 'dev', [
-        'fastapi[standard]',
-    ]);
+    // Files live under a per-framework dir (files/strands, files/langchain),
+    // mirrored one-for-one — including files that don't vary by framework
+    // (e.g. the empty package __init__.py) — so there's a single, uniform
+    // <framework>/<protocol> layout with no cross-framework fallbacks.
+    // `framework` is itself the directory name.
+    // Common files shared by both protocols: the agent module (Strands yields a
+    // contextmanaged Agent with a session.py sibling; LangChain returns a
+    // compiled create_agent graph) and the package __init__.py.
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', framework, 'common'), targetSourceDir, templateContext, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
+    if (framework === 'langchain' && session === 's3') {
+        ensureLangchainS3CheckpointSaver(tree);
+    }
+    // Protocol-specific files. Each protocol's server entry point is
+    // framework-specific (Strands yields a contextmanaged Agent; LangChain
+    // drives a compiled create_agent graph).
+    const protocolLower = protocol.toLowerCase();
+    generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', framework, protocolLower), targetSourceDir, templateContext, {
+        overwriteStrategy: OverwriteStrategy.KeepExisting
+    });
     if (infra === 'agentcore') {
-        const containers = await (0, containers_1.resolveContainers)(tree, 'inherit');
-        const dockerImageTag = `${(0, npm_scope_1.getNpmScope)(tree)}-${name}:latest`;
+        const containers = await resolveContainers(tree, 'inherit');
+        const dockerImageTag = `${getNpmScope(tree)}-${name}:latest`;
         // Add bundle target
-        const { bundleTargetName, bundleOutputDir } = (0, bundle_1.addPythonBundleTarget)(project, {
-            pythonPlatform: 'aarch64-manylinux_2_28',
+        const { bundleTargetName, bundleOutputDir } = addPythonBundleTarget(project, {
+            pythonPlatform: 'aarch64-manylinux_2_28'
         });
         // Add the Dockerfile
-        (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'files', 'deploy'), targetSourceDir, {
+        generateFiles(tree, joinPathFragments(import.meta.dirname, 'files', 'deploy'), targetSourceDir, {
             agentNameSnakeCase,
             moduleName,
             bundleOutputDir,
             protocol,
-        }, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-        const dockerOutputDir = (0, devkit_1.joinPathFragments)('dist', project.root, 'docker', name);
+            pythonBaseImage: BASE_IMAGES.python
+        }, {
+            overwriteStrategy: OverwriteStrategy.KeepExisting
+        });
+        const dockerOutputDir = joinPathFragments('dist', project.root, 'docker', name);
         const dockerTargetName = `${agentTargetPrefix}-docker`;
         // Add a docker target that prepares the docker context and builds the image
-        const fs = new fs_1.FsCommands(tree);
+        const fs = new FsCommands(tree, DEPENDENCIES);
         project.targets[dockerTargetName] = {
-            cache: true,
+            cache: IMAGE_BUILD_CACHE,
             executor: 'nx:run-commands',
             options: {
                 commands: [
@@ -116,21 +319,33 @@ const pyAgentGenerator = async (tree, options) => {
                     fs.mkdir(dockerOutputDir),
                     fs.cp(bundleOutputDir, dockerOutputDir),
                     fs.cp(`${targetSourceDir}/Dockerfile`, `${dockerOutputDir}/Dockerfile`),
-                    `${containers} build --platform linux/arm64 -t ${dockerImageTag} ${dockerOutputDir}`,
+                    `${containers} build --platform linux/arm64 -t ${dockerImageTag} ${dockerOutputDir}`
                 ],
-                parallel: false,
+                parallel: false
             },
-            dependsOn: [bundleTargetName],
+            dependsOn: [
+                bundleTargetName
+            ]
         };
-        (0, nx_1.addDependencyToTargetIfNotPresent)(project, 'docker', dockerTargetName);
-        (0, nx_1.addDependencyToTargetIfNotPresent)(project, 'build', 'docker');
+        addDependencyToTargetIfNotPresent(project, 'docker', dockerTargetName);
+        addArtifactDependencyToTargets(project, 'docker');
+        addDockerScanTarget(tree, {
+            project,
+            containerEngine: containers,
+            trivyTargetName: `${agentTargetPrefix}-trivy`,
+            dockerTargetName,
+            imageTags: [
+                dockerImageTag
+            ]
+        }, DEPENDENCIES);
         // Add shared constructs
-        const iac = await (0, iac_1.resolveIac)(tree, options.iac);
-        await (0, shared_constructs_1.sharedConstructsGenerator)(tree, { iac });
+        await sharedConstructsGenerator(tree, {
+            iac
+        }, DEPENDENCIES);
         // Add the construct to deploy the agent.
         // AG-UI uses HTTP as the AgentCore protocol type (AG-UI is HTTP-based with SSE over POST).
         const infraProtocol = protocol === 'ag-ui' ? 'http' : protocol;
-        await (0, agent_core_constructs_1.addAgentInfra)(tree, {
+        await addAgentInfra(tree, {
             agentNameKebabCase: name,
             agentNameClassName,
             dockerImageTag,
@@ -138,15 +353,39 @@ const pyAgentGenerator = async (tree, options) => {
             iac,
             projectName: project.name,
             auth,
+            session,
             serverProtocol: infraProtocol,
-            containers,
+            containers
         });
     }
     // A2A servers use port 9000 as per the Strands A2A SDK default and AgentCore A2A contract.
     // HTTP and AG-UI agents use port 8081+ to avoid conflict with VS Code server on 8080.
     const localDevPortStart = protocol === 'a2a' ? 9000 : 8081;
-    const localDevPort = (0, port_1.assignPort)(tree, project, localDevPortStart, {
-        component: { info: exports.PY_AGENT_GENERATOR_INFO, name: agentTargetPrefix },
+    const localDevPort = assignPort(tree, project, localDevPortStart, {
+        component: {
+            info: PY_AGENT_GENERATOR_INFO,
+            name: agentTargetPrefix
+        }
+    });
+    // Recorded below and read by the declaration's predicates, so the packages
+    // added here are exactly the ones the version sync will own.
+    const metadata = {
+        port: localDevPort,
+        rc: agentNameClassName,
+        auth,
+        protocol,
+        framework,
+        session,
+        ...iac ? {
+            iac
+        } : {}
+    };
+    addPyDependencies(tree, DEPENDENCIES, {
+        metadata,
+        projectRoot: project.root
+    });
+    addTsDependencies(tree, DEPENDENCIES, {
+        metadata
     });
     // All protocols use fastapi dev for hot reload:
     // - HTTP: FastAPI app directly defined in init.py
@@ -159,135 +398,142 @@ const pyAgentGenerator = async (tree, options) => {
     // we can run `agent-chat-cli` directly as a binary.
     const openApiTargetName = `${agentTargetPrefix}-openapi`;
     const clientGenTargetName = `${agentTargetPrefix}-generate-client`;
+    const scriptsDir = joinPathFragments(project.root, 'scripts', agentTargetPrefix);
     if (protocol === 'http') {
         // Emit the OpenAPI spec generator script (shared with react-connection)
-        (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'react-connection', 'files', 'agent'), project.root, {
+        generateFiles(tree, joinPathFragments(import.meta.dirname, 'react-connection', 'files', 'agent'), project.root, {
             moduleName,
-            agentNameSnakeCase,
-        }, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
-        // Emit the chat CLI adapter script
-        const scriptsDir = (0, devkit_1.joinPathFragments)(project.root, 'scripts', agentTargetPrefix);
-        (0, devkit_1.generateFiles)(tree, (0, devkit_1.joinPathFragments)(__dirname, 'scripts', 'http'), scriptsDir, {
-            agentNameClassName,
-            agentTargetPrefix,
-            localDevPort,
-        }, { overwriteStrategy: devkit_1.OverwriteStrategy.KeepExisting });
+            agentNameSnakeCase
+        }, {
+            overwriteStrategy: OverwriteStrategy.KeepExisting
+        });
         // Ignore the generated client directory
-        (0, git_1.updateGitIgnore)(tree, project.root, (patterns) => [
-            ...patterns,
-            `scripts/${agentTargetPrefix}/generated/`,
-        ]);
+        updateGitIgnore(tree, project.root, (patterns)=>[
+                ...patterns,
+                `scripts/${agentTargetPrefix}/generated/`
+            ]);
     }
-    // Add TypeScript deps for the chat CLI. `agent-chat-cli` transitively
-    // bundles the protocol clients (@a2a-js/sdk, @ag-ui/client) and
-    // @clack/prompts, so nothing else is needed. HTTP also needs tsx to
-    // run the adapter script.
-    (0, devkit_1.addDependenciesToPackageJson)(tree, {}, (0, versions_1.withVersions)([
-        'agent-chat-cli',
-        ...(protocol === 'http'
-            ? ['tsx', '@types/node']
-            : []),
-    ]));
-    const chatUrl = protocol === 'ag-ui'
-        ? `http://localhost:${localDevPort}/invocations`
-        : `http://localhost:${localDevPort}`;
-    const chatCommand = protocol === 'http'
-        ? `tsx ./scripts/${agentTargetPrefix}/chat.ts`
-        : protocol === 'ag-ui'
-            ? `agent-chat-cli agui ${chatUrl}`
-            : `agent-chat-cli a2a ${chatUrl}`;
-    const httpOnlyTargets = protocol === 'http'
-        ? {
-            [openApiTargetName]: {
-                cache: true,
-                executor: 'nx:run-commands',
-                outputs: [
-                    `{workspaceRoot}/dist/{projectRoot}/openapi/${agentNameSnakeCase}`,
+    // Every protocol gets a standalone `chat.ts`. It connects to the local
+    // `dev` server by default, or to the deployed agent (with the
+    // appropriate auth) when `RUNTIME_CONFIG_APP_ID` is set.
+    addAgentChatScripts(tree, {
+        scriptsDir,
+        protocol,
+        language: 'py',
+        agentNameClassName,
+        auth
+    });
+    const chatUrl = protocol === 'ag-ui' ? `http://localhost:${localDevPort}/invocations` : `http://localhost:${localDevPort}`;
+    const chatCommand = `tsx ./scripts/${agentTargetPrefix}/chat.ts`;
+    const httpOnlyTargets = protocol === 'http' ? {
+        [openApiTargetName]: {
+            cache: true,
+            // The spec serialises models a dependency may own, and this target
+            // has no `dependsOn` for `default`'s transitive
+            // `dependentTasksOutputFiles` to resolve against — so `^production`
+            // is the only edge to the dependency, and without it a model change
+            // there serves a stale spec.
+            inputs: [
+                'production',
+                '^production'
+            ],
+            executor: 'nx:run-commands',
+            outputs: [
+                `{workspaceRoot}/dist/{projectRoot}/openapi/${agentNameSnakeCase}`
+            ],
+            options: {
+                commands: [
+                    `uv run python {projectRoot}/scripts/${agentNameSnakeCase}_openapi.py "dist/{projectRoot}/openapi/${agentNameSnakeCase}/openapi.json"`
+                ]
+            }
+        },
+        [clientGenTargetName]: openApiCodegenTarget({
+            generator: 'ts-client',
+            openApiSpecPath: `dist/${project.root}/openapi/${agentNameSnakeCase}/openapi.json`,
+            outputPath: `${project.root}/scripts/${agentTargetPrefix}/generated`,
+            specBuildTargetName: openApiTargetName,
+            outputs: [
+                `{projectRoot}/scripts/${agentTargetPrefix}/generated`
+            ]
+        })
+    } : {};
+    const agentTargets = {
+        ...project.targets,
+        ...httpOnlyTargets,
+        [`${agentTargetPrefix}-serve`]: {
+            executor: 'nx:run-commands',
+            continuous: true,
+            options: {
+                commands: [
+                    serveCommand
                 ],
-                options: {
-                    commands: [
-                        `uv run python {projectRoot}/scripts/${agentNameSnakeCase}_openapi.py "dist/{projectRoot}/openapi/${agentNameSnakeCase}/openapi.json"`,
-                    ],
-                },
-            },
-            [clientGenTargetName]: {
-                cache: true,
-                executor: 'nx:run-commands',
-                inputs: [
-                    {
-                        dependentTasksOutputFiles: '**/*.json',
-                    },
+                cwd: '{projectRoot}',
+                env: {
+                    PORT: `${localDevPort}`
+                }
+            }
+        },
+        [`${agentTargetPrefix}-dev`]: {
+            executor: 'nx:run-commands',
+            continuous: true,
+            options: {
+                commands: [
+                    serveCommand
                 ],
-                outputs: [`{projectRoot}/scripts/${agentTargetPrefix}/generated`],
-                options: {
-                    commands: [
-                        `nx g @aws/nx-plugin:open-api#ts-client --openApiSpecPath="dist/${project.root}/openapi/${agentNameSnakeCase}/openapi.json" --outputPath="${project.root}/scripts/${agentTargetPrefix}/generated" --no-interactive`,
-                    ],
-                },
-                dependsOn: [openApiTargetName],
-            },
-        }
-        : {};
-    (0, devkit_1.updateProjectConfiguration)(tree, project.name, {
-        ...project,
-        targets: (0, object_1.sortObjectKeys)({
-            ...project.targets,
-            ...httpOnlyTargets,
-            [`${agentTargetPrefix}-serve`]: {
-                executor: 'nx:run-commands',
-                options: {
-                    commands: [serveCommand],
-                    cwd: '{projectRoot}',
-                    env: {
-                        PORT: `${localDevPort}`,
-                    },
-                },
-                continuous: true,
-            },
-            [`${agentTargetPrefix}-serve-local`]: {
-                executor: 'nx:run-commands',
-                options: {
-                    commands: [serveCommand],
-                    cwd: '{projectRoot}',
-                    env: {
-                        PORT: `${localDevPort}`,
-                        SERVE_LOCAL: 'true',
-                    },
-                },
-                continuous: true,
-            },
-            [`${agentTargetPrefix}-chat`]: {
-                executor: 'nx:run-commands',
-                options: {
-                    commands: [chatCommand],
-                    cwd: '{projectRoot}',
-                    env: {
-                        URL: chatUrl,
-                    },
-                },
-                dependsOn: [
-                    ...(protocol === 'http' ? [clientGenTargetName] : []),
-                    `${agentTargetPrefix}-serve-local`,
+                cwd: '{projectRoot}',
+                env: {
+                    PORT: `${localDevPort}`,
+                    LOCAL_DEV: 'true'
+                }
+            }
+        },
+        // HTTP chat imports the generated client, so ensure it's built first.
+        // No dev dependency — chat runs standalone against a local or
+        // deployed agent. normalizeTargetKeyOrder keeps the conditional dependsOn
+        // in Nx 23's serialization order so re-runs stay byte-identical.
+        [`${agentTargetPrefix}-chat`]: normalizeTargetKeyOrder({
+            executor: 'nx:run-commands',
+            options: {
+                commands: [
+                    chatCommand
                 ],
+                cwd: '{projectRoot}',
+                env: {
+                    URL: chatUrl
+                }
             },
-        }),
-    });
-    (0, nx_1.addComponentGeneratorMetadata)(tree, project.name, exports.PY_AGENT_GENERATOR_INFO, (0, paths_1.toProjectRelativePath)(project, targetSourceDir), agentTargetPrefix, {
-        port: localDevPort,
-        rc: agentNameClassName,
-        auth,
-        protocol,
+            ...protocol === 'http' ? {
+                dependsOn: [
+                    clientGenTargetName
+                ]
+            } : {}
+        })
+    };
+    // Aggregate `<agent>-dev` under the project-level `dev` target.
+    addComponentDevTarget(agentTargets, `${agentTargetPrefix}-dev`);
+    updateProjectConfiguration(tree, project.name, {
+        ...project,
+        targets: sortObjectKeys(agentTargets)
     });
-    await (0, metrics_1.addGeneratorMetricsIfApplicable)(tree, [exports.PY_AGENT_GENERATOR_INFO]);
-    if (protocol === 'ag-ui') {
-        await (0, config_1.ensureLicenseExceptions)(tree, known_exceptions_1.AG_UI_STRANDS_EXCEPTIONS);
+    addComponentGeneratorMetadata(tree, project.name, PY_AGENT_GENERATOR_INFO, toProjectRelativePath(project, targetSourceDir), agentTargetPrefix, metadata);
+    await addGeneratorMetricsIfApplicable(tree, [
+        PY_AGENT_GENERATOR_INFO
+    ]);
+    // langchain-core (pulled by every langchain agent regardless of protocol)
+    // brings jsonpatch/jsonpointer, whose wheels ship without resolvable SPDX
+    // license metadata, so register those exceptions so the workspace license
+    // check still passes.
+    if (framework === 'langchain') {
+        await ensureLicenseExceptions(tree, AG_UI_LANGGRAPH_EXCEPTIONS);
     }
-    await (0, format_1.formatFilesInSubtree)(tree);
-    return async () => {
-        (0, devkit_1.installPackagesTask)(tree);
-        await new nxlv_python_1.UVProvider(tree.root, new nxlv_python_1.Logger(), tree).install();
-    };
+    await formatFilesInSubtree(tree);
+    return ()=>installDependencies(tree, options.preferInstallDependencies, {
+            languages: [
+                'typescript',
+                'python'
+            ]
+        });
 };
-exports.pyAgentGenerator = pyAgentGenerator;
-exports.default = exports.pyAgentGenerator;
+export default pyAgentGenerator;
+
 //# sourceMappingURL=generator.js.map