Simplify flat Dockerfile helpers

Add a repository-wide `<corridor>` block to `AGENTS.md` requiring agents
to plan first and run Corridor `analyzePlan` before generating or
modifying code. The tags are explicit and balanced so Corridor-specific
guidance remains scoped.

Validation: `git diff --check` and a tag-balance assertion.

---------

Co-authored-by: langsmith-fleet[bot] <langsmith-fleet[bot]@users.noreply.github.com>

.github/workflows/_integration_test.yml

@@ -17,6 +17,9 @@ jobs:
         python-version:
           - "3.10"
           - "3.14"
+        build_mode:
+          - layered
+          - flat
         example:
           - name: A
             workdir: libs/cli/examples
@@ -30,9 +33,11 @@ jobs:
           - name: D
             workdir: libs/cli/examples/graphs_reqs_b
             tag: langgraph-test-d
-    name: "CLI integration test"
+    name: "CLI integration test (${{ matrix.python-version }}, ${{ matrix.example.name }}, ${{ matrix.build_mode }})"
     env:
+      BUILD_ARGS: ${{ matrix.build_mode == 'flat' && '--flat' || '' }}
       HAS_LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY != '' }}
+      TAG_SUFFIX: ${{ matrix.build_mode == 'flat' && '-flat' || '' }}
     defaults:
       run:
         working-directory: libs/cli
@@ -58,7 +63,7 @@ jobs:
         if: (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch')
         working-directory: ${{ matrix.example.workdir }}
         run: |
-          langgraph build -t ${{ matrix.example.tag }}
+          langgraph build $BUILD_ARGS -t ${{ matrix.example.tag }}$TAG_SUFFIX
       - name: Test service ${{ matrix.example.name }}
         if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&env.HAS_LANGSMITH_API_KEY == 'true' }}
         working-directory: ${{ matrix.example.workdir }}
@@ -71,98 +76,98 @@ jobs:
           if [ -f ../.env ]; then echo "LANGSMITH_API_KEY=${{ secrets.LANGSMITH_API_KEY }}" >> ../.env; fi
           # Run the integration test using the built tag
           REPO_ROOT=$(git rev-parse --show-toplevel)
-          timeout 60 python "$REPO_ROOT/.github/scripts/run_langgraph_cli_test.py" -t ${{ matrix.example.tag }}
+          timeout 60 python "$REPO_ROOT/.github/scripts/run_langgraph_cli_test.py" -t ${{ matrix.example.tag }}$TAG_SUFFIX
 
       - name: Build JS service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/js-examples
         run: |
-          langgraph build -t langgraph-test-e
+          langgraph build $BUILD_ARGS -t langgraph-test-e$TAG_SUFFIX
 
       - name: Build JS monorepo service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/js-monorepo-example
         run: |
-          langgraph build -t langgraph-test-f -c apps/agent/langgraph.json --build-command "yarn run turbo build" --install-command "yarn install"
+          langgraph build $BUILD_ARGS -t langgraph-test-f$TAG_SUFFIX -c apps/agent/langgraph.json --build-command "yarn run turbo build" --install-command "yarn install"
 
       - name: Build Python monorepo service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/python-monorepo-example
         run: |
-          langgraph build -t langgraph-test-g -c apps/agent/langgraph.json
+          langgraph build $BUILD_ARGS -t langgraph-test-g$TAG_SUFFIX -c apps/agent/langgraph.json
       - name: Test Python monorepo service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
         working-directory: libs/cli/python-monorepo-example
         env:
           LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
         run: |
           cp apps/agent/.env.example apps/agent/.env
           echo "LANGSMITH_API_KEY=${{ secrets.LANGSMITH_API_KEY }}" >> apps/agent/.env
-          timeout 60 python ../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-g -c apps/agent/langgraph.json
+          timeout 60 python ../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-g$TAG_SUFFIX -c apps/agent/langgraph.json
 
       - name: Build prerelease reqs service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/examples/graph_prerelease_reqs
         run: |
-          langgraph build -t langgraph-test-h
+          langgraph build $BUILD_ARGS -t langgraph-test-h$TAG_SUFFIX
       - name: Test prerelease reqs service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
         working-directory: libs/cli/examples/graph_prerelease_reqs
         env:
           LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
         run: |
           cp ../.env.example .env
           echo "LANGSMITH_API_KEY=${{ secrets.LANGSMITH_API_KEY }}" >> .env
-          timeout 60 python ../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-h
+          timeout 60 python ../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-h$TAG_SUFFIX
           echo "Finished starting up langgraph-test-h"
-          LANGGRAPH_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h python -c "import sys; from importlib.metadata import version; v = version('langgraph'); print(v);")
+          LANGGRAPH_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h$TAG_SUFFIX python -c "import sys; from importlib.metadata import version; v = version('langgraph'); print(v);")
           if [ "$LANGGRAPH_VERSION" != "1.1.5" ]; then
             echo "LANGGRAPH_VERSION != 1.1.5; $LANGGRAPH_VERSION"
             exit 1
           fi
-          LANGCHAIN_OPENAI_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h python -c "import sys; from importlib.metadata import version; v = version('langchain-openai'); print(v);")
+          LANGCHAIN_OPENAI_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h$TAG_SUFFIX python -c "import sys; from importlib.metadata import version; v = version('langchain-openai'); print(v);")
           if [ "$LANGCHAIN_OPENAI_VERSION" != "1.1.14" ]; then
             echo "LANGCHAIN_OPENAI_VERSION != 1.1.14; $LANGCHAIN_OPENAI_VERSION"
             exit 1
           fi
-          LANGCHAIN_ANTHROPIC_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h python -c "import sys; from importlib.metadata import version; v = version('langchain-anthropic'); print(v);")
+          LANGCHAIN_ANTHROPIC_VERSION=$(docker run --rm --entrypoint "" langgraph-test-h$TAG_SUFFIX python -c "import sys; from importlib.metadata import version; v = version('langchain-anthropic'); print(v);")
           if [ "$LANGCHAIN_ANTHROPIC_VERSION" != "1.4.6" ]; then
             echo "LANGCHAIN_ANTHROPIC_VERSION != 1.4.6; $LANGCHAIN_ANTHROPIC_VERSION"
             exit 1
           fi
 
       - name: Build and test prerelease reqs fail service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/examples/graph_prerelease_reqs_fail
         run: |
-          langgraph build -t langgraph-test-i || [ $? -eq 1 ]
+          langgraph build $BUILD_ARGS -t langgraph-test-i$TAG_SUFFIX || [ $? -eq 1 ]
 
       - name: Build uv simple service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/uv-examples/simple
         run: |
-          langgraph build -t langgraph-test-uv-simple
+          langgraph build $BUILD_ARGS -t langgraph-test-uv-simple$TAG_SUFFIX
       - name: Test uv simple service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
         working-directory: libs/cli/uv-examples/simple
         env:
           LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
         run: |
           cp .env.example .env
           echo "LANGSMITH_API_KEY=${{ secrets.LANGSMITH_API_KEY }}" >> .env
-          timeout 60 python ../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-uv-simple
+          timeout 60 python ../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-uv-simple$TAG_SUFFIX
 
       - name: Build uv monorepo service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' }}
         working-directory: libs/cli/uv-examples/monorepo/apps/agent
         run: |
-          langgraph build -t langgraph-test-uv-monorepo
+          langgraph build $BUILD_ARGS -t langgraph-test-uv-monorepo$TAG_SUFFIX
       - name: Test uv monorepo service
