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

ksadk/studio/api_contracts.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
-from pydantic import Field, SecretStr
+from pydantic import Field, SecretStr, field_validator
 
 from ksadk.evaluation import EvaluationConfig as PublicEvaluationConfig
 from ksadk.evaluation import TargetRef
@@ -48,6 +48,28 @@ class BuildRequest(ContractModel):
     evaluation_suite_refs: list[str] = Field(default_factory=list)
 
 
+class ImportRootRequest(ContractModel):
+    """一键导入根 Framework 项目（方案 §6.1）。"""
+    name: str | None = None
+    slug: str | None = None
+
+
+class PromptCompileRequest(ContractModel):
+    """PR-S2：Prompt 编译预览请求（方案 §6.2）。只读，不写 Session/Trace。"""
+    revision: int = Field(default=1, ge=1)
+    request_instructions: str = Field(default="", max_length=32768)
+    include_content: bool = False  # local debug 显式请求正文
+
+
+class ContextPreviewRequest(ContractModel):
+    """PR-S2：Context 预览请求（方案 §6.2）。复用真实 Planner，不调模型。"""
+    revision: int = Field(default=1, ge=1)
+    user_input: str = Field(default="", max_length=1_000_000)
+    request_instructions: str = Field(default="", max_length=32768)
+    simulated_history: list[MessageInput] = Field(default_factory=list)
+    include_content: bool = False
+
+
 class MessageInput(ContractModel):
     role: str = "user"
     content: str = Field(min_length=1, max_length=1_000_000)
@@ -69,7 +91,29 @@ class AuthoringConversationMessage(ContractModel):
 
 class ConversationAuthoringRequest(ContractModel):
     messages: list[AuthoringConversationMessage] = Field(min_length=1, max_length=100)
+    # This is the single profile used to generate the Draft Patch.  It is not
+    # implicitly the deployed Agent's only model: callers may bind a separate
+    # allow-list and default below.
     model_profile_id: str = Field(min_length=3, max_length=256)
+    # Runtime is a Studio-owned deployment choice.  The authoring model only
+    # supplies semantic intent and must not choose an incompatible framework
+    # source contract on its own.
+    runtime_type: Literal["codex", "adk", "langgraph"] = "codex"
+    agent_model_profile_ids: list[str] = Field(default_factory=list, max_length=100)
+    agent_default_model_profile_id: str | None = Field(
+        default=None,
+        min_length=3,
+        max_length=256,
+    )
+    # Resource identities are selected by the Studio user, never generated by
+    # the authoring model.  The API resolves and validates their contracts
+    # before adding them to the returned Draft Patch.
+    tool_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    mcp_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    skill_resource_ids: list[str] = Field(default_factory=list, max_length=100)
+    # 可选的进度关联标识：前端生成后随请求带上，可通过
+    # GET /api/v1/authoring/conversations:status/{request_id} 轮询构建阶段。
+    request_id: str | None = Field(default=None, min_length=1, max_length=128)
 
 
 class AuthoringCommitRequest(ContractModel):
@@ -96,10 +140,71 @@ class InteractionSubmitRequest(ContractModel):
     data: dict[str, Any] = Field(default_factory=dict)
 
 
-class EvaluationRequest(ContractModel):
-    suite_refs: list[str] = Field(min_length=1)
-    concurrency: int = Field(default=1, ge=1, le=4)
-    fail_fast: bool = False
+class CloudChatMessageRequest(ContractModel):
+    """One cloud turn submitted through Studio's loopback control plane.
+
+    The loopback process, never the browser, owns the AK/SK used to admit the
+    message through the cloud control plane.  ``content`` uses the same
+    OpenAI-compatible text/image/file part shape as RunAgent; execution-policy
+    fields remain bounded enums and are revalidated by Server/Runtime.
+    """
+
+    content: str | list[dict[str, Any]]
+    model: str | None = Field(default=None, min_length=1, max_length=256)
+    model_options: dict[str, Any] = Field(default_factory=dict)
+    tool_approval_mode: Literal["ask", "risk", "full"] = "risk"
+    collaboration_mode: Literal["default", "plan"] | None = None
+    goal_objective: str | None = Field(default=None, min_length=1, max_length=4096)
+
+    @field_validator("content")
+    @classmethod
+    def validate_content(cls, value):
+        if isinstance(value, str):
+            if not value.strip():
+                raise ValueError("content must not be empty")
+            if len(value) > 1_000_000:
+                raise ValueError("text content is too large")
+            return value
+        if not 1 <= len(value) <= 9:
+            raise ValueError("content must contain between 1 and 9 parts")
+        attachment_count = 0
+        for part in value:
+            kind = str(part.get("type") or "")
+            if kind == "input_text":
+                text = part.get("text")
+                if not isinstance(text, str) or not text.strip() or len(text) > 1_000_000:
+                    raise ValueError("input_text must contain bounded non-empty text")
+                continue
+            if kind == "input_image":
+                attachment_count += 1
+                url = part.get("image_url")
+                if not isinstance(url, str) or not url or len(url) > 14_000_000:
+                    raise ValueError("input_image must contain a bounded image_url")
+                continue
+            if kind == "input_file":
+                attachment_count += 1
+                filename = part.get("filename")
+                data = part.get("file_data") or part.get("file_url")
+                if not isinstance(filename, str) or not filename.strip():
+                    raise ValueError("input_file must contain a filename")
+                if not isinstance(data, str) or not data or len(data) > 14_000_000:
+                    raise ValueError("input_file must contain bounded file data")
+                continue
+            raise ValueError(f"unsupported content part: {kind or '<missing>'}")
+        if attachment_count > 8:
+            raise ValueError("a turn supports at most 8 attachments")
+        return value
+
+
+class CloudChatInteractionSubmitRequest(ContractModel):
+    """Public Interaction/v1 fields accepted by the local cloud-chat proxy."""
+
+    run_id: str = Field(min_length=1, max_length=256)
+    interaction_id: str = Field(min_length=1, max_length=256)
+    expected_revision: int = Field(ge=1)
+    action: Literal["approve", "reject", "submit", "cancel"]
+    response: dict[str, Any] = Field(default_factory=dict)
+    idempotency_key: str = Field(min_length=1, max_length=256)
 
 
 class StudioEvaluationCreate(ContractModel):
