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

ksadk/common/kop_client.py

@@ -19,6 +19,7 @@ from urllib.parse import urlsplit
 import requests
 
 from ksadk.common.auth import AWSV4Auth
+from ksadk.common.cloud_headers import build_cloud_headers
 
 logger = logging.getLogger(__name__)
 
@@ -152,7 +153,7 @@ class KOPClient:
             if action:
                 headers["X-Action"] = action
                 headers["X-Version"] = self.api_version
-        return headers
+        return build_cloud_headers(headers)
 
     def _build_url(self, action: str) -> str:
         if self._kop_mode:

ksadk/configs/env_registry.py

@@ -1,35 +1,68 @@
 from __future__ import annotations
 
+from ksadk.configs.env_registry_a2a import A2A_ENV_VAR_REGISTRY_ITEMS
 from ksadk.configs.env_registry_pcm import PCM_ENV_VAR_REGISTRY_ITEMS
-from ksadk.configs.env_var_spec import EnvVarSpec
 from ksadk.configs.env_registry_studio import STUDIO_ENV_VAR_REGISTRY_ITEMS
+from ksadk.configs.env_var_spec import EnvVarSpec
 
 _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec(
+        "KSADK_TRAFFIC_SOURCE",
+        "cloud",
+        "Cloud resource request X-Traffic-Source header.",
+        "agentkit",
+    ),
     *STUDIO_ENV_VAR_REGISTRY_ITEMS,
+    EnvVarSpec("KSADK_DB_CONNECT_SECONDS", "sessions", "Database connect budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_READ_ACQUIRE_SECONDS", "sessions", "Database read acquire budget in seconds.", ".3"),
+    EnvVarSpec("KSADK_DB_READ_SQL_SECONDS", "sessions", "Database read sql budget in seconds.", "1"),
+    EnvVarSpec("KSADK_DB_WRITE_ACQUIRE_SECONDS", "sessions", "Database write acquire budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_WRITE_SQL_SECONDS", "sessions", "Database write sql budget in seconds.", "3"),
+    EnvVarSpec("KSADK_DB_WRITE_OPERATION_SECONDS", "sessions", "Database write operation budget in seconds.", "5"),
+    EnvVarSpec("KSADK_DB_LOCK_SECONDS", "sessions", "Database lock budget in seconds.", ".5"),
+    EnvVarSpec("KSADK_DB_CLEANUP_SECONDS", "sessions", "Database cleanup budget in seconds.", "1"),
+    EnvVarSpec("KSADK_DB_REPLAY_OPERATION_SECONDS", "sessions", "Database replay operation budget in seconds.", "30"),
+    EnvVarSpec("KSADK_DB_REPLAY_SQL_SECONDS", "sessions", "Database replay sql budget in seconds.", "3"),
+    EnvVarSpec("KSADK_HISTORY_INITIAL_EVENTS", "sessions", "Initial history projection window (32–256 events).", "256"),
+    EnvVarSpec("KSADK_HISTORY_READ_CONCURRENCY", "sessions", "Concurrent PostgreSQL history transfers per process (1–32).", "4"),
     EnvVarSpec(
         "AGENTENGINE_CHANNEL_URL",
         "studio",
         "Channel service HTTPS base URL used by Studio and Channel Connector defaults.",
     ),
     EnvVarSpec(
-        "KSADK_MEMORY_POSTGRES_DSN", "memory", "Harness memory PostgreSQL DSN.",
-        sensitive=True, documented=False,
+        "KSADK_MEMORY_POSTGRES_DSN",
+        "memory",
+        "Harness memory PostgreSQL DSN.",
+        sensitive=True,
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_OTEL_ENDPOINT", "harness", "Optional Harness trace export endpoint.",
+        "KSADK_OTEL_ENDPOINT",
+        "harness",
+        "Optional Harness trace export endpoint.",
         documented=False,
     ),
     EnvVarSpec(
-        "KSADK_OTEL_SERVICE_NAME", "harness", "Harness trace service name.",
-        "ksadk-harness", documented=False,
+        "KSADK_OTEL_SERVICE_NAME",
+        "harness",
+        "Harness trace service name.",
+        "ksadk-harness",
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_SANDBOX_API_KEY", "sandbox", "Legacy Skill MCP forwarded sandbox credential.",
-        sensitive=True, documented=False,
+        "KSADK_SANDBOX_API_KEY",
+        "sandbox",
+        "Legacy Skill MCP forwarded sandbox credential.",
+        sensitive=True,
+        documented=False,
     ),
     EnvVarSpec(
-        "KSADK_SKILL_MANIFEST_TTL", "skills", "Skill manifest cache TTL in seconds.",
-        "60", documented=False,
+        "KSADK_SKILL_MANIFEST_TTL",
+        "skills",
+        "Skill manifest cache TTL in seconds.",
+        "60",
+        documented=False,
     ),
     EnvVarSpec(
         "KSADK_AGENT_EVAL",
@@ -44,122 +77,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     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",
-        "AgentEngine A2A runtime control-plane base URL injected by the deploy layer.",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_ENABLE_PUBLIC_EGRESS",
-        "a2a",
-        "Allow calling external (public-egress) agents in the A2A Space.",
-        "false when the deploy layer does not inject a value",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_EVENT_OUTBOX_PATH",
-        "a2a",
-        "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",
-        "Directory containing audience-specific projected A2A workload JWT files.",
-        "/var/run/secrets/agentengine/a2a",
-    ),
-    EnvVarSpec(
-        "KSADK_A2A_SERVICE_URL",
-        "a2a",
-        "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).",
-    ),
+    *A2A_ENV_VAR_REGISTRY_ITEMS,
     EnvVarSpec(
         "KSADK_EVAL_JUDGE_API_KEY",
         "eval",
@@ -402,6 +320,17 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "builders",
         "Internal bundled LangGraph PostgreSQL checkpointer requirement constant.",
     ),