-        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') &&matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
+        if: ${{ (steps.changed-files.outputs.all || github.event_name == 'workflow_dispatch') && matrix.example.name == 'A' && env.HAS_LANGSMITH_API_KEY == 'true' }}
         working-directory: libs/cli/uv-examples/monorepo/apps/agent
         env:
           LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
         run: |
           cp .env.example .env
           echo "LANGSMITH_API_KEY=${{ secrets.LANGSMITH_API_KEY }}" >> .env
-          timeout 60 python ../../../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-uv-monorepo
+          timeout 60 python ../../../../../../.github/scripts/run_langgraph_cli_test.py -t langgraph-test-uv-monorepo$TAG_SUFFIX

.gitignore

@@ -76,7 +76,12 @@ __pypackages__/
 
 # Environments
 .env
+.env.*
 .envrc
+*.crt
+*.key
+*.pem
+credentials.json
 .venv
 .venvs
 env/
@@ -98,6 +103,7 @@ dmypy.json
 
 .vercel
 .turbo
+node_modules/
 .editorconfig
 .scratch
 .worktrees/

AGENTS.md

@@ -2,6 +2,14 @@
 
 This repository is a monorepo. Each library lives in a subdirectory under `libs/`.
 
+<corridor>
+
+## Corridor security analysis
+
+When Corridor's `analyzePlan` tool is available, create a plan and use the tool to analyze it before generating or modifying code. Apply the resulting security guidance before writing code.
+
+</corridor>
+
 When you modify code in any library, run the following commands in that library's directory before creating a pull request:
 
 - `make format` – run code formatters

CLAUDE.md

@@ -2,6 +2,14 @@
 
 This repository is a monorepo. Each library lives in a subdirectory under `libs/`.
 
+<corridor>
+
+## Corridor security analysis
+
+Before generating or modifying code, create a plan and use Corridor's `analyzePlan` tool to analyze it. Apply the resulting security guidance before writing code.
+
+</corridor>
+
 When you modify code in any library, run the following commands in that library's directory before creating a pull request:
 
 - `make format` – run code formatters

libs/cli/langgraph_cli/cli.py

@@ -408,6 +408,12 @@ For production use, requires a license key in env var LANGGRAPH_CLOUD_LICENSE_KE
     "--build-command",
     help="Custom build command to run from the langgraph.json directory. If not provided, uses default build process.",
 )
+@click.option(
+    "--flat",
+    is_flag=True,
+    envvar="LANGGRAPH_CLI_FLAT_IMAGES",
+    help="Flatten generated build steps into one image layer when supported.",
+)
 @click.argument("docker_build_args", nargs=-1, type=click.UNPROCESSED)
 @cli.command(
     help="📦 Build LangGraph API server Docker image.",
@@ -426,6 +432,7 @@ def build(
     tag: str,
     install_command: str | None,
     build_command: str | None,
+    flat: bool,
 ):
     if install_command and langgraph_cli.config.has_disallowed_build_command_content(
         install_command
@@ -461,6 +468,7 @@ def build(
             docker_build_args,
             install_command,
             build_command,
+            flat=flat,
         )
 
 

libs/cli/langgraph_cli/config.py

@@ -1162,6 +1162,208 @@ def _build_runtime_env_vars(config: Config) -> list[str]:
     return env_vars
 
 
+def _faux_package_pyproject_command(package_name: str) -> str:
+    pyproject_path = shlex.quote(f"/deps/outer-{package_name}/pyproject.toml")
+    return f"""cat > {pyproject_path} <<'PYPROJECT'
+[project]
+name = {json.dumps(package_name)}
+version = "0.1"
+[tool.setuptools.package-data]
+"*" = ["**/*"]
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+PYPROJECT"""
+
+
+_FLAT_BUILD_CONTEXT = pathlib.PurePosixPath("/__build_context")
+_FLAT_ADDITIONAL_CONTEXTS = pathlib.PurePosixPath("/__additional_contexts")
+_DEFAULT_NODE_BUILD_COMMAND = (
+    '(test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, '
+    'skipping") || tsx /api/langgraph_api/js/build.mts'
+)
+
+
+def _render_flat_dockerfile(
+    *,
+    image: str,
+    dockerfile_lines: list[str],
+    env_vars: list[str],
+    commands: list[str],
+    workdir: str | None,
+    additional_context_names: dict[pathlib.Path, str] | None = None,
+) -> str:
+    mounts = [f"--mount=type=bind,target={_FLAT_BUILD_CONTEXT},readonly"]
+    mounts.extend(
+        f"--mount=type=bind,from={name},"
+        f"target={_FLAT_ADDITIONAL_CONTEXTS / name},readonly"
+        for name in (additional_context_names or {}).values()
+    )
+
+    return os.linesep.join(
+        [
+            "# syntax=docker/dockerfile:1.7",
+            f"FROM {image}",
+            *dockerfile_lines,
+            *env_vars,
+            f"RUN {' '.join(mounts)} <<'USER_LAYER'",
+            *commands,
+            "USER_LAYER",
+            f"WORKDIR {workdir}" if workdir else "",
+        ]
+    )
+
+
+def _flat_context_source(
+    path: pathlib.Path,
+    relative_path: str,
+    additional_context_names: dict[pathlib.Path, str],
+    *,
+    additional_relative_path: str = ".",
+) -> str:
+    if name := additional_context_names.get(path):
+        return str(_FLAT_ADDITIONAL_CONTEXTS / name / additional_relative_path)
+    return str(_FLAT_BUILD_CONTEXT / relative_path)
+
+
+def _copy_directory_command(source: str, destination: str) -> str:
+    return f"""mkdir -p {shlex.quote(destination)}
+cp -a {shlex.quote(f"{source}/.")} {shlex.quote(destination)}/"""
+
+
+def _flat_local_dependency_commands(
+    *,
+    config_path: pathlib.Path,
+    local_deps: LocalDeps,
+    local_reqs_pip_install: str,
+    additional_context_names: dict[pathlib.Path, str],
+) -> list[str]:
+    commands = []
+
+    for reqpath, destination in local_deps.pip_reqs:
+        source = _flat_context_source(
+            reqpath.parent,
+            str(reqpath.relative_to(config_path.parent)),
+            additional_context_names,
+            additional_relative_path=reqpath.name,
+        )
+        destination_parent = pathlib.PurePosixPath(destination).parent
+        commands.append(f"""mkdir -p {shlex.quote(str(destination_parent))}
+cp {shlex.quote(source)} {shlex.quote(destination)}""")
+    if local_deps.pip_reqs:
+        requirements = " ".join(
+            f"-r {destination}" for _, destination in local_deps.pip_reqs
+        )
+        commands.append(f"{local_reqs_pip_install} {requirements}")
+
+    for full_path, (relative_path, name) in local_deps.real_pkgs.items():
+        source = _flat_context_source(
+            full_path, relative_path, additional_context_names
+        )
+        commands.append(_copy_directory_command(source, f"/deps/{name}"))
+
+    for full_path, (relative_path, destination) in local_deps.faux_pkgs.items():
+        source = _flat_context_source(
+            full_path, relative_path, additional_context_names
+        )
+        pyproject = _faux_package_pyproject_command(full_path.name)
+        commands.append(f"{_copy_directory_command(source, destination)}\n{pyproject}")
+
+    return commands
+
+
+def _build_flat_python_commands(
+    *,
+    config_path: pathlib.Path,
+    config: Config,
+    local_deps: LocalDeps,
+    pypi_deps: list[str],
+    local_reqs_pip_install: str,
+    local_deps_install_command: str,
+    pip_cleanup: str,
+    additional_context_names: dict[pathlib.Path, str],
+    js_working_dir: str | None,
+) -> list[str]:
+    commands = ["set -eu"]
+
+    if js_working_dir:
+        commands.append("/storage/install-node.sh")
+
+    if pip_config_file := config.get("pip_config_file"):
+        source = shlex.quote(str(_FLAT_BUILD_CONTEXT / pip_config_file))
+        commands.append(f"cp {source} /pipconfig.txt")
+    if pypi_deps:
+        commands.append(f"{local_reqs_pip_install} {' '.join(pypi_deps)}")
+
+    commands.extend(
+        _flat_local_dependency_commands(
+            config_path=config_path,
+            local_deps=local_deps,
+            local_reqs_pip_install=local_reqs_pip_install,
+            additional_context_names=additional_context_names,
+        )
+    )
+
+    commands.append(local_deps_install_command)
+    if js_working_dir:
+        working_dir = shlex.quote(js_working_dir)
+        commands.append(
+            f"cd {working_dir}\n"
+            f"{_get_node_pm_install_cmd(config_path.parent)} "
+            "&& tsx /api/langgraph_api/js/build.mts"
+        )
+    commands.extend(
+        line.removeprefix("RUN ")
+        for line in pip_cleanup.splitlines()
+        if line and not line.startswith("#")
+    )
+    return commands
+
+
+def _build_flat_python_dockerfile(
+    config_path: pathlib.Path,
+    config: Config,
+    local_deps: LocalDeps,
+    pypi_deps: list[str],
+    local_reqs_pip_install: str,
+    local_deps_install_command: str,
+    pip_cleanup: str,
+    image: str,
+    env_vars: list[str],
+    additional_context_names: dict[pathlib.Path, str],
+) -> str:
+    js_working_dir = (
+        local_deps.working_dir
+        if config.get("ui") or config.get("node_version")
+        else None
+    )
+    commands = _build_flat_python_commands(
+        config_path=config_path,
+        config=config,
+        local_deps=local_deps,
+        pypi_deps=pypi_deps,
+        local_reqs_pip_install=local_reqs_pip_install,
+        local_deps_install_command=local_deps_install_command,
+        pip_cleanup=pip_cleanup,
+        additional_context_names=additional_context_names,
+        js_working_dir=js_working_dir,
+    )
+    if js_working_dir:
+        env_vars = [
+            f"ENV NODE_VERSION={config.get('node_version') or DEFAULT_NODE_VERSION}",
+            *env_vars,
+        ]
+
+    return _render_flat_dockerfile(
+        image=image,
+        dockerfile_lines=config["dockerfile_lines"],
+        env_vars=env_vars,
+        commands=commands,
+        workdir=local_deps.working_dir,
+        additional_context_names=additional_context_names,
+    )
+
+
 def _get_node_pm_install_cmd(project_dir: pathlib.Path) -> str:
     def test_file(file_name):
         full_path = project_dir / file_name
@@ -1267,6 +1469,7 @@ def python_config_to_docker(
     api_version: str | None = None,
     *,
     escape_variables: bool = False,
+    flat: bool = False,
 ) -> tuple[str, dict[str, str]]:
     """Generate a Dockerfile from the configuration."""
     source_kind = _get_source_kind(config)
@@ -1428,6 +1631,36 @@ ADD {relpath} /deps/{name}
             ]
         )
     image_str = docker_tag(config, base_image, api_version)
