agentseek-api 0.2.3__tar.gz → 0.3.1__tar.gz

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/.env.example

@@ -12,7 +12,7 @@ AUTH_MODULE_PATH=
 # REDIS_STREAM_MAXLEN=10000
 # REDIS_STREAM_TTL_SECONDS=3600
 
-# Embedded SeekDB — set to true for a zero-config local backend.
+# Embedded seekdb — set to true for a zero-config local backend.
 # Data stored in SEEKDB_EMBED_DIR (default: ~/.agentseek/seekdb_data).
 # Requires: uv sync --dev --extra embedded
 # SEEKDB_EMBED=true

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/.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,11 +96,13 @@ 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
 
-      - name: Sync embedded SeekDB extra for serve smoke
+      - name: Sync embedded seekdb extra for serve smoke
         if: runner.os == 'Linux' || (runner.os == 'macOS' && runner.arch == 'ARM64')
         run: uv sync --dev --extra embedded
 
@@ -109,7 +115,7 @@ jobs:
         run: uv run python scripts/test_minimum_cli_dependencies.py
 
   embedded-seekdb-smoke:
-    name: Embedded SeekDB Smoke
+    name: Embedded seekdb Smoke
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
@@ -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
 

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/CHANGELOG.md

@@ -4,6 +4,63 @@ Notable changes to AgentSeek API are documented in this file.
 
 ## Unreleased
 
+## 0.3.1 - 2026-09-03
+
+### Highlights
+
+- Upgraded both the base and embedded `langchain-oceanbase` dependency pins to
+  0.6.3, with the resolved embedded seekdb stack at `pylibseekdb` 1.4.0,
+  `pyobvector` 0.2.29, and `pyseekdb` 1.4.0.post1.
+- Synchronized package metadata, generated container runtime artifacts,
+  attestations, scripts, fixtures, and runtime labels at 0.3.1.
+- Restricted the supported Python range to `>=3.12,<3.14` and made generated
+  runtime verification reject unsupported Python versions.
+- Normalized current human-facing documentation and runtime prose to the
+  lowercase `seekdb` product spelling.
+
+### Upgrade notes
+
+- No API or schema migration is required for this release.
+
+## 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

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/CONTRIBUTING.md

@@ -31,8 +31,8 @@ GitHub Actions is split into three validation layers:
   Coverage-backed unit and integration suite (`make test-cov`) on every supported push and PR.
 - Sample Graphs
   In-process graph runner plus the in-process API smoke flow (`make test-samples`).
-- SeekDB Validation
-  Real backend checkpoint smoke plus live HTTP e2e coverage (`make test-seekdb`) on PRs to `develop` or `main`, and on pushes to `develop`, `main`, `release/*`, and `hotfix/*`. CI runs this in a Docker matrix across `seekdb`, `oceanbase`, and `mysql`, while local quick verification should prefer embedded SeekDB via `scripts/seekdb_embed_launcher.py`.
+- seekdb Validation
+  Real backend checkpoint smoke plus live HTTP e2e coverage (`make test-seekdb`) on PRs to `develop` or `main`, and on pushes to `develop`, `main`, `release/*`, and `hotfix/*`. CI runs this in a Docker matrix across `seekdb`, `oceanbase`, and `mysql`, while local quick verification should prefer embedded seekdb via `scripts/seekdb_embed_launcher.py`.
 
 Keep local commands aligned with CI when possible:
 
@@ -42,6 +42,6 @@ Keep local commands aligned with CI when possible:
 - `make test-e2e`
 - `make test-seekdb`
 
-For embedded SeekDB locally, install the optional extra first:
+For embedded seekdb locally, install the optional extra first:
 
 - `uv sync --dev --extra embedded`

agentseek_api-0.2.3/README.md → agentseek_api-0.3.1/PKG-INFO

@@ -1,8 +1,41 @@
+Metadata-Version: 2.5
+Name: agentseek-api
+Version: 0.3.1
+Summary: AgentSeek API core runtime with OceanBase checkpoints.
+License-File: LICENSE
+Requires-Python: <3.14,>=3.12
+Requires-Dist: aiomysql>=0.2.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: cryptography>=45.0.0
+Requires-Dist: fastapi>=0.110.1
+Requires-Dist: greenlet>=3.1.0
+Requires-Dist: langchain-anthropic>=1.0.0
+Requires-Dist: langchain-core>=1.2.5
+Requires-Dist: langchain-oceanbase==0.6.3
+Requires-Dist: langchain-openai>=1.0.0
+Requires-Dist: langchain>=0.3.9
+Requires-Dist: langgraph-sdk>=0.3.5
+Requires-Dist: langgraph>=1.0.6
+Requires-Dist: mcp<2,>=1.27.1
+Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: pymysql>=1.1.0
+Requires-Dist: python-dotenv<1.3,>=1.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: scalar-fastapi>=1.0.3
+Requires-Dist: sqlalchemy>=2.0.12
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: embedded
+Requires-Dist: langchain-oceanbase[pyseekdb]==0.6.3; extra == 'embedded'
+Description-Content-Type: text/markdown
+
 # AgentSeek API
 
 **English** | [中文](README.zh-CN.md)
 
