@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/migrations/latest/py-agent-a2a-httpx-client-per-call/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/py-agent-a2a-httpx-client-per-call/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  type MigrationReturnObject,\n  type Tree,\n  visitNotIgnoredFiles,\n} from '@nx/devkit';\nimport { applyGritQL, matchGritQL } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\n\n/**\n * Rebuild the `httpx.AsyncClient` (and, for Strands, the `A2AAgent`) fresh on\n * every A2A delegate call, instead of reusing the one built once at factory\n * time - fixes a reproducible `RuntimeError: Event loop is closed` on the\n * second call through a shared client.\n *\n * Both frameworks' A2A clients call out through a synchronous wrapper\n * (`_run_sync`) that runs the async call via `asyncio.run(...)` - a brand new\n * event loop per call, closed when the call returns. `AgentCoreA2aClientConfig`\n * builds one `httpx.AsyncClient` a single time, at factory call time, and that\n * client's connection pool binds to whichever event loop first touches it. So\n * call #1 creates a loop, uses the shared client, closes the loop; call #2\n * creates a *new* loop, but the shared client's pool is still bound to the\n * old, now-closed one.\n *\n * Strands hits the same failure one layer down: `A2AAgent.__call__` is itself\n * synchronous and does its own `asyncio.run(...)` per call internally, while\n * reusing the same factory-built `httpx.AsyncClient` via `client_config`.\n *\n * The fix in both `AgentCoreA2aClientLangChain`/`AgentCoreA2aClientStrands` is\n * to stop handing out a client wired to one long-lived `httpx.AsyncClient`.\n * Instead each call opens a fresh `httpx.AsyncClient` (reusing only the\n * `auth`/`timeout` off the once-built shared config) scoped to that call via\n * `async with`, so its connection pool lives and dies with the same loop that\n * created it. For Strands this also means `AgentCoreA2aClientStrands`'s\n * factories no longer return a raw `A2AAgent` (dropped in favour of a private\n * `_A2AClient` built per call), so the per-target `<Agent>ClientStrands.create`\n * wrapper's `-> A2AAgent` return annotation and its now-unused `A2AAgent`\n * import go stale too.\n */\nconst pyMatch = (snippet: string) => `language python\\n\\`${snippet}\\``;\n\nconst pyRewrite = (from: string, to: string): string => {\n  const replacement = to.includes('\\n') ? `raw\\`${to}\\`` : `\\`${to}\\``;\n  return `${pyMatch(from)} => ${replacement}`;\n};\n\nconst allMatch = async (\n  tree: Tree,\n  filePath: string,\n  patterns: string[],\n): Promise<boolean> => {\n  for (const pattern of patterns) {\n    if (!(await matchGritQL(tree, filePath, pattern))) return false;\n  }\n  return true;\n};\n\n// --- agentcore_a2a_client_langchain.py (framework-agnostic core, shared) ---\n\nconst LANGCHAIN_IMPORT_OLD =\n  'from a2a.client import A2ACardResolver, ClientConfig, ClientFactory';\nconst LANGCHAIN_IMPORT_NEW = `import httpx\nfrom a2a.client import A2ACardResolver, ClientConfig, ClientFactory`;\n\nconst LANGCHAIN_INVOKE_OLD = `    async def _invoke(self, prompt: str) -> str:\n        # AgentCoreA2aClientConfig always sets the signed httpx client.\n        httpx_client = self._config.httpx_client\n        if httpx_client is None:\n            raise RuntimeError(\"A2A client config is missing an httpx client\")\n        card = await A2ACardResolver(\n            httpx_client=httpx_client, base_url=self._url\n        ).get_agent_card()\n        client = ClientFactory(self._config).create(card)\n        message = Message(\n            kind=\"message\",\n            role=Role.user,\n            message_id=uuid4().hex,\n            parts=[Part(TextPart(kind=\"text\", text=prompt))],\n        )\n        # The client config uses streaming=False, so the last event carries the\n        # complete response.\n        reply = \"\"\n        async for event in client.send_message(message):\n            text = _text(event)\n            if text:\n                reply = text\n        return reply`;\n\nconst LANGCHAIN_INVOKE_NEW = `async def _invoke(self, prompt: str) -> str:\n    # AgentCoreA2aClientConfig always sets the signed httpx client.\n    shared_client = self._config.httpx_client\n    if shared_client is None:\n        raise RuntimeError(\"A2A client config is missing an httpx client\")\n    async with httpx.AsyncClient(\n        auth=shared_client.auth, timeout=shared_client.timeout\n    ) as httpx_client:\n        card = await A2ACardResolver(\n            httpx_client=httpx_client, base_url=self._url\n        ).get_agent_card()\n        client = ClientFactory(\n            ClientConfig(httpx_client=httpx_client, streaming=False)\n        ).create(card)\n        message = Message(\n            kind=\"message\",\n            role=Role.user,\n            message_id=uuid4().hex,\n            parts=[Part(TextPart(kind=\"text\", text=prompt))],\n        )\n        # The client config uses streaming=False, so the last event carries\n        # the complete response.\n        reply = \"\"\n        async for event in client.send_message(message):\n            text = _text(event)\n            if text:\n                reply = text\n        return reply`;\n\nconst migrateLangchainCoreClient = async (\n  tree: Tree,\n  filePath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  const contents = tree.read(filePath, 'utf-8') ?? '';\n  if (!contents.includes('client = ClientFactory(self._config).create(card)'))\n    return;\n\n  const ready = await allMatch(tree, filePath, [\n    pyMatch(LANGCHAIN_IMPORT_OLD),\n    pyMatch(LANGCHAIN_INVOKE_OLD),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${filePath}: diverged from the generated shape - left untouched. Manually rebuild a fresh httpx.AsyncClient per call in _invoke instead of reusing the one built at factory time (see the agent-connection generator's agentcore_a2a_client_langchain.py template).`,\n    );\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(LANGCHAIN_IMPORT_OLD, LANGCHAIN_IMPORT_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(LANGCHAIN_INVOKE_OLD, LANGCHAIN_INVOKE_NEW),\n  );\n};\n\n// --- agentcore_a2a_client_strands.py (Strands core client) ------------------\n\nconst STRANDS_IMPORT1_OLD = 'from collections.abc import Callable';\nconst STRANDS_IMPORT1_NEW = `import asyncio\nfrom collections.abc import Callable\nfrom concurrent.futures import ThreadPoolExecutor`;\n\nconst STRANDS_IMPORT2_OLD = 'from strands.agent.a2a_agent import A2AAgent';\nconst STRANDS_IMPORT2_NEW = `import httpx\nfrom a2a.client import ClientConfig\nfrom strands.agent.a2a_agent import A2AAgent\nfrom strands.agent.agent_result import AgentResult`;\n\nconst STRANDS_BUILD_OLD = `def _build(\n    config: tuple, *, name: str | None, description: str | None\n) -> A2AAgent:\n    url, client_config = config\n    kwargs: dict = {\"endpoint\": url, \"client_config\": client_config}\n    if name:\n        kwargs[\"name\"] = name\n    if description:\n        kwargs[\"description\"] = description\n    return A2AAgent(**kwargs)`;\n\nconst STRANDS_BUILD_NEW = `def _run_sync(coro):\n    # The tool is invoked from sync agent code, which under uvicorn runs inside a\n    # live event loop where asyncio.run() would raise — fall back to a worker.\n    try:\n        asyncio.get_running_loop()\n    except RuntimeError:\n        return asyncio.run(coro)\n    with ThreadPoolExecutor(max_workers=1) as pool:\n        return pool.submit(asyncio.run, coro).result()\n\n\nclass _A2AClient:\n    def __init__(\n        self,\n        url: str,\n        client_config: ClientConfig,\n        *,\n        name: str | None,\n        description: str | None,\n    ):\n        shared_client = client_config.httpx_client\n        if shared_client is None:\n            raise RuntimeError(\"A2A client config is missing an httpx client\")\n        self._url = url\n        self._auth = shared_client.auth\n        self._timeout = shared_client.timeout\n        self._name = name\n        self._description = description\n\n    def __call__(self, prompt: str) -> AgentResult:\n        return _run_sync(self._invoke(prompt))\n\n    async def _invoke(self, prompt: str) -> AgentResult:\n        async with httpx.AsyncClient(\n            auth=self._auth, timeout=self._timeout\n        ) as httpx_client:\n            agent = A2AAgent(\n                endpoint=self._url,\n                name=self._name,\n                description=self._description,\n                client_config=ClientConfig(httpx_client=httpx_client, streaming=False),\n            )\n            return await agent.invoke_async(prompt)\n\n\ndef _build(\n    config: tuple, *, name: str | None, description: str | None\n) -> _A2AClient:\n    url, client_config = config\n    return _A2AClient(url, client_config, name=name, description=description)`;\n\nconst STRANDS_IAM_OLD = `    @staticmethod\n    def with_iam_auth(\n        agent_runtime_arn: str,\n        *,\n        name: str | None = None,\n        description: str | None = None,\n    ) -> A2AAgent:\n        \"\"\"SigV4-authenticated client for a Bedrock AgentCore runtime.\"\"\"\n        return _build(\n            AgentCoreA2aClientConfig.with_iam_auth(agent_runtime_arn),\n            name=name,\n            description=description,\n        )`;\n\nconst STRANDS_IAM_NEW = `@staticmethod\ndef with_iam_auth(\n    agent_runtime_arn: str,\n    *,\n    name: str | None = None,\n    description: str | None = None,\n) -> _A2AClient:\n    \"\"\"SigV4-authenticated client for a Bedrock AgentCore runtime.\"\"\"\n    return _build(\n        AgentCoreA2aClientConfig.with_iam_auth(agent_runtime_arn),\n        name=name,\n        description=description,\n    )`;\n\nconst STRANDS_JWT_OLD = `    @staticmethod\n    def with_jwt_auth(\n        agent_runtime_arn: str,\n        access_token_provider: Callable[[], str],\n        *,\n        name: str | None = None,\n        description: str | None = None,\n    ) -> A2AAgent:\n        \"\"\"Bearer-authenticated client for a Bedrock AgentCore runtime.\"\"\"\n        return _build(\n            AgentCoreA2aClientConfig.with_jwt_auth(\n                agent_runtime_arn, access_token_provider\n            ),\n            name=name,\n            description=description,\n        )`;\n\nconst STRANDS_JWT_NEW = `@staticmethod\ndef with_jwt_auth(\n    agent_runtime_arn: str,\n    access_token_provider: Callable[[], str],\n    *,\n    name: str | None = None,\n    description: str | None = None,\n) -> _A2AClient:\n    \"\"\"Bearer-authenticated client for a Bedrock AgentCore runtime.\"\"\"\n    return _build(\n        AgentCoreA2aClientConfig.with_jwt_auth(\n            agent_runtime_arn, access_token_provider\n        ),\n        name=name,\n        description=description,\n    )`;\n\nconst STRANDS_NOAUTH_OLD = `    @staticmethod\n    def without_auth(\n        url: str,\n        *,\n        name: str | None = None,\n        description: str | None = None,\n    ) -> A2AAgent:\n        \"\"\"Plain-HTTP client — for local dev.\"\"\"\n        return _build(\n            AgentCoreA2aClientConfig.without_auth(url),\n            name=name,\n            description=description,\n        )`;\n\nconst STRANDS_NOAUTH_NEW = `@staticmethod\ndef without_auth(\n    url: str,\n    *,\n    name: str | None = None,\n    description: str | None = None,\n) -> _A2AClient:\n    \"\"\"Plain-HTTP client — for local dev.\"\"\"\n    return _build(\n        AgentCoreA2aClientConfig.without_auth(url),\n        name=name,\n        description=description,\n    )`;\n\nconst migrateStrandsCoreClient = async (\n  tree: Tree,\n  filePath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  const contents = tree.read(filePath, 'utf-8') ?? '';\n  if (!contents.includes('return A2AAgent(**kwargs)')) return;\n\n  const ready = await allMatch(tree, filePath, [\n    pyMatch(STRANDS_IMPORT1_OLD),\n    pyMatch(STRANDS_IMPORT2_OLD),\n    pyMatch(STRANDS_BUILD_OLD),\n    pyMatch(STRANDS_IAM_OLD),\n    pyMatch(STRANDS_JWT_OLD),\n    pyMatch(STRANDS_NOAUTH_OLD),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${filePath}: diverged from the generated shape - left untouched. Manually rebuild a fresh httpx.AsyncClient (and A2AAgent) per call instead of reusing the ones built at factory time (see the agent-connection generator's agentcore_a2a_client_strands.py template).`,\n    );\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_IMPORT1_OLD, STRANDS_IMPORT1_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_IMPORT2_OLD, STRANDS_IMPORT2_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_BUILD_OLD, STRANDS_BUILD_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_IAM_OLD, STRANDS_IAM_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_JWT_OLD, STRANDS_JWT_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(STRANDS_NOAUTH_OLD, STRANDS_NOAUTH_NEW),\n  );\n};\n\n// --- <target>_client_strands.py (per-target wrapper, one per connection) ---\n\nconst WRAPPER_IMPORT_OLD = 'from strands.agent.a2a_agent import A2AAgent';\n\nconst WRAPPER_CREATE_OLD = 'def create() -> A2AAgent:\\n    $body';\nconst WRAPPER_CREATE_NEW = 'def create():\\n    $body';\n\nconst migrateStrandsWrapperClient = async (\n  tree: Tree,\n  filePath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  const contents = tree.read(filePath, 'utf-8') ?? '';\n  if (!contents.includes('def create() -> A2AAgent:')) return;\n\n  const ready = await allMatch(tree, filePath, [\n    pyMatch(WRAPPER_IMPORT_OLD),\n    pyMatch(WRAPPER_CREATE_OLD),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${filePath}: diverged from the generated shape - left untouched. Manually drop the A2AAgent import and its -> A2AAgent return annotation on create() (see the py#agent#a2a-connection generator's per-target client_strands.py template).`,\n    );\n    return;\n  }\n\n  await applyGritQL(tree, filePath, `${pyMatch(WRAPPER_IMPORT_OLD)} => .`);\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(WRAPPER_CREATE_OLD, WRAPPER_CREATE_NEW),\n  );\n};\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  const filePaths: string[] = [];\n  visitNotIgnoredFiles(tree, '', (filePath) => filePaths.push(filePath));\n\n  for (const filePath of filePaths) {\n    if (filePath.endsWith('/agentcore_a2a_client_langchain.py')) {\n      await migrateLangchainCoreClient(tree, filePath, nextSteps);\n    } else if (filePath.endsWith('/agentcore_a2a_client_strands.py')) {\n      await migrateStrandsCoreClient(tree, filePath, nextSteps);\n    } else if (filePath.endsWith('_client_strands.py')) {\n      await migrateStrandsWrapperClient(tree, filePath, nextSteps);\n    }\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["visitNotIgnoredFiles","applyGritQL","matchGritQL","formatFilesInSubtree","pyMatch","snippet","pyRewrite","from","to","replacement","includes","allMatch","tree","filePath","patterns","pattern","LANGCHAIN_IMPORT_OLD","LANGCHAIN_IMPORT_NEW","LANGCHAIN_INVOKE_OLD","LANGCHAIN_INVOKE_NEW","migrateLangchainCoreClient","nextSteps","contents","read","ready","push","STRANDS_IMPORT1_OLD","STRANDS_IMPORT1_NEW","STRANDS_IMPORT2_OLD","STRANDS_IMPORT2_NEW","STRANDS_BUILD_OLD","STRANDS_BUILD_NEW","STRANDS_IAM_OLD","STRANDS_IAM_NEW","STRANDS_JWT_OLD","STRANDS_JWT_NEW","STRANDS_NOAUTH_OLD","STRANDS_NOAUTH_NEW","migrateStrandsCoreClient","WRAPPER_IMPORT_OLD","WRAPPER_CREATE_OLD","WRAPPER_CREATE_NEW","migrateStrandsWrapperClient","migration","filePaths","endsWith"],"mappings":"AAAA;;;CAGC,GACD,SAGEA,oBAAoB,QACf,aAAa;AACpB,SAASC,WAAW,EAAEC,WAAW,QAAQ,wBAAqB;AAC9D,SAASC,oBAAoB,QAAQ,2BAAwB;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,MAAMC,UAAU,CAACC,UAAoB,CAAC,mBAAmB,EAAEA,QAAQ,EAAE,CAAC;AAEtE,MAAMC,YAAY,CAACC,MAAcC;IAC/B,MAAMC,cAAcD,GAAGE,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAEF,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAEA,GAAG,EAAE,CAAC;IACpE,OAAO,GAAGJ,QAAQG,MAAM,IAAI,EAAEE,aAAa;AAC7C;AAEA,MAAME,WAAW,OACfC,MACAC,UACAC;IAEA,KAAK,MAAMC,WAAWD,SAAU;QAC9B,IAAI,CAAE,MAAMZ,YAAYU,MAAMC,UAAUE,UAAW,OAAO;IAC5D;IACA,OAAO;AACT;AAEA,8EAA8E;AAE9E,MAAMC,uBACJ;AACF,MAAMC,uBAAuB,CAAC;mEACqC,CAAC;AAEpE,MAAMC,uBAAuB,CAAC;;;;;;;;;;;;;;;;;;;;;;oBAsBV,CAAC;AAErB,MAAMC,uBAAuB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA2BV,CAAC;AAErB,MAAMC,6BAA6B,OACjCR,MACAC,UACAQ;IAEA,MAAMC,WAAWV,KAAKW,IAAI,CAACV,UAAU,YAAY;IACjD,IAAI,CAACS,SAASZ,QAAQ,CAAC,sDACrB;IAEF,MAAMc,QAAQ,MAAMb,SAASC,MAAMC,UAAU;QAC3CT,QAAQY;QACRZ,QAAQc;KACT;IAED,IAAI,CAACM,OAAO;QACVH,UAAUI,IAAI,CACZ,GAAGZ,SAAS,wPAAwP,CAAC;QAEvQ;IACF;IAEA,MAAMZ,YACJW,MACAC,UACAP,UAAUU,sBAAsBC;IAElC,MAAMhB,YACJW,MACAC,UACAP,UAAUY,sBAAsBC;AAEpC;AAEA,+EAA+E;AAE/E,MAAMO,sBAAsB;AAC5B,MAAMC,sBAAsB,CAAC;;iDAEoB,CAAC;AAElD,MAAMC,sBAAsB;AAC5B,MAAMC,sBAAsB,CAAC;;;kDAGqB,CAAC;AAEnD,MAAMC,oBAAoB,CAAC;;;;;;;;;6BASE,CAAC;AAE9B,MAAMC,oBAAoB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAiDkD,CAAC;AAE9E,MAAMC,kBAAkB,CAAC;;;;;;;;;;;;SAYhB,CAAC;AAEV,MAAMC,kBAAkB,CAAC;;;;;;;;;;;;KAYpB,CAAC;AAEN,MAAMC,kBAAkB,CAAC;;;;;;;;;;;;;;;SAehB,CAAC;AAEV,MAAMC,kBAAkB,CAAC;;;;;;;;;;;;;;;KAepB,CAAC;AAEN,MAAMC,qBAAqB,CAAC;;;;;;;;;;;;SAYnB,CAAC;AAEV,MAAMC,qBAAqB,CAAC;;;;;;;;;;;;KAYvB,CAAC;AAEN,MAAMC,2BAA2B,OAC/B1B,MACAC,UACAQ;IAEA,MAAMC,WAAWV,KAAKW,IAAI,CAACV,UAAU,YAAY;IACjD,IAAI,CAACS,SAASZ,QAAQ,CAAC,8BAA8B;IAErD,MAAMc,QAAQ,MAAMb,SAASC,MAAMC,UAAU;QAC3CT,QAAQsB;QACRtB,QAAQwB;QACRxB,QAAQ0B;QACR1B,QAAQ4B;QACR5B,QAAQ8B;QACR9B,QAAQgC;KACT;IAED,IAAI,CAACZ,OAAO;QACVH,UAAUI,IAAI,CACZ,GAAGZ,SAAS,2PAA2P,CAAC;QAE1Q;IACF;IAEA,MAAMZ,YACJW,MACAC,UACAP,UAAUoB,qBAAqBC;IAEjC,MAAM1B,YACJW,MACAC,UACAP,UAAUsB,qBAAqBC;IAEjC,MAAM5B,YACJW,MACAC,UACAP,UAAUwB,mBAAmBC;IAE/B,MAAM9B,YACJW,MACAC,UACAP,UAAU0B,iBAAiBC;IAE7B,MAAMhC,YACJW,MACAC,UACAP,UAAU4B,iBAAiBC;IAE7B,MAAMlC,YACJW,MACAC,UACAP,UAAU8B,oBAAoBC;AAElC;AAEA,8EAA8E;AAE9E,MAAME,qBAAqB;AAE3B,MAAMC,qBAAqB;AAC3B,MAAMC,qBAAqB;AAE3B,MAAMC,8BAA8B,OAClC9B,MACAC,UACAQ;IAEA,MAAMC,WAAWV,KAAKW,IAAI,CAACV,UAAU,YAAY;IACjD,IAAI,CAACS,SAASZ,QAAQ,CAAC,8BAA8B;IAErD,MAAMc,QAAQ,MAAMb,SAASC,MAAMC,UAAU;QAC3CT,QAAQmC;QACRnC,QAAQoC;KACT;IAED,IAAI,CAAChB,OAAO;QACVH,UAAUI,IAAI,CACZ,GAAGZ,SAAS,8NAA8N,CAAC;QAE7O;IACF;IAEA,MAAMZ,YAAYW,MAAMC,UAAU,GAAGT,QAAQmC,oBAAoB,KAAK,CAAC;IACvE,MAAMtC,YACJW,MACAC,UACAP,UAAUkC,oBAAoBC;AAElC;AAEA,eAAe,eAAeE,UAC5B/B,IAAU;IAEV,MAAMS,YAAsB,EAAE;IAE9B,MAAMuB,YAAsB,EAAE;IAC9B5C,qBAAqBY,MAAM,IAAI,CAACC,WAAa+B,UAAUnB,IAAI,CAACZ;IAE5D,KAAK,MAAMA,YAAY+B,UAAW;QAChC,IAAI/B,SAASgC,QAAQ,CAAC,uCAAuC;YAC3D,MAAMzB,2BAA2BR,MAAMC,UAAUQ;QACnD,OAAO,IAAIR,SAASgC,QAAQ,CAAC,qCAAqC;YAChE,MAAMP,yBAAyB1B,MAAMC,UAAUQ;QACjD,OAAO,IAAIR,SAASgC,QAAQ,CAAC,uBAAuB;YAClD,MAAMH,4BAA4B9B,MAAMC,UAAUQ;QACpD;IACF;IAEA,MAAMlB,qBAAqBS;IAE3B,OAAO;QAAES;IAAU;AACrB"}

package/src/migrations/latest/py-agent-a2a-lifespan-construction/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Move py#agent A2A agent construction (Strands and LangChain) out of module import time and into a FastAPI lifespan handler, stored on app.state; also updates with_session_id/session_id_context to use Generator instead of the deprecated Iterator return type"
+}

package/src/migrations/latest/py-agent-a2a-lifespan-construction/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/py-agent-a2a-lifespan-construction/migration.js

@@ -0,0 +1,234 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments, visitNotIgnoredFiles } from "@nx/devkit";
+import { PY_AGENT_GENERATOR_INFO } from "../../../py/agent/generator.js";
+import { addPythonDestructuredImport, applyGritQL, captureGritQLVariable, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Move py#agent A2A agent construction (Strands and LangChain) out of module
+ * import time and into a FastAPI `lifespan` handler, stored on `app.state`.
+ *
+ * The `v1.0.0-rc.61/0001-py-agent-lifespan-construction` migration (HTTP/AG-UI)
+ * deliberately left A2A alone, reasoning that `with_session_id` only touches
+ * its agent factory lazily on first use, so the eager `_agent_ctx.__enter__()`
+ * was never actually eager in practice. That held for `with_session_id`'s own
+ * laziness, but missed a separate trigger: `strands.multiagent.a2a.executor
+ * .StrandsA2AExecutor.__init__`, in its deprecated single-`agent=` mode, does
+ * `getattr(agent, "_session_manager", None)` - which the session-routing
+ * proxy's `__getattr__` happily serves by building the real underlying Agent
+ * right then, under a bogus "default" session, since no request has bound a
+ * real session id yet. That call happens inside `A2AServer.__init__`, which
+ * the old template constructed at plain module import time - so the "lazy"
+ * proxy was forced eager anyway, just one layer further down than the
+ * previous migration checked.
+ *
+ * Strands: `agent_factory=` mode sidesteps this - `StrandsA2AExecutor` takes
+ * an entirely different branch when given a factory (no `_session_manager`
+ * probe at all), and the one placeholder call `A2AServer.__init__` makes
+ * before `lifespan` has run returns a bare `SimpleNamespace` with just
+ * `name`/`description` - no `__getattr__`, nothing to force construction.
+ *
+ * LangChain: the compiled graph from `get_agent()` has no such trap, but was
+ * still built eagerly at import time (`_graph = get_agent()`). Moved into
+ * `lifespan` for the same reason HTTP/AG-UI were: it can require env vars
+ * (model id, region) or do network setup that isn't guaranteed available at
+ * import - e.g. under test collection or OpenAPI spec generation tooling.
+ *
+ * Also folds in an unrelated but adjacent fix: Pylance (Pyright) deprecates
+ * annotating a `@contextmanager`-decorated function's return type as
+ * `Iterator[T]`, in favor of the single-argument `Generator[T]` form enabled
+ * by PEP 696 default type parameters (Python 3.13+ - generated projects
+ * target >=3.14). `with_session_id_strands.py` and `session_context.py` both
+ * use this pattern. Both files are shared, protocol-agnostic files copied
+ * once per workspace (not per py#agent component), so that part scans the
+ * whole tree by basename rather than going through component metadata.
+ */ const pyMatch = (snippet)=>`language python\n\`${snippet}\``;
+const pyDelete = (snippet)=>`${pyMatch(snippet)} => .`;
+const pyRewrite = (from, to)=>{
+    const replacement = to.includes('\n') ? `raw\`${to}\`` : `\`${to}\``;
+    return `${pyMatch(from)} => ${replacement}`;
+};
+const AGENT_ENTER = '_agent = _agent_ctx.__enter__()';
+const OLD_AGENT_CONTEXT = `_agent_ctx = with_session_id(
+    get_agent,
+    name="$name",
+    description="A Strands Agent exposed via the Agent-to-Agent (A2A) protocol.",
+)`;
+const NEW_CONSTANTS_AND_LIFESPAN = `AGENT_NAME = "$name"
+AGENT_DESCRIPTION = "A Strands Agent exposed via the Agent-to-Agent (A2A) protocol."
+
+# A2AServer.__init__ calls agent_factory once, synchronously, before the lifespan
+# below has run - this is what it reads name/description from at that point.
+# The cast is a lie about runtime shape, not behavior: only .name/.description
+# are ever read off this value.
+_card_placeholder = cast(
+    Agent, SimpleNamespace(name=AGENT_NAME, description=AGENT_DESCRIPTION)
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    with with_session_id(
+        get_agent,
+        name=AGENT_NAME,
+        description=AGENT_DESCRIPTION,
+    ) as agent:
+        app.state.agent = agent
+        yield`;
+const A2A_SERVER_STATEMENT = 'a2a_server = A2AServer($args)';
+const OLD_MOUNT_STATEMENT = 'app.mount("/", a2a_server.to_fastapi_app())';
+const OLD_FASTAPI_APP = 'app = FastAPI()';
+const NEW_FASTAPI_APP = 'app = FastAPI(lifespan=lifespan)';
+const SERVER_MATCH = 'language python\n`A2AServer($args)` where { $args <: contains `agent=_agent` }';
+const allMatch = async (tree, filePath, patterns)=>{
+    for (const pattern of patterns){
+        if (!await matchGritQL(tree, filePath, pattern)) return false;
+    }
+    return true;
+};
+const migrateStrandsA2AAgent = async (tree, mainPath, nextSteps)=>{
+    if (!tree.exists(mainPath)) return;
+    const contents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!contents.includes('_agent_ctx = with_session_id(')) return;
+    const ready = await allMatch(tree, mainPath, [
+        pyMatch('import logging'),
+        pyMatch('from $mod import session_id_context, with_session_id'),
+        pyMatch(OLD_AGENT_CONTEXT),
+        pyMatch(AGENT_ENTER),
+        pyMatch(OLD_FASTAPI_APP),
+        pyMatch(OLD_MOUNT_STATEMENT),
+        SERVER_MATCH
+    ]);
+    const diverged = ()=>{
+        nextSteps.push(`${mainPath}: diverged from the generated Strands A2A shape - left untouched. Manually rebuild the agent inside the FastAPI \`lifespan\` and have \`agent_factory\` read it off \`app.state\` (see the py#agent generator's strands/a2a template).`);
+    };
+    if (!ready) {
+        diverged();
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'SimpleNamespace'
+    ], 'types');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'cast'
+    ], 'typing');
+    await addPythonDestructuredImport(tree, mainPath, [
+        'Agent'
+    ], 'strands');
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_AGENT_CONTEXT, NEW_CONSTANTS_AND_LIFESPAN));
+    await applyGritQL(tree, mainPath, pyDelete(AGENT_ENTER));
+    // Swap the kwarg while the call is still in its original spot (any extra
+    // kwargs a user added are left alone), then capture the whole arg list so
+    // it can be reinserted at the call's new home below.
+    await applyGritQL(tree, mainPath, pyRewrite('agent=_agent', 'agent_factory=lambda _context_id: getattr(app.state, "agent", _card_placeholder)'));
+    const capturedArgs = await captureGritQLVariable(tree, mainPath, `language python\n\`${A2A_SERVER_STATEMENT}\``, 'args');
+    if (capturedArgs === undefined) {
+        diverged();
+        return;
+    }
+    await applyGritQL(tree, mainPath, pyDelete(A2A_SERVER_STATEMENT));
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_FASTAPI_APP, NEW_FASTAPI_APP));
+    await applyGritQL(tree, mainPath, pyRewrite(OLD_MOUNT_STATEMENT, `a2a_server = A2AServer(${capturedArgs})\n\n${OLD_MOUNT_STATEMENT}`));
+};
+// --- LangChain A2A -----------------------------------------------------------
+const LANGCHAIN_GRAPH_OLD = '_graph = get_agent()';
+const LANGCHAIN_LIFESPAN_NEW = `@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.agent = get_agent()
+    yield`;
+const LANGCHAIN_GRAPH_INVOKE_OLD = '_graph.ainvoke($args)';
+const LANGCHAIN_GRAPH_INVOKE_NEW = 'app.state.agent.ainvoke($args)';
+const LANGCHAIN_APP_OLD = 'app = FastAPI(title="$name")';
+const LANGCHAIN_APP_NEW = 'app = FastAPI(title="$name", lifespan=lifespan)';
+const migrateLangchainA2AAgent = async (tree, mainPath, nextSteps)=>{
+    if (!tree.exists(mainPath)) return;
+    const contents = tree.read(mainPath, 'utf-8') ?? '';
+    if (!contents.includes(LANGCHAIN_GRAPH_OLD)) return;
+    const ready = await allMatch(tree, mainPath, [
+        pyMatch(LANGCHAIN_GRAPH_OLD),
+        pyMatch('from .agent import get_agent'),
+        pyMatch(LANGCHAIN_GRAPH_INVOKE_OLD),
+        pyMatch(LANGCHAIN_APP_OLD)
+    ]);
+    if (!ready) {
+        nextSteps.push(`${mainPath}: diverged from the generated LangChain A2A shape - left untouched. Manually wrap \`get_agent()\` in a \`lifespan\` handler storing the graph on \`app.state.agent\` (see the py#agent generator's langchain/a2a template).`);
+        return;
+    }
+    await addPythonDestructuredImport(tree, mainPath, [
+        'asynccontextmanager'
+    ], 'contextlib');
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_GRAPH_OLD, LANGCHAIN_LIFESPAN_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_GRAPH_INVOKE_OLD, LANGCHAIN_GRAPH_INVOKE_NEW));
+    await applyGritQL(tree, mainPath, pyRewrite(LANGCHAIN_APP_OLD, LANGCHAIN_APP_NEW));
+};
+// --- Iterator -> Generator (with_session_id_strands.py / session_context.py) ---
+const WITH_SESSION_ID_IMPORT_OLD = 'from collections.abc import Callable, Iterator';
+const WITH_SESSION_ID_IMPORT_NEW = 'from collections.abc import Callable, Generator';
+const migrateWithSessionId = async (tree, filePath, nextSteps)=>{
+    const contents = tree.read(filePath, 'utf-8') ?? '';
+    if (!contents.includes('Iterator[Any]')) return;
+    const ready = await allMatch(tree, filePath, [
+        pyMatch(WITH_SESSION_ID_IMPORT_OLD),
+        pyMatch('Iterator[Any]')
+    ]);
+    if (!ready) {
+        nextSteps.push(`${filePath}: diverged from the generated shape - left untouched. Manually change the \`Iterator\` import and \`Iterator[Any]\` return annotation on \`with_session_id\` to \`Generator\`/\`Generator[Any]\` (see the agent-connection generator's with_session_id_strands.py template).`);
+        return;
+    }
+    await applyGritQL(tree, filePath, pyRewrite(WITH_SESSION_ID_IMPORT_OLD, WITH_SESSION_ID_IMPORT_NEW));
+    await applyGritQL(tree, filePath, pyRewrite('Iterator[Any]', 'Generator[Any]'));
+};
+const SESSION_CONTEXT_IMPORT_OLD = 'from collections.abc import Iterator';
+const SESSION_CONTEXT_IMPORT_NEW = 'from collections.abc import Generator';
+const migrateSessionContext = async (tree, filePath, nextSteps)=>{
+    const contents = tree.read(filePath, 'utf-8') ?? '';
+    if (!contents.includes('Iterator[None]')) return;
+    const ready = await allMatch(tree, filePath, [
+        pyMatch(SESSION_CONTEXT_IMPORT_OLD),
+        pyMatch('Iterator[None]')
+    ]);
+    if (!ready) {
+        nextSteps.push(`${filePath}: diverged from the generated shape - left untouched. Manually change the \`Iterator\` import and \`Iterator[None]\` return annotation on \`session_id_context\` to \`Generator\`/\`Generator[None]\` (see the agent-connection generator's session_context.py template).`);
+        return;
+    }
+    await applyGritQL(tree, filePath, pyRewrite(SESSION_CONTEXT_IMPORT_OLD, SESSION_CONTEXT_IMPORT_NEW));
+    await applyGritQL(tree, filePath, pyRewrite('Iterator[None]', 'Generator[None]'));
+};
+const findAgentComponents = (components)=>(components ?? []).filter((component)=>component.generator === PY_AGENT_GENERATOR_INFO.id);
+export default async function migration(tree) {
+    const nextSteps = [];
+    for (const project of getProjects(tree).values()){
+        const components = findAgentComponents(project.metadata?.components);
+        for (const component of components){
+            if (!component.path || component.protocol !== 'a2a') {
+                continue;
+            }
+            const componentDir = component.path.endsWith('/agent.py') ? component.path.slice(0, -'/agent.py'.length) : component.path;
+            const mainPath = joinPathFragments(project.root, componentDir, 'main.py');
+            if ((component.framework ?? 'strands') === 'langchain') {
+                await migrateLangchainA2AAgent(tree, mainPath, nextSteps);
+            } else {
+                await migrateStrandsA2AAgent(tree, mainPath, nextSteps);
+            }
+        }
+    }
+    const filePaths = [];
+    visitNotIgnoredFiles(tree, '', (filePath)=>filePaths.push(filePath));
+    for (const filePath of filePaths){
+        if (filePath.endsWith('/with_session_id_strands.py')) {
+            await migrateWithSessionId(tree, filePath, nextSteps);
+        } else if (filePath.endsWith('/session_context.py')) {
+            await migrateSessionContext(tree, filePath, nextSteps);
+        }
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/py-agent-a2a-lifespan-construction/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/py-agent-a2a-lifespan-construction/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  getProjects,\n  joinPathFragments,\n  type MigrationReturnObject,\n  type Tree,\n  visitNotIgnoredFiles,\n} from '@nx/devkit';\nimport { PY_AGENT_GENERATOR_INFO } from '../../../py/agent/generator';\nimport {\n  addPythonDestructuredImport,\n  applyGritQL,\n  captureGritQLVariable,\n  matchGritQL,\n} from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\nimport type { ComponentMetadata } from '../../../utils/nx';\n\n/**\n * Move py#agent A2A agent construction (Strands and LangChain) out of module\n * import time and into a FastAPI `lifespan` handler, stored on `app.state`.\n *\n * The `v1.0.0-rc.61/0001-py-agent-lifespan-construction` migration (HTTP/AG-UI)\n * deliberately left A2A alone, reasoning that `with_session_id` only touches\n * its agent factory lazily on first use, so the eager `_agent_ctx.__enter__()`\n * was never actually eager in practice. That held for `with_session_id`'s own\n * laziness, but missed a separate trigger: `strands.multiagent.a2a.executor\n * .StrandsA2AExecutor.__init__`, in its deprecated single-`agent=` mode, does\n * `getattr(agent, \"_session_manager\", None)` - which the session-routing\n * proxy's `__getattr__` happily serves by building the real underlying Agent\n * right then, under a bogus \"default\" session, since no request has bound a\n * real session id yet. That call happens inside `A2AServer.__init__`, which\n * the old template constructed at plain module import time - so the \"lazy\"\n * proxy was forced eager anyway, just one layer further down than the\n * previous migration checked.\n *\n * Strands: `agent_factory=` mode sidesteps this - `StrandsA2AExecutor` takes\n * an entirely different branch when given a factory (no `_session_manager`\n * probe at all), and the one placeholder call `A2AServer.__init__` makes\n * before `lifespan` has run returns a bare `SimpleNamespace` with just\n * `name`/`description` - no `__getattr__`, nothing to force construction.\n *\n * LangChain: the compiled graph from `get_agent()` has no such trap, but was\n * still built eagerly at import time (`_graph = get_agent()`). Moved into\n * `lifespan` for the same reason HTTP/AG-UI were: it can require env vars\n * (model id, region) or do network setup that isn't guaranteed available at\n * import - e.g. under test collection or OpenAPI spec generation tooling.\n *\n * Also folds in an unrelated but adjacent fix: Pylance (Pyright) deprecates\n * annotating a `@contextmanager`-decorated function's return type as\n * `Iterator[T]`, in favor of the single-argument `Generator[T]` form enabled\n * by PEP 696 default type parameters (Python 3.13+ - generated projects\n * target >=3.14). `with_session_id_strands.py` and `session_context.py` both\n * use this pattern. Both files are shared, protocol-agnostic files copied\n * once per workspace (not per py#agent component), so that part scans the\n * whole tree by basename rather than going through component metadata.\n */\nconst pyMatch = (snippet: string) => `language python\\n\\`${snippet}\\``;\n\nconst pyDelete = (snippet: string) => `${pyMatch(snippet)} => .`;\n\nconst pyRewrite = (from: string, to: string): string => {\n  const replacement = to.includes('\\n') ? `raw\\`${to}\\`` : `\\`${to}\\``;\n  return `${pyMatch(from)} => ${replacement}`;\n};\n\nconst AGENT_ENTER = '_agent = _agent_ctx.__enter__()';\n\nconst OLD_AGENT_CONTEXT = `_agent_ctx = with_session_id(\n    get_agent,\n    name=\"$name\",\n    description=\"A Strands Agent exposed via the Agent-to-Agent (A2A) protocol.\",\n)`;\n\nconst NEW_CONSTANTS_AND_LIFESPAN = `AGENT_NAME = \"$name\"\nAGENT_DESCRIPTION = \"A Strands Agent exposed via the Agent-to-Agent (A2A) protocol.\"\n\n# A2AServer.__init__ calls agent_factory once, synchronously, before the lifespan\n# below has run - this is what it reads name/description from at that point.\n# The cast is a lie about runtime shape, not behavior: only .name/.description\n# are ever read off this value.\n_card_placeholder = cast(\n    Agent, SimpleNamespace(name=AGENT_NAME, description=AGENT_DESCRIPTION)\n)\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    with with_session_id(\n        get_agent,\n        name=AGENT_NAME,\n        description=AGENT_DESCRIPTION,\n    ) as agent:\n        app.state.agent = agent\n        yield`;\n\nconst A2A_SERVER_STATEMENT = 'a2a_server = A2AServer($args)';\n\nconst OLD_MOUNT_STATEMENT = 'app.mount(\"/\", a2a_server.to_fastapi_app())';\n\nconst OLD_FASTAPI_APP = 'app = FastAPI()';\n\nconst NEW_FASTAPI_APP = 'app = FastAPI(lifespan=lifespan)';\n\nconst SERVER_MATCH =\n  'language python\\n`A2AServer($args)` where { $args <: contains `agent=_agent` }';\n\nconst allMatch = async (\n  tree: Tree,\n  filePath: string,\n  patterns: string[],\n): Promise<boolean> => {\n  for (const pattern of patterns) {\n    if (!(await matchGritQL(tree, filePath, pattern))) return false;\n  }\n  return true;\n};\n\nconst migrateStrandsA2AAgent = async (\n  tree: Tree,\n  mainPath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(mainPath)) return;\n\n  const contents = tree.read(mainPath, 'utf-8') ?? '';\n  if (!contents.includes('_agent_ctx = with_session_id(')) return;\n\n  const ready = await allMatch(tree, mainPath, [\n    pyMatch('import logging'),\n    pyMatch('from $mod import session_id_context, with_session_id'),\n    pyMatch(OLD_AGENT_CONTEXT),\n    pyMatch(AGENT_ENTER),\n    pyMatch(OLD_FASTAPI_APP),\n    pyMatch(OLD_MOUNT_STATEMENT),\n    SERVER_MATCH,\n  ]);\n\n  const diverged = () => {\n    nextSteps.push(\n      `${mainPath}: diverged from the generated Strands A2A shape - left untouched. Manually rebuild the agent inside the FastAPI \\`lifespan\\` and have \\`agent_factory\\` read it off \\`app.state\\` (see the py#agent generator's strands/a2a template).`,\n    );\n  };\n\n  if (!ready) {\n    diverged();\n    return;\n  }\n\n  await addPythonDestructuredImport(\n    tree,\n    mainPath,\n    ['asynccontextmanager'],\n    'contextlib',\n  );\n  await addPythonDestructuredImport(\n    tree,\n    mainPath,\n    ['SimpleNamespace'],\n    'types',\n  );\n  await addPythonDestructuredImport(tree, mainPath, ['cast'], 'typing');\n  await addPythonDestructuredImport(tree, mainPath, ['Agent'], 'strands');\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(OLD_AGENT_CONTEXT, NEW_CONSTANTS_AND_LIFESPAN),\n  );\n  await applyGritQL(tree, mainPath, pyDelete(AGENT_ENTER));\n\n  // Swap the kwarg while the call is still in its original spot (any extra\n  // kwargs a user added are left alone), then capture the whole arg list so\n  // it can be reinserted at the call's new home below.\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(\n      'agent=_agent',\n      'agent_factory=lambda _context_id: getattr(app.state, \"agent\", _card_placeholder)',\n    ),\n  );\n  const capturedArgs = await captureGritQLVariable(\n    tree,\n    mainPath,\n    `language python\\n\\`${A2A_SERVER_STATEMENT}\\``,\n    'args',\n  );\n  if (capturedArgs === undefined) {\n    diverged();\n    return;\n  }\n\n  await applyGritQL(tree, mainPath, pyDelete(A2A_SERVER_STATEMENT));\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(OLD_FASTAPI_APP, NEW_FASTAPI_APP),\n  );\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(\n      OLD_MOUNT_STATEMENT,\n      `a2a_server = A2AServer(${capturedArgs})\\n\\n${OLD_MOUNT_STATEMENT}`,\n    ),\n  );\n};\n\n// --- LangChain A2A -----------------------------------------------------------\n\nconst LANGCHAIN_GRAPH_OLD = '_graph = get_agent()';\n\nconst LANGCHAIN_LIFESPAN_NEW = `@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    app.state.agent = get_agent()\n    yield`;\n\nconst LANGCHAIN_GRAPH_INVOKE_OLD = '_graph.ainvoke($args)';\n\nconst LANGCHAIN_GRAPH_INVOKE_NEW = 'app.state.agent.ainvoke($args)';\n\nconst LANGCHAIN_APP_OLD = 'app = FastAPI(title=\"$name\")';\n\nconst LANGCHAIN_APP_NEW = 'app = FastAPI(title=\"$name\", lifespan=lifespan)';\n\nconst migrateLangchainA2AAgent = async (\n  tree: Tree,\n  mainPath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  if (!tree.exists(mainPath)) return;\n\n  const contents = tree.read(mainPath, 'utf-8') ?? '';\n  if (!contents.includes(LANGCHAIN_GRAPH_OLD)) return;\n\n  const ready = await allMatch(tree, mainPath, [\n    pyMatch(LANGCHAIN_GRAPH_OLD),\n    pyMatch('from .agent import get_agent'),\n    pyMatch(LANGCHAIN_GRAPH_INVOKE_OLD),\n    pyMatch(LANGCHAIN_APP_OLD),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${mainPath}: diverged from the generated LangChain A2A shape - left untouched. Manually wrap \\`get_agent()\\` in a \\`lifespan\\` handler storing the graph on \\`app.state.agent\\` (see the py#agent generator's langchain/a2a template).`,\n    );\n    return;\n  }\n\n  await addPythonDestructuredImport(\n    tree,\n    mainPath,\n    ['asynccontextmanager'],\n    'contextlib',\n  );\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(LANGCHAIN_GRAPH_OLD, LANGCHAIN_LIFESPAN_NEW),\n  );\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(LANGCHAIN_GRAPH_INVOKE_OLD, LANGCHAIN_GRAPH_INVOKE_NEW),\n  );\n  await applyGritQL(\n    tree,\n    mainPath,\n    pyRewrite(LANGCHAIN_APP_OLD, LANGCHAIN_APP_NEW),\n  );\n};\n\n// --- Iterator -> Generator (with_session_id_strands.py / session_context.py) ---\n\nconst WITH_SESSION_ID_IMPORT_OLD =\n  'from collections.abc import Callable, Iterator';\nconst WITH_SESSION_ID_IMPORT_NEW =\n  'from collections.abc import Callable, Generator';\n\nconst migrateWithSessionId = async (\n  tree: Tree,\n  filePath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  const contents = tree.read(filePath, 'utf-8') ?? '';\n  if (!contents.includes('Iterator[Any]')) return;\n\n  const ready = await allMatch(tree, filePath, [\n    pyMatch(WITH_SESSION_ID_IMPORT_OLD),\n    pyMatch('Iterator[Any]'),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${filePath}: diverged from the generated shape - left untouched. Manually change the \\`Iterator\\` import and \\`Iterator[Any]\\` return annotation on \\`with_session_id\\` to \\`Generator\\`/\\`Generator[Any]\\` (see the agent-connection generator's with_session_id_strands.py template).`,\n    );\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(WITH_SESSION_ID_IMPORT_OLD, WITH_SESSION_ID_IMPORT_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite('Iterator[Any]', 'Generator[Any]'),\n  );\n};\n\nconst SESSION_CONTEXT_IMPORT_OLD = 'from collections.abc import Iterator';\nconst SESSION_CONTEXT_IMPORT_NEW = 'from collections.abc import Generator';\n\nconst migrateSessionContext = async (\n  tree: Tree,\n  filePath: string,\n  nextSteps: string[],\n): Promise<void> => {\n  const contents = tree.read(filePath, 'utf-8') ?? '';\n  if (!contents.includes('Iterator[None]')) return;\n\n  const ready = await allMatch(tree, filePath, [\n    pyMatch(SESSION_CONTEXT_IMPORT_OLD),\n    pyMatch('Iterator[None]'),\n  ]);\n\n  if (!ready) {\n    nextSteps.push(\n      `${filePath}: diverged from the generated shape - left untouched. Manually change the \\`Iterator\\` import and \\`Iterator[None]\\` return annotation on \\`session_id_context\\` to \\`Generator\\`/\\`Generator[None]\\` (see the agent-connection generator's session_context.py template).`,\n    );\n    return;\n  }\n\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite(SESSION_CONTEXT_IMPORT_OLD, SESSION_CONTEXT_IMPORT_NEW),\n  );\n  await applyGritQL(\n    tree,\n    filePath,\n    pyRewrite('Iterator[None]', 'Generator[None]'),\n  );\n};\n\nconst findAgentComponents = (\n  components: ComponentMetadata[] | undefined,\n): ComponentMetadata[] =>\n  (components ?? []).filter(\n    (component) => component.generator === PY_AGENT_GENERATOR_INFO.id,\n  );\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  for (const project of getProjects(tree).values()) {\n    const components = findAgentComponents(\n      (project.metadata as { components?: ComponentMetadata[] })?.components,\n    );\n\n    for (const component of components) {\n      if (!component.path || component.protocol !== 'a2a') {\n        continue;\n      }\n\n      const componentDir = component.path.endsWith('/agent.py')\n        ? component.path.slice(0, -'/agent.py'.length)\n        : component.path;\n      const mainPath = joinPathFragments(project.root, componentDir, 'main.py');\n\n      if ((component.framework ?? 'strands') === 'langchain') {\n        await migrateLangchainA2AAgent(tree, mainPath, nextSteps);\n      } else {\n        await migrateStrandsA2AAgent(tree, mainPath, nextSteps);\n      }\n    }\n  }\n\n  const filePaths: string[] = [];\n  visitNotIgnoredFiles(tree, '', (filePath) => filePaths.push(filePath));\n\n  for (const filePath of filePaths) {\n    if (filePath.endsWith('/with_session_id_strands.py')) {\n      await migrateWithSessionId(tree, filePath, nextSteps);\n    } else if (filePath.endsWith('/session_context.py')) {\n      await migrateSessionContext(tree, filePath, nextSteps);\n    }\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["getProjects","joinPathFragments","visitNotIgnoredFiles","PY_AGENT_GENERATOR_INFO","addPythonDestructuredImport","applyGritQL","captureGritQLVariable","matchGritQL","formatFilesInSubtree","pyMatch","snippet","pyDelete","pyRewrite","from","to","replacement","includes","AGENT_ENTER","OLD_AGENT_CONTEXT","NEW_CONSTANTS_AND_LIFESPAN","A2A_SERVER_STATEMENT","OLD_MOUNT_STATEMENT","OLD_FASTAPI_APP","NEW_FASTAPI_APP","SERVER_MATCH","allMatch","tree","filePath","patterns","pattern","migrateStrandsA2AAgent","mainPath","nextSteps","exists","contents","read","ready","diverged","push","capturedArgs","undefined","LANGCHAIN_GRAPH_OLD","LANGCHAIN_LIFESPAN_NEW","LANGCHAIN_GRAPH_INVOKE_OLD","LANGCHAIN_GRAPH_INVOKE_NEW","LANGCHAIN_APP_OLD","LANGCHAIN_APP_NEW","migrateLangchainA2AAgent","WITH_SESSION_ID_IMPORT_OLD","WITH_SESSION_ID_IMPORT_NEW","migrateWithSessionId","SESSION_CONTEXT_IMPORT_OLD","SESSION_CONTEXT_IMPORT_NEW","migrateSessionContext","findAgentComponents","components","filter","component","generator","id","migration","project","values","metadata","path","protocol","componentDir","endsWith","slice","length","root","framework","filePaths"],"mappings":"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"}