+    dep_vname = "$$dep" if escape_variables else "$dep"
+    local_deps_install_command = f"""for dep in /deps/*; do \
+            echo "Installing {dep_vname}"; \
+            if [ -d "{dep_vname}" ]; then \
+                echo "Installing {dep_vname}"; \
+                (cd "{dep_vname}" && {global_reqs_pip_install} -e .); \
+            fi; \
+        done"""
+    pip_cleanup = _get_pip_cleanup_lines(
+        install_cmd=install_cmd,
+        to_uninstall=build_tools_to_uninstall,
+        pip_installer=pip_installer,
+    )
+
+    if flat:
+        return (
+            _build_flat_python_dockerfile(
+                config_path=config_path,
+                config=config,
+                local_deps=local_deps,
+                pypi_deps=pypi_deps,
+                local_reqs_pip_install=local_reqs_pip_install,
+                local_deps_install_command=local_deps_install_command,
+                pip_cleanup=pip_cleanup,
+                image=image_str,
+                env_vars=env_vars,
+                additional_context_names=additional_context_names,
+            ),
+            additional_contexts,
+        )
 
     # Prepare docker file contents
     docker_file_contents = []
@@ -1442,14 +1675,6 @@ ADD {relpath} /deps/{name}
         )
 
     # Add main dockerfile content