-[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python >=3.12](https://img.shields.io/badge/python-%3E%3D3.12-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
+[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python 3.12-3.13](https://img.shields.io/badge/python-3.12--3.13-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
 
 > [!WARNING]
 > This project is under active development and is **not production-ready**.
@@ -33,7 +66,7 @@ Current release boundary:
 
 ### Prerequisites
 
-- Python 3.12+
+- Python >=3.12,<3.14
 - `uv`
 
 ### Choose the right local loop
@@ -83,7 +116,7 @@ uv sync --extra embedded
 ### 2. Configure seekdb embed as the default backend (recommended)
 
 The fastest way to get a real backend running locally is **seekdb embed** — an
-in-process SeekDB instance, no Docker or separate process required:
+in-process seekdb instance, no Docker or separate process required:
 
 ```bash
 SEEKDB_EMBED=true agentseek-api dev
@@ -296,7 +329,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 +356,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,11 +446,45 @@ 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 contract introduced in 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.1`
+
+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
 Store API and the injected LangGraph `BaseStore` runtime for TTL and semantic
-search. This repo uses the published `langchain-oceanbase==0.5.2` package from
+search. This repo uses the published `langchain-oceanbase==0.6.3` package from
 PyPI.
 
 Config-driven custom auth can live in `agentseek.json` or `langgraph.json`:

agentseek_api-0.2.3/PKG-INFO → agentseek_api-0.3.1/README.md

@@ -1,40 +1,8 @@
-Metadata-Version: 2.5
-Name: agentseek-api
-Version: 0.2.3
-Summary: AgentSeek API core runtime with OceanBase checkpoints.
-License-File: LICENSE
-Requires-Python: >=3.12
-Requires-Dist: aiomysql>=0.2.0
-Requires-Dist: aiosqlite>=0.20.0
-Requires-Dist: asyncpg>=0.29.0
-Requires-Dist: cryptography>=45.0.0
-Requires-Dist: fastapi>=0.110.1
-Requires-Dist: greenlet>=3.1.0
-Requires-Dist: langchain-anthropic>=1.0.0
-Requires-Dist: langchain-core>=1.2.5
-Requires-Dist: langchain-oceanbase==0.6.0
-Requires-Dist: langchain-openai>=1.0.0
-Requires-Dist: langchain>=0.3.9
-Requires-Dist: langgraph-sdk>=0.3.5
-Requires-Dist: langgraph>=1.0.6
-Requires-Dist: mcp<2,>=1.27.1
-Requires-Dist: pydantic-settings>=2.4.0
-Requires-Dist: pydantic>=2.8.0
-Requires-Dist: pymysql>=1.1.0
-Requires-Dist: python-dotenv<1.3,>=1.0
-Requires-Dist: redis>=5.0.0
-Requires-Dist: scalar-fastapi>=1.0.3
-Requires-Dist: sqlalchemy>=2.0.12
-Requires-Dist: uvicorn>=0.30.0
-Provides-Extra: embedded
-Requires-Dist: langchain-oceanbase[pyseekdb]==0.6.0; extra == 'embedded'
-Description-Content-Type: text/markdown
-
 # AgentSeek API
 
 **English** | [中文](README.zh-CN.md)
 
-[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python >=3.12](https://img.shields.io/badge/python-%3E%3D3.12-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
+[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python 3.12-3.13](https://img.shields.io/badge/python-3.12--3.13-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
 
 > [!WARNING]
 > This project is under active development and is **not production-ready**.
@@ -65,7 +33,7 @@ Current release boundary:
 
 ### Prerequisites
 
-- Python 3.12+
+- Python >=3.12,<3.14
 - `uv`
 
 ### Choose the right local loop
@@ -115,7 +83,7 @@ uv sync --extra embedded
 ### 2. Configure seekdb embed as the default backend (recommended)
 
 The fastest way to get a real backend running locally is **seekdb embed** — an
-in-process SeekDB instance, no Docker or separate process required:
+in-process seekdb instance, no Docker or separate process required:
 
 ```bash
 SEEKDB_EMBED=true agentseek-api dev
@@ -328,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
@@ -355,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,
@@ -436,11 +413,45 @@ 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 contract introduced in 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.1`
+
+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
 Store API and the injected LangGraph `BaseStore` runtime for TTL and semantic
-search. This repo uses the published `langchain-oceanbase==0.5.2` package from
+search. This repo uses the published `langchain-oceanbase==0.6.3` package from
 PyPI.
 
 Config-driven custom auth can live in `agentseek.json` or `langgraph.json`:

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | **中文**
 
-[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python >=3.12](https://img.shields.io/badge/python-%3E%3D3.12-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
+[![PyPI version](https://img.shields.io/pypi/v/agentseek-api.svg)](https://pypi.org/project/agentseek-api/) [![Python 3.12-3.13](https://img.shields.io/badge/python-3.12--3.13-blue.svg)](https://pypi.org/project/agentseek-api/) [![CI](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ob-labs/agentseek-api/actions/workflows/ci.yml?query=branch%3Amain)
 
 > [!WARNING]
 > 本项目正在积极开发中，**尚未达到生产可用状态**。
@@ -32,7 +32,7 @@
 
 ### 前置条件
 
-- Python 3.12+
+- Python >=3.12,<3.14
 - `uv`
 
 ### 选择合适的本地开发循环
@@ -80,7 +80,7 @@ uv sync --extra embedded
 
 ### 2. 将 seekdb embed 配置为默认后端（推荐）
 
-最快获得真实后端的方式是 **seekdb embed** — 一个进程内嵌入式 SeekDB 实例，
+最快获得真实后端的方式是 **seekdb embed** — 一个进程内嵌入式 seekdb 实例，
 无需 Docker 或独立进程：
 
 ```bash
@@ -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,11 +379,40 @@ 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.1`
+
+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
 `BaseStore` 运行时用于 TTL 与语义检索。本仓库使用 PyPI 上发布的
-`langchain-oceanbase==0.5.2` 包。
+`langchain-oceanbase==0.6.3` 包。
 
 配置驱动的自定义鉴权可以放在 `agentseek.json` 或 `langgraph.json` 中：
 

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/examples/README.md

@@ -42,7 +42,7 @@ uv run python examples/external_graph/run.py
 ```
 
 Invokes every sample graph directly through LangGraph — no HTTP server, no
-SeekDB. Useful during development when you want a tight feedback loop.
+seekdb. Useful during development when you want a tight feedback loop.
 
 ## Running them through the HTTP API
 
@@ -76,7 +76,7 @@ curl -s http://127.0.0.1:2024/threads/$THREAD_ID/runs/$RUN_ID/wait \
 `tests/e2e/e2e_live_http_multi_graph.py` does the full dance against every
 registered sample. `make test-cli-dev-samples` runs that sweep through the
 `agentseek dev` CLI, and `make test-seekdb` runs it end-to-end against a real
-SeekDB-compatible backend.
+seekdb-compatible backend.
 
 ## Adding your own graph
 

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/examples/run_sample_graphs.py

@@ -1,7 +1,7 @@
 """Run every sample graph once, in-process, to prove they import and execute.
 
 Useful as a local smoke test while developing a new graph. Does not require
-the HTTP server or SeekDB — it invokes each compiled graph directly through
+the HTTP server or seekdb — it invokes each compiled graph directly through
 LangGraph.
 """
 

{agentseek_api-0.2.3 → agentseek_api-0.3.1}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "agentseek-api"
-version = "0.2.3"
+version = "0.3.1"
 description = "AgentSeek API core runtime with OceanBase checkpoints."
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.12,<3.14"
 dependencies = [
     "fastapi>=0.110.1",
     "uvicorn>=0.30.0",
@@ -20,18 +20,19 @@ dependencies = [
     "langchain-core>=1.2.5",
     "langchain-openai>=1.0.0",
     "langchain-anthropic>=1.0.0",
-    "langchain-oceanbase==0.6.0",
+    "langchain-oceanbase==0.6.3",
     "cryptography>=45.0.0",
     "pymysql>=1.1.0",
     "langchain>=0.3.9",
     "mcp>=1.27.1,<2",
     "python-dotenv>=1.0,<1.3",
     "scalar-fastapi>=1.0.3",
+    "packaging>=24.0",
 ]
 
 [project.optional-dependencies]
 embedded = [
-    "langchain-oceanbase[pyseekdb]==0.6.0",
+    "langchain-oceanbase[pyseekdb]==0.6.3",
 ]
 
 [project.scripts]
@@ -53,6 +54,9 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+exclude = ["/.superpowers", "/docs/superpowers"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/agentseek_api"]
 
@@ -60,5 +64,6 @@ packages = ["src/agentseek_api"]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 markers = [
-    "e2e: end-to-end tests against a live server and real SeekDB/OceanBase backend",
+    "docker: tests requiring Docker or Docker Compose",
+    "e2e: end-to-end tests against a live server and real seekdb/OceanBase backend",
 ]