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

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/.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
 

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/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

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentseek-api
-Version: 0.2.3
+Version: 0.3.0
 Summary: AgentSeek API core runtime with OceanBase checkpoints.
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -18,6 +18,7 @@ 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
@@ -328,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
@@ -355,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,
@@ -436,6 +446,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

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/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

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/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

{agentseek_api-0.2.3 → agentseek_api-0.3.0}/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]
@@ -53,6 +54,9 @@ dev = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build]
+exclude = ["/.superpowers"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/agentseek_api"]
 
@@ -60,5 +64,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",
 ]

agentseek_api-0.3.0/scripts/container_image_archive.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""Fail-closed structural scanning for Docker-save and OCI image archives."""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import io
+import json
+import os
+import posixpath
+import tarfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+class ImageArchiveError(RuntimeError):
+    """A value-free image archive validation failure."""
+
+
+_OCI_CONFIG_MEDIA_TYPES = {
+    "application/vnd.oci.image.config.v1+json",
+    "application/vnd.docker.container.image.v1+json",
+}
+_OCI_MANIFEST_MEDIA_TYPES = {
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+}
+_OCI_LAYER_ENCODINGS = {
+    "application/vnd.oci.image.layer.v1.tar": "tar",
+    "application/vnd.oci.image.layer.v1.tar+gzip": "gzip",
+    "application/vnd.oci.image.layer.v1.tar+zstd": "zstd",
+    "application/vnd.docker.image.rootfs.diff.tar": "tar",
+    "application/vnd.docker.image.rootfs.diff.tar.gzip": "gzip",
+}
+
+
+def _safe_name(name: str) -> bool:
+    return (
+        bool(name)
+        and not name.startswith("/")
+        and posixpath.normpath(name) == name
+        and not any(part in {"", ".", ".."} for part in name.split("/"))
+    )
+
+
+def _canonical_tar_name(name: str) -> str | None:
+    if not name or "\x00" in name or name.startswith("/"):
+        return None
+    trimmed = name.rstrip("/")
+    if any(part == ".." for part in trimmed.split("/")):
+        return None
+    normalized = posixpath.normpath(trimmed)
+    if normalized == ".." or normalized.startswith("../"):
+        return None
+    return normalized
+
+
+def _json_object(payload: bytes, boundary: str) -> Mapping[str, Any]:
+    try:
+        value = json.loads(payload)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ImageArchiveError(f"{boundary} JSON was malformed") from exc
+    if not isinstance(value, dict):
+        raise ImageArchiveError(f"{boundary} JSON shape was invalid")
+    return value
+
+
+def _tar_files(payload: bytes, boundary: str) -> dict[str, bytes]:
+    files: dict[str, bytes] = {}
+    names: set[str] = set()
+    try:
+        with tarfile.open(fileobj=io.BytesIO(payload), mode="r:") as archive:
+            for member in archive:
+                name = _canonical_tar_name(member.name)
+                if name is None or (name == "." and not member.isdir()):
+                    raise ImageArchiveError(f"{boundary} member path was unsafe")
+                if name == ".":
+                    continue
+                if name in names:
+                    raise ImageArchiveError(f"{boundary} contained duplicate members")
+                names.add(name)
+                if member.isfile():
+                    stream = archive.extractfile(member)
+                    if stream is None:
+                        raise ImageArchiveError(f"{boundary} member was unreadable")
+                    files[name] = stream.read()
+    except ImageArchiveError:
+        raise
+    except (tarfile.TarError, OSError, EOFError) as exc:
+        raise ImageArchiveError(f"{boundary} was malformed") from exc
+    return files
+
+
+def _require_file(
+    files: Mapping[str, bytes], reference: object, boundary: str
+) -> bytes:
+    if not isinstance(reference, str) or not _safe_name(reference):
+        raise ImageArchiveError(f"{boundary} reference path was unsafe")
+    if reference not in files:
+        raise ImageArchiveError(f"{boundary} reference was missing")
+    return files[reference]
+
+
+def _scan_forbidden(payload: bytes, forbidden: bytes) -> None:
+    if not forbidden:
+        raise ImageArchiveError("forbidden byte sequence was empty")
+    if forbidden in payload:
+        raise ImageArchiveError("image surface contained forbidden bytes")
+
+
+def _decode_layer(payload: bytes, encoding: str | None = None) -> bytes:
+    if encoding is None:
+        if payload.startswith(b"\x1f\x8b"):
+            encoding = "gzip"
+        elif payload.startswith(b"\x28\xb5\x2f\xfd"):
+            encoding = "zstd"
+        else:
+            encoding = "tar"
+    if encoding == "gzip":
+        try:
+            return gzip.decompress(payload)
+        except (OSError, EOFError) as exc:
+            raise ImageArchiveError("image layer compression was malformed") from exc
+    if encoding == "zstd":
+        try:
+            import zstandard
+        except ImportError as exc:
+            raise ImageArchiveError("zstd layer support was unavailable") from exc
+        try:
+            return zstandard.ZstdDecompressor().decompress(payload)
+        except zstandard.ZstdError as exc:
+            raise ImageArchiveError("image layer compression was malformed") from exc
+    if encoding == "tar":
+        return payload
+    raise ImageArchiveError("image layer compression was unsupported")
+
+
+def _scan_layer(
+    payload: bytes, forbidden: bytes, *, encoding: str | None = None
+) -> None:
+    decoded = _decode_layer(payload, encoding)
+    _scan_forbidden(decoded, forbidden)
+    for member_payload in _tar_files(decoded, "image layer").values():
+        _scan_forbidden(member_payload, forbidden)
+
+
+def _scan_docker_save(files: Mapping[str, bytes], forbidden: bytes) -> None:
+    try:
+        manifest = json.loads(
+            _require_file(files, "manifest.json", "Docker save manifest")
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ImageArchiveError("Docker save manifest JSON was malformed") from exc
+    if (
+        not isinstance(manifest, list)
+        or len(manifest) != 1
+        or not isinstance(manifest[0], dict)
+    ):
+        raise ImageArchiveError("Docker save manifest shape was unsupported")
+    entry = manifest[0]
+    config_reference = entry.get("Config")
+    layer_references = entry.get("Layers")
+    if not isinstance(layer_references, list) or not layer_references:
+        raise ImageArchiveError("Docker save layer references were invalid")
+    if (
+        not isinstance(config_reference, str)
+        or any(not isinstance(reference, str) for reference in layer_references)
+        or config_reference in layer_references
+    ):
+        raise ImageArchiveError("Docker save references were invalid")
+    config = _require_file(files, config_reference, "Docker save config")
+    _json_object(config, "Docker save config")
+    _scan_forbidden(config, forbidden)
+    for reference in dict.fromkeys(layer_references):
+        _scan_layer(_require_file(files, reference, "Docker save layer"), forbidden)
+
+
+def _oci_blob(
+    files: Mapping[str, bytes],
+    descriptor: object,
+    media_types: set[str],
+    boundary: str,
+) -> tuple[bytes, str]:
+    if not isinstance(descriptor, dict):
+        raise ImageArchiveError(f"{boundary} descriptor shape was invalid")
+    digest = descriptor.get("digest")
+    size = descriptor.get("size")
+    media_type = descriptor.get("mediaType")
+    if (
+        not isinstance(digest, str)
+        or not digest.startswith("sha256:")
+        or len(digest) != 71
+    ):
+        raise ImageArchiveError(f"{boundary} digest was invalid")
+    hexadecimal = digest.removeprefix("sha256:")
+    if any(character not in "0123456789abcdef" for character in hexadecimal):
+        raise ImageArchiveError(f"{boundary} digest was invalid")
+    if not isinstance(size, int) or size < 0 or media_type not in media_types:
+        raise ImageArchiveError(f"{boundary} descriptor was unsupported")
+    payload = _require_file(files, f"blobs/sha256/{hexadecimal}", boundary)
+    if len(payload) != size or hashlib.sha256(payload).hexdigest() != hexadecimal:
+        raise ImageArchiveError(f"{boundary} blob integrity failed")
+    return payload, media_type
+
+
+def _scan_oci(files: Mapping[str, bytes], forbidden: bytes) -> None:
+    layout = _json_object(
+        _require_file(files, "oci-layout", "OCI layout"), "OCI layout"
+    )
+    if layout.get("imageLayoutVersion") != "1.0.0":
+        raise ImageArchiveError("OCI layout version was unsupported")
+    index = _json_object(_require_file(files, "index.json", "OCI index"), "OCI index")
+    manifests = index.get("manifests")
+    if not isinstance(manifests, list) or len(manifests) != 1:
+        raise ImageArchiveError("OCI index manifest selection was unsupported")
+    manifest_bytes, _ = _oci_blob(
+        files, manifests[0], _OCI_MANIFEST_MEDIA_TYPES, "OCI manifest"
+    )
+    manifest = _json_object(manifest_bytes, "OCI manifest")
+    config_descriptor = manifest.get("config")
+    config_bytes, _ = _oci_blob(
+        files, config_descriptor, _OCI_CONFIG_MEDIA_TYPES, "OCI config"
+    )
+    _json_object(config_bytes, "OCI config")
+    _scan_forbidden(config_bytes, forbidden)
+    layers = manifest.get("layers")
+    if not isinstance(layers, list) or not layers:
+        raise ImageArchiveError("OCI layer descriptors were invalid")
+    config_digest = (
+        config_descriptor.get("digest") if isinstance(config_descriptor, dict) else None
+    )
+    descriptors: dict[str, Mapping[str, Any]] = {}
+    for descriptor in layers:
+        if not isinstance(descriptor, dict):
+            raise ImageArchiveError("OCI layer references were invalid")
+        digest = descriptor.get("digest")
+        if not isinstance(digest, str) or digest == config_digest:
+            raise ImageArchiveError("OCI layer references were invalid")
+        previous = descriptors.get(digest)
+        if previous is not None:
+            if descriptor != previous:
+                raise ImageArchiveError("OCI layer references conflicted")
+            continue
+        descriptors[digest] = descriptor
+        layer_bytes, media_type = _oci_blob(
+            files, descriptor, set(_OCI_LAYER_ENCODINGS), "OCI layer"
+        )
+        _scan_layer(layer_bytes, forbidden, encoding=_OCI_LAYER_ENCODINGS[media_type])
+
+
+def scan_image_archive(
+    archive: bytes | Path, *, forbidden: bytes, history: bytes
+) -> None:
+    """Validate and scan every referenced image surface without exposing values."""
+
+    try:
+        payload = archive.read_bytes() if isinstance(archive, Path) else bytes(archive)
+    except OSError as exc:
+        raise ImageArchiveError("image archive could not be read") from exc
+    files = _tar_files(payload, "image archive")
+    _scan_forbidden(history, forbidden)
+    recognized = False
+    if "manifest.json" in files:
+        _scan_docker_save(files, forbidden)
+        recognized = True
+    if "oci-layout" in files or "index.json" in files:
+        _scan_oci(files, forbidden)
+        recognized = True
+    if not recognized:
+        raise ImageArchiveError("image archive format was unsupported")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--archive", type=Path, required=True)
+    parser.add_argument("--history", type=Path, required=True)
+    args = parser.parse_args(argv)
+    sentinel = os.environ.get("AGENTSEEK_IMAGE_SCAN_SENTINEL")
+    if not sentinel:
+        raise SystemExit("image archive sentinel was unavailable")
+    try:
+        scan_image_archive(
+            args.archive,
+            forbidden=sentinel.encode(),
+            history=args.history.read_bytes(),
+        )
+    except (ImageArchiveError, OSError):
+        raise SystemExit("image archive boundary verification failed") from None
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())