-    dep_vname = "$$dep" if escape_variables else "$dep"
-    local_deps_install_str = f"""RUN for dep in /deps/*; do \
-            echo "Installing {dep_vname}"; \
-            if [ -d "{dep_vname}" ]; then \
-                echo "Installing {dep_vname}"; \
-                (cd "{dep_vname}" && {global_reqs_pip_install} -e .); \
-            fi; \
-        done"""
     docker_file_contents.extend(
         [
             f"FROM {image_str}",
@@ -1459,18 +1684,14 @@ ADD {relpath} /deps/{name}
             installs,
             "",
             "# -- Installing all local dependencies --",
-            local_deps_install_str,
+            f"RUN {local_deps_install_command}",
             "# -- End of local dependencies install --",
             os.linesep.join(env_vars),
             "",
             js_inst_str,
             "",
             # Add pip cleanup after all installations are complete
-            _get_pip_cleanup_lines(
-                install_cmd=install_cmd,
-                to_uninstall=build_tools_to_uninstall,
-                pip_installer=pip_installer,
-            ),
+            pip_cleanup,
             "",
             f"WORKDIR {local_deps.working_dir}" if local_deps.working_dir else "",
         ]
@@ -1479,6 +1700,31 @@ ADD {relpath} /deps/{name}
     return os.linesep.join(docker_file_contents), additional_contexts
 
 
+def _build_flat_node_dockerfile(
+    *,
+    config: Config,
+    image: str,
+    env_vars: list[str],
+    install_workdir: str,
+    build_workdir: str,
+    install_command: str,
+    build_command: str,
+) -> str:
+    commands = [
+        "set -eu",
+        _copy_directory_command(str(_FLAT_BUILD_CONTEXT), install_workdir),
+        f"cd {shlex.quote(install_workdir)}\n{install_command}",
+        f"cd {shlex.quote(build_workdir)}\n{build_command}",
+    ]
+    return _render_flat_dockerfile(
+        image=image,
+        dockerfile_lines=config["dockerfile_lines"],
+        env_vars=env_vars,
+        commands=commands,
+        workdir=build_workdir,
+    )
+
+
 def node_config_to_docker(
     config_path: pathlib.Path,
     config: Config,
@@ -1487,6 +1733,7 @@ def node_config_to_docker(
     install_command: str | None = None,
     build_command: str | None = None,
     build_context: str | None = None,
+    flat: bool = False,
 ) -> tuple[str, dict[str, str]]:
     # Calculate paths for monorepo support
     install_root = (
@@ -1496,56 +1743,56 @@ def node_config_to_docker(
     if build_context:
         relative_workdir = _calculate_relative_workdir(config_path, build_context)
         container_name = pathlib.Path(build_context).name
-        if relative_workdir:
-            faux_path = f"/deps/{container_name}/{relative_workdir}"
-        else:
-            faux_path = f"/deps/{container_name}"
+        install_workdir = f"/deps/{container_name}"
+        build_workdir = (
+            f"{install_workdir}/{relative_workdir}"
+            if relative_workdir
+            else install_workdir
+        )
     else:
         # Backward compatibility: use the original behavior
-        faux_path = f"/deps/{config_path.parent.name}"
+        install_workdir = build_workdir = f"/deps/{config_path.parent.name}"
 
     image_str = docker_tag(config, base_image, api_version)
 
     env_vars = _build_runtime_env_vars(config)
 
-    # For monorepo support, we need to handle install and build commands differently
-    if build_context:
-        # Monorepo case: install from root, build from config directory
-        container_root = f"/deps/{pathlib.Path(build_context).name}"
-        install_workdir = container_root
-        install_step = f"RUN {install_cmd}"
+    build_cmd = (
+        build_command
+        if build_context and build_command
+        else _DEFAULT_NODE_BUILD_COMMAND
+    )
 
-        if build_command:
-            build_step = f"RUN {build_command}"
-        else:
-            build_step = 'RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts'
-    else:
-        # Original behavior: everything happens in the same directory
-        install_workdir = faux_path
-        install_step = f"RUN {install_cmd}"
-        build_step = 'RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts'
-
-    if build_context:
-        build_workdir = faux_path
-    else:
-        build_workdir = faux_path
+    if flat:
+        return (
+            _build_flat_node_dockerfile(
+                config=config,
+                image=image_str,
+                env_vars=env_vars,
+                install_workdir=install_workdir,
+                build_workdir=build_workdir,
+                install_command=install_cmd,
+                build_command=build_cmd,
+            ),
+            {},
+        )
 
     docker_file_contents = [
         f"FROM {image_str}",
         "",
         os.linesep.join(config["dockerfile_lines"]),
         "",
-        f"ADD . {faux_path if not build_context else container_root}",
+        f"ADD . {install_workdir}",
         "",
         f"WORKDIR {install_workdir}",
         "",
-        install_step,
+        f"RUN {install_cmd}",
         "",
         os.linesep.join(env_vars),
         "",
         f"WORKDIR {build_workdir}",
         "",
-        build_step,
+        f"RUN {build_cmd}",
     ]
 
     return os.linesep.join(docker_file_contents), {}
@@ -1625,6 +1872,7 @@ def config_to_docker(
     build_command: str | None = None,
     build_context: str | None = None,
     escape_variables: bool = False,
+    flat: bool = False,
 ) -> tuple[str, dict[str, str]]:
     base_image = base_image or default_base_image(config)
 
@@ -1637,6 +1885,7 @@ def config_to_docker(
             install_command=install_command,
             build_command=build_command,
             build_context=build_context,
+            flat=flat,
         )
 
     return python_config_to_docker(
@@ -1645,6 +1894,7 @@ def config_to_docker(
         base_image=base_image,
         api_version=api_version,
         escape_variables=escape_variables,
+        flat=flat,
     )
 
 

libs/cli/langgraph_cli/docker.py

@@ -345,6 +345,7 @@ def build_docker_image(
     docker_command: Sequence[str] | None = None,
     extra_flags: Sequence[str] = (),
     verbose: bool = True,
+    flat: bool = False,
 ):
     """Build a Docker image from a LangGraph config."""
     # pull latest images
@@ -387,6 +388,7 @@ def build_docker_image(
         install_command=install_command,
         build_command=build_command,
         build_context=build_context,
+        flat=flat,
     )
     # add additional_contexts
     if additional_contexts:

libs/cli/langgraph_cli/uv_lock.py

@@ -970,6 +970,22 @@ def python_config_to_docker_uv_lock(
             f"{uv_export_project_dir}/uv.lock",
         )
     )
+    for package_root in sorted(
+        plan.all_workspace_roots,
+        key=lambda root: root.as_posix(),
+    ):
+        if package_root == plan.project_root:
+            continue
+        package_relative_path = pathlib.PurePosixPath(
+            package_root.relative_to(plan.project_root).as_posix()
+        )
+        package_pyproject_path = package_relative_path / "pyproject.toml"
+        docker_plan.add_raw(
+            copy_from_project_root(
+                package_pyproject_path,
+                f"{uv_export_project_dir}/{package_pyproject_path.as_posix()}",
+            )
+        )
     docker_plan.add_instruction("WORKDIR", uv_export_project_dir)
     docker_plan.add_instruction(
         "RUN",

libs/cli/tests/unit_tests/test_config.py

@@ -723,6 +723,67 @@ WORKDIR /deps/outer-unit_tests/unit_tests\
     }
 
 
+def test_config_to_docker_flat():
+    dockerfile, additional_contexts = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {"dependencies": ["."], "graphs": {"agent": "./agent.py:graph"}}
+        ),
+        base_image="langchain/langgraph-api",
+        flat=True,
+    )
+
+    assert additional_contexts == {}
+    assert dockerfile.count("\nRUN ") == 1
+    assert "--mount=type=bind" in dockerfile
+    assert "cp -a /__build_context/. /deps/outer-unit_tests/unit_tests/" in dockerfile
+    assert "cat > /deps/outer-unit_tests/pyproject.toml <<'PYPROJECT'" in dockerfile
+    assert '[tool.setuptools.package-data]\n"*" = ["**/*"]' in dockerfile
+    assert dockerfile.endswith("WORKDIR /deps/outer-unit_tests/unit_tests")
+
+
+def test_config_to_docker_flat_with_custom_lines_and_escaped_variables():
+    dockerfile, _ = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {
+                "dependencies": ["."],
+                "graphs": {"agent": "./agent.py:graph"},
+                "dockerfile_lines": ["RUN echo custom"],
+            }
+        ),
+        base_image="langchain/langgraph-api",
+        escape_variables=True,
+        flat=True,
+    )
+
+    assert dockerfile.index("RUN echo custom") < dockerfile.index("USER_LAYER")
+    assert 'echo "Installing $$dep"' in dockerfile
+
+
+def test_config_to_docker_flat_with_additional_context():
+    dockerfile, additional_contexts = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {"dependencies": [".", ".."], "graphs": {"agent": "./agent.py:graph"}}
+        ),
+        base_image="langchain/langgraph-api",
+        flat=True,
+    )
+
+    assert additional_contexts == {
+        "outer-tests": str(pathlib.Path(__file__).parent.parent.absolute()),
+    }
+    assert (
+        "--mount=type=bind,from=outer-tests,"
+        "target=/__additional_contexts/outer-tests,readonly" in dockerfile
+    )
+    assert (
+        "cp -a /__additional_contexts/outer-tests/. /deps/outer-tests/tests/"
+        in dockerfile
+    )
+
+
 def test_config_to_docker_outside_path():
     graphs = {"agent": "./agent.py:graph"}
     actual_docker_stdin, additional_contexts = config_to_docker(
@@ -998,6 +1059,28 @@ RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not foun
     assert additional_contexts == {}
 
 
+def test_config_to_docker_nodejs_flat():
+    dockerfile, additional_contexts = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {
+                "node_version": "20",
+                "graphs": {"agent": "./graphs/agent.js:graph"},
+                "dockerfile_lines": ["RUN echo custom"],
+            }
+        ),
+        base_image="langchain/langgraphjs-api",
+        flat=True,
+    )
+
+    assert additional_contexts == {}
+    assert dockerfile.index("RUN echo custom") < dockerfile.index("USER_LAYER")
+    assert "cp -a /__build_context/. /deps/unit_tests/" in dockerfile
+    assert "cd /deps/unit_tests\nnpm i" in dockerfile
+    assert "tsx /api/langgraph_api/js/build.mts" in dockerfile
+    assert dockerfile.endswith("WORKDIR /deps/unit_tests")
+
+
 def test_config_to_docker_python_encryption():
     # Test that encryption config is included in validation
     graphs = {"agent": "./agent.py:graph"}
