agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/studio/compiler.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass
 from typing import Any
 from urllib.parse import urlparse
 
+from ksadk.plugins.providers.legacy_catalog import CODEX_AGENT_PROVIDER_PLUGIN_ID
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
 from ksadk.studio.capabilities import (
     CapabilityResolver,
     LocalCapabilityResolver,
@@ -46,6 +48,39 @@ class AgentCompiler:
         self.catalog = catalog or LocalResourceCatalog(workspace)
 
     def compile(self, draft: AgentDraft) -> CompileResult:
+        unsupported_plugins = [
+            binding.plugin_ref
+            for binding in draft.spec.bindings.plugins
+            if binding.enabled
+            and resource_plugin_config(
+                binding.plugin_ref,
+                binding.ecosystem,
+                binding.config,
+                enabled=True,
+            )
+            is None
+        ]
+        if unsupported_plugins:
+            raise StudioError(
+                "NATIVE_PLUGIN_RUNTIME_INCOMPATIBLE",
+                "Framework Agent 不能直接绑定未物化的原生插件快照",
+                status_code=422,
+                field="spec.bindings.plugins",
+                details={"pluginRefs": sorted(unsupported_plugins)},
+            )
+        direct_dynamic = [
+            server.name
+            for server in draft.spec.capabilities.mcp_servers
+            if server.enabled and server.materialization == "dsh-profile"
+        ]
+        if direct_dynamic:
+            raise StudioError(
+                "DSH_MCP_MANAGED_BINDING_REQUIRED",
+                "DSH Profile MCP 必须从当前 Catalog Resource 显式绑定，不能直接写入 AgentSpec",
+                status_code=422,
+                field="spec.capabilities.mcpServers",
+                details={"servers": sorted(direct_dynamic)},
+            )
         source_payload = draft.model_dump(by_alias=True, exclude_none=True, mode="json")
         source_digest = sha256_digest(canonical_json(source_payload))
         materialized = self._materialize_bindings(draft)
@@ -62,13 +97,19 @@ class AgentCompiler:
             for ref in materialized.spec.capabilities.mcp_servers
             if ref.enabled
         ]
-        tools = [
-            self.resolver.resolve_tool(tool)
-            for tool in materialized.spec.capabilities.tools
-        ]
+        tools = [self.resolver.resolve_tool(tool) for tool in materialized.spec.capabilities.tools]
         skills.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         mcp_servers.sort(key=lambda item: (item["name"], item["version"], item["digest"]))
         tools.sort(key=lambda item: (item.name, item.version, item.digest or ""))
+        available_tools = {tool.name for tool in tools}
+        for sub in materialized.spec.sub_agents:
+            if set(sub.tools) - available_tools or sub.name in available_tools:
+                raise StudioError(
+                    "SUBAGENT_TOOL_SCOPE_INVALID",
+                    "子 Agent 只能使用父 Agent 已绑定工具，且子 Agent 名称不能与工具重名",
+                    status_code=422,
+                    field="spec.subAgents",
+                )
 
         resolved = ResolvedAgentSpec(
             agent_id=draft.metadata.id,
@@ -89,6 +130,7 @@ class AgentCompiler:
             memory=materialized.spec.memory,
             security=materialized.spec.security,
             evaluation=materialized.spec.evaluation,
+            sub_agents=materialized.spec.sub_agents,
             source_digest=source_digest,
         )
         digest_payload = resolved.model_dump(
@@ -111,21 +153,53 @@ class AgentCompiler:
             "skills": skills,
             "mcpServers": mcp_servers,
             "tools": [
-                tool.model_dump(by_alias=True, exclude_none=True, mode="json")
-                for tool in tools
+                tool.model_dump(by_alias=True, exclude_none=True, mode="json") for tool in tools
             ],
         }
         return CompileResult(resolved=resolved, dependency_lock=dependency_lock)
 
     def _materialize_bindings(self, draft: AgentDraft) -> AgentDraft:
+        runtime = draft.spec.runtime
+        uses_codex_native_tools = bool(
+            runtime
+            and (
+                runtime.type == "codex"
+                or (
+                    runtime.type == "plugin"
+                    and runtime.provider_ref
+                    and runtime.provider_ref.startswith(
+                        f"plugin://{CODEX_AGENT_PROVIDER_PLUGIN_ID}@"
+                    )
+                )
+            )
+        )
         bindings = draft.spec.bindings
+        if uses_codex_native_tools and bindings.tools:
+            bindings = bindings.model_copy(update={"tools": []})
         if (
-            not bindings.model_profile_id
+            not uses_codex_native_tools
+            and not bindings.model_profile_id
             and not bindings.tools
             and not bindings.mcp_servers
             and not bindings.skills
         ):
             return draft
+        runtime_type = draft.spec.runtime.type if draft.spec.runtime is not None else None
+        for binding in bindings.mcp_servers:
+            if not binding.enabled:
+                continue
+            descriptor = self.catalog.get(binding.resource_id)
+            if (
+                descriptor.contract.get("materialization") == "dsh-profile"
+                and runtime_type != "harness"
+            ):
+                raise StudioError(
+                    "DSH_MCP_RUNTIME_INCOMPATIBLE",
+                    "DSH Profile MCP 当前只支持 Harness Runtime",
+                    status_code=422,
+                    field="spec.runtime.type",
+                    details={"runtimeType": runtime_type},
+                )
         materialized = draft.model_copy(deep=True)
         model = self.catalog.resolve_model(bindings) or materialized.spec.model
         if model is None:
@@ -147,9 +221,13 @@ class AgentCompiler:
                 *self.catalog.resolve_mcp_servers(bindings),
             ],
             tools=[
-                *materialized.spec.capabilities.tools,
+                *([] if uses_codex_native_tools else materialized.spec.capabilities.tools),
                 *bound_tools,
-                *bound_mcp_tools,
+                # Non-Codex runtimes consume the probed MCP contracts through
+                # the generic Tool execution path. Codex connects to the MCP
+                # server natively, so expanding those contracts here turns a
+                # valid MCP binding into unsupported third-party tools.
+                *([] if uses_codex_native_tools else bound_mcp_tools),
             ],
         )
         self._require_unique(
@@ -169,11 +247,7 @@ class AgentCompiler:
         materialized.spec.security.allowed_permissions = sorted(
             set(materialized.spec.security.allowed_permissions)
             | set(permissions)
-            | {
-                permission
-                for tool in bound_mcp_tools
-                for permission in tool.permissions
-            }
+            | {permission for tool in bound_mcp_tools for permission in tool.permissions}
         )
         endpoint = model.endpoint_url or model.base_url or ""
         hostname = (urlparse(endpoint).hostname or "").lower().rstrip(".")

ksadk/studio/configuration.py

@@ -0,0 +1,182 @@
+"""One workspace configuration store for Studio settings and secret references."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from threading import RLock
+from typing import Any
+
+import yaml
+from dotenv import dotenv_values
+
+from ksadk.configs.global_config import get_env_from_global_config
+from ksadk.studio.errors import StudioError
+
+SETTINGS_ENV = {
+    "cloudAccessKey": "KSYUN_ACCESS_KEY",
+    "cloudSecretKey": "KSYUN_SECRET_KEY",
+    "cloudAccountId": "KSYUN_ACCOUNT_ID",
+    "cloudServerUrl": "AGENTENGINE_SERVER_URL",
+    "teamsServerUrl": "KSADK_TEAMS_SERVER_URL",
+    "cloudRegion": "AGENTENGINE_REGION",
+    "cloudBucket": "KS3_BUCKET",
+    "sandbox": "KSADK_CODEX_SANDBOX",
+}
+SECRET_SETTINGS = {"cloudAccessKey", "cloudSecretKey"}
+_LOCK = RLock()
+
+
+class WorkspaceConfiguration:
+    """Explicit env-file > workspace > inherited environment > workspace .env.
+
+    The canonical file is written atomically with mode 0600. Old files are
+    imported once, without modifying them or the user's .env. Read fresh on
+    each operation so settings and credential API writes share one store.
+    """
+
+    def __init__(self, workspace: Any, *, overrides: Mapping[str, str] | None = None):
+        self.workspace = workspace
+        self.path = workspace.resolve(".agentkit/config.yaml")
+        self.overrides = dict(overrides or {})
+        self.inherited = dict(os.environ)
+        self.global_defaults = get_env_from_global_config()
+        self.dotenv = {
+            key: value
+            for key, value in dotenv_values(workspace.resolve(".env")).items()
+            if value is not None
+        }
+
+    def _read(self) -> dict[str, Any]:
+        try:
+            if self.path.is_file():
+                data = yaml.safe_load(self.path.read_text(encoding="utf-8"))
+                if not isinstance(data, dict) or data.get("version") != 1:
+                    raise ValueError("schema")
+                if not isinstance(data.get("settings"), dict) or not isinstance(
+                    data.get("secrets"), dict
+                ):
+                    raise ValueError("sections")
+                if any(
+                    not isinstance(k, str) or not isinstance(v, str)
+                    for k, v in data["secrets"].items()
+                ):
+                    raise ValueError("secrets")
+                return data
+            legacy_settings = self.workspace.resolve(".agentkit/settings.yaml")
+            legacy_secrets = self.workspace.resolve(".agentkit/secrets.env")
+            settings = (
+                yaml.safe_load(legacy_settings.read_text(encoding="utf-8")) or {}
+                if legacy_settings.is_file()
+                else {}
+            )
+            if not isinstance(settings, dict):
+                raise ValueError("legacy settings")
+            # Legacy writer stored literal values, without dotenv interpolation.
+            secrets = {}
+            if legacy_secrets.is_file():
+                for line in legacy_secrets.read_text(encoding="utf-8").splitlines():
+                    if line and not line.startswith("#") and "=" in line:
+                        key, _, value = line.partition("=")
+                        secrets[key.strip()] = value
+            for key in SECRET_SETTINGS:
+                if settings.get(key):
+                    secrets.setdefault(SETTINGS_ENV[key], str(settings.pop(key)))
+            data = {"version": 1, "settings": settings, "secrets": secrets}
+            if legacy_settings.is_file() or legacy_secrets.is_file():
+                self._write(data)
+            return data
+        except (ValueError, OSError, yaml.YAMLError) as error:
+            raise StudioError(
+                "CONFIGURATION_INVALID",
+                "工作区配置无法读取，请检查 .agentkit/config.yaml 或旧配置文件",
+                status_code=422,
+            ) from error
+
+    def _write(self, data: dict[str, Any]) -> None:
+        try:
+            self.workspace.ignore_private_configuration()
+            self.workspace.atomic_write_yaml(self.path, data)
+        except OSError as error:
+            raise StudioError(
+                "CONFIGURATION_SAVE_FAILED", "工作区配置保存失败，请检查目录权限", status_code=500
+            ) from error
+
+    def settings(self) -> dict[str, Any]:
+        with _LOCK:
+            return dict(self._read()["settings"])
+
+    def secrets(self) -> dict[str, str]:
+        with _LOCK:
+            return dict(self._read()["secrets"])
+
+    def update_settings(self, patch: Mapping[str, Any]) -> None:
+        with _LOCK:
+            data = self._read()
+            for key, value in patch.items():
+                if key in SECRET_SETTINGS:
+                    data["secrets"][SETTINGS_ENV[key]] = value
+                else:
+                    data["settings"][key] = value
+            self._write(data)
+
+    def put_secret(self, name: str, value: str | None) -> None:
+        with _LOCK:
+            data = self._read()
+            if value is None:
+                data["secrets"].pop(name, None)
+            else:
+                data["secrets"][name] = value
+            self._write(data)
+
+    def resolve(self, name: str) -> tuple[str | None, str]:
+        if name in self.overrides:
+            return self.overrides[name], "env-file"
+        with _LOCK:
+            data = self._read()
+        if name in data["secrets"]:
+            return data["secrets"][name], "workspace"
+        for key, env in SETTINGS_ENV.items():
+            if env == name and key in data["settings"]:
+                return str(data["settings"][key]), "workspace"
+        if self.global_defaults.get(name):
+            return self.global_defaults[name], "global"
+        if self.inherited.get(name):
+            return self.inherited[name], "environment"
+        if self.dotenv.get(name):
+            return self.dotenv[name], "dotenv"
+        return None, "missing"
+
+    def resolve_candidates(self, names: list[str]) -> tuple[str | None, str]:
+        ranked = {
+            "env-file": 0,
+            "workspace": 1,
+            "global": 2,
+            "environment": 3,
+            "dotenv": 4,
+            "missing": 5,
+        }
+        candidates = [(self.resolve(name), i) for i, name in enumerate(names)]
+        (value, source), index = min(candidates, key=lambda item: (ranked[item[0][1]], item[1]))
+        return value, source + ("-alias" if value and index else "")
+
+    def environment(self) -> dict[str, str]:
+        with _LOCK:
+            data = self._read()
+        values = {**self.dotenv, **self.global_defaults, **self.inherited}
+        for key, name in SETTINGS_ENV.items():
+            if key in data["settings"]:
+                values[name] = str(data["settings"][key])
+        if "codexProxy" in data["settings"]:
+            from ksadk.studio.codex_builder import proxy_mode_env_value
+
+            proxy = proxy_mode_env_value(data["settings"]["codexProxy"])
+            if proxy is None:
+                values.pop("KSADK_CODEX_USE_PROXY", None)
+            else:
+                values["KSADK_CODEX_USE_PROXY"] = proxy
+        if "traceContent" in data["settings"]:
+            values["KSADK_STUDIO_TRACE_CONTENT"] = "1" if data["settings"]["traceContent"] else "0"
+        values.update(data["secrets"])
+        values.update(self.overrides)
+        return values

ksadk/studio/contracts.py

@@ -9,6 +9,8 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
+from ksadk.harness.spec import SubAgentBinding
+
 
 def _to_camel(value: str) -> str:
     head, *tail = value.split("_")
@@ -107,9 +109,40 @@ class MCPServerRef(CapabilityRef):
     args: list[str] = Field(default_factory=list)
     endpoint_url: str | None = None
     env_refs: dict[str, str] = Field(default_factory=dict)
+    # ``dsh-profile`` is resolved at PluginHost activation time.  Only the
+    # immutable profile/inventory identity is allowed into an Agent Build;
+    # the loopback endpoint and bearer token remain process-scoped lease data.
+    materialization: Literal["dsh-profile"] | None = None
+    profile: str | None = None
+    profile_digest: str | None = None
+    descriptor_digest: str | None = None
+    inventory_digest: str | None = None
 
     @model_validator(mode="after")
     def validate_transport(self) -> "MCPServerRef":
+        dynamic_fields = (
+            self.profile,
+            self.profile_digest,
+            self.descriptor_digest,
+            self.inventory_digest,
+        )
+        if self.materialization == "dsh-profile":
+            if self.transport != "http":
+                raise ValueError("DSH Profile MCP 必须使用运行时 HTTP 租约")
+            if self.endpoint_url or self.command or self.args or self.env_refs:
+                raise ValueError("DSH Profile MCP 不能持久化 endpoint、命令或环境变量")
+            if not all(dynamic_fields):
+                raise ValueError("DSH Profile MCP 必须锁定 Profile 与能力摘要")
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}", self.profile or ""):
+                raise ValueError("DSH Profile 名称无效")
+            if any(
+                not re.fullmatch(r"sha256:[0-9a-f]{64}", value or "")
+                for value in dynamic_fields[1:]
+            ):
+                raise ValueError("DSH Profile MCP 摘要无效")
+            return self
+        if any(value is not None for value in dynamic_fields):
+            raise ValueError("静态 MCP 不能声明 DSH Profile 运行时字段")
         if self.transport == "stdio" and not self.command:
             raise ValueError("stdio MCP 必须配置 command")
         if self.transport in {"http", "sse"} and not self.endpoint_url:
@@ -129,6 +162,10 @@ class ToolContract(ContractModel):
     )
     permissions: list[str] = Field(default_factory=list)
     timeout_seconds: int = Field(default=20, ge=1, le=3600)
+    # Optional deterministic per-Run budget. The Managed Harness reserves one
+    # slot immediately before execution, so model retries and process restarts
+    # cannot bypass the limit.
+    max_calls_per_run: int | None = Field(default=None, ge=1, le=100_000)
     side_effect: Literal["none", "read", "write", "external"] = "none"
     approval: Literal["never", "always", "policy"] = "never"
     executor: Literal["builtin", "mcp", "deferred", "python"] = "builtin"
@@ -198,6 +235,53 @@ class CapabilityBinding(ContractModel):
     config: dict[str, Any] = Field(default_factory=dict)
 
 
+class NativePluginBinding(ContractModel):
+    """Immutable component selection from a host-managed native plugin."""
+
+    ecosystem: Literal["codex", "dsh"]
+    plugin_ref: str = Field(min_length=12, max_length=256)
+    snapshot_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    components: list[str] = Field(min_length=1, max_length=128)
+    enabled: bool = True
+    config: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("plugin_ref")
+    @classmethod
+    def validate_plugin_ref(cls, value: str) -> str:
+        if not re.fullmatch(
+            r"plugin://[a-z0-9]+(?:[._-][a-z0-9]+)*@"
+            r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?",
+            value,
+        ):
+            raise ValueError("插件绑定必须使用 plugin://<id>@<exact-version>")
+        return value
+
+    @field_validator("components")
+    @classmethod
+    def validate_components(cls, value: list[str]) -> list[str]:
+        if len(value) != len(set(value)):
+            raise ValueError("插件组件不能重复")
+        if any(
+            not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}", component)
+            for component in value
+        ):
+            raise ValueError("插件组件 ID 无效")
+        return value
+
+    @field_validator("config")
+    @classmethod
+    def validate_config(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _reject_clear_runtime_secrets(value, path="pluginBinding.config")
+        return value
+
+    @model_validator(mode="after")
+    def validate_platform_resource_config(self) -> "NativePluginBinding":
+        from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+        resource_plugin_config(self.plugin_ref, self.ecosystem, self.config, enabled=self.enabled)
+        return self
+
+
 class AgentBindings(ContractModel):
     model_profile_id: str | None = None
     model_profile_ids: list[str] = Field(default_factory=list)
@@ -206,6 +290,7 @@ class AgentBindings(ContractModel):
     tools: list[CapabilityBinding] = Field(default_factory=list)
     mcp_servers: list[CapabilityBinding] = Field(default_factory=list)
     skills: list[CapabilityBinding] = Field(default_factory=list)
+    plugins: list[NativePluginBinding] = Field(default_factory=list)
 
     @model_validator(mode="after")
     def validate_model_profiles(self) -> "AgentBindings":
@@ -219,6 +304,12 @@ class AgentBindings(ContractModel):
             and self.model_profile_id not in self.model_profile_ids
         ):
             raise ValueError("默认 modelProfileId 必须包含在 modelProfileIds 中")
+        plugin_refs = [binding.plugin_ref for binding in self.plugins if binding.enabled]
+        if len(plugin_refs) != len(set(plugin_refs)):
+            raise ValueError("启用的插件绑定不能重复 pluginRef")
+        from ksadk.resource_runtime.plugin_config import validate_resource_plugin_bindings
+
+        validate_resource_plugin_bindings(self.plugins)
         return self
 
 
@@ -235,8 +326,8 @@ class RetryPolicy(ContractModel):
 
 class ExecutionSpec(ContractModel):
     strategy: Literal["direct", "plan-act-observe"] = "direct"
-    max_steps: int = Field(default=12, ge=1, le=100)
-    timeout_seconds: int = Field(default=120, ge=1, le=3600)
+    max_steps: int = Field(default=100, ge=1, le=100)
+    timeout_seconds: int = Field(default=600, ge=1, le=3600)
     retry: RetryPolicy = Field(default_factory=RetryPolicy)
     sandbox: str | None = None
     approval_mode: str | None = None
@@ -418,9 +509,7 @@ class RuntimeRef(ContractModel):
         return self
 
 
-_RUNTIME_SECRET_KEY = re.compile(
-    r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE
-)
+_RUNTIME_SECRET_KEY = re.compile(r"(?:secret|password|token|api[_-]?key)", re.IGNORECASE)
 _RUNTIME_SECRET_REF_PREFIXES = (
     "secret://",
     "env://",
@@ -436,9 +525,7 @@ def _reject_clear_runtime_secrets(value: Any, *, path: str = "providerConfig") -
         for key, child in value.items():
             child_path = f"{path}.{key}"
             if _RUNTIME_SECRET_KEY.search(str(key)) and child is not None:
-                if not isinstance(child, str) or not child.startswith(
-                    _RUNTIME_SECRET_REF_PREFIXES
-                ):
+                if not isinstance(child, str) or not child.startswith(_RUNTIME_SECRET_REF_PREFIXES):
                     raise ValueError(f"{child_path} 必须保存 Secret 引用，不能保存明文")
             _reject_clear_runtime_secrets(child, path=child_path)
     elif isinstance(value, list):
@@ -459,6 +546,48 @@ class AgentSpec(ContractModel):
     memory: MemorySpec = Field(default_factory=MemorySpec)
     security: SecuritySpec = Field(default_factory=SecuritySpec)
     evaluation: EvaluationSpec = Field(default_factory=EvaluationSpec)
+    sub_agents: tuple[SubAgentBinding, ...] = Field(default=(), max_length=32)
+
+    @model_validator(mode="after")
+    def validate_sub_agents(self) -> "AgentSpec":
+        if not self.sub_agents:
+            return self
+        if self.runtime is not None and self.runtime.type != "harness":
+            raise ValueError("subAgents 当前需要 Harness Runtime")
+        names = {sub.name for sub in self.sub_agents}
+        if len(names) != len(self.sub_agents):
+            raise ValueError("subAgents 名称不能重复")
+        dependencies = {sub.name: set(sub.depends_on) for sub in self.sub_agents}
+        if any(deps - names for deps in dependencies.values()):
+            raise ValueError("subAgents dependsOn 引用了未声明的子 Agent")
+        resolved: set[str] = set()
+        while len(resolved) < len(names):
+            ready = {name for name, deps in dependencies.items() if deps <= resolved} - resolved
+            if not ready:
+                raise ValueError("subAgents dependsOn 存在依赖环")
+            resolved.update(ready)
+        return self
+
+    @model_validator(mode="after")
+    def validate_memory_resource_reference(self) -> "AgentSpec":
+        if not self.memory.enabled or not self.memory.provider_ref.startswith("binding://"):
+            return self
+        from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+        binding_id = self.memory.provider_ref.removeprefix("binding://")
+        for binding in self.bindings.plugins:
+            if not binding.enabled:
+                continue
+            resource = resource_plugin_config(
+                binding.plugin_ref, binding.ecosystem, binding.config, enabled=True
+            )
+            if resource is not None and resource.binding.id == binding_id:
+                if resource.binding.resource.kind != "memory-instance":
+                    raise ValueError("Memory providerRef must reference a memory-instance binding")
+                if self.memory.scopes != ["user"]:
+                    raise ValueError("Platform memory requires explicit scopes: [user]")
+                return self
+        raise ValueError("Memory providerRef references a missing or disabled resource binding")
 
 
 _AGENT_ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{2,62}$")
@@ -521,8 +650,8 @@ class AgentTemplateComposeRequest(ContractModel):
     mcp_resource_ids: list[str] = Field(default_factory=list)
     policy_template: Literal["loose", "strict", "custom"] = "strict"
     execution_strategy: Literal["direct", "plan-act-observe"] = "direct"
-    max_steps: int = Field(default=12, ge=1, le=100)
-    timeout_seconds: int = Field(default=120, ge=1, le=3600)
+    max_steps: int = Field(default=100, ge=1, le=100)
+    timeout_seconds: int = Field(default=600, ge=1, le=3600)
     auto_bind_tools: bool = True
     auto_bind_mcp: bool = True
 
@@ -591,6 +720,7 @@ class ResolvedAgentSpec(ContractModel):
     memory: MemorySpec
     security: SecuritySpec
     evaluation: EvaluationSpec
+    sub_agents: tuple[SubAgentBinding, ...] = Field(default=(), max_length=32)
     source_digest: str
     resolved_digest: str = ""
 
@@ -638,6 +768,14 @@ class BundleManifest(ContractModel):
     composition_mode: Literal["legacy", "composed"] | None = None
     composition_profile_digest: str | None = None
     hosted_kernel_requirement_digest: str = ""
+    resource_build_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
+    resource_snapshot_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
     files: list[FileEntry]
     created_at: str = "1970-01-01T00:00:00Z"
     bundle_digest: str = ""
@@ -648,6 +786,10 @@ class BundleManifest(ContractModel):
             raise ValueError("composed Bundle v2 requires compositionProfileDigest")
         if self.composition_mode == "legacy" and self.composition_profile_digest:
             raise ValueError("legacy Bundle v2 cannot declare compositionProfileDigest")
+        if bool(self.resource_build_digest) != bool(self.resource_snapshot_digest):
+            raise ValueError(
+                "resourceBuildDigest and resourceSnapshotDigest must be declared together"
+            )
         return self
 
     @property
@@ -665,7 +807,7 @@ class BundleManifest(ContractModel):
 
 
 # ``BundleManifest`` is the existing, installed source type.  The explicit
-# name documents that its ``agentkit.bundle/v2`` branch is the Phase 2
+# name documents that its ``agentkit.bundle/v2`` branch is the Release
 # AgentBundleManifest/v2 contract; it is an alias, not a parallel manifest.
 AgentBundleManifest = BundleManifest
 
@@ -680,6 +822,14 @@ class BuildRecord(ContractModel):
     source_digest: str = ""
     runtime_lock: dict[str, Any] = Field(default_factory=dict)
     bundle_digest: str = ""
+    resource_build_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
+    resource_snapshot_digest: str | None = Field(
+        default=None,
+        pattern=r"^sha256:[0-9a-f]{64}$",
+    )
     artifact_path: str | None = None
     diagnostics: list[Diagnostic] = Field(default_factory=list)
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
@@ -854,6 +1004,10 @@ class DeploymentRequest(ContractModel):
 
 
 class DeploymentRecord(ContractModel):
+    # Identity observed when the cloud Agent was created, never inferred from
+    # whichever credentials happen to be configured when history is read.
+    created_by_name: str | None = None
+    created_by_user_id: str | None = None
     id: str
     build_id: str
     bundle_digest: str