agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/studio/codex_provider_build.py

@@ -8,7 +8,9 @@ from __future__ import annotations
 
 import hashlib
 import json
+from datetime import datetime, timezone
 from typing import Any
+from uuid import uuid4
 
 from pydantic import Field
 
@@ -218,6 +220,10 @@ class CodexProviderBuildManager:
             and record.provider_bundle.bundle_digest == bundle.bundle_digest
             and record.provider_bundle.registration_digest == registration_digest
         ]
+        if not matches:
+            repaired = self._repair_registration(bundle, marker, registration_digest)
+            if repaired is not None:
+                matches = [repaired]
         if len(matches) != 1:
             raise StudioError(
                 "CODEX_PROVIDER_BUILD_MISMATCH",
@@ -229,3 +235,62 @@ class CodexProviderBuildManager:
         # Retain native bootstrap, credentials, exact build HOME and workspace
         # from the existing resolver. No cloud schema or second launch policy.
         return self.studio.codex_runs.resolve(record.id).launch_context
+
+    def _repair_registration(self, bundle, marker: str, registration_digest: str):
+        """Re-register a rebuilt Provider Bundle after any upgrade.
+
+        A Studio upgrade may change the plugin composition (new channel
+        plugin, updated DSH toolchain), so ``ensure_current_build`` rebuilds
+        the Agent Bundle with a fresh digest. The rebuilt bundle may carry a
+        *different* manifest marker (plugin composition changed) but the same
+        provider registration (the user's consent to the Codex Provider is
+        unchanged). Without auto-repair every conversation fails until the
+        Agent is manually rebuilt.
+
+        Repair is allowed when the consent anchor is unchanged: a prior record
+        exists under the same provider registration digest. The repair
+        registers the rebuilt bundle under that unchanged consent, regardless
+        of whether the manifest changed. If the provider registration itself
+        changed (different consent), the caller keeps failing into the
+        explicit re-authorization flow.
+        """
+        records = self.studio.codex_builds.list()
+        prior = [
+            record
+            for record in records
+            if record.provider_bundle is not None
+            and record.provider_bundle.registration_digest == registration_digest
+        ]
+        if not prior:
+            return None
+        build_id = self._build_id_for_bundle(bundle)
+        if build_id is None:
+            return None
+        # Use the most recent prior record (same provider registration, any
+        # manifest/fingerprint) to seed the new reference. The consent anchor
+        # is the provider registration digest, not the manifest — installing a
+        # new plugin changes the manifest but not the provider consent.
+        old = prior[0]
+        reference = CodexProviderBuildReference(
+            provider_ref=CODEX_PROVIDER_REF,
+            registration_digest=registration_digest,
+            bundle_build_id=build_id,
+            bundle_digest=bundle.bundle_digest,
+        )
+        repaired = old.model_copy(
+            update={
+                "id": f"build_{uuid4().hex}",
+                "provider_bundle": reference,
+                "created_at": datetime.now(tz=timezone.utc),
+            }
+        )
+        return self.studio.codex_builds.save(repaired)
+        return None
+
+    def _build_id_for_bundle(self, bundle) -> str | None:
+        """Resolve the Build id that produced this bundle root."""
+
+        for build in self.studio.builds.list():
+            if build.bundle_digest == bundle.bundle_digest:
+                return build.id
+        return None

ksadk/studio/codex_run.py

@@ -474,7 +474,12 @@ class CodexRunSpecResolver:
         }
         approval_presets = {
             "ask": ("workspace-write", "manual"),
-            "risk": ("workspace-write", "auto_review"),
+            # Risk operations must be surfaced to Studio's approval card. The
+            # Codex guardian's ``auto_review`` is an upstream model review;
+            # when that stream is unavailable it fails the tool call without
+            # giving the user a chance to confirm. Studio owns the decision,
+            # so use the native user-reviewed mode for both ask and risk.
+            "risk": ("workspace-write", "manual"),
             "full": ("full-access", "deny_all"),
         }
         if approval_mode:

ksadk/studio/compiler.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any
 from urllib.parse import urlparse
 