@@ -1214,6 +1297,29 @@ WORKDIR /deps/outer-unit_tests/unit_tests"""
     assert additional_contexts == {}
 
 
+def test_config_to_docker_gen_ui_python_flat():
+    dockerfile, additional_contexts = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config(
+            {
+                "dependencies": ["."],
+                "graphs": {"agent": "./agent.py:graph"},
+                "ui": {"agent": "./graphs/agent.ui.jsx"},
+            }
+        ),
+        base_image="langchain/langgraph-api",
+        flat=True,
+    )
+
+    assert additional_contexts == {}
+    assert dockerfile.count("\nRUN ") == 1
+    assert dockerfile.index("ENV NODE_VERSION=20") < dockerfile.index("\nRUN ")
+    assert dockerfile.index("ENV LANGGRAPH_UI=") < dockerfile.index("\nRUN ")
+    assert "/storage/install-node.sh" in dockerfile
+    assert "cd /deps/outer-unit_tests/unit_tests\nnpm i" in dockerfile
+    assert "tsx /api/langgraph_api/js/build.mts" in dockerfile
+
+
 def test_config_to_docker_multiplatform():
     graphs = {
         "python": "./multiplatform/python.py:graph",
@@ -1403,6 +1509,19 @@ def test_config_to_docker_uv_lock():
             "COPY --from=uv-workspace-root uv.lock /tmp/uv_export/project/uv.lock"
             in docker
         )
+        workspace_pyprojects = [
+            "apps/agent/pyproject.toml",
+            "libs/extra/pyproject.toml",
+            "libs/shared/pyproject.toml",
+        ]
+        export_instruction = "RUN uv export --package agent"
+        for pyproject_path in workspace_pyprojects:
+            copy_instruction = (
+                "COPY --from=uv-workspace-root "
+                f"{pyproject_path} /tmp/uv_export/project/{pyproject_path}"
+            )
+            assert copy_instruction in docker
+            assert docker.index(copy_instruction) < docker.index(export_instruction)
         assert additional_contexts == {"uv-workspace-root": str(project_root.resolve())}
 
         assert (

libs/cli/uv-examples/monorepo/uv.lock

@@ -266,20 +266,20 @@ wheels = [
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "4.0.1"
+version = "4.2.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "langchain-core" },
     { name = "ormsgpack" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b1/44/a8df45d1e8b4637e29789fa8bae1db022c953cc7ac80093cfc52e923547e/langgraph_checkpoint-4.0.1.tar.gz", hash = "sha256:b433123735df11ade28829e40ce25b9be614930cd50245ff2af60629234befd9", size = 158135, upload-time = "2026-02-27T21:06:16.092Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/dc/e1/089c4c9e0a2fec7f883f82ae8e6a727138d50074cfeb6644bc2d13b1019b/langgraph_checkpoint-4.2.0.tar.gz", hash = "sha256:51a593b6bee684b0818e5d6e58e28ab340c6db7794575056ce7bd1b746a84ed7", size = 180239, upload-time = "2026-08-07T20:05:03.756Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/65/4c/09a4a0c42f5d2fc38d6c4d67884788eff7fd2cfdf367fdf7033de908b4c0/langgraph_checkpoint-4.0.1-py3-none-any.whl", hash = "sha256:e3adcd7a0e0166f3b48b8cf508ce0ea366e7420b5a73aa81289888727769b034", size = 50453, upload-time = "2026-02-27T21:06:14.293Z" },
+    { url = "https://files.pythonhosted.org/packages/05/71/3b475f09bd57d3a5649792c66353312b4432afd843f301739dfcebd157f0/langgraph_checkpoint-4.2.0-py3-none-any.whl", hash = "sha256:0547fd228935a0b758865de3a3d6d7a2537c308895d0f9ab092ce9151b5da942", size = 56833, upload-time = "2026-08-07T20:05:02.655Z" },
 ]
 
 [[package]]
 name = "langgraph-checkpoint-postgres"
-version = "3.0.5"
+version = "3.1.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "langgraph-checkpoint" },
@@ -287,9 +287,9 @@ dependencies = [
     { name = "psycopg" },
     { name = "psycopg-pool" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/95/7a/8f439966643d32111248a225e6cb33a182d07c90de780c4dbfc1e0377832/langgraph_checkpoint_postgres-3.0.5.tar.gz", hash = "sha256:a8fd7278a63f4f849b5cbc7884a15ca8f41e7d5f7467d0a66b31e8c24492f7eb", size = 127856, upload-time = "2026-03-18T21:25:29.785Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/06/92/1e8959f8cd1b56e672fde3227f6fd642be85af6c5fd662d73921074aa39d/langgraph_checkpoint_postgres-3.1.1.tar.gz", hash = "sha256:d320e147ddad8c374cd546df0b52b532dd54d0541dd9fd23fc738cbd5de76f41", size = 150413, upload-time = "2026-07-30T19:15:39.014Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/e8/87/b0f98b33a67204bca9d5619bcd9574222f6b025cf3c125eedcec9a50ecbc/langgraph_checkpoint_postgres-3.0.5-py3-none-any.whl", hash = "sha256:86d7040a88fd70087eaafb72251d796696a0a2d856168f5c11ef620771411552", size = 42907, upload-time = "2026-03-18T21:25:28.75Z" },
+    { url = "https://files.pythonhosted.org/packages/03/32/ba457698a48a0e18d786caa770033067049fbe36d6846f8e50f13b594b51/langgraph_checkpoint_postgres-3.1.1-py3-none-any.whl", hash = "sha256:6e353aecd8150de144fef8e51a49076f58b7d6830d4cf51392b7ad4d79832ba7", size = 50778, upload-time = "2026-07-30T19:15:37.405Z" },
 ]
 
 [[package]]

libs/langgraph/langgraph/pregel/_utils.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
 
-import ast
-import inspect
+import dis
 import re
-import textwrap
 from collections.abc import Callable, Sequence
 from functools import partial
+from types import CodeType, FunctionType
 from typing import Any
 
 from langchain_core.runnables import (
@@ -17,7 +16,6 @@ from langchain_core.runnables import (
 from langchain_core.runnables.base import RunnableBindingBase
 from langchain_core.runnables.config import run_in_executor
 from langgraph.checkpoint.base import ChannelVersions
-from typing_extensions import override
 
 from langgraph._internal._runnable import RunnableCallable, RunnableSeq
 from langgraph._internal._timeout import sync_timeout_unsupported
@@ -137,155 +135,87 @@ def validate_timeout_supported(runnable: Runnable, *, name: str) -> None:
         raise sync_timeout_unsupported(name)
 
 
+# Values treated as dead ends when deciding whether to walk a function's
+# bytecode. A container can hold a graph, but `find_subgraph_pregel` does not
+# look inside one, so skipping it costs nothing while that holds. Matched by
+# exact type, since a subclass of a builtin can carry attributes.
+_LEAF_TYPES = frozenset(
+    {
+        int,
+        float,
+        complex,
+        bool,
+        str,
+        bytes,
+        bytearray,
+        list,
+        tuple,
+        dict,
+        set,
+        frozenset,
+        type(None),
+    }
+)
+
+
 def get_function_nonlocals(func: Callable) -> list[Any]:
-    """Get the nonlocal variables accessed by a function.
+    """Get the values a function reaches from outside its own scope.
 
     Args:
         func: The function to check.
 
     Returns:
-        List[Any]: The nonlocal variables accessed by the function.
+        Every captured cell value, the globals the function names, and each
+        value along an attribute path it loads. Over-approximates: a value can
+        come back without the function reaching it at runtime.
     """
