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

ksadk/common/kop_client.py

@@ -0,0 +1,232 @@
+"""KOP (Kingsoft Open Protocol) client — 公共 AICP 控制面调用层。
+
+skill / a2a / mcp 等运行时模块通过本层访问 agentengine-server 对外 Action
+（KOP 协议：`{base}/?Action=xxx&Version=xxx` + AWS V4 签名），避免每个模块
+各自实现一遍鉴权 + URL 构造 + header 装配。
+
+本层是同步（基于 requests + requests-aws4auth）；async 调用方用
+``asyncio.to_thread`` 包裹。AICP 控制面是低频调用，同步足够。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any, Mapping, Optional
+from urllib.parse import urlsplit
+
+import requests
+
+from ksadk.common.auth import AWSV4Auth
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_API_VERSION = "2024-06-12"
+DEFAULT_REGION = "cn-beijing-6"
+DEFAULT_SERVICE = "aicp"
+
+# 精确匹配 AICP 控制面域名（公网 + 内网 + internal），不接受用户自定义 URL 走签名。
+_AICP_HOSTS = {
+    "aicp.api.ksyun.com",
+    "aicp.inner.api.ksyun.com",
+    "aicp.internal.api.ksyun.com",
+}
+
+
+def is_kop_endpoint(base_url: str) -> bool:
+    """Return True only for exact AICP control-plane hosts.
+
+    User-controlled URLs must never receive KOP signing headers.
+    """
+    host = (urlsplit(base_url or "").hostname or "").lower()
+    return host in _AICP_HOSTS
+
+
+class KOPError(RuntimeError):
+    """KOP action 失败（非 2xx 或 Code != 0/200）。"""
+
+    def __init__(self, *, code: int, message: str, request_id: str = "", action: str = "") -> None:
+        super().__init__(f"KOP {action} failed: code={code} message={message}")
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.action = action
+
+
+class KOPClient:
+    """AICP KOP 控制面调用客户端。
+
+    凭证优先级：构造参数 > KSADK_*_ACCESS_KEY/SECRET_KEY > KSYUN_ACCESS_KEY/SECRET_KEY。
+    base_url 为空时按 region 探测默认 AICP（inner 优先,回落 public）。
+    非 AICP base_url（如本地 server 直连）走普通 POST，不签名。
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: Optional[str] = None,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        region: Optional[str] = None,
+        service: Optional[str] = None,
+        api_version: Optional[str] = None,
+        account_id: Optional[str] = None,
+        service_token: Optional[str] = None,
+        timeout: float = 15.0,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("KSADK_A2A_SERVICE_URL") or "").strip().rstrip("/")
+        if not self.base_url:
+            inner = os.getenv("KSADK_A2A_SERVICE_ENDPOINT", "").strip()
+            if inner:
+                scheme = os.getenv("KSADK_A2A_SERVICE_SCHEME", "https").strip() or "https"
+                self.base_url = f"{scheme}://{inner}".rstrip("/")
+        if not self.base_url:
+            # 默认探测：内网 inner 优先（runtime 在集群内），回落公网 public。
+            self.base_url = self._detect_default_base_url()
+        self.region = (
+            region
+            or os.getenv("KSADK_A2A_SERVICE_REGION")
+            or os.getenv("KSYUN_REGION")
+            or DEFAULT_REGION
+        ).strip()
+        self.service = (service or DEFAULT_SERVICE).strip()
+        self.api_version = (api_version or DEFAULT_API_VERSION).strip()
+        self.account_id = (
+            account_id
+            or os.getenv("KSADK_A2A_ACCOUNT_ID")
+            or os.getenv("KSYUN_ACCOUNT_ID")
+            or ""
+        ).strip()
+        self.service_token = (
+            service_token or os.getenv("KSADK_A2A_SERVICE_TOKEN") or ""
+        ).strip()
+        self.timeout = timeout
+        self._kop_mode = is_kop_endpoint(self.base_url)
+        ak = (
+            access_key
+            or os.getenv("KSADK_A2A_ACCESS_KEY")
+            or os.getenv("KSYUN_ACCESS_KEY")
+            or ""
+        ).strip()
+        sk = (
+            secret_key
+            or os.getenv("KSADK_A2A_SECRET_KEY")
+            or os.getenv("KSYUN_SECRET_KEY")
+            or ""
+        ).strip()
+        self._auth = AWSV4Auth(
+            access_key_id=ak,
+            secret_access_key=sk,
+            region=self.region,
+            service=self.service,
+        )
+        self._session: Optional[requests.Session] = None
+
+    @property
+    def is_kop_mode(self) -> bool:
+        return self._kop_mode
+
+    def _session_obj(self) -> requests.Session:
+        if self._session is None:
+            self._session = requests.Session()
+        return self._session
+
+    def _headers(self, action: str) -> dict[str, str]:
+        import uuid
+
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.account_id:
+            headers["X-Ksc-Account-Id"] = self.account_id
+        if self.service_token:
+            headers["Authorization"] = f"Bearer {self.service_token}"
+        if self._kop_mode:
+            headers["Host"] = urlsplit(self.base_url).netloc
+            headers["X-Ksc-Request-Id"] = str(uuid.uuid4())
+            headers["X-Ksc-Region"] = self.region
+            headers["X-Ksc-Source"] = "ksadk-runtime"
+            # 预发环境路由：AICP 据此把请求转发到预发 server（线上 KOP 默认路由到线上 server）。
+            logical_region = (os.getenv("KSYUN_REGION") or "").strip().lower()
+            if logical_region == "pre-online":
+                headers["X-KSC-CUSTOM-SOURCE"] = os.getenv("AGENTENGINE_PRE_CUSTOM_SOURCE", "pre")
+            if action:
+                headers["X-Action"] = action
+                headers["X-Version"] = self.api_version
+        return headers
+
+    def _build_url(self, action: str) -> str:
+        if self._kop_mode:
+            return f"{self.base_url}/?Action={action}&Version={self.api_version}"
+        return f"{self.base_url}/agentengine/api/v1/{action}"
+
+    def post_action(
+        self, action: str, payload: Optional[Mapping[str, Any]] = None
+    ) -> dict[str, Any]:
+        """POST 一个 KOP Action，返回 Data 字段（已解包信封）。
+
+        非KOP 模式走 ``/agentengine/api/v1/{action}``；KOP 模式走 ``?Action=&Version=`` + 签名。
+        """
+        url = self._build_url(action)
+        headers = self._headers(action)
+        body = json.dumps(dict(payload or {}), ensure_ascii=False)
+        auth = (
+            self._auth.get_auth()
+            if self._kop_mode and self._auth.is_enabled and not self.service_token
+            else None
+        )
+        try:
+            response = self._session_obj().post(
+                url,
+                data=body.encode("utf-8"),
+                headers=headers,
+                auth=auth,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise KOPError(
+                code=503,
+                message=f"KOP control plane unavailable: {exc}",
+                action=action,
+            ) from exc
+        if not 200 <= response.status_code < 300:
+            raise KOPError(
+                code=response.status_code,
+                message=f"KOP HTTP error: {response.text[:200]}",
+                action=action,
+            )
+        try:
+            envelope = response.json()
+        except ValueError as exc:
+            raise KOPError(
+                code=response.status_code or 502,
+                message="non-JSON response",
+                action=action,
+            ) from exc
+        if not isinstance(envelope, dict):
+            raise KOPError(
+                code=response.status_code or 502,
+                message="response not an object",
+                action=action,
+            )
+        code = int(envelope.get("Code") or 0)
+        if code and code != 200:
+            raise KOPError(
+                code=code,
+                message=str(envelope.get("Message") or "KOP error"),
+                request_id=str(envelope.get("RequestId") or ""),
+                action=action,
+            )
+        data = envelope.get("Data")
+        return data if isinstance(data, dict) else {}
+
+    def _detect_default_base_url(self) -> str:
+        """默认 AICP 地址探测：内网 inner 优先，失败回落公网 public。"""
+        inner = "http://aicp.inner.api.ksyun.com"
+        public = "https://aicp.api.ksyun.com"
+        try:
+            import socket
+            host = urlsplit(inner).hostname or ""
+            socket.create_connection((host, 80), timeout=1).close()
+            return inner
+        except OSError:
+            return public

ksadk/configs/__init__.py

@@ -8,7 +8,7 @@ AgentEngine 统一配置管理
 
 环境变量优先级 (举例):
     Model:    OPENAI_API_KEY > LLM_API_KEY > MODEL_API_KEY
-    Langfuse: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST
+    Tracing:  OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS
     Agent:    AGENT_ID > AGENT_RUNTIME_ID
 
 默认值:
@@ -24,7 +24,6 @@ from ksadk.configs.settings import (
     AgentConfig,
     CodeModeConfig,
     KingsoftCloudConfig,
-    LangfuseConfig,
     # 各配置类
     ModelConfig,
     OTelConfig,
@@ -44,7 +43,6 @@ __all__ = [
     "Settings",
     # 配置类
     "ModelConfig",
-    "LangfuseConfig",
     "AgentConfig",
     "KingsoftCloudConfig",
     "CodeModeConfig",

ksadk/configs/env_registry.py

@@ -1,24 +1,51 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
-
-
-@dataclass(frozen=True)
-class EnvVarSpec:
-    name: str
-    module: str
-    purpose: str
-    default: str = ""
-    sensitive: bool = False
-
+from ksadk.configs.env_registry_pcm import PCM_ENV_VAR_REGISTRY_ITEMS
+from ksadk.configs.env_var_spec import EnvVarSpec
 
 _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec(
+        "KSADK_AGENT_EVAL",
+        "evaluation",
+        "Enable internal Agent evaluation integration.",
+        "0",
+        documented=False,
+    ),
     EnvVarSpec("KSADK_ADK_RESUMABLE", "runners", "Enable ADK invocation resume support.", "false"),
     EnvVarSpec("KSADK_ADK_SESSION_BACKEND", "sessions", "ADK-native session backend selector."),
     EnvVarSpec("KSADK_ADK_SESSION_PATH", "sessions", "ADK-native SQLite session database path."),
     EnvVarSpec(
         "KSADK_ADK_SESSION_URL", "sessions", "ADK-native database session URL.", sensitive=True
     ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_ID",
+        "a2a",
+        "Opaque registered A2A Agent id injected post-registration; "
+        "required to wire full inbound JSON-RPC in v2. v1 discovery-only card "
+        "does not depend on it.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ACCOUNT_ID",
+        "a2a",
+        "Runtime owner account id injected by the deploy layer (ar-* agent's account).",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_RUNTIME_ID",
+        "a2a",
+        "Hosted Agent runtime resource id (ar-*) injected by the deploy layer; "
+        "the v1 discovery-only card mounts whenever this is non-empty.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_NAME",
+        "a2a",
+        "AgentCard display name injected by the deploy layer; falls back to "
+        "AGENTENGINE_MANAGED_RUNTIME_NAME then to the agent id.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_VERSION",
+        "a2a",
+        "AgentCard business version injected by the deploy layer; defaults to 0.1.0.",
+    ),
     EnvVarSpec(
         "KSADK_A2A_CONTROL_PLANE_URL",
         "a2a",
@@ -36,6 +63,27 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "SQLite path for durable A2A task-event delivery batches.",
         ".agentengine/a2a_event_outbox.sqlite3",
     ),
+    EnvVarSpec(
+        "KSADK_A2A_INTERNAL_BASE_URL",
+        "a2a",
+        "Internal HTTP(S) origin used as AgentCard base_url before the gateway rewrites it; "
+        "must be an absolute origin with no path/query/fragment.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SPACE_ID",
+        "a2a",
+        "Primary A2A Space id configured for this Runtime Agent.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SPACE_IDS",
+        "a2a",
+        "Compatibility JSON array of A2A Space ids configured for this Runtime Agent.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_TENANT_ID",
+        "a2a",
+        "Runtime tenant id injected by the deploy layer; falls back to account id.",
+    ),
     EnvVarSpec(
         "KSADK_A2A_TOKEN_DIR",
         "a2a",
@@ -43,9 +91,53 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "/var/run/secrets/agentengine/a2a",
     ),
     EnvVarSpec(
-        "KSADK_A2A_SPACE_IDS",
+        "KSADK_A2A_SERVICE_URL",
         "a2a",
-        "JSON array of A2A Space ids configured for this Runtime Agent.",
+        "A2A control plane service URL (KOP public API); auto-detected if unset.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_TOKEN",
+        "a2a",
+        "Bearer token for A2A control plane service authentication.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_ENDPOINT",
+        "a2a",
+        "A2A service endpoint hostname (used for auto-detection with scheme).",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_SCHEME",
+        "a2a",
+        "A2A service URL scheme (http/https) for auto-detection.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_REGION",
+        "a2a",
+        "A2A service region for KOP signing.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ACCESS_KEY",
+        "a2a",
+        "A2A KOP access key for signing; falls back to KSYUN_ACCESS_KEY.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SECRET_KEY",
+        "a2a",
+        "A2A KOP secret key for signing; falls back to KSYUN_SECRET_KEY.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE",
+        "a2a",
+        "A2A KOP signing service name (default: aicp).",
+    ),
+    EnvVarSpec(
+        "KSADK_EVAL_JUDGE_API_KEY",
+        "eval",
+        "API key for the LLM Judge evaluation backend.",
+        sensitive=True,
     ),
     EnvVarSpec(
         "KSADK_A2UI_GENERATION_TIMEOUT_SECONDS",
@@ -117,6 +209,55 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Codex proxy override: 1 forces the local Responses-to-Chat proxy and "
         "0 forces direct mode.",
     ),
+    EnvVarSpec(
+        "KSADK_CODEX_SANDBOX",
+        "codex",
+        "Codex sandbox mode: read_only (default, no writes) / workspace_write "
+        "(write inside workspace) / full_access (write anywhere).",
+    ),
+    EnvVarSpec(
+        "KSADK_CODEX_APPROVAL",
+        "codex",
+        "Codex approval mode: deny_all (default for read_only) / auto_review "
+        "(auto-approve with review log).",
+    ),
+    EnvVarSpec(
+        "KSADK_CODEX_HOME",
+        "codex",
+        "Explicit Codex home directory override for the native runtime.",
+    ),
+    EnvVarSpec(
+        "KSADK_CODEX_ISOLATE_HOME",
+        "codex",
+        "Isolate native Codex state under the project workspace; set to 0 for debugging only.",
+        "1",
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_NO_SECURITY",
+        "studio",
+        "Disable Studio loopback session and CSRF checks for controlled tests only.",
+        "0",
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_AUTHORIZER",
+        "studio",
+        "Internal authoring backend selector; bounded chat is the default and the "
+        "filesystem-capable Codex authorizer requires an explicit opt-in.",
+        "chat",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_SESSION_TOKEN",
+        "studio",
+        "Explicit local Studio browser session token; generated randomly when unset.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_TRACE_CONTENT",
+        "studio",
+        "Persist Studio trace event content; set to 0 to retain metadata only.",
+        "1",
+    ),
     EnvVarSpec(
         "KSADK_COMMAND_", "sandbox", "Internal prefix for command policy environment controls."
     ),
@@ -143,6 +284,19 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Enable L2 snip deterministic redundancy removal in compaction pipeline.",
         "true",
     ),
+    *PCM_ENV_VAR_REGISTRY_ITEMS,
+    EnvVarSpec(
+        "KSADK_DEPLOYMENT_MODE",
+        "runtime",
+        "Deployment-mode ownership declaration.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_EVAL_COMMIT",
+        "evaluation",
+        "Source commit recorded by evaluation runs.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_CORE_RUNTIME_REQUIREMENTS",
         "builders",
@@ -186,6 +340,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_KB_SECRET_KEY", "knowledge_base", "Knowledge-base API secret key.", sensitive=True
     ),
+    EnvVarSpec(
+        "KSADK_KB_SESSION_TOKEN",
+        "knowledge_base",
+        "Knowledge-base STS session token.",
+        sensitive=True,
+    ),
     EnvVarSpec("KSADK_KB_TOP_K", "knowledge_base", "Knowledge-base retrieval result count.", "5"),
     EnvVarSpec(
         "KSADK_LANGGRAPH_CHECKPOINT_DSN",
@@ -193,6 +353,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "LangGraph PostgreSQL checkpoint DSN.",
         sensitive=True,
     ),
+    EnvVarSpec(
+        "KSADK_LANGGRAPH_AUTO_CHECKPOINT",
+        "sessions",
+        "Allow a hosted LangGraph runner to rebuild a factory-exported graph with the managed PostgreSQL saver.",
+        "false",
+    ),
     EnvVarSpec(
         "KSADK_LOCAL_SKILLS_DIR", "skills", "Local directory containing extracted Skill packages."
     ),
@@ -224,6 +390,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_LTM_SECRET_KEY", "memory", "Long-term-memory API secret key.", sensitive=True
     ),
+    EnvVarSpec(
+        "KSADK_LTM_SESSION_TOKEN",
+        "memory",
+        "Long-term-memory STS session token.",
+        sensitive=True,
+    ),
     EnvVarSpec("KSADK_LTM_TOP_K", "memory", "Long-term-memory retrieval result count.", "5"),
     EnvVarSpec(
         "KSADK_MCP_RUNTIME_REQUIREMENTS",
@@ -306,12 +478,30 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "runners",
         "Header name for remote Responses session propagation.",
     ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_IMAGE_SOURCE_COMMIT",
+        "runtime",
+        "Build-injected source commit for Runtime image provenance.",
+        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_IMAGE_WHEEL_SHA256",
+        "runtime",
+        "Build-injected wheel digest for Runtime image provenance.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_RUNTIME_PORT", "cli", "Runtime HTTP port exported to template runtimes.", "8080"
     ),
     EnvVarSpec(
         "KSADK_RUNTIME_REQUIREMENTS", "builders", "Internal bundled runtime requirements constant."
     ),
+    EnvVarSpec(
+        "KSADK_RUNTIME_STATE_DIR",
+        "runtime",
+        "Internal Runtime state directory override.",
+        documented=False,
+    ),
     EnvVarSpec(
         "KSADK_ALLOW_POD_PROCESS_TOOLS",
         "sandbox",
@@ -442,6 +632,17 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_SESSION_DSN", "sessions", "Conversation session database DSN.", sensitive=True
     ),
     EnvVarSpec("KSADK_SESSION_NAMESPACE", "sessions", "Conversation session namespace."),
+    EnvVarSpec(
+        "KSADK_AGENT_ID",
+        "platform",
+        "Stable AgentEngine agent identity used only as a fallback checkpoint namespace.",
+    ),
+    EnvVarSpec(
+        "KSADK_AGENT_KERNEL",
+        "kernel",
+        "Opt in to Agent Kernel ingress locally; managed deployment may use AGENT_KERNEL_ENABLED instead.",
+        "false",
+    ),
     EnvVarSpec("KSADK_SESSION_PATH", "sessions", "Conversation local SQLite database path."),
     EnvVarSpec(
         "KSADK_SESSION_PG_CONNECT_TIMEOUT",
@@ -609,7 +810,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_WEB_VERSION",
         "web",
         "Published KsADK Web npm version used for a reproducible wheel build.",
-        "0.3.0",
+        "0.3.2",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",
@@ -629,38 +830,11 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "CLOUD_MONITOR_APP_KEY",
         "tracing",
-        "CloudMonitor AppKey for optional OTLP ingestion.",
+        "Deprecated: CloudMonitor AppKey translated to Ksc-Appkey OTLP header only when "
+        "both CLOUD_MONITOR_OTLP_TRACES_HEADERS and CLOUD_MONITOR_OTLP_HEADERS are absent. "
+        "Server should inject OTLP headers directly.",
         sensitive=True,
     ),
-    EnvVarSpec(
-        "CLOUD_MONITOR_LANGFUSE_ENABLED",
-        "tracing",
-        "Enable or disable the CloudMonitor Langfuse SDK callback; defaults to enabled "
-        "when keys and host are present.",
-    ),
-    EnvVarSpec(
-        "CLOUD_MONITOR_LANGFUSE_HOST",
-        "tracing",
-        "CloudMonitor AppMonitor Langfuse SDK host.",
-    ),
-    EnvVarSpec(
-        "CLOUD_MONITOR_LANGFUSE_PUBLIC_KEY",
-        "tracing",
-        "CloudMonitor AppMonitor Langfuse public key returned by the platform.",
-        sensitive=True,
-    ),
-    EnvVarSpec(
-        "CLOUD_MONITOR_LANGFUSE_SECRET_KEY",
-        "tracing",
-        "CloudMonitor AppMonitor Langfuse secret key returned by the platform.",
-        sensitive=True,
-    ),
-    EnvVarSpec(
-        "CLOUD_MONITOR_OTLP_ENABLED",
-        "tracing",
-        "Enable or disable the CloudMonitor OTLP exporter; defaults to enabled when "
-        "endpoint and AppKey are present.",
-    ),
     EnvVarSpec(
         "CLOUD_MONITOR_OTLP_ENDPOINT",
         "tracing",
@@ -670,7 +844,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "CLOUD_MONITOR_OTLP_HEADERS",
         "tracing",
-        "Additional CloudMonitor OTLP HTTP headers, comma-separated and URL-encoded.",
+        "CloudMonitor OTLP HTTP headers including Ksc-Appkey, comma-separated and URL-encoded.",
         sensitive=True,
     ),
     EnvVarSpec(
@@ -683,6 +857,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "tracing",
         "CloudMonitor OTLP HTTP traces endpoint; takes precedence over the generic endpoint.",
     ),
+    EnvVarSpec(
+        "CLOUD_MONITOR_OTLP_TRACES_HEADERS",
+        "tracing",
+        "CloudMonitor OTLP HTTP traces headers; takes precedence over generic headers.",
+        sensitive=True,
+    ),
     EnvVarSpec(
         "CLOUD_MONITOR_OTLP_TRACES_PROTOCOL",
         "tracing",
@@ -726,6 +906,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "OpenTelemetry resource attributes in key=value comma-separated form.",
     ),
     EnvVarSpec("OTEL_SERVICE_NAME", "tracing", "OpenTelemetry service name."),
+    EnvVarSpec(
+        "OPENCLAW_CONFIG_PATCH_JSON",
+        "openclaw",
+        "OpenClaw configuration patch JSON supplied at deployment time.",
+        sensitive=True,
+    ),
     EnvVarSpec(
         "KSADK_OTLP_MAX_EXPORT_BATCH_SIZE",
         "tracing",
@@ -737,6 +923,19 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
 ENV_VAR_REGISTRY: tuple[EnvVarSpec, ...] = tuple(
     sorted(_ENV_VAR_REGISTRY_ITEMS, key=lambda spec: spec.name)
 )
+_ENV_SENSITIVITY_BY_NAME = {spec.name: spec.sensitive for spec in ENV_VAR_REGISTRY}
+
+
+def is_sensitive_env_var(name: str) -> bool:
+    normalized = str(name or "").strip().upper()
+    if _ENV_SENSITIVITY_BY_NAME.get(normalized, False):
+        return True
+    if normalized.startswith("OTEL_EXPORTER_OTLP_") and normalized.endswith("_HEADERS"):
+        return True
+    return any(
+        token in normalized
+        for token in ("KEY", "TOKEN", "SECRET", "PASSWORD", "AUTHORIZATION", "SIGNATURE")
+    )
 
 
 def iter_env_vars() -> tuple[EnvVarSpec, ...]: