feat: enforce container environment boundaries

.github/workflows/ci.yml

@@ -44,7 +44,13 @@ jobs:
         run: uv sync --dev
 
       - name: Coverage-backed unit + integration suite
-        run: make test-cov
+        run: >-
+          uv run pytest tests/unit tests/integration
+          -m 'not docker'
+          --cov=src/agentseek_api
+          --cov-report=term-missing
+          --cov-fail-under=90
+          -q
 
   cli-compatibility:
     name: CLI Compatibility (${{ matrix.os }})
@@ -78,9 +84,7 @@ jobs:
         run: uv run python scripts/test_cli_config_autodiscovery.py
 
       - name: Dockerfile command renders a runnable config
-        run: >-
-          uv run python -c
-          "from pathlib import Path; import subprocess; out = Path('.tmp/agentseek.Dockerfile'); out.parent.mkdir(exist_ok=True); subprocess.run(['uv', 'run', 'agentseek-api', 'dockerfile', '--config', 'examples/external_graph/manifest.json', str(out)], check=True); text = out.read_text(encoding='utf-8'); assert 'ENV PYTHONPATH=/deps/agent' in text; assert 'ENV AGENTSEEK_GRAPHS=/deps/agent/examples/external_graph/manifest.json' in text"
+        run: uv run python scripts/test_cli_config_autodiscovery.py --config examples/external_graph/manifest.json
 
       - name: CLI config, host environment, and process tests
         run: >-
@@ -92,6 +96,8 @@ jobs:
           tests/unit/test_runtime_entrypoint.py
           tests/unit/test_process_supervisor.py
           tests/unit/test_sqlite_checkpointer.py
+          tests/unit/test_container_policy.py
+          tests/unit/test_secure_temp.py
           tests/integration/test_cli_runtime_processes.py
           tests/integration/test_metadata_db_config.py
           -q
@@ -130,9 +136,15 @@ jobs:
         run: uv run python scripts/test_cli_embed_serve_smoke.py
 
   cli-docker-runtime:
-    name: CLI Docker Runtime
+    name: CLI Docker Runtime (Compose ${{ matrix.compose-version }})
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        compose-version:
+          - runner-current
+          - v2.24.0
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -147,6 +159,21 @@ jobs:
       - name: Sync dependencies
         run: uv sync --dev
 
+      - name: Install Compose floor
+        if: matrix.compose-version == 'v2.24.0'
+        uses: docker/setup-compose-action@2fe291b7677a45ee1269ec56a42604c143505e7e # v1
+        with:
+          version: v2.24.0
+
+      - name: Record Compose version
+        run: docker compose version --short
+
+      - name: Container environment boundary
+        run: uv run python scripts/test_container_env_boundary.py
+
+      - name: Docker and Compose regression suite
+        run: uv run pytest tests/unit/test_docker_runtime.py -m docker -q
+
       - name: CLI Docker smoke
         run: make test-cli-docker
 

CHANGELOG.md

@@ -4,6 +4,45 @@ Notable changes to AgentSeek API are documented in this file.
 
 ## Unreleased
 
+## 0.3.0 - 2026-08-20
+
+### Highlights
+
+- Added the explicit `preloaded-v1` container environment contract so the host
+  remains the single owner of application environment resolution.
+- Generated containers install and attest the exact
+  `agentseek-api[embedded]==0.3.0` runtime independently of project
+  dependencies.
+- Hardened Docker, Compose, and build-context boundaries so application values
+  are carried only to the declared runtime target and credential-bearing source
+  files are excluded from image inputs.
+- Defined compatible custom-image labels and runtime-manifest checks for
+  `preloaded-v1` launches.
+
+### Upgrade notes
+
+- Container projects that pin `agentseek-api==0.2.2`, or otherwise exclude
+  `0.3.0`, must update their dependency constraint before using generated
+  images.
+- Custom images must publish the `preloaded-v1` environment-contract, runtime
+  manifest, distribution, and version labels; older images must keep using the
+  older launcher until migrated.
+- `dockerfile` now writes a complete build-bundle directory. Declare only
+  reviewed project paths with `build_include`; credentialed `pip_config_file`
+  input is delivered as a BuildKit secret rather than copied into the bundle.
+- Container application values cross only an explicit runtime boundary:
+  `--pass-env` selects the direct Docker carrier, while `compose_env` and
+  `--compose-pass-env` select the private Compose dotenv carrier. All are
+  trusted-input declarations and none authorize values to enter the build.
+- Custom images must provide the exact `org.agentseek.environment-contract`,
+  `org.agentseek.runtime-manifest`, `org.agentseek.runtime-distribution`, and
+  `org.agentseek.runtime-version` labels and matching manifest/runtime state.
+  There is no legacy-image fallback.
+- Release Train A shipped API 0.2.3, templates 0.1.3, and AgentSeek 0.1.3. The
+  planned Train B template/catalog release is 0.1.4. The separate planned
+  AgentSeek release is also 0.1.4; both follow their shipped 0.1.3 releases and
+  remain separate release gates.
+
 ## 0.2.3 - 2026-08-17
 
 ### Fixed