-    try:
-        code = inspect.getsource(func)
-        tree = ast.parse(textwrap.dedent(code))
-        visitor = FunctionNonLocals()
-        visitor.visit(tree)
-        values: list[Any] = []
-        closure = (
-            inspect.getclosurevars(func.__wrapped__)
-            if hasattr(func, "__wrapped__") and callable(func.__wrapped__)
-            else inspect.getclosurevars(func)
-        )
-        candidates = {**closure.globals, **closure.nonlocals}
-        for k, v in candidates.items():
-            if k in visitor.nonlocals:
-                values.append(v)
-            for kk in visitor.nonlocals:
-                if "." in kk and kk.startswith(k):
-                    vv = v
-                    for part in kk.split(".")[1:]:
-                        if vv is None:
-                            break
-                        else:
-                            try:
-                                vv = getattr(vv, part)
-                            except AttributeError:
-                                break
-                    else:
-                        values.append(vv)
-    except (SyntaxError, TypeError, OSError, SystemError):
+    func = getattr(func, "__func__", func)  # bound method -> function
+    wrapped = getattr(func, "__wrapped__", None)
+    if callable(wrapped):
+        func = getattr(wrapped, "__func__", wrapped)
+    if not isinstance(func, FunctionType):
         return []
+    code = func.__code__
 
+    cells: dict[str, Any] = {}
+    for name, cell in zip(code.co_freevars, func.__closure__ or ()):
+        try:
+            cells[name] = cell.cell_contents
+        except ValueError:
+            continue  # empty cell: a recursive def not yet bound
+
+    # Every captured value counts, referenced or not: over-declaring costs an
+    # introspection entry, under-declaring drops the subgraph's checkpoints and
+    # stream events. Checking each cell against the bytecode would cost more and
+    # only trade the cheap error for the expensive one.
+    values: list[Any] = list(cells.values())
+    global_ns = func.__globals__
+    globals_ = {name: global_ns[name] for name in code.co_names if name in global_ns}
+    if all(type(v) in _LEAF_TYPES for v in (*cells.values(), *globals_.values())):
+        return values
+
+    # Nested code objects hold the references made by inner defs, lambdas and
+    # comprehensions, which resolve against the namespaces gathered above.
+    codes = [code]
+    for c in codes:
+        codes.extend(k for k in c.co_consts if isinstance(k, CodeType))
+        value: Any = None
+        for instruction in dis.get_instructions(c):
+            opname = instruction.opname
+            if opname == "LOAD_GLOBAL":
+                value = globals_.get(instruction.argval)
+            elif opname == "LOAD_DEREF":
+                value = cells.get(instruction.argval)
+            elif opname in ("LOAD_ATTR", "LOAD_METHOD"):
+                value = getattr(value, instruction.argval, None)
+            else:
+                value = None  # anything else ends the chain: `a, b.c` is not `a.c`
+                continue
+            if value is not None:
+                values.append(value)
     return values
 
 
-class FunctionNonLocals(ast.NodeVisitor):
-    """Get the nonlocal variables accessed of a function."""
-
-    def __init__(self) -> None:
-        self.nonlocals: set[str] = set()
-
-    @override
-    def visit_FunctionDef(self, node: ast.FunctionDef) -> Any:
-        """Visit a function definition.
-
-        Args:
-            node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
-        """
-        visitor = NonLocals()
-        visitor.visit(node)
-        self.nonlocals.update(visitor.loads - visitor.stores)
-
-    @override
-    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Any:
-        """Visit an async function definition.
-
-        Args:
-            node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
-        """
-        visitor = NonLocals()
-        visitor.visit(node)
-        self.nonlocals.update(visitor.loads - visitor.stores)
-
-    @override
-    def visit_Lambda(self, node: ast.Lambda) -> Any:
-        """Visit a lambda function.
-
-        Args:
-            node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
-        """
-        visitor = NonLocals()
-        visitor.visit(node)
-        self.nonlocals.update(visitor.loads - visitor.stores)
-
-
-class NonLocals(ast.NodeVisitor):
-    """Get nonlocal variables accessed."""
-
-    def __init__(self) -> None:
-        self.loads: set[str] = set()
-        self.stores: set[str] = set()
-
-    @override
-    def visit_Name(self, node: ast.Name) -> Any:
-        """Visit a name node.
-
-        Args:
-            node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
-        """
-        if isinstance(node.ctx, ast.Load):
-            self.loads.add(node.id)
-        elif isinstance(node.ctx, ast.Store):
-            self.stores.add(node.id)
-
-    @override
-    def visit_Attribute(self, node: ast.Attribute) -> Any:
-        """Visit an attribute node.
-
-        Args:
-            node: The node to visit.
-
-        Returns:
-            Any: The result of the visit.
-        """
-        if isinstance(node.ctx, ast.Load):
-            parent = node.value
-            attr_expr = node.attr
-            while isinstance(parent, ast.Attribute):
-                attr_expr = parent.attr + "." + attr_expr
-                parent = parent.value
-            if isinstance(parent, ast.Name):
-                self.loads.add(parent.id + "." + attr_expr)
-                self.loads.discard(parent.id)
-            elif isinstance(parent, ast.Call):
-                if isinstance(parent.func, ast.Name):
-                    self.loads.add(parent.func.id)
-                else:
-                    parent = parent.func
-                    attr_expr = ""
-                    while isinstance(parent, ast.Attribute):
-                        if attr_expr:
-                            attr_expr = parent.attr + "." + attr_expr
-                        else:
-                            attr_expr = parent.attr
-                        parent = parent.value
-                    if isinstance(parent, ast.Name):
-                        self.loads.add(parent.id + "." + attr_expr)
-
-
 def is_xxh3_128_hexdigest(value: str) -> bool:
     """Check if the given string matches the format of xxh3_128_hexdigest."""
     return bool(re.fullmatch(r"[0-9a-f]{32}", value))

libs/langgraph/tests/test_subgraph_detection.py

