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

ksadk/studio/authoring.py

@@ -7,6 +7,7 @@ ID allocation to the server.
 
 from __future__ import annotations
 
+import copy
 import hashlib
 import io
 import json
@@ -21,14 +22,15 @@ from urllib.parse import urlparse
 from uuid import uuid4
 
 import yaml  # type: ignore[import-untyped]
-from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
 
 from ksadk.detection.detector import FrameworkDetector
+from ksadk.managed_runtime import installed_runtime_version
 from ksadk.studio.capabilities import canonical_json, sha256_digest
 from ksadk.studio.codex_manifest import CodexAgentManifest
 from ksadk.studio.contracts import (
     AgentDraft,
-    Instructions,
+    AgentSpec,
     NetworkPolicy,
     RuntimeRef,
 )
@@ -48,7 +50,33 @@ class ConversationProposal(BaseModel):
     slug: str = Field(min_length=1, max_length=63)
     runtimeType: Literal["codex", "adk", "langgraph"]
     description: str = Field(default="", max_length=1024)
-    instructions: Instructions
+    spec: AgentSpec
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_prompt_only_proposal(cls, value: Any) -> Any:
+        """Accept one release of old model output without persisting its data loss.
+
+        Older authoring prompts asked the model for only ``instructions``.  Turn
+        that response into a complete AgentSpec at the boundary so callers only
+        ever consume the lossless proposal shape.
+        """
+
+        if not isinstance(value, dict) or "spec" in value:
+            return value
+        payload = dict(value)
+        instructions = payload.pop("instructions", None)
+        payload["spec"] = {
+            "description": str(payload.get("description") or ""),
+            "instructions": instructions or {},
+        }
+        return payload
+
+    @model_validator(mode="after")
+    def validate_runtime_type(self) -> "ConversationProposal":
+        if self.spec.runtime is not None and self.spec.runtime.type != self.runtimeType:
+            raise ValueError("spec.runtime.type 必须与 runtimeType 一致")
+        return self
 
 
 @dataclass(frozen=True)
@@ -82,16 +110,11 @@ class AgentAuthoringService:
             normalized = f"agent-{normalized}" if normalized else "agent"
         return normalized[:48].rstrip("-")
 
-    def allocate_agent_id(self, _slug: str) -> str:
-        """Allocate a server-owned identifier without using a slug as a path segment.
-
-        Callers retain the normalized slug in Agent metadata for display and search,
-        while source directories only use this opaque identifier.
-        """
-
+    def allocate_agent_id(self, slug: str) -> str:
+        base = self.normalize_slug(slug)
         for _attempt in range(100):
-            candidate = f"agentkit-{uuid4().hex[:8]}"
-            if not (self.workspace.resolve("agents") / candidate).exists():
+            candidate = f"{base}-{uuid4().hex[:12]}"
+            if not self.workspace.resolve(Path("agents") / candidate).exists():
                 return candidate
         raise StudioError(
             "AGENT_ID_ALLOCATION_FAILED",
@@ -111,7 +134,13 @@ class AgentAuthoringService:
                 details={"runtimeType": normalized},
             )
         if normalized == "codex":