README.md

@@ -296,7 +296,7 @@ keys with similar names.
 uv run agentseek-api dev
 uv run agentseek-api serve --config ./langgraph.json --port 8080
 uv run agentseek-api worker --config ./langgraph.json
-uv run agentseek-api dockerfile --config ./langgraph.json ./Dockerfile.agentseek
+uv run agentseek-api dockerfile --config ./langgraph.json ./agentseek-build-bundle
 uv run agentseek-api build --config ./langgraph.json -t agentseek-api:dev
 uv run agentseek-api up --config ./langgraph.json --port 8123 --wait
 uv run agentseek-api version
@@ -323,9 +323,18 @@ uv run agentseek-api version
 - `build`
   - Use `-t, --tag` to set the image tag
   - Supports `--platform`, `--pull`, and `--no-pull`
+- `dockerfile`
+  - Writes a complete private build-bundle directory, including the generated
+    `Dockerfile`, sanitized runtime manifest, and selected project files; the
+    output argument is a new directory, not a standalone Dockerfile path
 - `up`
   - Supports `--wait`, `--image`, `--base-image`, `--postgres-uri`,
     `--recreate`, and `--no-recreate`
+  - `--pass-env NAME` explicitly selects a resolved application value for the
+    direct Docker carrier; the value is inherited by name and never put in argv
+  - `--compose-pass-env NAME` explicitly selects a resolved application value
+    for Compose interpolation; config can make the same selection with
+    `compose_env`
 
 Some LangGraph CLI-shaped flags are parsed for command compatibility but
 rejected when their runtime behavior is not implemented yet. For mocked,
@@ -404,6 +413,40 @@ Useful config fields:
 - `http.disable_a2a`: disable the A2A endpoint and agent-card discovery route
 - `base_image`, `python_version`, `image_distro`, `pip_config_file`,
   `dockerfile_lines`: Docker build customization fields
+- `build_include`: additional trusted regular files or directory trees to copy
+  into the sanitized build bundle
+- `compose_env`: names from the already-resolved application environment that
+  may cross into an explicitly selected Compose dotenv carrier
+
+### Container migration for 0.3.0
+
+The `preloaded-v1` contract is a breaking, fail-closed container boundary. The
+host resolves application configuration once. Containers started from generated images receive only
+the selected runtime payload, while ambient host values, dotenv files, package
+credentials, and unselected Compose values stay outside the build context and
+image layers. Use `--pass-env` or `--compose-pass-env` only for trusted input;
+these flags authorize a value to cross the named runtime boundary, not to enter
+the build.
+
+`build_include` is also a trusted-input declaration: review every selected path.
+Credentialed Python indexes belong in `pip_config_file`, which is mounted as a
+BuildKit pip secret and is not copied into the context. The `dockerfile` command
+now writes the complete bundle directory consumed by Docker rather than a lone
+Dockerfile.
+
+Custom images must expose all four exact labels:
+
+- `org.agentseek.environment-contract=preloaded-v1`
+- `org.agentseek.runtime-manifest=/opt/agentseek/manifest.v1.json`
+- `org.agentseek.runtime-distribution=agentseek-api`
+- `org.agentseek.runtime-version=0.3.0`
+
+The manifest, installed distribution, entrypoint, and labels must agree. There
+is no legacy-image fallback: migrate and attest the image before passing it to
+`up --image`, or keep using the older launcher with the older image. Release
+Train A coordinates are API 0.2.3, templates 0.1.3, and AgentSeek 0.1.3; the
+The planned Train B template/catalog release is 0.1.4. The separate planned
+AgentSeek release is also 0.1.4; both follow the shipped 0.1.3 releases.
 
 Endpoint-level LangGraph config keys such as `http` and `api_version` are
 tolerated by the CLI layer where possible. Store config is used by the HTTP

README.zh-CN.md

@@ -262,7 +262,7 @@ agentseek-api <command> [arguments]
 uv run agentseek-api dev
 uv run agentseek-api serve --config ./langgraph.json --port 8080
 uv run agentseek-api worker --config ./langgraph.json