@@ -0,0 +1,286 @@
+"""Tests for subgraph auto-detection (`pregel/_utils.py`).
+
+Detection failing is silent — the graph still runs, only introspection goes
+quiet — so every shape a node can hold a graph in is pinned here. The expected
+values are what the source-parsing implementation this replaced produced for
+the same shapes, except for `sourceless`, whose source it could not read,
+`empty_closure_cell`, on which it raised, and `unreachable_attribute_chain`,
+where it reported a graph that dropped code could never invoke.
+"""
+
+import functools
+import operator
+from typing import Annotated, Any
+
+import pytest
+from typing_extensions import TypedDict
+
+from langgraph.graph import END, START, StateGraph
+from langgraph.pregel._utils import get_function_nonlocals
+
+
+class State(TypedDict):
+    log: Annotated[list, operator.add]
+
+
+def _leaf(tag: str) -> Any:
+    """Return a compiled graph that reports itself as `tag`."""
+    builder = StateGraph(State)
+    builder.add_node(tag, lambda s: {"log": [tag]})
+    builder.add_edge(START, tag)
+    builder.add_edge(tag, END)
+    compiled = builder.compile()
+    compiled.name = tag
+    return compiled
+
+
+def _detect(node: Any) -> str | None:
+    """Return the name of the subgraph detected for `node`, or None."""
+    builder = StateGraph(State)
+    builder.add_node("n", node)
+    builder.add_edge(START, "n")
+    builder.add_edge("n", END)
+    subgraphs = builder.compile().nodes["n"].subgraphs
+    return getattr(subgraphs[0], "name", "?") if subgraphs else None
+
+
+class _Box:
+    def __init__(self, payload: Any) -> None:
+        self.payload = payload
+
+
+class _ListSubclass(list):
+    pass
+
+
+class _MethodHolder:
+    def __init__(self) -> None:
+        self.graph = _leaf("via_self")
+
+    def as_node(self, state: State) -> Any:
+        return self.graph.invoke(state)
+
+
+MODULE_GRAPH = _leaf("module_global")
+CHAIN = _Box(_Box(_leaf("attr_chain")))
+GRAPH_IN_PLAIN_LIST = [_leaf("in_list")]
+METHOD_HOLDER = _MethodHolder()
+
+
+def closure_capture() -> Any:
+    sub = _leaf("closure")
+
+    def node(state: State) -> Any:
+        return sub.invoke(state)
+
+    return node
+
+
+def module_global() -> Any:
+    def node(state: State) -> Any:
+        return MODULE_GRAPH.invoke(state)
+
+    return node
+
+
+def attribute_chain() -> Any:
+    def node(state: State) -> Any:
+        return CHAIN.payload.payload.invoke(state)
+
+    return node
+
+
+def nested_def_captured_attribute() -> Any:
+    """A chain on a captured holder, named only inside a nested code object.
+
+    The captured value is the holder, not the graph, so the chain itself has to
+    be recovered from the nested scope.
+    """
+    holder = _Box(_leaf("nested_captured"))
+
+    def node(state: State) -> Any:
+        def inner() -> Any:
+            return holder.payload.invoke(state)
+
+        return inner()
+
+    return node
+
+
+def unreachable_branch() -> Any:
+    """A captured graph referenced only from code the compiler removes."""
+    sub = _leaf("unreachable")
+
+    def node(state: State) -> Any:
+        if False:
+            sub.invoke(state)
+        return {"log": []}
+
+    return node
+
+
+def unreachable_attribute_chain() -> Any:
+    """A graph named only along an attribute path the compiler dropped.
+
+    The closure keeps `holder`, but the `.payload` load is gone. The source
+    parser reported this one; dropped code cannot invoke anything, so that was
+    a phantom rather than a detection.
+    """
+    holder = _Box(_leaf("unreachable_attr"))
+
+    def node(state: State) -> Any:
+        if False:
+            holder.payload.invoke(state)
+        return {"log": []}
+
+    return node
+
+
+def wrapper_referencing_nothing() -> Any:
+    """A wrapper whose own scope holds nothing, so only `__wrapped__` leads on.
+
+    `functools.wraps` would leave the wrapper closing over the inner function;
+    setting the attribute by hand does not.
+    """
+    sub = _leaf("via_wrapped")
+
+    def inner(state: State) -> Any:
+        return sub.invoke(state)
+
+    def wrapper(state: State) -> Any:
+        return {"log": []}
+
+    wrapper.__wrapped__ = inner
+    return wrapper
+
+
+def captured_list_subclass() -> Any:
+    """A `list` subclass is not a leaf: it can carry a graph as an attribute."""
+    holder = _ListSubclass()
+    holder.payload = _leaf("list_subclass")
+
+    def node(state: State) -> Any:
+        return holder.payload.invoke(state)
+
+    return node
+
+
+def empty_closure_cell() -> Any:
+    """An unassigned closure variable leaves a cell that cannot be read."""
+    sub = _leaf("beside_empty_cell")
+
+    def node(state: State) -> Any:
+        return unassigned, sub.invoke(state)
+
+    return node
+    unassigned = 1  # never runs, so the cell it creates is never filled
+
+
+def sourceless() -> Any:
+    """A node compiled without a source file, which `getsource` could not read."""
+    namespace: dict[str, Any] = {"SOURCELESS": _leaf("sourceless")}
+    exec(
+        compile(
+            "def node(state):\n    return SOURCELESS.invoke(state)", "<test>", "exec"
+        ),
+        namespace,
+    )
+    return namespace["node"]
+
+
+async def _async_node(state: State) -> Any:
+    return await MODULE_GRAPH.ainvoke(state)
+
+
+def async_node() -> Any:
+    return _async_node
+
+
+def no_subgraph() -> Any:
+    """Nothing but leaf values in reach, so the bytecode walk is skipped."""
+
+    def node(state: State) -> Any:
+        return {"log": [len("abc") + 1]}
+
+    return node
+
+
+def recombined_names() -> Any:
+    """Loads `CHAIN.payload` and `local.payload`, never `CHAIN.payload.payload`."""
+
+    def node(state: State) -> Any:
+        local = _Box("not a graph")
+        return {"log": [CHAIN.payload, local.payload]}
+
+    return node
+
+
+def broken_attribute_chain() -> Any:
+    holder = _Box("a string, so `.payload.missing` cannot resolve")
+
+    def node(state: State) -> Any:
+        return holder.payload.missing.invoke(state)
+
+    return node
+
+
+def nested_def_global() -> Any:
+    """A global named only in a nested code object: out of reach, as before."""
+
+    def node(state: State) -> Any:
+        def inner() -> Any:
+            return MODULE_GRAPH.invoke(state)
+
+        return inner()
+
+    return node
+
+
+def graph_in_plain_list() -> Any:
+    def node(state: State) -> Any:
+        return GRAPH_IN_PLAIN_LIST[0].invoke(state)
+
+    return node
+
+
+def bound_method_self() -> Any:
+    return METHOD_HOLDER.as_node
+
+
+@pytest.mark.parametrize(
+    ("factory", "expected"),
+    [
+        (closure_capture, "closure"),
+        (module_global, "module_global"),
+        (attribute_chain, "attr_chain"),
+        (nested_def_captured_attribute, "nested_captured"),
+        (unreachable_branch, "unreachable"),
+        (wrapper_referencing_nothing, "via_wrapped"),
+        (captured_list_subclass, "list_subclass"),
+        (empty_closure_cell, "beside_empty_cell"),
+        (sourceless, "sourceless"),
+        (async_node, "module_global"),
+        # Shapes no reference chain reaches: a subscript, an instance attribute
+        # of `self`, a global named only in a nested scope, and an attribute
+        # path the compiler dropped.
+        (no_subgraph, None),
+        (recombined_names, None),
+        (broken_attribute_chain, None),
+        (nested_def_global, None),
+        (graph_in_plain_list, None),
+        (bound_method_self, None),
+        (unreachable_attribute_chain, None),
+    ],
+    ids=lambda value: value.__name__ if callable(value) else str(value),
+)
+def test_subgraph_detection(factory: Any, expected: str | None) -> None:
+    assert _detect(factory()) == expected
+
+
+@pytest.mark.parametrize(
+    "candidate",
+    [functools.partial(lambda state, extra: {"log": [extra]}, extra="x"), len],
+    ids=["partial", "builtin"],
+)
+def test_callables_without_a_code_object_are_handled(candidate: Any) -> None:
+    assert get_function_nonlocals(candidate) == []