+    EnvVarSpec(
+        "KSADK_LANGGRAPH_RECURSION_LIMIT",
+        "sessions",
+        (
+            "Fallback LangGraph recursion limit carried by the hosted runner when the "
+            "graph's own with_config does not set one. Must be explicit: astream_events "
+            "otherwise fills LangChain's default 25, which overrides the graph-level "
+            "setting on the streaming path."
+        ),
+        "50",
+    ),
     EnvVarSpec(
         "KSADK_LOCAL_PROCESS_ADDRESS_SPACE_BYTES",
         "skills",
@@ -545,6 +474,45 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "models",
         "Provider capability declaration file produced by the model matrix.",
     ),
+    EnvVarSpec(
+        "KSADK_MODEL_GATEWAY_METADATA_FILE",
+        "models",
+        "Platform-provided model metadata consumed before measured capability probes.",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_WIRE_API",
+        "models",
+        "Direct SDK model wire protocol: chat or responses.",
+        "chat",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_COMPAT_RULE",
+        "models",
+        "Explicit model endpoint compatibility profile override.",
+    ),
+    EnvVarSpec(
+        "KSADK_DELEGATION_DECISION_MAX_OUTPUT_TOKENS",
+        "harness",
+        "Maximum output-token budget for a delegation decision turn.",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_WARN_SECONDS",
+        "studio",
+        "Seconds without run progress before Studio emits a stall warning; <=0 disables it.",
+        "60",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_DUMP_SECONDS",
+        "studio",
+        "Seconds without run progress before Studio captures a diagnostic dump.",
+        "120",
+    ),
+    EnvVarSpec(
+        "KSADK_RUN_STALL_MAX_DUMPS",
+        "studio",
+        "Maximum diagnostic dumps retained for one continuously stalled run.",
+        "5",
+    ),
     EnvVarSpec(
         "KSADK_MODEL_PROXY_AGENTS",
         "model_proxy",
@@ -960,7 +928,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_WEB_VERSION",
         "web",
         "Published KsADK Web npm version used for a reproducible wheel build.",
-        "0.3.10",
+        "0.3.13",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",
@@ -1068,6 +1036,17 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Maximum spans exported per OTLP batch to avoid oversized collector requests.",
         "64",
     ),