-uv run agentseek-api dockerfile --config ./langgraph.json ./Dockerfile.agentseek
+uv run agentseek-api dockerfile --config ./langgraph.json ./agentseek-build-bundle
 uv run agentseek-api build --config ./langgraph.json -t agentseek-api:dev
 uv run agentseek-api up --config ./langgraph.json --port 8123 --wait
 uv run agentseek-api version
@@ -289,9 +289,17 @@ uv run agentseek-api version
 - `build`
   - 使用 `-t, --tag` 设置镜像 tag
   - 支持 `--platform`、`--pull`、`--no-pull`
+- `dockerfile`
+  - 输出完整的私有构建 bundle 目录，其中包含生成的 `Dockerfile`、净化后的
+    runtime manifest 与选中的项目文件；输出参数必须是新目录，而不是单个
+    Dockerfile 文件路径
 - `up`
   - 支持 `--wait`、`--image`、`--base-image`、`--postgres-uri`、
     `--recreate`、`--no-recreate`
+  - `--pass-env NAME` 显式选择一个已解析的应用变量，通过名称继承方式交给
+    直接 Docker carrier，变量值不会进入 argv
+  - `--compose-pass-env NAME` 显式选择一个已解析的应用变量交给 Compose；
+    配置文件中的 `compose_env` 提供同样的选择能力
 
 部分仿照 LangGraph CLI 的参数会为了命令兼容性被解析，但当对应运行时
 行为还未实现时会被直接拒绝。对于 mock、内存或 tunnel 化的本地工作流，
@@ -371,6 +379,35 @@ Redis 实例同时运行。
 - `http.disable_a2a`：关闭 A2A 端点及 agent-card 发现路由
 - `base_image`、`python_version`、`image_distro`、`pip_config_file`、
   `dockerfile_lines`：Docker 构建自定义字段
+- `build_include`：额外复制到净化构建 bundle 中的受信任普通文件或目录树
+- `compose_env`：允许通过显式 Compose dotenv carrier 的、已完成解析的应用
+  环境变量名称
+
+### 0.3.0 容器迁移
+
+`preloaded-v1` 是不兼容旧行为、失败即关闭的容器边界。宿主机只解析一次
+应用配置。从生成镜像启动的容器只接收显式选择的运行时 payload；宿主机环境、dotenv
+文件、包仓库凭证和未选择的 Compose 值都不会进入构建上下文或镜像层。
+`--pass-env` 与 `--compose-pass-env` 只应接收可信输入：它们授权变量跨越指定
+运行时边界，并不允许变量进入镜像构建。
+
+`build_include` 同样属于可信输入声明，必须审查每条路径。带凭证的 Python
+仓库配置应使用 `pip_config_file`，CLI 会将其作为 BuildKit pip secret 挂载，
+不会复制到上下文。`dockerfile` 命令现在输出 Docker 实际消费的完整 bundle
+目录，而不是单独的 Dockerfile。
+
+自定义镜像必须提供以下四个精确标签：
+
+- `org.agentseek.environment-contract=preloaded-v1`
+- `org.agentseek.runtime-manifest=/opt/agentseek/manifest.v1.json`
+- `org.agentseek.runtime-distribution=agentseek-api`
+- `org.agentseek.runtime-version=0.3.0`
+
+manifest、已安装 distribution、entrypoint 与标签必须一致。系统不提供旧镜像
+回退：传给 `up --image` 前必须完成迁移与校验；否则应继续用旧 launcher 配合
+旧镜像。Train A 已达成版本为 API 0.2.3、templates 0.1.3、AgentSeek 0.1.3；
+后续 Train B 的 template/catalog 计划单独发布 0.1.4。AgentSeek 也计划另行发布
+0.1.4；两者都基于已经发布的 0.1.3。
 
 CLI 层会尽量容忍 LangGraph 在端点级别使用的配置键，例如 `http` 与
 `api_version`。Store 配置会被 HTTP Store API 以及注入的 LangGraph

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentseek-api"
-version = "0.2.3"
+version = "0.3.0"
 description = "AgentSeek API core runtime with OceanBase checkpoints."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -27,6 +27,7 @@ dependencies = [
     "mcp>=1.27.1,<2",
     "python-dotenv>=1.0,<1.3",
     "scalar-fastapi>=1.0.3",
+    "packaging>=24.0",
 ]
 
 [project.optional-dependencies]
@@ -60,5 +61,6 @@ packages = ["src/agentseek_api"]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
+    "docker: tests requiring Docker or Docker Compose",
     "e2e: end-to-end tests against a live server and real SeekDB/OceanBase backend",
 ]