+from ksadk.conversations.model_context import supports_native_image_input
 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 (
@@ -15,10 +16,13 @@ from ksadk.studio.capabilities import (
     sha256_digest,
 )
 from ksadk.studio.contracts import (
+    AgentBindings,
     AgentDraft,
     CapabilitiesSpec,
+    ModelSpec,
     ResolvedAgentSpec,
     ResolvedCapabilities,
+    RemoteAgentBinding,
 )
 from ksadk.studio.errors import StudioError
 from ksadk.studio.resource_catalog import LocalResourceCatalog
@@ -31,6 +35,8 @@ from ksadk.studio.workspace import Workspace
 class CompileResult:
     resolved: ResolvedAgentSpec
     dependency_lock: dict[str, Any]
+    a2a_source: str | None = None
+    a2a_entry_source: str | None = None
 
 
 class AgentCompiler:
@@ -48,6 +54,13 @@ class AgentCompiler:
         self.catalog = catalog or LocalResourceCatalog(workspace)
 
     def compile(self, draft: AgentDraft) -> CompileResult:
+        from ksadk.studio.a2a_orchestration import compile_orchestration
+        from ksadk.studio.a2a_bindings import require_execution_policy
+
+        orchestration = compile_orchestration(draft)
+        for binding in draft.spec.bindings.remote_agents:
+            RemoteAgentBinding.model_validate(binding.model_dump())
+            require_execution_policy(binding.policy_ref)
         unsupported_plugins = [
             binding.plugin_ref
             for binding in draft.spec.bindings.plugins
@@ -101,8 +114,46 @@ class AgentCompiler:
         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_model = self.resolver.resolve_model(materialized.spec.model)
+        vision_spec = self._vision_model_spec(materialized.spec.bindings)
+        vision_model = self.resolver.resolve_model(vision_spec) if vision_spec is not None else None
+        if (
+            vision_model is not None
+            and not supports_native_image_input(vision_model.metadata)
+        ):
+            raise StudioError(
+                "VISION_MODEL_IMAGE_INPUT_REQUIRED",
+                "视觉模型资源必须显式声明图片输入能力",
+                status_code=422,
+                field="spec.bindings.visionModelProfileId",
+            )
+        bound_models = [
+            self.resolver.resolve_model(model)
+            for model in self.catalog.resolve_models(materialized.spec.bindings)
+        ]
+        fallback_models = []
+        if materialized.spec.bindings.model_failover_mode == "automatic":
+            fallback_models = [
+                model
+                for model in bound_models
+                if not (
+                    model.model == resolved_model.model
+                    and model.endpoint_url == resolved_model.endpoint_url
+                )
+            ]
 
         resolved = ResolvedAgentSpec(
+            a2a_orchestration=({**orchestration.plan, "digest": orchestration.digest} if orchestration else None),
             agent_id=draft.metadata.id,
             source_revision=draft.metadata.revision,
             instructions=compose_system_instruction(
@@ -110,17 +161,22 @@ class AgentCompiler:
                 materialized.spec.soul,
             ),
             soul=materialized.spec.soul,
-            model=self.resolver.resolve_model(materialized.spec.model),
+            model=resolved_model,
+            vision_model=vision_model,
+            fallback_models=fallback_models[:4],
+            model_failover_mode=materialized.spec.bindings.model_failover_mode,
             capabilities=ResolvedCapabilities(
                 skills=skills,
                 mcp_servers=mcp_servers,
                 tools=tools,
             ),
+            remote_agents=sorted(materialized.spec.bindings.remote_agents, key=lambda item: (item.local_name, item.binding_id)),
             execution=materialized.spec.execution,
             context=materialized.spec.context,
             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(
@@ -140,13 +196,53 @@ class AgentCompiler:
                 exclude_none=True,
                 mode="json",
             ),
+            "fallbackModels": [
+                model.model_dump(by_alias=True, exclude_none=True, mode="json")
+                for model in resolved.fallback_models
+            ],
+            **(
+                {
+                    "visionModel": vision_model.model_dump(
+                        by_alias=True, exclude_none=True, mode="json"
+                    )
+                }
+                if vision_model is not None
+                else {}
+            ),
             "skills": skills,
             "mcpServers": mcp_servers,
             "tools": [
                 tool.model_dump(by_alias=True, exclude_none=True, mode="json") for tool in tools
             ],
         }
-        return CompileResult(resolved=resolved, dependency_lock=dependency_lock)
+        dependency_lock["remoteAgents"] = [binding.model_dump(by_alias=True, mode="json") for binding in resolved.remote_agents]
+        if orchestration:
+            dependency_lock["a2aOrchestration"] = {**orchestration.plan, "digest": orchestration.digest}
+        return CompileResult(resolved=resolved, dependency_lock=dependency_lock,
+                             a2a_source=orchestration.source if orchestration else None,
+                             a2a_entry_source=orchestration.entry_source if orchestration else None)
+
+    def _vision_model_spec(self, bindings: AgentBindings) -> ModelSpec | None:
+        profile_id = bindings.vision_model_profile_id
+        if profile_id is None:
+            return None
+        selected = bindings.model_copy(
+            update={
+                "model_profile_id": profile_id,
+                "model_profile_ids": [],
+                "model_parameters": None,
+                "vision_model_profile_id": None,
+            }
+        )
+        model = self.catalog.resolve_model(selected)
+        if model is None:
+            raise StudioError(
+                "VISION_MODEL_PROFILE_REQUIRED",
+                "视觉模型资源不可用",
+                status_code=422,
+                field="spec.bindings.visionModelProfileId",
+            )
+        return model
 
     def _materialize_bindings(self, draft: AgentDraft) -> AgentDraft:
         runtime = draft.spec.runtime
@@ -169,6 +265,7 @@ class AgentCompiler:
         if (
             not uses_codex_native_tools
             and not bindings.model_profile_id
+            and not bindings.vision_model_profile_id
             and not bindings.tools
             and not bindings.mcp_servers
             and not bindings.skills
@@ -239,11 +336,20 @@ class AgentCompiler:
             | set(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(".")
-        if hostname and materialized.spec.security.network.mode == "restricted":
+        network_models = self.catalog.resolve_models(bindings)
+        vision_spec = self._vision_model_spec(bindings)
+        if vision_spec is not None:
+            network_models.append(vision_spec)
+        model_hosts = {
+            (urlparse(item.endpoint_url or item.base_url or "").hostname or "")
+            .lower()
+            .rstrip(".")
+            for item in network_models
+        }
+        model_hosts.discard("")
+        if model_hosts and materialized.spec.security.network.mode == "restricted":
             materialized.spec.security.network.allowed_hosts = sorted(
-                set(materialized.spec.security.network.allowed_hosts) | {hostname}
+                set(materialized.spec.security.network.allowed_hosts) | model_hosts
             )
         return materialized
 

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/contract_base.py

@@ -0,0 +1,19 @@
+"""Shared strict Pydantic base for Studio wire contracts."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+def _to_camel(value: str) -> str:
+    head, *tail = value.split("_")
+    return head + "".join(part.capitalize() for part in tail)
+
+
+class ContractModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=_to_camel,
+        populate_by_name=True,
+        extra="forbid",
+        use_enum_values=True,
+    )