package/src/migrations/latest/smithy-server-package-rename/metadata.json

@@ -0,0 +1,3 @@
+{
+  "description": "Move Smithy APIs onto the renamed @smithy/server-* packages"
+}

package/src/migrations/latest/smithy-server-package-rename/migration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type MigrationReturnObject, type Tree } from '@nx/devkit';
+export default function migration(tree: Tree): Promise<MigrationReturnObject>;

package/src/migrations/latest/smithy-server-package-rename/migration.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { getProjects, joinPathFragments, readJson, updateJson } from "@nx/devkit";
+import { applyGritQL, matchGritQL } from "../../../utils/ast.js";
+import { formatFilesInSubtree } from "../../../utils/format.js";
+/**
+ * Move a Smithy API onto the renamed `@smithy/server-*` packages.
+ *
+ * The Smithy server runtime was published as `@aws-smithy/server-*`, stopped at
+ * `1.0.0-alpha.10`, and was renamed to `@smithy/server-*`. The Server SDK codegen
+ * this release vends generates against the renamed packages, importing
+ * `AuthScheme` and `ServerInterceptor` — types the deprecated packages never
+ * exported — so a workspace left on them fails to bundle its SSDK.
+ *
+ * Both the imports and the declarations move: the renamed packages are no longer
+ * the same names, so the version sync cannot recognise the old ones and would
+ * leave them installed alongside the new.
+ *
+ * Guardrails:
+ * - Scoped to a Smithy API project this plugin generated, found through the
+ *   metadata the generator records. A file of the user's own that happens to
+ *   import these packages is left alone.
+ * - Imports are rewritten by module specifier, preserving whatever the file
+ *   imports from it, so a project that imports more than the generated shape
+ *   keeps its own bindings. Only the two packages the generators vend are
+ *   matched: `@aws-smithy/server-common` is a transitive dependency of those and
+ *   is never declared or imported directly.
+ * - A manifest is only rewritten where it declares the old package, and the new
+ *   name takes the field the old one occupied. A workspace that already moved
+ *   itself is left alone.
+ * - Idempotent: nothing matches the old names once they are gone.
+ *
+ * Every value here is hardcoded rather than read from the generators: this runs
+ * once, for the release that renamed the packages, so it has to keep applying
+ * that exact change however far the vended versions and generators move
+ * afterwards.
+ */ /** The id the `ts#smithy-api` generator records on the projects it creates. */ const SMITHY_API_GENERATOR_ID = 'ts#smithy-api';
+/** The renamed packages, old name to new, with the version this release vends. */ const RENAMES = [
+    {
+        old: '@aws-smithy/server-apigateway',
+        renamed: '@smithy/server-apigateway',
+        version: '0.2.0'
+    },
+    {
+        old: '@aws-smithy/server-node',
+        renamed: '@smithy/server-node',
+        version: '0.2.0'
+    }
+];
+/** The source files the generators give these imports. */ const SOURCE_FILES = [
+    'src/handler.ts',
+    'src/local-server.ts'
+];
+/**
+ * Rewrite an import's module specifier, keeping its bindings — `$bindings` holds
+ * whatever the file imports, so a binding the project added survives the move.
+ */ const importPattern = (from, to)=>`\`import { $bindings } from '${from}'\` => \`import { $bindings } from '${to}'\``;
+/** Whether the file still imports the old package under any other form. */ const hasRemainingImport = (from)=>`\`import $_ from '${from}'\``;
+/** Rename the packages a manifest declares, reporting whether anything changed. */ const renameInManifest = (tree, path)=>{
+    if (!tree.exists(path)) {
+        return false;
+    }
+    const json = readJson(tree, path);
+    const fields = [
+        'dependencies',
+        'devDependencies'
+    ].filter((field)=>RENAMES.some(({ old })=>json[field]?.[old]));
+    if (fields.length === 0) {
+        return false;
+    }
+    updateJson(tree, path, (manifest)=>{
+        for (const field of fields){
+            const declared = manifest[field];
+            for (const { old, renamed, version } of RENAMES){
+                if (!declared[old]) {
+                    continue;
+                }
+                delete declared[old];
+                // The vended pin rather than the old specifier: the renamed line
+                // restarted at 0.x, so carrying `1.0.0-alpha.10` across resolves nothing.
+                declared[renamed] = version;
+            }
+        }
+        return manifest;
+    });
+    return true;
+};
+const divergedNextStep = (path)=>`${path}: still imports a deprecated '@aws-smithy/server-*' package in a form this migration does not rewrite - update the import to the matching '@smithy/server-*' package by hand.`;
+export default async function migration(tree) {
+    const nextSteps = [];
+    // Only a Smithy API project this plugin generated carries these packages.
+    const projects = [
+        ...getProjects(tree).values()
+    ].filter((project)=>project.metadata?.generator === SMITHY_API_GENERATOR_ID);
+    for (const project of projects){
+        for (const sourceFile of SOURCE_FILES){
+            const sourcePath = joinPathFragments(project.root, sourceFile);
+            if (!tree.exists(sourcePath)) {
+                continue;
+            }
+            for (const { old, renamed } of RENAMES){
+                await applyGritQL(tree, sourcePath, importPattern(old, renamed));
+                // A namespace or default import of the same package is left as it is —
+                // reported rather than rewritten, so a diverged file is never clobbered.
+                if (await matchGritQL(tree, sourcePath, hasRemainingImport(old))) {
+                    nextSteps.push(divergedNextStep(sourcePath));
+                }
+            }
+        }
+        renameInManifest(tree, joinPathFragments(project.root, 'package.json'));
+    }
+    // A workspace may hoist these to the root manifest, which is not an nx project.
+    if (projects.length > 0) {
+        renameInManifest(tree, 'package.json');
+    }
+    await formatFilesInSubtree(tree);
+    return {
+        nextSteps
+    };
+}
+
+//# sourceMappingURL=migration.js.map