-            return RuntimeRef(type="codex", version="0.144.4")
+            # A new YAML Agent must lock the CLI actually installed on this
+            # Studio host. Cloud admission resolves that explicit version via
+            # the Server-owned catalog instead of accepting a client image.
+            return RuntimeRef(
+                type="codex",
+                version=installed_runtime_version("codex") or "0.144.4",
+            )
         return RuntimeRef(
             type=cast(Any, normalized),
             project_path=f"agents/{agent_id}/source",
@@ -291,17 +320,197 @@ class AgentAuthoringService:
             path.unlink()
 
     @staticmethod
-    def parse_conversation_proposal(content: str) -> ConversationProposal:
+    def _sanitize_model_block(payload: dict[str, Any]) -> None:
+        """清掉模型照抄示例或凭空编造的 spec.model 字段。
+
+        - baseUrl/endpointUrl 写着 example.com/placeholder 等占位域名的直接删掉
+          （Studio 会按选中的模型 Profile 注入真实 endpoint）
+        - parameters 只保留用户对话明确要求时模型写出的值；模型自行编造的
+          常见值（temperature 0.x + maxTokens 2048/4096 这类组合）无法与
+          用户意图区分时一并删除，交平台默认值兜底
+        """
+        spec = payload.get("spec")
+        if not isinstance(spec, dict):
+            return
+        model = spec.get("model")
+        if not isinstance(model, dict):
+            return
+        for key in ("baseUrl", "endpointUrl"):
+            value = model.get(key)
+            if not isinstance(value, str):
+                continue
+            try:
+                hostname = (urlparse(value).hostname or "").lower().rstrip(".")
+            except ValueError:
+                hostname = ""
+            labels = hostname.split(".")
+            is_example_host = hostname == "example.com" or hostname.endswith(".example.com")
+            is_placeholder_host = any(label == "placeholder" for label in labels)
+            if is_example_host or is_placeholder_host:
+                model.pop(key, None)
+        # ModelSpec 校验要求 baseUrl/endpointUrl 二选一；模型没写或写了占位被删时，
+        # 置一个显式标记值，coordinator 会用选中模型 Profile 的真实 endpoint 覆写。
+        if not model.get("baseUrl") and not model.get("endpointUrl"):
+            model["baseUrl"] = "https://model-profile.invalid/placeholder"
+
+    @staticmethod
+    def _coerce_model_credential_ref(payload: dict[str, Any]) -> None:
+        """容忍模型把 spec.model.credentialRef 写成对象/空值的常见错误形态。
+
+        模型偶尔会把字符串引用字段写成 {} 或 {"ref": ...}；在进入 Pydantic 校验前
+        收敛为默认 env 引用，避免浪费唯一一次纠错重试。
+        """
+        spec = payload.get("spec")
+        if not isinstance(spec, dict):
+            return
+        model = spec.get("model")
+        if not isinstance(model, dict):
+            return
+        ref = model.get("credentialRef")
+        if isinstance(ref, str) and ref.strip().startswith(("env://", "keychain://", "secret-manager://")):
+            return
+        if isinstance(ref, dict):
+            nested = ref.get("ref") or ref.get("credentialRef") or ref.get("value")
+            if isinstance(nested, str) and nested.strip().startswith(("env://", "keychain://", "secret-manager://")):
+                model["credentialRef"] = nested.strip()
+                return
+        model["credentialRef"] = "env://AGENTKIT_MODEL_API_KEY"
+
+    @staticmethod
+    def _coerce_runtime_type(payload: dict[str, Any]) -> None:
+        """容忍模型把 spec.runtime.type 写成 provider 的常见错误形态。"""
+        spec = payload.get("spec")
+        if not isinstance(spec, dict):
+            return
+        runtime = spec.get("runtime")
+        if not isinstance(runtime, dict):
+            return
+        if not runtime.get("type") and runtime.get("provider"):
+            runtime["type"] = runtime.pop("provider")
+        elif runtime.get("provider") and runtime.get("type"):
+            runtime.pop("provider")
+
+    @staticmethod
+    def _conversation_json_object(content: str) -> dict[str, Any]:
+        """Extract one JSON object without trusting surrounding model prose."""
+
         text = str(content or "").strip()
-        if text.startswith("```"):
-            lines = text.splitlines()
-            if lines and lines[0].startswith("```"):
-                lines = lines[1:]
-            if lines and lines[-1].strip() == "```":
-                lines = lines[:-1]
-            text = "\n".join(lines).strip()
+        candidates = [text]
+        candidates.extend(
+            match.group(1).strip()
+            for match in re.finditer(r"```(?:json)?\s*([\s\S]*?)```", text, re.IGNORECASE)
+        )
+        decoder = json.JSONDecoder()
+        for candidate in candidates:
+            try:
+                payload = json.loads(candidate)
+            except ValueError:
+                payload = None
+            if isinstance(payload, dict):
+                return cast(dict[str, Any], payload)
+        for start, character in enumerate(text):
+            if character != "{":
+                continue
+            try:
+                payload, _end = decoder.raw_decode(text, start)
+            except ValueError:
+                continue
+            if isinstance(payload, dict):
+                return cast(dict[str, Any], payload)
+        raise ValueError("model output does not contain a JSON object")
+
+    @staticmethod
+    def _merge_conversation_patch(
+        base: dict[str, Any], patch: dict[str, Any]
+    ) -> dict[str, Any]:
+        merged = copy.deepcopy(base)
+        for key, value in patch.items():
+            if isinstance(value, dict) and isinstance(merged.get(key), dict):
+                merged[key] = AgentAuthoringService._merge_conversation_patch(
+                    cast(dict[str, Any], merged[key]), value
+                )
+            else:
+                merged[key] = copy.deepcopy(value)
+        return merged
+
+    @staticmethod
+    def _studio_owned_conversation_patch(
+        payload: dict[str, Any],
+        *,
+        runtime_type: str,
+    ) -> dict[str, Any]:
+        """Keep an authoring-model response to semantic fields only.
+
+        A conversation can describe an Agent, but it cannot produce a valid
+        local ADK/LangGraph project, resource identity, credential or runtime
+        binding.  Treating its complete AgentSpec as deployable made a simple
+        conversation depend on it guessing every evolving Studio contract.
+        Studio owns those fields and injects them after this parser returns.
+        """
+
+        normalized = str(runtime_type or "").strip().lower()
+        if normalized not in _SUPPORTED_RUNTIMES:
+            raise ValueError("runtimeType is not supported")
+        raw_spec = payload.get("spec")
+        if not isinstance(raw_spec, dict):
+            raw_spec = {}
+        raw_instructions = raw_spec.get("instructions", payload.get("instructions"))
+        instructions = raw_instructions if isinstance(raw_instructions, dict) else {}
+        spec: dict[str, Any] = {
+            "instructions": {
+                key: str(value).strip()
+                for key in ("system", "task")
+                if isinstance((value := instructions.get(key)), str) and value.strip()
+            }
+        }
+        if isinstance(raw_spec.get("description"), str):
+            spec["description"] = raw_spec["description"].strip()
+        return {
+            key: copy.deepcopy(payload[key])
+            for key in ("name", "slug", "description")
+            if key in payload
+        } | {
+            "runtimeType": normalized,
+            "spec": spec,
+        }
+
+    @staticmethod
+    def parse_conversation_proposal(
+        content: str,
+        *,
+        base: ConversationProposal | dict[str, Any] | None = None,
+        runtime_type: str | None = None,
+    ) -> ConversationProposal:
         try:
-            payload = json.loads(text)
+            payload = AgentAuthoringService._conversation_json_object(content)
+            for wrapper in ("proposal", "patch"):
+                wrapped = payload.get(wrapper)
+                if isinstance(wrapped, dict) and len(payload) == 1:
+                    payload = cast(dict[str, Any], wrapped)
+                    break
+            if runtime_type is not None:
+                payload = AgentAuthoringService._studio_owned_conversation_patch(
+                    payload,
+                    runtime_type=runtime_type,
+                )
+            AgentAuthoringService._coerce_model_credential_ref(payload)
+            AgentAuthoringService._sanitize_model_block(payload)
+            AgentAuthoringService._coerce_runtime_type(payload)
+            if base is not None:
+                base_payload = (
+                    base.model_dump(by_alias=True, mode="json")
+                    if isinstance(base, ConversationProposal)
+                    else base
+                )
+                payload = AgentAuthoringService._merge_conversation_patch(
+                    base_payload, payload
+                )
+            if runtime_type is not None:
+                # The merge can reintroduce an old runtimeType from a previous
+                # Draft Patch; the live Studio selector remains authoritative.
+                payload["runtimeType"] = str(runtime_type).strip().lower()
+                if isinstance(payload.get("spec"), dict):
+                    payload["spec"].pop("runtime", None)
             proposal = ConversationProposal.model_validate(payload)
         except (ValueError, ValidationError) as exc:
             raise StudioError(
@@ -314,7 +523,11 @@ class AgentAuthoringService:
         return proposal.model_copy(update={"slug": normalized_slug})
 
     @staticmethod
-    def conversation_messages(messages: list[dict[str, str]]) -> list[dict[str, str]]:
+    def conversation_messages(
+        messages: list[dict[str, str]],
+        *,
+        runtime_type: str = "codex",
+    ) -> list[dict[str, str]]:
         if not messages:
             raise StudioError(
                 "AUTHORING_CONVERSATION_EMPTY",
@@ -326,9 +539,14 @@ class AgentAuthoringService:
                 "role": "system",
                 "content": (
                     "你是 AgentKit Studio 的 Agent 设计助手。根据对话生成一个 JSON Draft Patch，"
-                    "不得输出 Markdown。字段必须且只能包含 name、slug、runtimeType、description、"
-                    "instructions；runtimeType 只能是 codex、adk、langgraph；instructions 必须包含"
-                    " system 和 task。只提出配置，不写文件、不宣称已经创建。"
+                    "不得输出 Markdown。只返回一个最小 JSON Draft Patch：首轮只包含 name、"
+                    "slug、description、spec；spec 只包含 instructions，instructions 只允许"
+                    "system 和 task。后续轮次只返回要更新的上述字段，由 Studio 与上一版 Patch"
+                    "合并。当前 Runtime 已由 Studio 选择为 "
+                    f"{runtime_type}，不得输出 runtimeType、spec.runtime、execution、context、"
+                    "memory、security、evaluation、model、bindings、capabilities 或任何资源 ID。"
+                    "模型 Profile、运行 Runtime、模型参数、Tool、MCP、Skill、凭证、端点与"
+                    "资源 ID 都由 Studio 按用户选择注入。只提出配置，不写文件、不宣称已经创建。"
                 ),
             }
         ]
@@ -469,9 +687,23 @@ class AgentAuthoringService:
 
     @staticmethod
     def _tree_digest(root: Path, *, exclude: set[str] | None = None) -> str:
-        ignored = exclude or set()
+        # 默认排除 .agentkit（Studio 自身状态）与常见忽略目录，避免 inspect 后写 token json
+        # 改变 digest 导致 commit 时 PROJECT_CHANGED_AFTER_INSPECTION 误报（方案 §6.1）。
+        ignored = set(exclude or [])
+        ignored.add(".agentkit")
+        ignored.add(".git")
         entries: list[dict[str, Any]] = []
         for path in sorted(root.rglob("*"), key=lambda item: item.as_posix()):
+            relative = path.relative_to(root).as_posix()
+            # Studio state and VCS internals may legitimately contain symlinks
+            # (for example managed Node dependencies). They are outside the
+            # imported project contract, so prune them before applying the
+            # source-tree symlink safety check.
+            if any(
+                relative == ignored_dir or relative.startswith(ignored_dir + "/")
+                for ignored_dir in (".agentkit", ".git")
+            ):
+                continue
             if path.is_symlink():
                 raise StudioError(
                     "AUTHORING_SOURCE_UNSAFE",
@@ -481,7 +713,6 @@ class AgentAuthoringService:
                 )
             if not path.is_file() or path.name in ignored:
                 continue
-            relative = path.relative_to(root).as_posix()
             content = path.read_bytes()
             entries.append(
                 {