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

ksadk/studio/teams_remote.py

@@ -0,0 +1,274 @@
+"""Studio projection of a server-owned Teams authority and local node.
+
+Enabled explicitly with KSADK_TEAMS_SERVER_URL. Cloud coordination outlives
+this adapter; shutting it down never revokes a team or a cloud execution.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import socket
+from urllib.parse import urlsplit
+from uuid import uuid4
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from ksadk.plugins.teams.contracts import API_VERSION
+from ksadk.plugins.teams.errors import TeamsError
+from ksadk.plugins.teams.transport import TeamsHTTPClient
+from ksadk.studio.teams_catalog import StudioTeamsCatalog
+from ksadk.studio.teams_node import TeamsExecutionNode
+from ksadk.studio.workspace_plugins import WorkspacePlugin
+
+
+class RemoteStudioTeamsInstallation:
+    def __init__(self, studio, base_url: str):
+        self.studio, self.base_url = studio, base_url
+        self.authority_ref = ""
+        self.available = True
+        self._enabled = False
+        self._failure = None
+        self.client = None
+        self.node = None
+        self.registry = None
+        self.host = None
+        self._prior_resolver = None
+        studio.workspace_plugins.register(
+            WorkspacePlugin(
+                "teams", API_VERSION, self.enable, self.disable, self.status, shutdown=self._close
+            )
+        )
+        # Reading remote history does not depend on local node startup.
+        studio.workspace_plugins.contribute_routes("teams", self._router())
+
+    def status(self):
+        return {
+            "enabled": self._enabled,
+            "configured": True,
+            "available": True,
+            "mode": "server",
+            "authorityLocation": "server",
+            "authorityRef": self.authority_ref,
+            "health": "degraded"
+            if self._enabled and self._failure
+            else "ready"
+            if self._enabled
+            else "error"
+            if self._failure
+            else "disabled",
+            "stage": "connection",
+            "reason": self._failure,
+            "nodeReason": self.node.last_error if self.node else None,
+            "recoveryUrl": "/studio-recovery/",
+        }
+
+    def _client(self):
+        if self.client is None:
+            environment = self.studio.configuration.environment()
+            token = environment.get("KSADK_TEAMS_ACCESS_TOKEN") or None
+            gateway_client = getattr(
+                getattr(getattr(self.studio, "cloud", None), "gateway", None), "client", None
+            )
+
+            async def signed(method, url, body):
+                if token:
+                    return {}
+                if gateway_client is None:
+                    if not token:
+                        raise TeamsError(
+                            "teams_credentials_required", "请配置团队服务连接凭据", status=401
+                        )
+                    return {}
+
+                def create():
+                    headers = gateway_client._build_headers()
+                    headers["Host"] = urlsplit(url).netloc
+                    return gateway_client._auth.sign_headers(
+                        method=method, url=url, headers=headers, body=body
+                    )
+
+                return await asyncio.to_thread(create)
+
+            self.client = TeamsHTTPClient(self.base_url, access_token=token, headers=signed)
+        return self.client
+
+    async def enable(self):
+        if self._enabled:
+            if self.node is None:
+                await self._start_node()
+                self._failure = None
+            return
+        try:
+            status = await self._client().request("GET", "/lifecycle")
+            self.authority_ref = status["authorityRef"]
+            self._enabled = True
+            self._failure = None
+        except TeamsError as error:
+            self._failure = error.code
+            raise
+        # Server teams remain accessible if this particular device cannot run.
+        try:
+            await self._start_node()
+        except Exception as error:
+            self._failure = getattr(error, "code", "local_node_unavailable")
+
+    async def _start_node(self):
+        if self.node is not None:
+            return
+        from ksadk.studio.execution_host import StudioExecutionHost
+        from ksadk.studio.kernel_registry import StudioBuildKernelRegistry
+
+        await self.studio.start()
+        state = self.studio.workspace.resolve(".agentkit/teams-node")
+        state.mkdir(parents=True, exist_ok=True)
+        identity_path = state / "identity.json"
+        if identity_path.exists():
+            identity = json.loads(identity_path.read_text())
+        else:
+            identity = {"nodeId": "node_" + uuid4().hex}
+            with os.fdopen(
+                os.open(identity_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w"
+            ) as stream:
+                json.dump(identity, stream)
+        catalog = StudioTeamsCatalog(self.studio, authority_ref=self.authority_ref)
+        bindings = catalog._local()
+        environment = self.studio.configuration.environment()
+        kind = environment.get("KSADK_TEAMS_NODE_KIND", "local")
+        name = environment.get("KSADK_TEAMS_NODE_NAME") or socket.gethostname()
+        registration = await self._client().request(
+            "POST",
+            "/nodes/register",
+            {
+                "nodeId": identity["nodeId"],
+                "name": name,
+                "kind": kind,
+                "bindings": bindings,
+                "idempotencyKey": TeamsExecutionNode.registration_key(
+                    identity["nodeId"], name, kind, bindings
+                ),
+            },
+        )
+        self.registry = StudioBuildKernelRegistry(
+            resolve_build=self.studio.resolve_run_spec,
+            resolve_adapter_provider=self.studio._scheduler_adapter_provider,
+            session_service=self.studio.session_service,
+            runtime_executor=self.studio.runtime_executor,
+            state_dir=state / "runtime",
+            tenant_id=registration["tenantId"],
+            workspace_id=registration["nodeId"],
+        )
+        try:
+            await self.registry.start()
+            self.host = StudioExecutionHost(self.registry, state_path=state / "host.sqlite")
+            self.node = TeamsExecutionNode(
+                self._client(),
+                self.host,
+                state_dir=state,
+                name=name,
+                kind=kind,
+                bindings=bindings,
+                allowed_roots=(self.studio.workspace.root,),
+                list_bindings=catalog._local,
+            )
+            self._prior_resolver = self.studio.plugin_runs.execution_policy_resolver
+            self.studio.plugin_runs.execution_policy_resolver = self.host
+            await self.node.start()
+        except BaseException:
+            await self._close_node()
+            raise
+
+    def _router(self):
+        router = APIRouter()
+
+        @router.api_route("/groups", methods=["GET", "POST"])
+        @router.api_route("/groups/{rest:path}", methods=["GET", "POST", "PATCH", "DELETE"])
+        async def proxy(request: Request, rest: str = ""):
+            if any(part in {".", ".."} for part in rest.split("/")) or any(
+                char in rest for char in "\\%?#\x00"
+            ):
+                return JSONResponse(
+                    {"error": {"code": "teams_path_forbidden", "message": "团队接口路径无效"}},
+                    status_code=400,
+                )
+            path = "/groups" + ("/" + rest if rest else "")
+            if request.url.query:
+                path += "?" + request.url.query
+            client = self._client()
+            body = await request.body()
+            text = body.decode("utf-8") if body else ""
+            upstream = None
+            try:
+                headers = await client.request_headers(request.method, path, text)
+                upstream = await client.http.send(
+                    client.http.build_request(
+                        request.method, client.base_url + path, content=body, headers=headers
+                    ),
+                    stream=True,
+                )
+                media = upstream.headers.get("content-type", "application/json")
+                if "text/event-stream" in media:
+
+                    async def stream():
+                        try:
+                            async for chunk in upstream.aiter_bytes():
+                                yield chunk
+                        finally:
+                            await upstream.aclose()
+
+                    return StreamingResponse(
+                        stream(), status_code=upstream.status_code, media_type="text/event-stream"
+                    )
+                content = await upstream.aread()
+                await upstream.aclose()
+                return Response(
+                    content,
+                    status_code=upstream.status_code,
+                    media_type=media,
+                    headers={
+                        key: value
+                        for key, value in upstream.headers.items()
+                        if key.lower() in {"content-disposition", "etag"}
+                    },
+                )
+            except Exception as error:
+                if upstream:
+                    await upstream.aclose()
+                return JSONResponse(
+                    {
+                        "error": {
+                            "code": error.code
+                            if isinstance(error, TeamsError)
+                            else "teams_transport_unavailable",
+                            "message": "团队服务连接中断，请重试核对原操作",
+                        }
+                    },
+                    status_code=503,
+                )
+
+        return router
+
+    async def _close_node(self):
+        if self.node:
+            await self.node.close()
+            self.node = None
+        if self.registry:
+            await self.registry.close()
+            self.registry = None
+        if self.host:
+            if self.studio.plugin_runs.execution_policy_resolver is self.host:
+                self.studio.plugin_runs.execution_policy_resolver = self._prior_resolver
+            await self.host.close()
+            self.host = None
+
+    async def disable(self):
+        await self._close_node()
+        self._enabled = False
+
+    async def _close(self):
+        await self.disable()
+        if self.client:
+            await self.client.close()
+            self.client = None

ksadk/studio/templates.py

@@ -58,9 +58,9 @@ def _blank_behavior_design(goal: str, policy_template: str) -> AgentBehaviorDesi
     explicit = _explicit_boundaries(goal)
     safety = list(explicit)
     policy_boundary = (
-        "执行外部写入、生产变更或其他高风险操作前，说明影响并取得用户确认。"
+        "高风险操作前说明影响并取得用户确认。"
         if policy_template == "strict"
-        else "调用工具和外部服务时遵守当前权限策略，不宣称未实际完成的操作。"
+        else "遵守当前权限策略，不宣称未实际完成的操作。"
     )
     if policy_boundary not in safety:
         safety.append(policy_boundary)
@@ -68,25 +68,24 @@ def _blank_behavior_design(goal: str, policy_template: str) -> AgentBehaviorDesi
         role=f"以“{primary_goal[:80]}”为核心职责的智能助手",
         objective=goal,
         operating_principles=[
-            "优先理解当前目标、已知事实和成功标准，不把假设表述为事实。",
-            "信息不足或存在关键歧义时，先提出最少必要问题。",
-            "只在确有需要时调用已绑定能力，并检查工具输入与返回结果。",
+            "优先理解目标与已知事实，不把假设当事实。",
+            "信息不足时先问最少必要的问题。",
+            "按需调用已绑定能力，检查输入与返回。",
         ],
         workflow=[
-            "识别本次请求、约束条件和期望结果",
-            "检查信息是否充分并澄清关键缺口",
-            "制定并执行必要步骤，使用可用 Tool、MCP 或 Skill",
-            "核对结果、说明限制并按约定结构交付",
+            "明确请求、约束与期望结果",
+            "调用可用 Tool/MCP/Skill 执行",
+            "核对结果并按约定结构交付",
         ],
         explicit_boundaries=explicit,
         safety_boundaries=safety,
         output_expectations=[
-            "回答准确、清晰、可执行，并区分事实、判断和建议。",
-            "涉及风险、假设或未完成事项时明确说明，不伪造执行结果。",
+            "回答准确清晰，区分事实、判断与建议。",
+            "涉及风险或未完成事项时明确说明。",
         ],
         source_notes=[
             "用户输入：核心目标和明确提出的边界",
-            "模板补充：通用执行流程、澄清原则和交付要求",
+            "模板补充：通用执行流程与交付要求",
             "平台策略：工具权限与高风险操作边界",
         ],
     )
@@ -95,19 +94,17 @@ def _blank_behavior_design(goal: str, policy_template: str) -> AgentBehaviorDesi
 def _blank_system_prompt(design: AgentBehaviorDesign) -> str:
     principles = "\n".join(f"- {item}" for item in design.operating_principles)
     boundaries = "\n".join(f"- {item}" for item in design.safety_boundaries)
-    outputs = "\n".join(f"- {item}" for item in design.output_expectations)
     return (
         f"# 角色\n{design.role}\n\n"
         f"# 核心目标\n{design.objective}\n\n"
-        f"# 工作原则\n{principles}\n\n"
-        f"# 安全与边界\n{boundaries}\n\n"
-        f"# 回答要求\n{outputs}"
+        f"# 原则\n{principles}\n\n"
+        f"# 边界\n{boundaries}"
     )
 
 
 def _blank_task_prompt(design: AgentBehaviorDesign) -> str:
     workflow = "\n".join(f"{index}. {item}" for index, item in enumerate(design.workflow, 1))
-    return f"每次收到请求时遵循以下执行契约：\n{workflow}"
+    return f"按以下步骤处理请求：\n{workflow}"
 
 _RESEARCH_SKILL_MANIFEST = {
     "name": RESEARCH_SKILL_NAME,
@@ -154,7 +151,7 @@ _MCP_KEYWORDS = {
 _DEPTH_SETTINGS = {
     "focused": {"max_steps": 8, "timeout_seconds": 180, "max_tokens": 3072},
     "standard": {"max_steps": 16, "timeout_seconds": 360, "max_tokens": 4096},
-    "deep": {"max_steps": 28, "timeout_seconds": 900, "max_tokens": 6144},
+    "deep": {"max_steps": 40, "timeout_seconds": 900, "max_tokens": 6144},
 }
 
 _OUTPUT_NAMES_ZH = {
@@ -213,7 +210,7 @@ def default_agent_spec(
             instructions=prompt,
             execution=ExecutionSpec(
                 strategy="plan-act-observe",
-                max_steps=28,
+                max_steps=40,
                 timeout_seconds=900,
             ),
         )
@@ -720,3 +717,27 @@ Operating principles:
 
 def _research_goal(request: AgentTemplateComposeRequest) -> str:
     return request.goal.strip() or request.prompt.strip()
+
+
+#: DSH harness provider 运行前检查必需的宿主权限（见 specs/studio-harness-authoring）。
+HARNESS_PROVIDER_REQUIRED_PERMISSION = "process:host-user"
+
+
+def with_harness_provider_permissions(spec: AgentSpec) -> AgentSpec:
+    """为模板默认创建的 Harness Agent 预置 provider 必需权限。
+
+    仅作用于"调用方未显式提供 spec"的路径；显式 spec 的授权语义
+    （含显式拒绝）由调用方保证，不在本函数改写。
+    """
+
+    security = spec.security
+    permission = HARNESS_PROVIDER_REQUIRED_PERMISSION
+    if permission in security.allowed_permissions:
+        return spec
+    return spec.model_copy(
+        update={
+            "security": security.model_copy(
+                update={"allowed_permissions": [*security.allowed_permissions, permission]}
+            )
+        }
+    )

ksadk/studio/validator.py

@@ -155,6 +155,19 @@ class AgentValidator:
         mcp_names = {ref.name for ref in capabilities.mcp_servers if ref.enabled}
         tool_names: set[str] = set()
         for index, tool in enumerate(capabilities.tools):
+            if (
+                tool.enabled and draft.spec.runtime and draft.spec.runtime.type == "harness"
+                and not (tool.executor == "mcp" and tool.mcp_server in mcp_names)
+            ):
+                from ksadk.plugins.providers.harness_tools import validate_tool_executor
+
+                try:
+                    validate_tool_executor(tool.model_dump(by_alias=True, mode="json"))
+                except ValueError as exc:
+                    diagnostics.append(self._error(
+                        "TOOL_RUNTIME_INCOMPATIBLE", str(exc),
+                        f"spec.capabilities.tools[{index}].executor",
+                    ))
             try:
                 require_exact_version(
                     tool.version,

ksadk/studio/workspace.py

@@ -48,12 +48,27 @@ class Workspace:
                     "metadata": {"name": self.root.name or "agentkit-workspace"},
                 },
             )
-        gitignore = self.root / ".gitignore"
-        wanted = ".agentkit/secrets.env\n"
+        self.ignore_private_configuration()
+
+    def ignore_private_configuration(self) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        gitignore = self.resolve(".gitignore")
         existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
-        if ".agentkit/secrets.env" not in existing.splitlines():
+        missing = [
+            name
+            for name in (
+                ".agentkit/config.yaml",
+                ".agentkit/settings.yaml",
+                ".agentkit/secrets.env",
+            )
+            if name not in existing.splitlines()
+        ]
+        if missing:
             gitignore.write_text(
-                (existing + ("\n" if existing and not existing.endswith("\n") else "") + wanted),
+                existing
+                + ("\n" if existing and not existing.endswith("\n") else "")
+                + "\n".join(missing)
+                + "\n",
                 encoding="utf-8",
             )
 

ksadk/studio/workspace_plugins.py

@@ -0,0 +1,136 @@
+"""Lifecycle and route slots for trusted, installed workspace plugins.
+
+The router mounts after built-in Studio routes and inherits local session/CSRF
+middleware. Contributions are disposed when their owning plugin goes away.
+It does not interpret feature payloads or execute code from message data.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import APIRouter, FastAPI
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict
+
+from ksadk.studio.plugin_lifecycle import lifecycle_error
+
+
+@dataclass(frozen=True)
+class WorkspacePlugin:
+    plugin_id: str
+    api_version: str
+    enable: Callable[[], Awaitable[None]]
+    disable: Callable[[], Awaitable[None]]
+    status: Callable[[], dict[str, Any]]
+    shutdown: Callable[[], Awaitable[None]] | None = None
+    repair: Callable[[], Awaitable[dict[str, Any]]] | None = None
+
+
+class LifecycleInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    enabled: bool
+
+
+class WorkspacePluginRegistry:
+    def __init__(self) -> None:
+        self.api = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+        self._plugins: dict[str, WorkspacePlugin] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+        self._routes: dict[str, list[Any]] = {}
+
+        @self.api.get("/plugins/{plugin_id}/lifecycle")
+        async def status(plugin_id: str):
+            plugin = self._plugins.get(plugin_id)
+            if not plugin:
+                return JSONResponse(
+                    {"error": {"code": "plugin_not_installed", "message": "工作区插件未安装"}},
+                    status_code=404,
+                )
+            return {"apiVersion": plugin.api_version, **plugin.status()}
+
+        @self.api.post("/plugins/{plugin_id}/lifecycle")
+        async def lifecycle(plugin_id: str, payload: LifecycleInput):
+            plugin = self._plugins.get(plugin_id)
+            if not plugin:
+                return JSONResponse(
+                    {"error": {"code": "plugin_not_installed", "message": "工作区插件未安装"}},
+                    status_code=404,
+                )
+            async with self._locks[plugin_id]:
+                try:
+                    await (plugin.enable() if payload.enabled else plugin.disable())
+                except Exception as error:
+                    failure = lifecycle_error(error, plugin.status().get("stage", "configuration"))
+                    import logging
+                    logging.getLogger(__name__).warning(
+                        "workspace plugin lifecycle failed: %s (%s)", plugin_id, failure.code
+                    )
+                    return JSONResponse(
+                        failure.as_dict(),
+                        status_code=failure.status_code,
+                    )
+                return {"apiVersion": plugin.api_version, **plugin.status()}
+
+        @self.api.post("/plugins/{plugin_id}/repair")
+        async def repair(plugin_id: str):
+            plugin = self._plugins.get(plugin_id)
+            if not plugin or not plugin.repair:
+                return JSONResponse(
+                    {
+                        "error": {
+                            "code": "repair_unavailable",
+                            "message": "此插件没有适用的修复操作",
+                        }
+                    },
+                    status_code=409,
+                )
+            async with self._locks[plugin_id]:
+                try:
+                    result = await plugin.repair()
+                except Exception as error:
+                    failure = lifecycle_error(error, "data_migration")
+                    return JSONResponse(failure.as_dict(), status_code=failure.status_code)
+                return {"apiVersion": plugin.api_version, **plugin.status(), "repair": result}
+
+    def register(self, plugin: WorkspacePlugin) -> Callable[[], None]:
+        if plugin.plugin_id in self._plugins:
+            raise ValueError("workspace plugin already registered")
+        self._plugins[plugin.plugin_id] = plugin
+        self._locks[plugin.plugin_id] = asyncio.Lock()
+
+        def dispose() -> None:
+            self.remove_routes(plugin.plugin_id)
+            self._plugins.pop(plugin.plugin_id, None)
+            self._locks.pop(plugin.plugin_id, None)
+
+        return dispose
+
+    def contribute_routes(self, plugin_id: str, router: APIRouter) -> Callable[[], None]:
+        if plugin_id not in self._plugins:
+            raise ValueError("only a registered plugin may contribute routes")
+        self.remove_routes(plugin_id)
+        before = {id(route) for route in self.api.router.routes}
+        self.api.include_router(router)
+        self._routes[plugin_id] = [
+            route for route in self.api.router.routes if id(route) not in before
+        ]
+        return lambda: self.remove_routes(plugin_id)
+
+    def remove_routes(self, plugin_id: str) -> None:
+        removed = {id(route) for route in self._routes.pop(plugin_id, [])}
+        self.api.router.routes[:] = [
+            route for route in self.api.router.routes if id(route) not in removed
+        ]
+
+    async def close(self) -> None:
+        for plugin in tuple(self._plugins.values()):
+            result = (plugin.shutdown or plugin.disable)()
+            if inspect.isawaitable(result):
+                await result
+        self._plugins.clear()
+        self._locks.clear()