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

ksadk/conversations/message_projection.py

@@ -431,6 +431,34 @@ def _tool_event_from_call(event: Mapping[str, Any], metadata: Mapping[str, Any])
     }
 
 
+def _approval_status_from_resume(response: Any, resume_input: Mapping[str, Any]) -> str:
+    """从 approval_response 事件的 resume_input 判断审批结果状态。
+
+    支持两种协议：
+    - mcp_approval_response: resume_input 含 approve/approved bool
+    - ksadk_resume + decisions: resume_input.value.decisions[0].type 为
+      approve/edit/reject（HumanInTheLoopMiddleware 协议）
+    """
+    if response is None:
+        return "paused"
+    # ksadk_resume + decisions 协议
+    value = resume_input.get("value")
+    if isinstance(value, Mapping):
+        decisions = value.get("decisions")
+        if isinstance(decisions, list) and decisions:
+            first = decisions[0]
+            if isinstance(first, Mapping):
+                decision_type = str(first.get("type") or "").strip().lower()
+                if decision_type in {"approve", "edit"}:
+                    return "approved"
+                if decision_type in {"reject", "respond"}:
+                    return "denied"
+    # mcp_approval_response 协议
+    if resume_input.get("approve") or resume_input.get("approved"):
+        return "approved"
+    return "denied"
+
+
 def _project_approval_events(
     events: Sequence[Mapping[str, Any]],
     *,
@@ -438,10 +466,52 @@ def _project_approval_events(
 ) -> list[dict[str, Any]]:
     approvals: list[dict[str, Any]] = []
     for request in events:
-        if request.get("EventType") != "approval_request":
+        event_type = str(request.get("EventType") or "")
+        # 识别归一化后的 approval_request，以及未归一化的 canonical interaction.requested。
+        if event_type not in {"approval_request", "interaction.requested"}:
             continue
         metadata = _event_metadata(request)
+        # 归一化路径：interrupt_info 在 metadata；canonical 路径在
+        # Content.runtime_event.request.detail。
         interrupt_info = metadata.get("interrupt_info")
+        if not isinstance(interrupt_info, Mapping):
+            # 尝试从 canonical event 的 Content.runtime_event 提取
+            raw_content = request.get("Content")
+            content = raw_content if isinstance(raw_content, Mapping) else {}
+            runtime_event = content.get("runtime_event")
+            if isinstance(runtime_event, Mapping):
+                req = runtime_event.get("request") or {}
+                if isinstance(req, Mapping):
+                    detail = req.get("detail")
+                    if isinstance(detail, Mapping):
+                        # 从 detail.action_requests[0] 提取（HumanInTheLoopMiddleware 结构）
+                        action_requests = detail.get("action_requests")
+                        first_action = (
+                            action_requests[0]
+                            if isinstance(action_requests, list) and action_requests
+                            else {}
+                        )
+                        if not isinstance(first_action, Mapping):
+                            first_action = {}
+                        interaction_id = runtime_event.get("interaction_id") or req.get(
+                            "call_id"
+                        )
+                        interrupt_info = {
+                            "approval_request_id": interaction_id,
+                            "id": interaction_id,
+                            "tool_name": detail.get("tool_name")
+                            or first_action.get("name")
+                            or req.get("kind"),
+                            "arguments": detail.get("arguments")
+                            or detail.get("args")
+                            or first_action.get("args")
+                            or first_action.get("arguments"),
+                            "description": detail.get("description")
+                            or first_action.get("description"),
+                            "review_configs": detail.get("review_configs"),
+                            "approval_message": detail.get("message")
+                            or first_action.get("description"),
+                        }
         if not isinstance(interrupt_info, Mapping):
             interrupt_info = {}
         request_id = str(
@@ -452,31 +522,56 @@ def _project_approval_events(
         resume_input = response_metadata.get("resume_input")
         if not isinstance(resume_input, Mapping):
             resume_input = {}
-        status = (
-            "paused"
-            if response is None
-            else (
-                "approved"
-                if resume_input.get("approve") or resume_input.get("approved")
-                else "denied"
-            )
+        status = _approval_status_from_resume(response, resume_input)
+        # HumanInTheLoopMiddleware 的 interrupt_info 把 tool_name 嵌在
+        # action_requests[0].name 里，runtime path 存的事件可能没有顶层 tool_name。
+        # 这里统一提取，避免 Name fallback 成 "approval" 导致前端显示不对。
+        action_requests = interrupt_info.get("action_requests")
+        first_action = (
+            action_requests[0]
+            if isinstance(action_requests, list) and action_requests
+            else {}
+        )
+        if not isinstance(first_action, Mapping):
+            first_action = {}
+        tool_name = (
+            interrupt_info.get("tool_name")
+            or first_action.get("name")
+            or "approval"
         )
         entry: dict[str, Any] = {
             "SeqId": request.get("SeqId"),
             "Type": "approval",
-            "Name": str(interrupt_info.get("tool_name") or "approval"),
+            "Name": str(tool_name),
             "Status": status,
             "ApprovalRequestId": request_id or None,
         }
         if metadata.get("protocol") == "ag-ui":
             entry["Protocol"] = "ag-ui"
+        # arguments/description 优先从顶层取（_get_interrupt_info/归一化已提取），
+        # fallback 到 action_requests[0]（runtime path 存的原始 interrupt_info）。
         arguments = (
             interrupt_info.get("arguments")
             or interrupt_info.get("tool_args")
             or interrupt_info.get("args")
+            or first_action.get("args")
+            or first_action.get("arguments")
         )
         if arguments is not None:
             entry["Args"] = arguments
+        description = (
+            interrupt_info.get("description")
+            or first_action.get("description")
+        )
+        if description:
+            entry["Description"] = str(description)
+        review_configs = interrupt_info.get("review_configs")
+        if isinstance(review_configs, list) and review_configs:
+            first_review = review_configs[0]
+            if isinstance(first_review, Mapping):
+                allowed = first_review.get("allowed_decisions")
+                if isinstance(allowed, list) and allowed:
+                    entry["AllowedDecisions"] = [str(d) for d in allowed]
         approval_level = interrupt_info.get("approval_level") or interrupt_info.get("risk_level")
         if approval_level:
             entry["ApprovalLevel"] = str(approval_level)
@@ -722,15 +817,36 @@ def _normalize_canonical_event(
             detail = request.get("detail")
             if not isinstance(detail, Mapping):
                 detail = {}
+            # HumanInTheLoopMiddleware 的 detail 把 tool_name/arguments/description
+            # 嵌在 action_requests[0] 里，detail 顶层没有，需要提取。
+            action_requests = detail.get("action_requests")
+            first_action = (
+                action_requests[0]
+                if isinstance(action_requests, list) and action_requests
+                else {}
+            )
+            if not isinstance(first_action, Mapping):
+                first_action = {}
+            review_configs = detail.get("review_configs")
             normalized["EventType"] = "approval_request"
             normalized["Content"] = {"detail": detail}
             normalized_metadata["interrupt_info"] = {
                 "approval_request_id": interaction_id or call_id,
                 "id": interaction_id or call_id,
-                "tool_name": detail.get("tool_name") or kind,
-                "arguments": detail.get("arguments") or detail.get("args"),
-                "approval_level": detail.get("approval_level"),
-                "approval_message": detail.get("message"),
+                "tool_name": detail.get("tool_name")
+                or first_action.get("name")
+                or kind,
+                "arguments": detail.get("arguments")
+                or detail.get("args")
+                or first_action.get("args")
+                or first_action.get("arguments"),
+                "description": detail.get("description")
+                or first_action.get("description"),
+                "review_configs": review_configs if isinstance(review_configs, list) else None,
+                "approval_level": detail.get("approval_level")
+                or first_action.get("approval_level"),
+                "approval_message": detail.get("message")
+                or first_action.get("description"),
             }
             # Preserve ag-ui protocol tag from source metadata.
             source = runtime_event.get("source") or {}
@@ -861,6 +977,11 @@ def _normalize_runtime_event(
             or approval_request.get("args")
             or detail.get("arguments")
             or detail.get("args"),
+            "description": action.get("description")
+            or approval_request.get("description")
+            or detail.get("description"),
+            "review_configs": approval_request.get("review_configs")
+            or detail.get("review_configs"),
             "approval_level": action.get("approval_level")
             or approval_request.get("approval_level")
             or detail.get("approval_level")

ksadk/conversations/projector.py

@@ -203,6 +203,7 @@ def project_conversation_item(
         )
         payload = {
             "interactionId": event.interaction_id,
+            "callId": getattr(event.request, "call_id", None),
             "kind": getattr(event.request, "kind", event.interaction_kind),
             "detail": getattr(event.request, "detail", None),
             "prompt": getattr(event.request, "prompt", None),
@@ -250,7 +251,7 @@ def project_conversation_item(
         schema = "conversation.item.error/v1"
         payload = {
             "status": "failed" if isinstance(event, RunFailed) else "canceled",
-            "error": event.error.message if isinstance(event, RunFailed) else event.reason or ""
+            "error": event.error.message if isinstance(event, RunFailed) else event.reason or "",
         }
     elif isinstance(event, (ContinuationCreated, ContinuationResumed)):
         kind = "progress"
@@ -524,9 +525,7 @@ def _item_snapshot(
 def _artifact_payload(snapshot: ContentSnapshot | None) -> dict[str, Any]:
     if snapshot is None:
         return {}
-    artifact = next(
-        (part for part in snapshot.parts if isinstance(part, ArtifactContent)), None
-    )
+    artifact = next((part for part in snapshot.parts if isinstance(part, ArtifactContent)), None)
     if artifact is None:
         return {}
     return {
@@ -583,8 +582,7 @@ def _is_codex_goal_item(event: RuntimeEvent) -> bool:
         isinstance(event, (ItemStarted, ItemUpdated, ItemSnapshotReplaced, ItemCompleted))
         and event.item_kind == "data"
         and event.source.framework == "codex"
-        and event.source.metadata.get("method")
-        in {"thread/goal/updated", "thread/goal/cleared"}
+        and event.source.metadata.get("method") in {"thread/goal/updated", "thread/goal/cleared"}
     )
 
 

ksadk/conversations/runtime_invocation.py

@@ -123,6 +123,7 @@ async def invoke_conversation_once(
     agent_system: str = "",
     agent_task: str = "",
     prompt_integration_mode: str = "",
+    resume_lifecycle_prepared: bool = False,
 ) -> tuple[str, dict[str, Any]]:
     """非流式 turn 编排入口。
 
@@ -159,6 +160,7 @@ async def invoke_conversation_once(
             agent_system=agent_system,
             agent_task=agent_task,
             prompt_integration_mode=prompt_integration_mode,
+            resume_lifecycle_prepared=resume_lifecycle_prepared,
         )
         # prepared 之后的 run_status 写入复用 prepared 的 mode/trigger
         run_mode = prepared.run_mode
@@ -184,7 +186,10 @@ async def invoke_conversation_once(
         user_input=prepared.user_input,
     )
     prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
+    from ksadk.session_context import SessionContext
+
     runtime_context = PlatformInvocationContext(
+        session=SessionContext.from_payload(prepared.session_context),
         agent_id=agent_id,
         user_id=user_id,
         account_id=str(account_id or ""),

ksadk/conversations/runtime_payloads.py

@@ -91,6 +91,7 @@ class PreparedConversationTurn:
     memory_write_mode: str = "candidate"
     flush_before_compaction: bool = True
     provider_ref: str = "local-default"
+    session_context: dict[str, Any] = field(default_factory=dict)
 
 
 @dataclass

ksadk/conversations/runtime_preparation.py

@@ -49,6 +49,7 @@ from ksadk.conversations.runtime_metadata import (
 )
 from ksadk.conversations.runtime_observability import _latest_deferred_tool_names
 from ksadk.conversations.runtime_payloads import PreparedConversationTurn
+from ksadk.session_context import split_session_context
 from ksadk.conversations.runtime_persistence import (
     append_conversation_event,
     append_run_resume_event,
@@ -110,6 +111,7 @@ async def build_run_input(
     deployment_mode: str = "local",
     agent_max_input_tokens: int | None = None,
     agent_reserve_output_tokens: int | None = None,
+    resume_lifecycle_prepared: bool = False,
 ) -> PreparedConversationTurn:
     """构建一次 turn 的标准运行输入，并在进入模型前做上下文投影/压缩。
 
@@ -138,7 +140,7 @@ async def build_run_input(
         model,
         model_metadata=model_metadata,
     )
-    normalized_request_metadata = dict(request_metadata or {})
+    session_context, normalized_request_metadata = split_session_context(request_metadata)
     normalized_custom_metadata = dict(custom_metadata or {})
     policy_model = model or os.getenv("OPENAI_MODEL_NAME") or os.getenv("MODEL_NAME")
     normalized_model_options = {
@@ -170,39 +172,37 @@ async def build_run_input(
     if resume_input is not None:
         if not session_id:
             raise ValueError("Responses resume input requires session_id")
-        existing_events = await service.get_events(resolved_session_id)
         normalized_resume_input = dict(resume_input)
         if _is_checkpoint_resume_input(normalized_resume_input):
             normalized_resume_input = _normalize_checkpoint_resume_input(normalized_resume_input)
-            await append_run_resume_event(
-                session_id=resolved_session_id,
-                author=agent_id,
-                run_id=str(normalized_resume_input["run_id"]),
-                checkpoint_id=str(normalized_resume_input["checkpoint_id"]),
-                resume_attempt_id=str(normalized_resume_input["resume_attempt_id"]),
-                framework=str(normalized_resume_input["framework"]),
-                framework_ref=normalized_resume_input["framework_ref"],
-                invocation_id=resolved_invocation_id,
-                session_service_provider=provider,
-            )
-            # 补写 run_status(resuming)：让 ActiveRunStatus 在 resume 期间正确反映"恢复中"。
-            # append_run_resume_event 写的是 run_resume 事件（status=resuming），而
-            # _latest_session_run_status 只扫 run_status 事件 → 不补写则
-            # resuming 不进 ActiveRunStatus。
-            await append_run_status_event(
-                session_id=resolved_session_id,
-                author=agent_id,
-                status="resuming",
-                invocation_id=resolved_invocation_id,
-                detail="checkpoint_resume",
-                session_service_provider=provider,
-                run_mode=caller_run_mode,
-                run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
-            )
+            if not resume_lifecycle_prepared:
+                await append_run_resume_event(
+                    session_id=resolved_session_id,
+                    author=agent_id,
+                    run_id=str(normalized_resume_input["run_id"]),
+                    checkpoint_id=str(normalized_resume_input["checkpoint_id"]),
+                    resume_attempt_id=str(normalized_resume_input["resume_attempt_id"]),
+                    framework=str(normalized_resume_input["framework"]),
+                    framework_ref=normalized_resume_input["framework_ref"],
+                    invocation_id=resolved_invocation_id,
+                    session_service_provider=provider,
+                )
+                # run_resume 与 ActiveRunStatus 分属不同事件类型，因此补写 resuming。
+                await append_run_status_event(
+                    session_id=resolved_session_id,
+                    author=agent_id,
+                    status="resuming",
+                    invocation_id=resolved_invocation_id,
+                    detail="checkpoint_resume",
+                    session_service_provider=provider,
+                    run_mode=caller_run_mode,
+                    run_trigger=RUN_TRIGGER_CHECKPOINT_RESUME,
+                )
             event_history = await service.get_events(resolved_session_id)
             history = build_history_from_events(event_history)
             responses_history = project_responses_history(event_history)
             return PreparedConversationTurn(
+                session_context=session_context.to_payload(),
                 session_id=resolved_session_id,
                 invocation_id=resolved_invocation_id,
                 user_input="",
@@ -239,6 +239,7 @@ async def build_run_input(
                 provider_ref=provider_ref,
             )
 
+        existing_events = await service.get_events(resolved_session_id)
         is_approval_resume = _is_approval_resume_input(normalized_resume_input)
         existing_tool_receipt_event = None
         if is_approval_resume and not _has_pending_approval(existing_events):
@@ -319,6 +320,7 @@ async def build_run_input(
         history = build_history_from_events(event_history)
         responses_history = project_responses_history(event_history)
         return PreparedConversationTurn(
+            session_context=session_context.to_payload(),
             session_id=resolved_session_id,
             invocation_id=resolved_invocation_id,
             user_input=resume_text,
@@ -478,6 +480,7 @@ async def build_run_input(
         working_state = _latest_checkpoint_working_state(event_history)
 
     prepared = PreparedConversationTurn(
+        session_context=session_context.to_payload(),
         session_id=resolved_session_id,
         invocation_id=resolved_invocation_id,
         user_id=resolved_user_id,

ksadk/conversations/runtime_resume.py

@@ -185,6 +185,48 @@ def _parse_approval_arguments(value: Any) -> dict[str, Any]:
 
 
 def _approval_decision_from_resume(resume_input: Mapping[str, Any]) -> dict[str, Any]:
+    # ksadk_resume + decisions 协议（HumanInTheLoopMiddleware）：
+    # resume_input.value.decisions[0].type 为 approve/edit/reject。
+    value = resume_input.get("value")
+    if isinstance(value, Mapping):
+        decisions = value.get("decisions")
+        if isinstance(decisions, list) and decisions:
+            first = decisions[0]
+            if isinstance(first, Mapping):
+                decision_type = str(first.get("type") or "").strip().lower()
+                if decision_type in {"approve", "edit"}:
+                    approved = True
+                    if decision_type == "edit":
+                        # edit 带修改后的参数；记录到 decision 供下游使用。
+                        edited = first.get("edited_action")
+                        if isinstance(edited, Mapping):
+                            return {
+                                "approved": True,
+                                "approval_request_id": str(
+                                    resume_input.get("approval_request_id")
+                                    or resume_input.get("interrupt_id")
+                                    or resume_input.get("id")
+                                    or ""
+                                ),
+                                "edited_action": dict(edited),
+                            }
+                elif decision_type in {"reject", "respond"}:
+                    approved = False
+                else:
+                    approved = True
+                decision = {
+                    "approved": approved,
+                    "approval_request_id": str(
+                        resume_input.get("approval_request_id")
+                        or resume_input.get("interrupt_id")
+                        or resume_input.get("id")
+                        or ""
+                    ),
+                }
+                message = first.get("message") or first.get("feedback")
+                if message is not None:
+                    decision["reason"] = str(message)
+                return decision
     if "approve" in resume_input:
         approved = bool(resume_input.get("approve"))
     elif "approved" in resume_input:
@@ -624,7 +666,11 @@ def _extract_agentengine_metadata(result: Mapping[str, Any] | None) -> dict[str,
     agentengine = metadata.get("agentengine")
     if not isinstance(agentengine, Mapping):
         return {}
-    return {"agentengine": dict(agentengine)}
+    return {
+        "agentengine": {
+            key: value for key, value in agentengine.items() if key != "session_context"
+        }
+    }
 
 
 def _checkpoint_event_args_from_agentengine_metadata(
@@ -682,7 +728,9 @@ def _merge_agentengine_metadata(
         agentengine = metadata.get("agentengine")
         if not isinstance(agentengine, Mapping):
             continue
-        next_agentengine = dict(agentengine)
+        next_agentengine = {
+            key: value for key, value in agentengine.items() if key != "session_context"
+        }
         merged.update(next_agentengine)
         framework_ref = agentengine.get("framework_ref")
         if isinstance(framework_ref, Mapping):

ksadk/conversations/runtime_stream_events.py

@@ -136,6 +136,7 @@ async def _iter_conversation_turn_events(
     agent_system: str = "",
     agent_task: str = "",
     prompt_integration_mode: str = "",
+    resume_lifecycle_prepared: bool = False,
 ) -> AsyncIterator[dict[str, Any]]:
     """Internal semantic event stream shared by protocol serializers."""
     provider = session_service_provider or resolve_session_service
@@ -198,6 +199,7 @@ async def _iter_conversation_turn_events(
             agent_system=agent_system,
             agent_task=agent_task,
             prompt_integration_mode=prompt_integration_mode,
+            resume_lifecycle_prepared=resume_lifecycle_prepared,
         )
         # prepared 之后的 run_status 写入复用 prepared 的 mode/trigger
         run_mode = prepared.run_mode
@@ -224,7 +226,10 @@ async def _iter_conversation_turn_events(
         user_input=prepared.user_input,
     )
     prepared.memory_recall_events = ambient_contexts.get("memory_recall_events", [])
+    from ksadk.session_context import SessionContext
+
     runtime_context = PlatformInvocationContext(
+        session=SessionContext.from_payload(prepared.session_context),
         agent_id=agent_id,
         user_id=user_id,
         account_id=str(account_id or ""),

ksadk/conversations/runtime_streaming.py

@@ -39,6 +39,7 @@ async def stream_conversation_turn(
     invocation_id: Optional[str] = None,
     session_service_provider: Callable[[], Any] | None = None,
     run_mode: str = RUN_MODE_FOREGROUND,
+    resume_lifecycle_prepared: bool = False,
 ) -> AsyncIterator[str]:
     """Legacy ksadk response SSE stream used by hosted chat and chat-completions."""
     events = _iter_conversation_turn_events(
@@ -60,6 +61,7 @@ async def stream_conversation_turn(
         invocation_id=invocation_id,
         session_service_provider=session_service_provider,
         run_mode=run_mode,
+        resume_lifecycle_prepared=resume_lifecycle_prepared,
     )
     async for chunk in _stream_conversation_semantic_events(
         events=events,
@@ -151,7 +153,7 @@ async def _stream_conversation_semantic_events(
             yield _response_sse(
                 "response.tool_call",
                 {
-                    "name": event.get("name"),
+                    "name": event.get("tool_name") or event.get("name"),
                     "args": event.get("args", {}),
                     "run_id": event.get("run_id"),
                     "stage": event.get("stage"),
@@ -164,7 +166,7 @@ async def _stream_conversation_semantic_events(
             yield _response_sse(
                 "response.tool_result",
                 {
-                    "name": event.get("name"),
+                    "name": event.get("tool_name") or event.get("name"),
                     "output": event.get("output", ""),
                     "run_id": event.get("run_id"),
                 },
@@ -174,7 +176,7 @@ async def _stream_conversation_semantic_events(
                 f"response.ksadk.{event_type}",
                 {
                     "type": event_type,
-                    "name": event.get("name"),
+                    "name": event.get("tool_name") or event.get("name"),
                     "args": event.get("args", {}),
                     "output": event.get("output", ""),
                     "run_id": event.get("run_id"),
@@ -228,6 +230,7 @@ async def stream_responses_conversation_turn(
     invocation_id: Optional[str] = None,
     session_service_provider: Callable[[], Any] | None = None,
     run_mode: str = RUN_MODE_FOREGROUND,
+    resume_lifecycle_prepared: bool = False,
 ) -> AsyncIterator[str]:
     """OpenAI Responses-style SSE stream."""
     response_id = f"resp_{uuid.uuid4().hex}"
@@ -476,12 +479,14 @@ async def _stream_responses_semantic_events(
             call_id = str(event.get("run_id") or f"call_{uuid.uuid4().hex[:12]}")
             item_id = f"fc_{uuid.uuid4().hex[:12]}"
             call_output_index = _next_output_index()
+            # tool_name 是 runner stream 的字段名；name 用于向后兼容旧事件源。
+            tool_name = event.get("tool_name") or event.get("name") or "unknown"
             item = {
                 "id": item_id,
                 "type": "function_call",
                 "status": "in_progress",
                 "call_id": call_id,
-                "name": event.get("name") or "unknown",
+                "name": tool_name,
                 "arguments": "",
             }
             yield _response_sse(
@@ -505,7 +510,7 @@ async def _stream_responses_semantic_events(
                     "response.ksadk.tool_call",
                     {
                         "type": "tool_call",
-                        "name": event.get("name"),
+                        "name": tool_name,
                         "args": event.get("args", {}),
                         "run_id": event.get("run_id"),
                         "stage": event.get("stage"),
@@ -520,7 +525,7 @@ async def _stream_responses_semantic_events(
             yield _response_sse(
                 "response.ksadk.tool_result",
                 {
-                    "name": event.get("name"),
+                    "name": event.get("tool_name") or event.get("name"),
                     "output": event.get("output", ""),
                     "run_id": event.get("run_id"),
                 },
@@ -532,7 +537,7 @@ async def _stream_responses_semantic_events(
                 f"response.ksadk.{event_type}",
                 {
                     "type": event_type,
-                    "name": event.get("name"),
+                    "name": event.get("tool_name") or event.get("name"),
                     "args": event.get("args", {}),
                     "output": event.get("output", ""),
                     "run_id": event.get("run_id"),
@@ -569,6 +574,19 @@ async def _stream_responses_semantic_events(
                     "arguments": arguments,
                     "server_label": str(interrupt_info.get("server_label") or "ksadk"),
                 }
+                # 透传 HumanInTheLoopMiddleware 的可读描述和允许决策类型，
+                # 供前端审批卡展示操作说明和 edit 按钮。
+                if interrupt_info.get("description"):
+                    approval_item["description"] = str(interrupt_info.get("description"))
+                review_configs = interrupt_info.get("review_configs")
+                if isinstance(review_configs, list) and review_configs:
+                    first_review = review_configs[0]
+                    if isinstance(first_review, Mapping):
+                        allowed = first_review.get("allowed_decisions")
+                        if isinstance(allowed, list) and allowed:
+                            approval_item["allowed_decisions"] = [
+                                str(d) for d in allowed
+                            ]
                 approval_output_index = _next_output_index()
                 yield _response_sse(
                     "response.output_item.added",

ksadk/deployment/env_forward.py

@@ -1,7 +1,7 @@
 """部署时的 shell 进程环境变量转发规则。
 
 通用 deploy (serverless/kcf/kce) 与 hermes/openclaw deploy 共用同一套规则：
-按前缀 (KSADK_/OPENAI_/KSYUN_/E2B_) + 显式 allowlist 转发 shell 环境变量，
+按前缀 (KSADK_/OPENAI_/KSYUN_/E2B_/AGENTENGINE_/AGENTKIT_) + 显式 allowlist 转发 shell 环境变量，
 denylist 中的 CLI/builders/configs/web 模块本地键不转发。
 """
 
@@ -37,7 +37,7 @@ DEPLOY_PROCESS_ENV_ALLOWLIST = frozenset(
         "KSYUN_SECRET_KEY",
     }
 )
-DEPLOY_PROCESS_ENV_PREFIXES = ("KSADK_", "OPENAI_", "KSYUN_", "E2B_")
+DEPLOY_PROCESS_ENV_PREFIXES = ("KSADK_", "OPENAI_", "KSYUN_", "E2B_", "AGENTENGINE_", "AGENTKIT_")
 DEPLOY_PROCESS_ENV_DENYLIST = frozenset(
     {spec.name for spec in ENV_VAR_REGISTRY if spec.module in {"builders", "cli", "configs", "web"}}
 ) | frozenset(

ksadk/deployment/providers/serverless.py

@@ -49,7 +49,7 @@ logger = logging.getLogger(__name__)
 _HOSTED_CODE_COMMAND = (
     "ksadk",
     "web",
-    "/app/code/runtime",
+    "/app/code",
     "--port",
     "8080",
     "--host",