+    EnvVarSpec(
+        "KSADK_HARNESS_SPEC",
+        "harness",
+        "Path to the HarnessSpec JSON consumed by `python -m ksadk.harness.rpc`.",
+    ),
+    EnvVarSpec(
+        "KSADK_MODEL_REQUEST_IDLE_TIMEOUT_SECONDS",
+        "studio",
+        "Idle timeout in seconds for a single managed model request before failover.",
+        "60",
+    ),
 )
 
 ENV_VAR_REGISTRY: tuple[EnvVarSpec, ...] = tuple(

ksadk/configs/env_registry_a2a.py

@@ -0,0 +1,173 @@
+"""A2A environment variable contracts consumed by the canonical registry."""
+
+from __future__ import annotations
+
+from ksadk.configs.env_var_spec import EnvVarSpec
+
+A2A_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
+    EnvVarSpec(
+        "KSADK_A2A_API_KEY",
+        "a2a",
+        "Product API Key used only by product_key_http_client when api_key is omitted; "
+        "never inherits unrelated service credentials.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_ID",
+        "a2a",
+        "Managed Runtime target Agent id (ar-*); required for the fail-closed "
+        "A2A data-plane composition.",
+    ),
+    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 injected before registration for discovery.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED",
+        "a2a",
+        "Platform-owned marker enabling the complete managed A2A composition.",
+        "false",
+    ),
+    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",
+        "AgentEngine A2A runtime control-plane base URL injected by the deploy layer.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_CONTROL_PLANE_CA_FILE",
+        "a2a",
+        "Platform-projected CA bundle used only for managed A2A control-plane HTTPS.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_GATEWAY_CA_FILE",
+        "a2a",
+        "Optional Gateway CA file added to public trust roots for managed A2A HTTPS.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_ENABLE_PUBLIC_EGRESS",
+        "a2a",
+        "Allow calling external (public-egress) agents in the A2A Space.",
+        "false when the deploy layer does not inject a value",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_EVENT_OUTBOX_PATH",
+        "a2a",
+        "SQLite path for local-only A2A task-event delivery batches; forbidden in managed Runtime.",
+        ".agentengine/a2a_event_outbox.sqlite3",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_INBOUND_ENABLED",
+        "a2a",
+        "Enable managed inbound A2A serving; false configures a caller-only Runtime.",
+        "true",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_PUBLIC_TOOL_POLICY_FILE",
+        "a2a",
+        "Projected JSON file containing the public tool activity disclosure policy.",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_DATABASE_DSN",
+        "a2a",
+        "PostgreSQL DSN projected from the AgentKernel store SecretKeyRef.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_GATEWAY_PUBLIC_KEY_FILE",
+        "a2a",
+        "Projected file locator containing the Gateway forward-assertion public key.",
+        sensitive=True,
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_AGENT_REGISTRATION_ID",
+        "a2a",
+        "Opaque registered a2a-agent-* target identity injected by the deploy layer.",
+    ),
+    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",
+        "Directory containing audience-specific projected A2A workload JWT files.",
+        "/var/run/secrets/agentengine/a2a",
+    ),
+    EnvVarSpec(
+        "KSADK_A2A_SERVICE_URL",
+        "a2a",
+        "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).",
+    ),
+)

ksadk/configs/env_registry_studio.py

@@ -23,7 +23,8 @@ STUDIO_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_STUDIO_LAZY_START",
         "studio",
-        "Internal desktop startup mode; keep the Studio window responsive while optional DSH warmup runs.",
+        "Internal desktop startup mode; keep the Studio window responsive "
+        "while optional DSH warmup runs.",
         "0",
         documented=False,
     ),
@@ -36,9 +37,31 @@ STUDIO_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_STUDIO_TEAMS_DEFAULT",
         "studio",
-        "Default-enable the Teams plugin after HTTP startup (1=on, 0=off).",
+        "Default-enable Teams after HTTP startup; 0/false/no/off disables discovery.",
         "1",