libs/sdk-py/langgraph_sdk/__init__.py

@@ -1,8 +1,15 @@
 from langgraph_sdk.auth import Auth
 from langgraph_sdk.client import get_client, get_sync_client
 from langgraph_sdk.encryption import Encryption
-from langgraph_sdk.encryption.types import EncryptionContext
+from langgraph_sdk.encryption.types import DecryptResult, EncryptionContext
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
-__all__ = ["Auth", "Encryption", "EncryptionContext", "get_client", "get_sync_client"]
+__all__ = [
+    "Auth",
+    "DecryptResult",
+    "Encryption",
+    "EncryptionContext",
+    "get_client",
+    "get_sync_client",
+]

libs/sdk-py/langgraph_sdk/encryption/__init__.py

@@ -18,6 +18,9 @@ import warnings
 
 from langgraph_sdk.encryption import types
 
+_BlobDecryptorT = typing.TypeVar("_BlobDecryptorT", bound=types.BlobDecryptor)
+_JsonDecryptorT = typing.TypeVar("_JsonDecryptorT", bound=types.JsonDecryptor)
+
 
 class LangGraphBetaWarning(UserWarning):
     """Warning for beta features in LangGraph SDK."""
@@ -141,7 +144,7 @@ class _DecryptDecorators:
     def __init__(self, parent: Encryption):
         self._parent = parent
 
-    def blob(self, fn: types.BlobDecryptor) -> types.BlobDecryptor:
+    def blob(self, fn: _BlobDecryptorT) -> _BlobDecryptorT:
         """Register a blob decryption handler.
 
         The handler will be called to decrypt opaque data like checkpoint blobs.
@@ -149,7 +152,9 @@ class _DecryptDecorators:
         Example:
             ```python
             @encryption.decrypt.blob
-            async def decrypt_blob(ctx: EncryptionContext, blob: bytes) -> bytes:
+            async def decrypt_blob(
+                ctx: EncryptionContext, blob: bytes
+            ) -> bytes | DecryptResult[bytes]:
                 # Decrypt the blob using your encryption service
                 return decrypted_blob
             ```
@@ -170,13 +175,15 @@ class _DecryptDecorators:
         self._parent._blob_decryptor = fn
         return fn
 
-    def json(self, fn: types.JsonDecryptor) -> types.JsonDecryptor:
+    def json(self, fn: _JsonDecryptorT) -> _JsonDecryptorT:
         """Register the JSON decryption handler.
 
         Example:
             ```python
             @encryption.decrypt.json
-            async def decrypt_json(ctx: EncryptionContext, data: dict) -> dict:
+            async def decrypt_json(
+                ctx: EncryptionContext, data: dict
+            ) -> dict | DecryptResult[dict]:
                 # Decrypt the data
                 return decrypt_data(data)
             ```
@@ -369,7 +376,7 @@ class Encryption:
     """Reference to encryption type definitions.
 
     Provides access to all type definitions used in the encryption system,
-    including EncryptionContext, BlobEncryptor, BlobDecryptor,
+    including EncryptionContext, DecryptResult, BlobEncryptor, BlobDecryptor,
     JsonEncryptor, and JsonDecryptor.
     """
 

libs/sdk-py/langgraph_sdk/encryption/types.py

@@ -9,10 +9,30 @@ from __future__ import annotations
 
 import typing
 from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
 
 Json = dict[str, typing.Any]
 """JSON-serializable dictionary type for structured data encryption."""
 
+T = typing.TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class DecryptResult(typing.Generic[T]):
+    """Decrypted data and optional replacement ciphertext.
+
+    Return this from a decrypt handler when encrypted data should be replaced,
+    such as after rotating its encryption key. Returning plaintext directly
+    remains supported when no replacement is needed.
+
+    Attributes:
+        plaintext: Decrypted data returned to the caller
+        replacement: New encrypted data to persist in place of the input
+    """
+
+    plaintext: T
+    replacement: T | None = None
+
 
 class EncryptionContext:
     """Context passed to encryption/decryption handlers.
@@ -57,7 +77,9 @@ Returns:
     Awaitable that resolves to encrypted bytes
 """
 
-BlobDecryptor = Callable[[EncryptionContext, bytes], Awaitable[bytes]]
+BlobDecryptor = Callable[
+    [EncryptionContext, bytes], Awaitable[bytes | DecryptResult[bytes]]
+]
 """Handler for decrypting opaque blob data like checkpoints.
 
 Note: Must be an async function. Decryption typically involves I/O operations
@@ -68,7 +90,8 @@ Args:
     blob: The encrypted bytes to decrypt
 
 Returns:
-    Awaitable that resolves to decrypted bytes
+    Awaitable that resolves to decrypted bytes, or a DecryptResult containing
+    decrypted bytes and replacement ciphertext
 """
 
 JsonEncryptor = Callable[[EncryptionContext, Json], Awaitable[Json]]
@@ -101,7 +124,9 @@ Returns:
     Awaitable that resolves to encrypted JSON dictionary
 """
 
-JsonDecryptor = Callable[[EncryptionContext, Json], Awaitable[Json]]
+JsonDecryptor = Callable[
+    [EncryptionContext, Json], Awaitable[Json | DecryptResult[Json]]
+]
 """Handler for decrypting structured JSON data.
 
 Note: Must be an async function. Decryption typically involves I/O operations
@@ -115,7 +140,8 @@ Args:
     data: The encrypted JSON dictionary
 
 Returns:
-    Awaitable that resolves to decrypted JSON dictionary
+    Awaitable that resolves to a decrypted JSON dictionary, or a DecryptResult
+    containing decrypted JSON and replacement ciphertext
 """
 
 if typing.TYPE_CHECKING:

libs/sdk-py/tests/test_encryption.py

@@ -1,8 +1,40 @@
+from collections.abc import Awaitable, Callable
+
 import pytest
 
+from langgraph_sdk import DecryptResult, EncryptionContext
 from langgraph_sdk.encryption import DuplicateHandlerError, Encryption
 
 
+def test_decrypt_result():
+    result = DecryptResult(plaintext=b"plain", replacement=b"rotated")
+
+    assert result.plaintext == b"plain"
+    assert result.replacement == b"rotated"
+    assert DecryptResult(plaintext={"plain": True}).replacement is None
+
+
+def test_decrypt_decorators_preserve_return_types():
+    encryption = Encryption()
+
+    @encryption.decrypt.blob
+    async def blob_dec(_ctx: EncryptionContext, data: bytes) -> bytes:
+        return data
+
+    @encryption.decrypt.json
+    async def json_dec(
+        _ctx: EncryptionContext, data: dict[str, object]
+    ) -> dict[str, object]:
+        return data
+
+    blob_handler: Callable[[EncryptionContext, bytes], Awaitable[bytes]] = blob_dec
+    json_handler: Callable[
+        [EncryptionContext, dict[str, object]], Awaitable[dict[str, object]]
+    ] = json_dec
+    assert blob_handler is blob_dec
+    assert json_handler is json_dec
+
+
 class TestHandlerValidation:
     """Test duplicate handler and signature validation."""