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

ksadk/kernel/bootstrap.py

@@ -39,7 +39,7 @@ from ksadk.kernel.contract_fingerprints import (
 )
 from ksadk.kernel.contracts import RuntimeCapabilityMatrix
 from ksadk.kernel.control import AgentKernel, default_capability_matrix
-from ksadk.kernel.errors import InvalidCommandError
+from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
 from ksadk.kernel.recovery import RecoveryCoordinator
 from ksadk.kernel.runtime_identity import runtime_identity
 from ksadk.kernel.store import AgentKernelStore, now_utc
@@ -465,8 +465,25 @@ class AgentKernelRuntime:
                             lease,
                             session_id=session_id,
                         )
-                        if result.outcome != "idle":
+                        if result.outcome in {"claimed", "completed"}:
                             progressed = True
+                        elif result.outcome == "terminal_failure":
+                            if isinstance(result.error, StaleFenceError):
+                                # 当前 activation 已失去 fence，不能继续触碰该
+                                # session，也不应把正常 takeover 误判为坏数据。
+                                self._heartbeat_sessions.discard(session_id)
+                                self._last_renewed.pop(session_id, None)
+                                self.lease_heartbeat.forget(session_id)
+                                continue
+                            failure = result.error or RuntimeError(
+                                "agent kernel command failed without an error detail"
+                            )
+                            if not await self._quarantine_session(
+                                session_id,
+                                failure,
+                                context="command execution",
+                            ):
+                                return
                     self._store_failures = 0
                 except asyncio.CancelledError:
                     raise
@@ -609,7 +626,13 @@ class AgentKernelRuntime:
             return False
         return True
 
-    async def _quarantine_session(self, session_id: str, exc: Exception) -> bool:
+    async def _quarantine_session(
+        self,
+        session_id: str,
+        exc: Exception,
+        *,
+        context: str = "takeover recovery",
+    ) -> bool:
         """隔离一个恢复失败的 session；返回 False 表示已触发进程级降级。
 
         被隔离的 session 不再被本 runtime claim / 恢复 / 续约，其 inbox
@@ -631,9 +654,10 @@ class AgentKernelRuntime:
         self._last_renewed.pop(session_id, None)
         self.lease_heartbeat.forget(session_id)
         logger.warning(
-            "agent kernel session %s quarantined after takeover recovery "
+            "agent kernel session %s quarantined after %s "
             "failed: agent_instance_id=%s error=%s: %s",
             session_id,
+            context,
             self.config.agent_instance_id,
             type(exc).__name__,
             exc,

ksadk/kernel/contract_fingerprints.py

@@ -15,7 +15,7 @@ from typing import Any
 
 AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
 AGENT_KERNEL_V1_AGGREGATE_DIGEST = (
-    "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
+    "b610a25aae957306b9f84a2cc2c948b30d1ce6218585cfd2a91f96736b92d102"
 )
 
 
@@ -23,12 +23,13 @@ def runtime_capability_matrix_wire_value(matrix: Any) -> dict[str, Any]:
     """Serialize the additive matrix without materializing absent v2 modes.
 
     Pydantic includes optional ``None`` defaults in ``model_dump``.  Omitting