-        documented=False,
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_NATIVE_DEFAULT", "studio",
+        "Local Studio Harness engine policy: 1 selects Native by default; 0 selects "
+        "the optional Managed compatibility host. Only exact 0/1 values are accepted.",
+        "1 for ordinary Studio; 0 with explicit Agent selection or injected legacy host",
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_NATIVE_AGENT_IDS", "studio",
+        "Comma-separated exact local Agent IDs selecting Native in compatibility mode; "
+        "presence disables the ordinary Native default when DEFAULT is unset.",
+    ),
+    EnvVarSpec(
+        "KSADK_STUDIO_NATIVE_DURABLE", "studio",
+        "Local Native ledger storage: 1 selects SQLite; 0 selects process memory. "
+        "Only exact 0/1 values are accepted; durability requires Native to be selected.",
+        "1 with the ordinary Native default; 0 with explicit compatibility selection",
+    ),
+    EnvVarSpec(
+        "KSADK_REASONING_ONLY_ACTION_BUDGET_CHARS", "studio",
+        "Maximum streamed reasoning characters before action in a tool-capable "
+        "Studio provider turn; clamped to 1024..65536, invalid values use the default.",
+        "8192",
     ),
     EnvVarSpec(
         "KSADK_STUDIO_NO_SECURITY",
@@ -72,7 +95,8 @@ STUDIO_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     ),
     EnvVarSpec(
         "KSADK_TEAMS_ACCESS_TOKEN", "studio",
-        "Bearer credential for the configured Teams authority; unset uses configured request signing.",
+        "Bearer credential for the configured Teams authority; "
+        "unset uses configured request signing.",
         sensitive=True,
     ),
     EnvVarSpec(
@@ -80,7 +104,31 @@ STUDIO_ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "local",
     ),
     EnvVarSpec(
-        "KSADK_TEAMS_NODE_NAME", "studio", "Execution node display name sent to the Teams authority.",
+        "KSADK_TEAMS_NODE_NAME", "studio",
+        "Execution node display name sent to the Teams authority.",
         "system hostname",
     ),
+    EnvVarSpec(
+        "KSADK_TEAMS_PERMIT_ISSUER", "studio",
+        "Trusted Teams permit issuer; Studio defaults to agentengine-server; "
+        "cloud hosts require it.",
+        "agentengine-server (Studio only)",
+    ),
+    EnvVarSpec(
+        "KSADK_TEAMS_RUNTIME_SERVER_URL", "studio",
+        "Trusted Teams API base URL supplied to the cloud runtime host.",
+    ),
+    EnvVarSpec(
+        "KSADK_TEAMS_RUNTIME_TARGET", "studio",
+        "Frozen CloudTarget JSON supplied by the deployment control plane.",
+    ),
+    EnvVarSpec(
+        "KSADK_TEAMS_RUNTIME_PROVIDER_REF", "studio",
+        "Provider identity bound to the cloud runtime host's frozen target.",
+    ),
+    EnvVarSpec(
+        "KSADK_TEAMS_RUNTIME_STATE_DIR", "studio",
+        "Per-attempt workspace directory; authoritative execution state remains in PostgreSQL.",
+        "/tmp/ksadk-teams",
+    ),
 )

ksadk/configs/global_config.py

@@ -35,6 +35,7 @@ CONFIG_GROUPS = {
         "OPENAI_MODEL_NAME",
     ],
     "cloud": [
+        "KSADK_TRAFFIC_SOURCE",
         "KSYUN_ACCESS_KEY",
         "KSYUN_SECRET_KEY",
         "KSYUN_ACCOUNT_ID",

ksadk/configs/settings.py

@@ -386,6 +386,12 @@ class KingsoftCloudConfig:
         KS_REGION            - 区域 (默认 cn-beijing-6)
     """
 
+    @property
+    def traffic_source(self) -> str:
+        from ksadk.common.cloud_headers import resolve_traffic_source
+
+        return resolve_traffic_source()
+
     @property
     def access_key_id(self) -> Optional[str]:
         return os.getenv("KS_ACCESS_KEY_ID")

ksadk/context_engine/assembler.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any, Literal
 
+from ksadk.context_engine.instruction_authority import validate_instruction_authority
 from ksadk.context_engine.models import ContextItem, ContextPlan
 
 ProjectionFormat = Literal["chat", "responses"]
@@ -52,6 +53,9 @@ def _split_prompt_and_rest(selected: list[ContextItem]) -> tuple[str, list[Conte
     prompt_text = ""
     rest: list[ContextItem] = []
     for item in selected:
+        validate_instruction_authority(
+            kind=item.kind, trust_level=item.trust_level, metadata=item.metadata
+        )
         if item.kind == "compiled_prompt":
             prompt_text = (
                 (prompt_text + "\n\n" + _item_text(item)).strip("\n\n")
@@ -74,6 +78,11 @@ def _role_for(item: ContextItem) -> str:
         return "assistant"
     if item.kind == "tool_result":
         return "tool"
+    # 其他 kind（如 ContextSection 的 resource_manifest）可显式声明投影
+    # 角色：trust="system" 的段应进 system 层，而非被当作 assistant 文本。
+    role = item.metadata.get("role")
+    if isinstance(role, str):
+        return role
     return "assistant"