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

ksadk/conversations/reducer.py

@@ -0,0 +1,98 @@
+"""Identity-aware reducer for a ConversationItem surface.
+
+This reducer deliberately does not deduplicate by author or text.  Providers
+may emit the same content in two different items, and both are user-visible
+truth.  Reconnect de-duplication is limited to a previously applied source
+event for the same item.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from ksadk.conversations.contracts import ConversationItem
+
+
+class ConversationItemReducer:
+    """Apply append/replace/completed operations while preserving item identity."""
+
+    def __init__(self) -> None:
+        self._items: OrderedDict[str, ConversationItem] = OrderedDict()
+        self._source_events: set[tuple[str, str]] = set()
+
+    def apply(self, item: ConversationItem) -> bool:
+        """Apply one item operation and return whether this changed the view."""
+
+        keys = {(item.item_id, source_id) for source_id in item.source_event_ids}
+        if keys and keys.issubset(self._source_events):
+            return False
+
+        existing = self._items.get(item.item_id)
+        if existing is not None and _terminal(existing) and not _terminal(item):
+            # A reconnect may replay an older delta after the terminal snapshot
+            # has already arrived on the live connection.  Remember its event
+            # identity, but never regress a completed item back to streaming or
+            # append the stale delta a second time.
+            self._source_events.update(keys)
+            return False
+        if existing is None:
+            merged = item
+        elif item.operation == "append":
+            merged = item.model_copy(
+                update={
+                    "payload": _append_payload(existing.payload, item.payload),
+                    "source_event_ids": _merge_sources(
+                        existing.source_event_ids,
+                        item.source_event_ids,
+                    ),
+                }
+            )
+        else:
+            merged = item.model_copy(
+                update={
+                    "source_event_ids": _merge_sources(
+                        existing.source_event_ids,
+                        item.source_event_ids,
+                    )
+                }
+            )
+        self._items[item.item_id] = merged
+        self._source_events.update(keys)
+        return True
+
+    def items(self) -> tuple[ConversationItem, ...]:
+        """Return presentation items in first-seen order."""
+
+        return tuple(self._items.values())
+
+
+def _append_payload(
+    existing: dict[str, object],
+    update: dict[str, object],
+) -> dict[str, object]:
+    merged = dict(existing)
+    for key, value in update.items():
+        previous = merged.get(key)
+        if key == "text" and isinstance(previous, str) and isinstance(value, str):
+            merged[key] = previous + value
+        elif key in {"data", "operations"} and isinstance(previous, list) and isinstance(
+            value, list
+        ):
+            merged[key] = [*previous, *value]
+        else:
+            merged[key] = value
+    return merged
+
+
+def _merge_sources(
+    current: tuple[str, ...],
+    incoming: tuple[str, ...],
+) -> tuple[str, ...]:
+    return tuple(dict.fromkeys((*current, *incoming)))
+
+
+def _terminal(item: ConversationItem) -> bool:
+    return item.lifecycle in {"completed", "failed"}
+
+
+__all__ = ["ConversationItemReducer"]

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",

ksadk/events/_v1_compat/projection.py

@@ -370,6 +370,8 @@ def _project_item_completed(
     if text_projection or event.item_kind in {"message", "reasoning"}:
         return text_projection
     if event.item_kind == "data":
+        if event.source.metadata.get("operation_batch") is True:
+            return ()
         ref = _a2ui_surface_ref(event, context)
         if ref is None:
             return ()

ksadk/events/adapters/_codex_validators.py

@@ -8,15 +8,19 @@ from typing import Any, Literal, NoReturn, cast
 
 from pydantic import JsonValue
 
-_CODEX_ERROR_INFO_VALUES = frozenset("""
+_CODEX_ERROR_INFO_VALUES = frozenset(
+    """
     contextWindowExceeded sessionBudgetExceeded usageLimitExceeded serverOverloaded
     cyberPolicy internalServerError unauthorized badRequest threadRollbackFailed
     sandboxError other
-    """.split())
-_CODEX_ERROR_INFO_VARIANTS = frozenset("""
+    """.split()
+)
+_CODEX_ERROR_INFO_VARIANTS = frozenset(
+    """
     httpConnectionFailed responseStreamConnectionFailed responseStreamDisconnected
     responseTooManyFailedAttempts activeTurnNotSteerable
-    """.split())
+    """.split()
+)
 
 
 class CodexMappingError(ValueError):
@@ -151,16 +155,23 @@ def _question_schema(
                     )
                 )
                 option_details.append(_json_value(option))
+        multiple = bool(question.get("isMultiSelect", False))
+        allow_other = bool(question.get("isOther", False))
         property_schema: dict[str, JsonValue] = {
-            "type": "string",
+            "type": "array" if multiple else "string",
             "title": header,
             "description": prompt,
             "x-codex-options": option_details,
             "x-codex-is-secret": is_secret,
             "x-codex-is-other": bool(question.get("isOther", False)),
         }
-        if labels:
-            property_schema["enum"] = cast(JsonValue, labels)
+        value_schema: dict[str, JsonValue] = {"type": "string", "minLength": 1}
+        if labels and not allow_other:
+            value_schema["enum"] = cast(JsonValue, labels)
+        if multiple:
+            property_schema.update({"items": value_schema, "minItems": 1, "uniqueItems": True})
+        else:
+            property_schema.update(value_schema)
         properties[question_id] = property_schema
         required.append(question_id)
         prompts.append(prompt)