-    those three top-level keys preserves the exact pre-extension wire value and
-    capability digest for runtimes that do not publish goal/loop/plan.
+    those additive top-level keys preserves the exact pre-extension wire value
+    and capability digest for runtimes that do not publish execution controls
+    or an interaction delivery mode.
     """
 
     dump = matrix.model_dump(mode="json")
-    for key in ("goal", "loop", "plan"):
+    for key in ("interaction_mode", "goal", "loop", "plan"):
         if dump.get(key) is None:
             dump.pop(key, None)
     return dump

ksadk/kernel/contracts.py

@@ -309,6 +309,14 @@ class RuntimeCapabilityMatrix(WireModel):
     inject: RuntimeCapability
     checkpoint: RuntimeCapability
     durable_restore: RuntimeCapability
+    # Interaction delivery is deliberately separate from the verb matrix:
+    # ``submit_interaction`` alone does not tell a caller whether the reply
+    # reaches a live process, resumes a checkpoint, or has no native route.
+    # It remains optional so a v1 consumer can read records emitted before
+    # this additive declaration without inventing support.
+    interaction_mode: Literal[
+        "live_submit", "durable_resume", "unavailable"
+    ] | None = None
     # Runtime v2 execution controls are additive optional capabilities. Older
     # runtimes omit them; a runtime must never infer support from UI presence.
     # ``loop`` specifically means an externally bounded, eval-driven

ksadk/kernel/control.py

@@ -57,6 +57,7 @@ def default_capability_matrix() -> RuntimeCapabilityMatrix:
         inject=_unavailable("runtime_no_native_inject"),
         checkpoint=_unavailable(),
         durable_restore=_unavailable(),
+        interaction_mode="unavailable",
     )
 
 

ksadk/kernel/ingress.py

@@ -94,9 +94,22 @@ def get_agent_kernel() -> Any | None:
 
 
 def kernel_route_active() -> bool:
-    """当前请求是否走 kernel ingress（开关开 且 kernel 已注册）。"""
+    """Whether public compatibility routes may self-admit through the kernel.
+
+    A hosted Runtime accepts AgentControl commands only with a permit issued by
+    Server.  The public ``/v1/responses`` / legacy ``RunAgent`` routes do not
+    carry that permit, so routing them through ``trusted_context`` would create
+    a process-local signature that the hosted verifier must reject.  Keep those
+    authenticated compatibility routes on their established executor path;
+    Server continues to use the dedicated ``/agent-kernel/v1/*`` ingress, which
+    validates the Server-issued permit independently of this selector.
+    """
 
-    return kernel_ingress_enabled() and get_agent_kernel() is not None
+    return (
+        kernel_ingress_enabled()
+        and get_agent_kernel() is not None
+        and authority_mode() != _AUTHORITY_HOSTED
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -421,6 +434,26 @@ def map_studio_request(
     )
 
 
+def map_scheduler_request(
+    *,
+    session_id: str,
+    idempotency_key: str,
+    content: Any,
+    occurrence_id: str,
+    trusted: TrustedRuntimeContext,
+) -> AgentControlCommand:
+    """Scheduler occurrence -> enqueue with durable source and correlation IDs."""
+
+    return _command(
+        trusted=trusted,
+        command_type="enqueue",
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        payload={"content": content},
+        correlation_id=occurrence_id,
+    )
+
+
 def map_control_request(
     *,
     command_type: str,
@@ -1091,6 +1124,7 @@ __all__ = [
     "map_control_request",
     "map_responses_request",
     "map_run_request",
+    "map_scheduler_request",
     "map_studio_request",
     "receipt_error_payload",
     "receipt_http_status",

ksadk/kernel/memory_store.py

@@ -1124,6 +1124,7 @@ class InMemoryAgentKernelStore:
                         "fencing_token": int(expected_fence),
                     },
                     run_id=run.run_id,
+                    causation_id=str(run.metadata.get("command_id") or "") or None,
                 ),
                 activation_row=activation,
             )

ksadk/kernel/postgres_store.py

@@ -1647,6 +1647,7 @@ class PostgresAgentKernelStore:
                             "fencing_token": int(expected_fence),
                         },
                         run_id=run.run_id,
+                        causation_id=str(run.metadata.get("command_id") or "") or None,
                     ),
                     activation,
                     expected_fence,

ksadk/kernel/sqlite_store.py

@@ -1112,6 +1112,33 @@ class SQLiteAgentKernelStore:
             )
         return self._row_to_record(rows[0]) if rows else None
 
+    async def get_terminal_receipt(
+        self, interaction_id: str, *, tenant_id: str, agent_instance_id: str,
+        session_id: str, run_id: str,
+    ) -> InteractionReceipt | None:
+        """Read the committed outcome inside a complete trusted scope.
+
+        Resolved alone does not mean approved. Pending/resolving records never
+        yield an authorization receipt; callers must still match the request.
+        """
+        if not all(isinstance(value, str) and value for value in (
+            interaction_id, tenant_id, agent_instance_id, session_id, run_id
+        )):
+            raise InvalidCommandError("interaction receipt requires a complete trusted scope")
+        row = await self._fetchone(
+            await self._connect(),
+            "SELECT * FROM kernel_interactions WHERE interaction_id=? AND tenant_id=?"
+            " AND agent_instance_id=? AND session_id=? AND run_id=?",
+            (interaction_id, tenant_id, agent_instance_id, session_id, run_id),
+        )
+        if row is None or not is_terminal(row["status"]):
+            return None
+        return InteractionReceipt(
+            interaction_id=row["interaction_id"], revision=int(row["revision"]),
+            status=row["status"], outcome=row["outcome"], event_id=row["event_id"],
+            accepted_seq=row["accepted_seq"],
+        )
+
     async def list_pending_interactions(
         self, tenant_id: str, session_id: str
     ) -> list[InteractionRecord]:
@@ -1400,6 +1427,7 @@ class SQLiteAgentKernelStore:
                     "fencing_token": int(expected_fence),
                 },
                 run_id=run.run_id,
+                causation_id=str(run.metadata.get("command_id") or "") or None,
             ),
             activation,
             expected_fence,

ksadk/kernel/store.py

@@ -54,6 +54,9 @@ def command_digest(command: AgentControlCommand) -> str:
     canonical["source"] = source
 
     payload = dict(canonical.get("payload") or {})
+    # Admission derives this immutable snapshot from the current session. A
+    # retry after a tag update must still resolve to the first accepted command.
+    payload.pop("session_context", None)
     if command.command_type == "submit_interaction":
         payload.pop("token_ref", None)
     canonical["payload"] = payload

ksadk/kernel/worker.py

@@ -109,6 +109,7 @@ class WorkResult:
     message_id: str | None = None
     run_id: str | None = None
     last_seq: int | None = None
+    error: Exception | None = None
 
 
 class AgentKernelWorker:
@@ -294,8 +295,10 @@ class AgentKernelWorker:
             )
             await self._store.discard_claim(message_id, expected_fence=fence)
             return WorkResult(outcome="completed", message_id=message_id)
-        except StaleFenceError:
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+        except StaleFenceError as error:
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
         except AgentKernelError as error:
             if error.code == RUNTIME_INTERACTION_UNAVAILABLE:
                 # typed rejection：provider 诚实声明无法原生送达回包，
@@ -316,16 +319,46 @@ class AgentKernelWorker:
                 await self._store.discard_claim(message_id, expected_fence=fence)
                 return WorkResult(outcome="completed", message_id=message_id)
             if error.retryable:
-                return WorkResult(outcome="retryable_failure", message_id=message_id)
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
-        except Exception:
+                return WorkResult(
+                    outcome="retryable_failure", message_id=message_id, error=error
+                )
+            logger.error(
+                "agent kernel command failed permanently: "
+                "agent_instance_id=%s session_id=%s command_id=%s "
+                "command_type=%s error=%s: %s",
+                command.agent_instance_id,
+                command.session_id,
+                command.command_id,
+                command.command_type,
+                type(error).__name__,
+                error,
+            )
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
+        except Exception as error:
             # 未知异常绝不 ack 为成功：消息保持 claimed。
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+            logger.exception(
+                "agent kernel command raised an unexpected exception: "
+                "agent_instance_id=%s session_id=%s command_id=%s "
+                "command_type=%s error=%s: %s",
+                command.agent_instance_id,
+                command.session_id,
+                command.command_id,
+                command.command_type,
+                type(error).__name__,
+                error,
+            )
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
 
         try:
             await self._store.complete_claim(message_id, expected_fence=fence)
-        except StaleFenceError:
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+        except StaleFenceError as error:
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
         return WorkResult(outcome="completed", message_id=message_id, run_id=run_id)
 
     async def _message_id_for(self, command: AgentControlCommand) -> str:
@@ -356,6 +389,17 @@ class AgentKernelWorker:
             agent_instance_id=command.agent_instance_id,
             session_id=command.session_id,
             state=RunState.PENDING,
+            # Keep the admitted control identity on the durable run.  This is
+            # not user-supplied metadata: it is copied from the trusted
+            # command that the worker actually claimed.  Consumers such as the
+            # local Scheduler can therefore reconcile a runtime terminal fact
+            # back to one occurrence without matching text or wall-clock time.
+            metadata={
+                "command_id": str(command.command_id),
+                "source_kind": command.source.kind,
+                "source_ref": command.source.ref,
+                "correlation_id": command.correlation_id,
+            },
         )
         created = await self._store.save_run_transition(pending, expected_fence=fence)
         continuation_metadata = await self._session_continuation_metadata(command.session_id)
@@ -396,6 +440,11 @@ class AgentKernelWorker:
                 # durable run_id 优先传给 adapter；adapter 不认时以
                 # runtime_run_id 映射显式记录两个 ID 的对应关系。
                 metadata={
+                    **(
+                        {"session_context": command.payload["session_context"]}
+                        if "session_context" in command.payload
+                        else {}
+                    ),
                     "command_id": str(command.command_id),
                     "run_id": run_id,
                     **continuation_metadata,
@@ -735,7 +784,17 @@ class AgentKernelWorker:
             )
         else:
             request_schema = dict(event.request.schema_)
-            native_target = {"call_id": event.interaction_id}
+            # Codex maps the native JSON-RPC request id to a stable canonical
+            # interaction id for replay.  The live client, however, indexes its
+            # pending callback by the original request id.  Preserve that id as
+            # the provider target or SubmitInteraction can find the durable
+            # record but cannot wake the blocked Codex callback.
+            native_call_id = (
+                event.source.native_event_id
+                or event.source.native_item_id
+                or event.interaction_id
+            )
+            native_target = {"call_id": native_call_id}
         for key in ("checkpoint_id", "thread_id"):
             value = execution.handle.native_ref.get(key)
             if value is not None:
@@ -801,7 +860,13 @@ class AgentKernelWorker:
                 kind=RESUME_TARGET_KINDS[target_dict["kind"]],
                 id=str(target_dict["id"]),
             )
-            resumed = await adapter.resume(handle, target, AdapterResumePayload(kind="free_text"))
+            resumed = await adapter.resume(
+                handle,
+                target,
+                AdapterResumePayload(
+                    kind="free_text", session_context=command.payload.get("session_context")
+                ),
+            )
             execution = self._replace_handle(execution, resumed)
             self._start_stream(
                 execution,
@@ -899,6 +964,7 @@ class AgentKernelWorker:
         context = InteractionResolveContext(
             adapter=execution.adapter,
             handle=execution.handle,
+            session_context=command.payload.get("session_context"),
             activation_id=activation.activation_id,
             fencing_token=fence,
         )

ksadk/knowledge_base/client.py

@@ -86,6 +86,8 @@ class KnowledgeBaseClient(BaseModel):
     # KnowledgeBaseService.build_context 区分"后端吞错返空"与"真无结果"，
     # 避免错误伪装成"未找到"注入模型上下文。
     last_error: str = ""
+    last_request_id: str = ""
+    last_http_status: int | None = None
 
     _aicp_client: Any = None
 
@@ -140,9 +142,7 @@ class KnowledgeBaseClient(BaseModel):
                 "Ensure kingsoftcloud-sdk-python is installed and up to date."
             )
 
-        cred = credential.Credential(
-            self.access_key, self.secret_key, self.session_token or None
-        )
+        cred = credential.Credential(self.access_key, self.secret_key, self.session_token or None)
 
         http_profile = HttpProfile()
         http_profile.endpoint = self.endpoint
@@ -153,17 +153,23 @@ class KnowledgeBaseClient(BaseModel):
         client_profile = ClientProfile()
         client_profile.httpProfile = http_profile
 
-        self._aicp_client = aicp_module.AicpClient(cred, self.region, profile=client_profile)
+        owner = self
+
+        class ObservedAicpClient(aicp_module.AicpClient):
+            def _check_status(self, response):
+                # The upstream SDK discards HTTP status when raising its generic
+                # ServerNetworkError. Capture only the status before delegation;
+                # never infer authorization from exception text/response content.
+                owner.last_http_status = response.status
+                return super()._check_status(response)
+
+        self._aicp_client = ObservedAicpClient(cred, self.region, profile=client_profile)
 
         # 强制覆写 API 版本为 RetrieveKnowledge 所需的 2025-11-14
         # SDK 的 _apiVersion 由导入的模块版本决定，可能不匹配
         self._aicp_client._apiVersion = "2025-11-14"
 
-        logger.info(
-            f"KnowledgeBaseClient initialized: "
-            f"dataset_id={self.dataset_id}, region={self.region}, "
-            f"endpoint={self.endpoint}"
-        )
+        logger.debug("KnowledgeBaseClient initialized")
         return self._aicp_client
 
     def _build_params(self, query: str, top_k: Optional[int] = None) -> dict:
@@ -192,11 +198,41 @@ class KnowledgeBaseClient(BaseModel):
         try:
             data = json.loads(response) if isinstance(response, str) else response
         except (json.JSONDecodeError, TypeError):
-            self.last_error = f"Failed to parse response: {str(response)[:200]}"
-            logger.error(f"Failed to parse response: {str(response)[:200]}")
+            self.last_error = "Invalid knowledge response JSON"
+            logger.error("Invalid knowledge response JSON")
+            return []
+
+        if not isinstance(data, dict):
+            self.last_error = "Knowledge response must be an object"
+            return []
+        metadata = data.get("ResponseMetadata") or {}
+        if not isinstance(metadata, dict):
+            self.last_error = "Invalid knowledge response metadata"
+            return []
+        request_id = data.get("RequestId") or metadata.get("RequestId")
+        self.last_request_id = (
+            request_id if isinstance(request_id, str) and len(request_id) <= 256 else ""
+        )
+        code = data.get("Code")
+        if "Code" in data:
+            valid_code = (
+                (type(code) is int and code in {0, 200})
+                or (type(code) is str and code in {"0", "200"})
+            )
+            if not valid_code:
+                self.last_error = "Knowledge service rejected the request"
+                return []
+        if data.get("Error") or metadata.get("Error"):
+            self.last_error = "Knowledge service rejected the request"
             return []
 
-        records = data.get("Records", [])
+        if "Records" not in data:
+            self.last_error = "Knowledge response omitted records"
+            return []
+        records = data["Records"]
+        if not isinstance(records, list):
+            self.last_error = "Invalid knowledge records"
+            return []
         results = []
 
         for record in records:
@@ -228,24 +264,19 @@ class KnowledgeBaseClient(BaseModel):
         Returns:
             匹配的文档片段列表
         """
-        client = self._get_client()
-        params = self._build_params(query, top_k)
-
-        logger.info(
-            f"Searching knowledge base: dataset_id={self.dataset_id}, " f"query='{query[:50]}'"
-        )
-
         self.last_error = ""
+        self.last_request_id = ""
+        self.last_http_status = None
         try:
+            client = self._get_client()
+            params = self._build_params(query, top_k)
             response = client.call("RetrieveKnowledge", params, options={"IsPostJson": True})
             results = self._parse_response(response)
-            logger.info(
-                f"Knowledge base returned {len(results)} results " f"for query='{query[:50]}'"
-            )
+            logger.debug("Knowledge base returned %d results", len(results))
             return results
         except Exception as e:
             self.last_error = str(e)
-            logger.error(f"Knowledge base search failed: {e}")
+            logger.error("Knowledge base search failed (%s)", type(e).__name__)
             raise
 
     @classmethod
@@ -261,7 +292,7 @@ class KnowledgeBaseClient(BaseModel):
         dataset_id = os.environ.get("KSADK_KB_DATASET_ID", "")
         if not dataset_id:
             raise ValueError(
-                "KSADK_KB_DATASET_ID environment variable is required " "to enable knowledge base."
+                "KSADK_KB_DATASET_ID environment variable is required to enable knowledge base."
             )
 
         access_key = (
@@ -275,9 +306,8 @@ class KnowledgeBaseClient(BaseModel):
             or os.environ.get("KSYUN_SECRET_KEY")
             or os.environ.get("KSYUN_SECRET_ACCESS_KEY", "")
         )
-        session_token = (
-            os.environ.get("KSADK_KB_SESSION_TOKEN")
-            or os.environ.get("KSYUN_SESSION_TOKEN", "")
+        session_token = os.environ.get("KSADK_KB_SESSION_TOKEN") or os.environ.get(
+            "KSYUN_SESSION_TOKEN", ""
         )
 
         score_threshold_str = os.environ.get("KSADK_KB_SCORE_THRESHOLD", "")

ksadk/mcp_runtime/__init__.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 import inspect
 import json
 import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, Coroutine, Sequence, cast
 from urllib.parse import urlparse
 
 import httpx
+from pydantic import Field
 
 from ksadk.compat.adk_compat import (
     CheckableMcpHttpClientFactory,
@@ -21,8 +22,8 @@ MCP_TOOLSET_KEY_ATTR = "_ksadk_mcp_toolset_key"
 @dataclass(frozen=True)
 class MCPServerConfig:
     name: str
-    url: str
-    api_key: str | None = None
+    url: str = field(repr=False)
+    api_key: str | None = field(default=None, repr=False)
     tool_filter: tuple[str, ...] = ()
     tool_name_prefix: str | None = None
 
@@ -68,7 +69,14 @@ def build_connection_params(
     kwargs["httpx_client_factory"] = httpx_client_factory or _default_httpx_client_factory(
         config.url
     )
-    return StreamableHTTPConnectionParams(**kwargs)
+    return _RedactedStreamableHTTPConnectionParams(**kwargs)
+
+
+class _RedactedStreamableHTTPConnectionParams(StreamableHTTPConnectionParams):
+    """Keep process-scoped MCP connection material out of debug reprs."""
+
+    url: str = Field(repr=False)
+    headers: dict[str, Any] | None = Field(default=None, repr=False)
 
 
 def build_mcp_toolset(