package/src/migrations/latest/smithy-server-package-rename/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/migrations/latest/smithy-server-package-rename/migration.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  getProjects,\n  joinPathFragments,\n  type MigrationReturnObject,\n  readJson,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport { applyGritQL, matchGritQL } from '../../../utils/ast';\nimport { formatFilesInSubtree } from '../../../utils/format';\n\n/**\n * Move a Smithy API onto the renamed `@smithy/server-*` packages.\n *\n * The Smithy server runtime was published as `@aws-smithy/server-*`, stopped at\n * `1.0.0-alpha.10`, and was renamed to `@smithy/server-*`. The Server SDK codegen\n * this release vends generates against the renamed packages, importing\n * `AuthScheme` and `ServerInterceptor` — types the deprecated packages never\n * exported — so a workspace left on them fails to bundle its SSDK.\n *\n * Both the imports and the declarations move: the renamed packages are no longer\n * the same names, so the version sync cannot recognise the old ones and would\n * leave them installed alongside the new.\n *\n * Guardrails:\n * - Scoped to a Smithy API project this plugin generated, found through the\n *   metadata the generator records. A file of the user's own that happens to\n *   import these packages is left alone.\n * - Imports are rewritten by module specifier, preserving whatever the file\n *   imports from it, so a project that imports more than the generated shape\n *   keeps its own bindings. Only the two packages the generators vend are\n *   matched: `@aws-smithy/server-common` is a transitive dependency of those and\n *   is never declared or imported directly.\n * - A manifest is only rewritten where it declares the old package, and the new\n *   name takes the field the old one occupied. A workspace that already moved\n *   itself is left alone.\n * - Idempotent: nothing matches the old names once they are gone.\n *\n * Every value here is hardcoded rather than read from the generators: this runs\n * once, for the release that renamed the packages, so it has to keep applying\n * that exact change however far the vended versions and generators move\n * afterwards.\n */\n\n/** The id the `ts#smithy-api` generator records on the projects it creates. */\nconst SMITHY_API_GENERATOR_ID = 'ts#smithy-api';\n\n/** The renamed packages, old name to new, with the version this release vends. */\nconst RENAMES = [\n  {\n    old: '@aws-smithy/server-apigateway',\n    renamed: '@smithy/server-apigateway',\n    version: '0.2.0',\n  },\n  {\n    old: '@aws-smithy/server-node',\n    renamed: '@smithy/server-node',\n    version: '0.2.0',\n  },\n] as const;\n\n/** The source files the generators give these imports. */\nconst SOURCE_FILES = ['src/handler.ts', 'src/local-server.ts'];\n\n/**\n * Rewrite an import's module specifier, keeping its bindings — `$bindings` holds\n * whatever the file imports, so a binding the project added survives the move.\n */\nconst importPattern = (from: string, to: string): string =>\n  `\\`import { $bindings } from '${from}'\\` => \\`import { $bindings } from '${to}'\\``;\n\n/** Whether the file still imports the old package under any other form. */\nconst hasRemainingImport = (from: string): string =>\n  `\\`import $_ from '${from}'\\``;\n\n/** Rename the packages a manifest declares, reporting whether anything changed. */\nconst renameInManifest = (tree: Tree, path: string): boolean => {\n  if (!tree.exists(path)) {\n    return false;\n  }\n  const json = readJson(tree, path);\n  const fields = (['dependencies', 'devDependencies'] as const).filter(\n    (field) => RENAMES.some(({ old }) => json[field]?.[old]),\n  );\n  if (fields.length === 0) {\n    return false;\n  }\n  updateJson(tree, path, (manifest) => {\n    for (const field of fields) {\n      const declared = manifest[field] as Record<string, string>;\n      for (const { old, renamed, version } of RENAMES) {\n        if (!declared[old]) {\n          continue;\n        }\n        delete declared[old];\n        // The vended pin rather than the old specifier: the renamed line\n        // restarted at 0.x, so carrying `1.0.0-alpha.10` across resolves nothing.\n        declared[renamed] = version;\n      }\n    }\n    return manifest;\n  });\n  return true;\n};\n\nconst divergedNextStep = (path: string): string =>\n  `${path}: still imports a deprecated '@aws-smithy/server-*' package in a form this migration does not rewrite - update the import to the matching '@smithy/server-*' package by hand.`;\n\nexport default async function migration(\n  tree: Tree,\n): Promise<MigrationReturnObject> {\n  const nextSteps: string[] = [];\n\n  // Only a Smithy API project this plugin generated carries these packages.\n  const projects = [...getProjects(tree).values()].filter(\n    (project) =>\n      (project.metadata as { generator?: string } | undefined)?.generator ===\n      SMITHY_API_GENERATOR_ID,\n  );\n\n  for (const project of projects) {\n    for (const sourceFile of SOURCE_FILES) {\n      const sourcePath = joinPathFragments(project.root, sourceFile);\n      if (!tree.exists(sourcePath)) {\n        continue;\n      }\n      for (const { old, renamed } of RENAMES) {\n        await applyGritQL(tree, sourcePath, importPattern(old, renamed));\n        // A namespace or default import of the same package is left as it is —\n        // reported rather than rewritten, so a diverged file is never clobbered.\n        if (await matchGritQL(tree, sourcePath, hasRemainingImport(old))) {\n          nextSteps.push(divergedNextStep(sourcePath));\n        }\n      }\n    }\n\n    renameInManifest(tree, joinPathFragments(project.root, 'package.json'));\n  }\n\n  // A workspace may hoist these to the root manifest, which is not an nx project.\n  if (projects.length > 0) {\n    renameInManifest(tree, 'package.json');\n  }\n\n  await formatFilesInSubtree(tree);\n\n  return { nextSteps };\n}\n"],"names":["getProjects","joinPathFragments","readJson","updateJson","applyGritQL","matchGritQL","formatFilesInSubtree","SMITHY_API_GENERATOR_ID","RENAMES","old","renamed","version","SOURCE_FILES","importPattern","from","to","hasRemainingImport","renameInManifest","tree","path","exists","json","fields","filter","field","some","length","manifest","declared","divergedNextStep","migration","nextSteps","projects","values","project","metadata","generator","sourceFile","sourcePath","root","push"],"mappings":"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"}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-system-prompt.ts.fixture

@@ -0,0 +1,23 @@
+function buildSystemPrompt(targetLang: string): string {
+  return `You are an expert technical-documentation translator. You translate MDX documentation files from the source locale \`${config.sourceLanguage}\` into the target locale \`${targetLang}\`.
+
+Both are locale codes (ISO 639-1 / BCP-47 style, or short forms like \`jp\`, \`zh\`, \`pt\`). Translate naturally into the language the target code identifies.
+
+Use the \`fileEditor\` tool to read the files you are given and to write your translation. Read a long file in slices with \`view_range\`. Use the absolute paths exactly as given — write to the target path verbatim, never to a variation of it.
+
+Translate the prose. Everything else is copied from the source exactly as it is:
+
+- Code blocks. Reproduce each one character for character: the language and \`title\` on the opening fence, and every line of the body. Comments inside code are code — a \`# Creates a new subsegment\` stays in English. Never translate anything between the fences.
+- Inline code, URLs, link paths, \`import\` statements, component names, JSX attributes, and \`<Snippet name="..." />\` values.
+- Product, service, and people's names, and package names such as \`@aws/nx-plugin\` — translate no part of them, even where they appear in prose or in a \`title\`.
+- The MDX structure itself: frontmatter delimiters, heading levels, lists, and the blank lines between blocks. Add none and remove none.
+
+Two things do change:
+
+- In frontmatter, translate only \`title\` and \`description\`. Leave every other key and value alone. Frontmatter is YAML, so wrap a value in double quotes whenever it would otherwise begin with a character YAML reserves — for example a title starting with \`@aws/nx-plugin\` must be written as \`"@aws/nx-plugin ..."\`.
+- Rewrite link paths that embed the source locale (\`/${config.sourceLanguage}/foo\` becomes \`/${targetLang}/foo\`), and make a \`parentHeading\` match the translated heading it sits under.
+
+Write the finished file in one \`create\` call, and never with \`str_replace\` — a partial replacement silently duplicates or splices sections. Do not wrap the file in triple backticks.
+
+When the file is written, reply with a one-line summary and stop.`;
+}

package/src/migrations/latest/translate-script-whole-file-writes/files/build-user-prompt.ts.fixture

@@ -0,0 +1,96 @@
+function buildUserPrompt(file: FileToTranslate, targetLang: string): string {
+  const targetAbsPath = path.join(DOCS_DIR, targetLang, file.relativePath);
+
+  if (!file.diffPath) {
+    return `Translate \`${file.sourceAbsPath}\` into locale \`${targetLang}\` and write it to \`${targetAbsPath}\`.
+
+Read the source, then write the whole translated file with \`create\`. Always write it, even if a translation is already there — it may be out of date.`;
+  }
+
+  return `Update the \`${targetLang}\` translation of \`${file.sourceAbsPath}\`.
+
+- Source: \`${file.sourceAbsPath}\`
+- Existing translation to update: \`${targetAbsPath}\`
+- Diff of what changed in the source: \`${file.diffPath}\`
+
+Read all three. Retranslate only what the diff touched, keep the existing translated wording everywhere else, then write the whole file back with \`create\`.`;
+}
+
+const FENCE_RE = /^\s*(?:`{3,}|~{3,})/;
+
+/**
+ * Split a document into alternating prose and fenced-code segments.
+ */
+function splitOnFences(text: string): { prose: string[]; code: string[] } {
+  const prose: string[] = [];
+  const code: string[] = [];
+  let current: string[] = [];
+  let inFence = false;
+  for (const line of text.split('\n')) {
+    if (FENCE_RE.test(line)) {
+      (inFence ? code : prose).push(current.concat(line).join('\n'));
+      current = [];
+      inFence = !inFence;
+      continue;
+    }
+    current.push(line);
+  }
+  (inFence ? code : prose).push(current.join('\n'));
+  return { prose, code };
+}
+
+/**
+ * YAML frontmatter must still parse after translation. A value that begins with
+ * a character YAML reserves — most often a title starting with \`@aws/...\` —
+ * breaks the docs build, so reject it here and let the retry quote it.
+ */
+function assertFrontmatterIsParseable(text: string): void {
+  const lines = text.split('\n');
+  if (lines[0]?.trim() !== '---') return;
+  for (let i = 1; i < lines.length && lines[i].trim() !== '---'; i++) {
+    const value = lines[i].match(/^[A-Za-z0-9_-]+:\s+(\S)/)?.[1];
+    if (value && '@*&%!|>'.includes(value)) {
+      throw new Error(
+        `frontmatter line ${i + 1} starts with the reserved YAML character "${value}" and must be quoted: ${lines[i].trim()}`,
+      );
+    }
+  }
+}
+
+/**
+ * Copy the source's code blocks over the translated file's. The prompt tells the
+ * agent to reproduce them verbatim, but it occasionally translates a comment
+ * anyway, which would ship stale or broken code.
+ *
+ * A differing block count means the translation lost the document's shape —
+ * usually a section duplicated or dropped — so this throws rather than stitching
+ * mismatched blocks together, letting the caller retry.
+ */
+async function restoreCodeBlocks(
+  sourceAbsPath: string,
+  targetAbsPath: string,
+): Promise<void> {
+  const source = splitOnFences(await fs.readFile(sourceAbsPath, 'utf-8'));
+  const target = splitOnFences(await fs.readFile(targetAbsPath, 'utf-8'));
+
+  if (source.code.length !== target.code.length) {
+    throw new Error(
+      `translation has ${target.code.length} code block(s) but the source has ${source.code.length}`,
+    );
+  }
+  if (source.code.length === 0) return;
+
+  const merged = target.prose.flatMap((chunk, i) =>
+    i < source.code.length ? [chunk, source.code[i]] : [chunk],
+  );
+  await fs.writeFile(targetAbsPath, merged.join('\n'), 'utf-8');
+}
+
+/**
+ * Number of times to retry a single (file x language) translation. Large files
+ * occasionally hit transient Bedrock streaming errors; a fresh agent invocation
+ * re-reads the files from disk, so retries are idempotent.
+ */
+const TRANSLATE_MAX_ATTEMPTS = 4;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

package/src/migrations/latest/translate-script-whole-file-writes/files/config-path.ts.fixture

@@ -0,0 +1 @@
+const CONFIG_PATH = path.resolve(SCRIPTS_DIR, 'translate.config.json');

package/src/migrations/latest/translate-script-whole-file-writes/files/file-to-translate.ts.fixture

@@ -0,0 +1,10 @@
+interface FileToTranslate {
+  relativePath: string;
+  sourceAbsPath: string;
+  /**
+   * Path to a file holding the source diff, or undefined when there is no prior
+   * translation to update. Passed to the agent as a path rather than inlined
+   * into the prompt, so it reads only as much of it as it needs.
+   */
+  diffPath?: string;
+}