@@ -123,6 +228,10 @@ class RollbackRequest(ContractModel):
     target_build_id: str
 
 
+class CloudAgentVersionRollbackRequest(ContractModel):
+    version_id: str = Field(min_length=1, max_length=256)
+
+
 class ModelProfileCreateRequest(ContractModel):
     name: str = Field(pattern=r"^[a-z][a-z0-9._-]{1,127}$")
     display_name: str = Field(min_length=1, max_length=128)

ksadk/studio/api_memory_routes.py

@@ -0,0 +1,82 @@
+"""Memory observability and local management routes for Studio."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, Query
+
+from ksadk.memory.coordinator import agent_user_scope_id
+from ksadk.memory.models import MemoryDeleteRequest, MemorySearchRequest
+from ksadk.memory.providers.local_sqlite import resolve_default_memory_provider
+
+
+def register_memory_routes(app: FastAPI, studio: Any) -> None:
+    """Register PCM memory routes without expanding the central API module."""
+
+    @app.get("/api/v1/runs/{run_id}/memory-events")
+    async def get_run_memory_events(run_id: str):
+        events = studio.event_store.events(run_id)
+        items = []
+        for event in events:
+            data = event.data or {}
+            has_memory_payload = isinstance(data, dict) and (
+                "memory_event" in data
+                or any(
+                    isinstance(value, str) and value.startswith("memory.")
+                    for value in data.values()
+                )
+            )
+            if "memory" in str(event.type or "").lower() or has_memory_payload:
+                items.append({"id": event.id, "type": event.type, "data": data})
+        return {"items": items}
+
+    @app.get("/api/v1/memories")
+    async def list_memories(
+        user_id: str = Query(default="local-user", alias="userId"),
+        agent_id: str | None = Query(default=None, alias="agentId"),
+    ):
+        provider = resolve_default_memory_provider()
+        scope_id = agent_user_scope_id(agent_id=agent_id, user_id=user_id) if agent_id else user_id
+        result = provider.search(
+            MemorySearchRequest(
+                query="",
+                scopes=[("user", scope_id)],
+                memory_types=["profile", "fact", "episode"],
+                top_k=100,
+                max_tokens=10000,
+                min_score=0.0,
+            )
+        )
+        return {
+            "items": [
+                {
+                    "memory_id": record.memory_id,
+                    "scope": record.scope,
+                    "scope_id": record.scope_id,
+                    "memory_type": record.memory_type,
+                    "content": record.content[:200],
+                    "summary": record.summary,
+                    "status": record.status,
+                    "confidence": record.confidence,
+                    "created_at": record.created_at,
+                }
+                for record in result.records
+            ]
+        }
+
+    @app.delete("/api/v1/memories/{memory_id}")
+    async def delete_memory(memory_id: str):
+        provider = resolve_default_memory_provider()
+        record = provider.get(memory_id)
+        if record is None:
+            return {"deleted": False, "status": "ok"}
+        result = provider.delete(
+            MemoryDeleteRequest(
+                memory_id=memory_id,
+                scope=record.scope,
+                scope_id=record.scope_id,
+                hard=True,
+            )
+        )
+        return {"deleted": result.deleted, "status": result.status}

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,7 +687,11 @@ 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()):
             if path.is_symlink():
@@ -481,7 +703,10 @@ class AgentAuthoringService:
                 )
             if not path.is_file() or path.name in ignored:
                 continue
+            # 跳过 .agentkit / .git 目录下的文件
             relative = path.relative_to(root).as_posix()
+            if any(relative.startswith(ignored_dir + "/") for ignored_dir in (".agentkit", ".git")):
+                continue
             content = path.read_bytes()
             entries.append(
                 {