agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/studio/hosted_kernel.py

@@ -0,0 +1,317 @@
+"""Content-addressed preflight for Studio Code bundles hosted by Agent Kernel.
+
+This module deliberately proves only properties available in the local bundle:
+the frozen Agent Kernel wire-contract digest and the launch layout generated by
+Studio. Whether the target Server-selected image implements that digest remains
+a separate control-plane/readiness check.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any
+
+from ksadk.studio.capabilities import canonical_json, sha256_digest
+from ksadk.studio.errors import StudioError
+
+AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
+# This mirrors contracts/agent-kernel/v1/manifest.json. A Studio test compares
+# the two, so a frozen-contract update cannot leave packaged preflight stale.
+AGENT_KERNEL_V1_CONTRACT_DIGEST = "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
+HOSTED_KERNEL_REQUIREMENTS_PATH = "hosted-kernel-requirements.json"
+HOSTED_KERNEL_REQUIREMENTS_FORMAT = "agentkit.hosted-kernel-requirements/v1"
+HOSTED_KERNEL_RUNTIME_CONTRACT = "agentkit.runtime/v1"
+HOSTED_KERNEL_BUNDLE_FORMAT = "agentkit.bundle/v2"
+_RUNTIME_TYPES = frozenset({"adk", "codex", "langgraph"})
+
+
+@dataclass(frozen=True)
+class HostedKernelBundle:
+    """Facts proved from the exact ZIP bytes that will be uploaded."""
+
+    manifest: dict[str, Any]
+    provenance: dict[str, Any]
+    requirement: dict[str, Any]
+    requirement_digest: str
+
+
+def build_hosted_kernel_requirement(
+    *,
+    runtime_type: str,
+    entry_point: str | None,
+    agent_variable: str | None,
+    launch_config: bytes | None,
+) -> dict[str, Any]:
+    """Build the immutable local requirement embedded into every Studio ZIP."""
+
+    return {
+        "format": HOSTED_KERNEL_REQUIREMENTS_FORMAT,
+        "kernelContract": {
+            "set": AGENT_KERNEL_V1_CONTRACT_SET,
+            "digest": AGENT_KERNEL_V1_CONTRACT_DIGEST,
+        },
+        "bundleLayout": HOSTED_KERNEL_BUNDLE_FORMAT,
+        "runtimeContract": HOSTED_KERNEL_RUNTIME_CONTRACT,
+        "runtime": {
+            "type": runtime_type,
+            "entryPoint": entry_point or "",
+            "agentVariable": agent_variable or "",
+            "launchConfig": "runtime/agentengine.yaml" if launch_config is not None else "",
+            "launchConfigSha256": sha256_digest(launch_config) if launch_config is not None else "",
+        },
+    }
+
+
+def hosted_kernel_requirement_digest(requirement: dict[str, Any]) -> str:
+    return sha256_digest(canonical_json(requirement))
+
+
+def preflight_hosted_kernel_bundle(bundle: bytes) -> HostedKernelBundle:
+    """Reject a ZIP that cannot be proved compatible before CreateAgent.
+
+    This validates the uploaded bytes, including their file manifest, instead
+    of trusting a writable sibling directory from a local Build.
+    """
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(bundle)) as archive:
+            names = _validated_zip_names(archive)
+            entries = {name: archive.read(name) for name in names}
+    except (OSError, zipfile.BadZipFile, zipfile.LargeZipFile) as error:
+        raise _integrity_error("Bundle 不是可验证的 ZIP 文件", reason="invalid_zip") from error
+
+    manifest = _json_object(entries, "manifest.json")
+    provenance = _json_object(entries, "provenance.json")
+    requirement = _json_object(entries, HOSTED_KERNEL_REQUIREMENTS_PATH)
+    requirement_digest = hosted_kernel_requirement_digest(requirement)
+
+    _validate_requirement(manifest, provenance, requirement, requirement_digest, entries)
+    _validate_content_manifest(manifest, entries)
+    _validate_declared_bundle_digest(manifest)
+    return HostedKernelBundle(
+        manifest=manifest,
+        provenance=provenance,
+        requirement=requirement,
+        requirement_digest=requirement_digest,
+    )
+
+
+def _validated_zip_names(archive: zipfile.ZipFile) -> list[str]:
+    names = archive.namelist()
+    if not names:
+        raise _integrity_error("Bundle 为空", reason="empty_zip")
+    if len(names) != len(set(names)):
+        raise _integrity_error("Bundle 含有重复文件名", reason="duplicate_path")
+    for name in names:
+        path = PurePosixPath(name)
+        if (
+            not name
+            or "\\" in name
+            or name.endswith("/")
+            or path.is_absolute()
+            or any(part in {"", ".", ".."} for part in path.parts)
+        ):
+            raise _integrity_error("Bundle 含有不安全文件路径", reason="unsafe_path")
+    return names
+
+
+def _json_object(entries: dict[str, bytes], path: str) -> dict[str, Any]:
+    raw = entries.get(path)
+    if raw is None:
+        raise _incompatible_error(f"Bundle 缺少 {path}", reason="missing_required_file")
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise _incompatible_error(
+            f"Bundle 中的 {path} 不是 JSON 对象", reason="invalid_json"
+        ) from error
+    if not isinstance(parsed, dict):
+        raise _incompatible_error(f"Bundle 中的 {path} 不是 JSON 对象", reason="invalid_json")
+    return parsed
+
+
+def _validate_requirement(
+    manifest: dict[str, Any],
+    provenance: dict[str, Any],
+    requirement: dict[str, Any],
+    requirement_digest: str,
+    entries: dict[str, bytes],
+) -> None:
+    if manifest.get("bundleFormat") != HOSTED_KERNEL_BUNDLE_FORMAT:
+        raise _incompatible_error(
+            "Bundle 不是受支持的 Studio Code bundle 格式", reason="bundle_format"
+        )
+    if manifest.get("runtimeContract") != HOSTED_KERNEL_RUNTIME_CONTRACT:
+        raise _incompatible_error(
+            "Bundle runtime contract 不受 Hosted Agent Kernel 支持", reason="runtime_contract"
+        )
+    if requirement.get("format") != HOSTED_KERNEL_REQUIREMENTS_FORMAT:
+        raise _incompatible_error(
+            "Bundle 缺少 Hosted Agent Kernel requirement 格式声明", reason="requirement_format"
+        )
+    if requirement.get("bundleLayout") != manifest.get("bundleFormat"):
+        raise _incompatible_error(
+            "Bundle requirement 与 bundle layout 不一致", reason="bundle_layout"
+        )
+    if requirement.get("runtimeContract") != manifest.get("runtimeContract"):
+        raise _incompatible_error(
+            "Bundle requirement 与 runtime contract 不一致", reason="runtime_contract"
+        )
+
+    contract = requirement.get("kernelContract")
+    if not isinstance(contract, dict):
+        raise _incompatible_error(
+            "Bundle 缺少 Agent Kernel contract requirement", reason="missing_contract"
+        )
+    if contract.get("set") != AGENT_KERNEL_V1_CONTRACT_SET:
+        raise _incompatible_error(
+            "Bundle Agent Kernel contract set 不受支持", reason="contract_set"
+        )
+    if contract.get("digest") != AGENT_KERNEL_V1_CONTRACT_DIGEST:
+        raise _incompatible_error(
+            "Bundle Agent Kernel contract digest 与当前 KsADK 不一致，请重新 Build 后部署",
+            reason="contract_digest",
+        )
+
+    hosted = provenance.get("hostedKernel")
+    if not isinstance(hosted, dict):
+        raise _incompatible_error(
+            "Bundle provenance 缺少 Hosted Agent Kernel requirement", reason="missing_provenance"
+        )
+    if hosted.get("requirementsPath") != HOSTED_KERNEL_REQUIREMENTS_PATH:
+        raise _incompatible_error(
+            "Bundle provenance 的 requirement 路径不一致", reason="provenance_path"
+        )
+    if hosted.get("requirementDigest") != requirement_digest:
+        raise _incompatible_error(
+            "Bundle provenance 的 requirement digest 不一致", reason="provenance_digest"
+        )
+    if hosted.get("contractSet") != contract.get("set") or hosted.get(
+        "contractDigest"
+    ) != contract.get("digest"):
+        raise _incompatible_error(
+            "Bundle provenance 的 Agent Kernel contract 不一致", reason="provenance_contract"
+        )
+    if manifest.get("hostedKernelRequirementDigest") != requirement_digest:
+        raise _incompatible_error(
+            "Bundle manifest 的 requirement digest 不一致", reason="manifest_digest"
+        )
+
+    runtime = requirement.get("runtime")
+    if not isinstance(runtime, dict):
+        raise _incompatible_error(
+            "Bundle 缺少受支持的 runtime 启动 requirement", reason="missing_runtime"
+        )
+    runtime_type = str(runtime.get("type") or "").strip().lower()
+    entry_point = str(runtime.get("entryPoint") or "").strip()
+    agent_variable = str(runtime.get("agentVariable") or "").strip()
+    launch_path = str(runtime.get("launchConfig") or "").strip()
+    launch_digest = str(runtime.get("launchConfigSha256") or "").strip()
+    if runtime_type not in _RUNTIME_TYPES:
+        raise _incompatible_error(
+            "Bundle runtime 类型不受 Hosted Agent Kernel 支持", reason="runtime_type"
+        )
+    if (
+        runtime_type != str(manifest.get("runtimeType") or "").strip().lower()
+        or not entry_point
+        or not agent_variable
+        or launch_path != "runtime/agentengine.yaml"
+        or not launch_digest
+    ):
+        raise _incompatible_error("Bundle 缺少可验证的 runtime 启动配置", reason="runtime_launch")
+    if not _safe_relative_file(entry_point) or f"runtime/{entry_point}" not in entries:
+        raise _incompatible_error("Bundle runtime entryPoint 不存在或不安全", reason="entry_point")
+    launch_bytes = entries.get(launch_path)
+    if launch_bytes is None or sha256_digest(launch_bytes) != launch_digest:
+        raise _incompatible_error("Bundle runtime 启动配置 digest 不一致", reason="launch_digest")
+    launch = _json_object(entries, launch_path)
+    if (
+        str(launch.get("framework") or "").strip().lower() != runtime_type
+        or launch.get("entry_point") != entry_point
+        or launch.get("agent_variable") != agent_variable
+        or launch.get("package") != "."
+    ):
+        raise _incompatible_error(
+            "Bundle runtime 启动配置与 requirement 不一致", reason="launch_config"
+        )
+    runtime_lock = _json_object(entries, "runtime-lock.json")
+    if (
+        str(runtime_lock.get("type") or "").strip().lower() != runtime_type
+        or runtime_lock.get("entryPoint") != entry_point
+        or runtime_lock.get("agentVariable") != agent_variable
+    ):
+        raise _incompatible_error(
+            "Bundle runtime lock 与 requirement 不一致", reason="runtime_lock"
+        )
+
+
+def _validate_content_manifest(manifest: dict[str, Any], entries: dict[str, bytes]) -> None:
+    files = manifest.get("files")
+    if not isinstance(files, list):
+        raise _integrity_error("Bundle manifest 缺少文件清单", reason="missing_file_manifest")
+    recorded: dict[str, dict[str, Any]] = {}
+    for item in files:
+        if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+            raise _integrity_error("Bundle manifest 的文件清单无效", reason="invalid_file_manifest")
+        path = item["path"]
+        if path in recorded or not _safe_relative_file(path) or path == "manifest.json":
+            raise _integrity_error("Bundle manifest 的文件路径无效", reason="invalid_file_manifest")
+        recorded[path] = item
+    if set(entries) != set(recorded) | {"manifest.json"}:
+        raise _integrity_error("Bundle ZIP 与 manifest 文件清单不一致", reason="file_membership")
+    for path, item in recorded.items():
+        content = entries[path]
+        if item.get("sha256") != sha256_digest(content) or item.get("size") != len(content):
+            raise _integrity_error("Bundle 文件摘要与 manifest 不一致", reason="file_digest")
+
+
+def _validate_declared_bundle_digest(manifest: dict[str, Any]) -> None:
+    declared = manifest.get("bundleDigest")
+    digest_payload = dict(manifest)
+    digest_payload.pop("bundleDigest", None)
+    if declared != sha256_digest(canonical_json(digest_payload)):
+        raise _integrity_error("Bundle manifest 的 bundle digest 不一致", reason="bundle_digest")
+
+
+def _safe_relative_file(value: str) -> bool:
+    path = PurePosixPath(value)
+    return (
+        bool(value)
+        and "\\" not in value
+        and not path.is_absolute()
+        and all(part not in {"", ".", ".."} for part in path.parts)
+    )
+
+
+def _incompatible_error(message: str, *, reason: str) -> StudioError:
+    return StudioError(
+        "HOSTED_KERNEL_BUNDLE_INCOMPATIBLE",
+        message,
+        status_code=422,
+        details={"reason": reason},
+    )
+
+
+def _integrity_error(message: str, *, reason: str) -> StudioError:
+    return StudioError(
+        "HOSTED_KERNEL_BUNDLE_INTEGRITY_INVALID",
+        message,
+        status_code=422,
+        details={"reason": reason},
+    )
+
+
+__all__ = [
+    "AGENT_KERNEL_V1_CONTRACT_DIGEST",
+    "AGENT_KERNEL_V1_CONTRACT_SET",
+    "HOSTED_KERNEL_REQUIREMENTS_FORMAT",
+    "HOSTED_KERNEL_REQUIREMENTS_PATH",
+    "HostedKernelBundle",
+    "build_hosted_kernel_requirement",
+    "hosted_kernel_requirement_digest",
+    "preflight_hosted_kernel_bundle",
+]

ksadk/studio/identifiers.py

@@ -0,0 +1,33 @@
+"""Server-owned local identifiers for Studio resources."""
+
+from __future__ import annotations
+
+import re
+import secrets
+from collections.abc import Callable
+
+from ksadk.studio.errors import StudioError
+
+_GENERATED_AGENT_SLUG = re.compile(r"^agentkit-[0-9a-f]{8}$")
+
+
+def generate_agent_slug(exists: Callable[[str], bool]) -> str:
+    """Allocate a short opaque Agent ID without trusting a client-side default."""
+
+    for _attempt in range(32):
+        candidate = f"agentkit-{secrets.token_hex(4)}"
+        if not exists(candidate):
+            return candidate
+    raise StudioError(
+        "AGENT_ID_EXHAUSTED",
+        "无法分配唯一的本地标识",
+        status_code=503,
+        field="slug",
+    )
+
+
+def is_generated_agent_slug(value: str) -> bool:
+    return bool(_GENERATED_AGENT_SLUG.fullmatch(str(value or "").strip()))
+
+
+__all__ = ["generate_agent_slug", "is_generated_agent_slug"]

ksadk/studio/manifest_resolver.py

@@ -0,0 +1,131 @@
+"""ManifestResolver —— 统一识别工作区根 Manifest 的种类（方案 §6.1）。
+
+当前问题（方案 §2.4 第 1 点）：标准 LangGraph/ADK 项目作为 Studio workspace 启动后，根
+``agentengine.yaml`` 可能先进入 Codex Manifest 解析，导致 ``CODEX_MANIFEST_INVALID``。
+
+本模块提供统一入口：根 manifest 存在时先读 ``framework`` / ``runtime.type`` 字段决定 kind，
+只有明确 ``framework: codex`` 才走 ``CodexAgentManifest`` 解析；明确为 ADK/LangGraph 等框架时
+返回 framework kind（交给 ``FrameworkDetector`` 与标准 Code 项目导入）；无法判定时返回
+``MANIFEST_KIND_AMBIGUOUS``，列出候选，不猜测为 Codex。
+
+解析顺序（方案 §6.1）：
+1. 根 manifest 不存在 → ``none``
+2. 显式 ``framework: codex`` 或 ``runtime.name: codex`` → ``codex``
+3. 显式 ``framework: adk|langgraph|...`` 或 ``runtime.type: adk|langgraph|...`` → ``framework``
+4. 仍无法判定 → ``ambiguous``（列出已读到的关键字段，便于诊断）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+
+ManifestKind = Literal["none", "codex", "framework", "ambiguous"]
+
+# framework/runtime 字段的已知 codex / framework 取值。
+_CODEX_FRAMEWORK_VALUES = frozenset({"codex"})
+_CODEX_RUNTIME_VALUES = frozenset({"codex"})
+_FRAMEWORK_VALUES = frozenset({"adk", "langgraph", "langchain", "deepagents", "hermes", "openclaw"})
+
+
+@dataclass(frozen=True)
+class ManifestKindResult:
+    """根 manifest 识别结果。"""
+
+    kind: ManifestKind
+    path: Path
+    framework: str = ""
+    runtime_type: str = ""
+    artifact_type: str = ""
+    # ambiguous 时列出已读字段，供诊断与错误返回。
+    detected_fields: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_codex(self) -> bool:
+        return self.kind == "codex"
+
+
+def _safe_yaml(path: Path) -> dict[str, Any]:
+    try:
+        with open(path, "r", encoding="utf-8-sig") as f:
+            payload = yaml.safe_load(f)
+    except (OSError, yaml.YAMLError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return payload
+
+
+def detect_manifest_kind(workspace_root: Path | str) -> ManifestKindResult:
+    """识别工作区根 manifest 的种类（方案 §6.1）。
+
+    ``workspace_root`` 指工作区目录；本函数查其下的 ``agentengine.yaml``（不存在时返回 ``none``）。
+    """
+    root = Path(workspace_root)
+    path = root / "agentengine.yaml"
+    if not path.is_file():
+        return ManifestKindResult(kind="none", path=path)
+
+    payload = _safe_yaml(path)
+    if not payload:
+        # 文件存在但无法解析为 dict → ambiguous（不猜测为 codex）
+        return ManifestKindResult(kind="ambiguous", path=path, detected_fields={"unparsable": True})
+
+    framework = str(payload.get("framework") or "").strip().lower()
+    runtime = payload.get("runtime") or {}
+    runtime_type = (
+        str(runtime.get("type") or runtime.get("name") or "").strip().lower()
+        if isinstance(runtime, dict)
+        else ""
+    )
+    artifact_type = str(payload.get("artifact_type") or "").strip().lower()
+    detected = {
+        "framework": framework,
+        "runtimeType": runtime_type,
+        "artifactType": artifact_type,
+        "topLevelKeys": sorted(payload.keys()),
+    }
+
+    # 2. 显式 codex
+    if framework in _CODEX_FRAMEWORK_VALUES or runtime_type in _CODEX_RUNTIME_VALUES:
+        return ManifestKindResult(
+            kind="codex",
+            path=path,
+            framework=framework,
+            runtime_type=runtime_type,
+            artifact_type=artifact_type,
+        )
+    # 3. 显式 framework
+    if framework in _FRAMEWORK_VALUES or runtime_type in _FRAMEWORK_VALUES:
+        return ManifestKindResult(
+            kind="framework",
+            path=path,
+            framework=framework or runtime_type,
+            runtime_type=runtime_type,
+            artifact_type=artifact_type,
+        )
+    # 4. 无法判定（例如只有 name/version 但无 framework/runtime）
+    return ManifestKindResult(
+        kind="ambiguous",
+        path=path,
+        framework=framework,
+        runtime_type=runtime_type,
+        artifact_type=artifact_type,
+        detected_fields=detected,
+    )
+
+
+def root_manifest_is_codex(workspace_root: Path | str) -> bool:
+    """便捷判定：根 manifest 是否应走 Codex 解析（方案 §6.1）。"""
+    return detect_manifest_kind(workspace_root).is_codex
+
+
+__all__ = [
+    "ManifestKind",
+    "ManifestKindResult",
+    "detect_manifest_kind",
+    "root_manifest_is_codex",
+]