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

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"),
@@ -203,6 +205,8 @@ async def _stream_conversation_semantic_events(
                     event.get("metadata") if isinstance(event.get("metadata"), Mapping) else None
                 ),
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.completed", final_payload)
 
@@ -228,6 +232,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 +481,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 +512,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 +527,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 +539,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 +576,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",
@@ -608,6 +628,8 @@ async def _stream_responses_semantic_events(
                 status="failed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 error={"message": event.get("message") or "Agent 运行失败"},
             )
             yield _response_sse("response.failed", failed_payload)
@@ -623,6 +645,8 @@ async def _stream_responses_semantic_events(
                 status="cancelled",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
             )
             yield _response_sse("response.cancelled", cancelled_payload)
             return
@@ -686,6 +710,8 @@ async def _stream_responses_semantic_events(
                 status="completed",
                 metadata=response_metadata,
                 usage=event.get("usage") if isinstance(event.get("usage"), Mapping) else None,
+                timing=event.get("timing") if isinstance(event.get("timing"), Mapping) else None,
+                skill_eval_result=event.get("skill_eval_result"),
                 output_items=(
                     event.get("responses_output")
                     if isinstance(event.get("responses_output"), Sequence)

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/adapters/_codex_items.py

@@ -42,6 +42,7 @@ from ksadk.events.identity import stable_event_id, stable_item_id, stable_part_i
 
 _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     account/login/completed account/rateLimits/updated account/updated app/list/updated
+    autoApprovalReview/strictReviewRequired
     command/exec/outputDelta configWarning deprecationNotice error
     externalAgentConfig/import/completed externalAgentConfig/import/progress fs/changed
     fuzzyFileSearch/sessionCompleted fuzzyFileSearch/sessionUpdated guardianWarning
@@ -50,16 +51,23 @@ _CODEX_0_147_0_NOTIFICATION_METHODS = frozenset("""
     item/commandExecution/terminalInteraction item/completed item/fileChange/outputDelta
     item/fileChange/patchUpdated item/mcpToolCall/progress item/plan/delta
     item/reasoning/summaryPartAdded item/reasoning/summaryTextDelta item/reasoning/textDelta
-    item/started mcpServer/oauthLogin/completed mcpServer/startupStatus/updated
-    model/rerouted model/safetyBuffering/updated model/verification process/exited
-    process/outputDelta remoteControl/status/changed serverRequest/resolved skills/changed
-    thread/archived thread/closed thread/compacted thread/deleted thread/goal/cleared
-    thread/environment/connected thread/environment/disconnected
-    thread/goal/updated thread/name/updated thread/realtime/closed thread/realtime/error
+    item/started mcpServer/event/stream/notification mcpServer/oauthLogin/completed
+    mcpServer/startupStatus/updated
+    model/rerouted model/safetyBuffering/updated model/verification
+    modelProvider/authRecoveryCompleted modelProvider/authRecoveryStarted
+    process/exited process/outputDelta project/changed
+    remoteControl/status/changed serverRequest/resolved skills/changed
+    thread/archived thread/attachment/updated thread/closed thread/compacted thread/deleted
+    thread/goal/cleared thread/environment/connected thread/environment/disconnected
+    thread/goal/updated thread/name/updated thread/project/updated thread/queue/changed
+    thread/realtime/closed thread/realtime/error
+    thread/realtime/item/completed thread/realtime/item/started
+    thread/realtime/item/transcript/delta
     thread/realtime/itemAdded thread/realtime/outputAudio/delta thread/realtime/sdp
     thread/realtime/started thread/realtime/transcript/delta thread/realtime/transcript/done
-    thread/settings/updated thread/started thread/status/changed thread/tokenUsage/updated
-    thread/unarchived turn/completed turn/diff/updated turn/moderationMetadata
+    thread/reverted thread/settings/updated thread/started thread/status/changed
+    thread/tokenUsage/updated thread/unarchived turn/completed turn/diff/updated
+    turn/moderationMetadata
     turn/plan/updated turn/started warning windows/worldWritableWarning
     windowsSandbox/setupCompleted
     """.split())

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)

ksadk/events/adapters/_langgraph_support.py

@@ -17,6 +17,7 @@ from ksadk.events.canonical import (
     ItemUpdated,
     RuntimeEvent,
     SourceRef,
+    UsageReported,
 )
 from ksadk.events.content import (
     ContentSnapshot,
@@ -32,6 +33,7 @@ from ksadk.events.identity import (
     stable_part_id,
     stable_scope_id,
 )
+from ksadk.runners.base_runner import BaseRunner
 
 # Native content-block types that carry a tool call identity.
 _TOOL_CALL_BLOCKS = frozenset(
@@ -423,9 +425,41 @@ def _map_whole_message(
                 ),
             )
         )
+    usage = BaseRunner._message_usage(payload)
+    if usage:
+        usage_item_id = stable_item_id("langgraph", state.scope_id, "$run")
+        emitted.append(
+            UsageReported(
+                **env(
+                    state.scope_id,
+                    state.parent_scope_id,
+                    usage_item_id,
+                    "usage.reported",
+                    "usage",
+                    source,
+                ),
+                input_tokens=usage["input_tokens"],
+                output_tokens=usage["output_tokens"],
+                total_tokens=usage["total_tokens"],
+                cached_tokens=_usage_detail(usage.get("input_token_details"), "cached"),
+                reasoning_tokens=_usage_detail(usage.get("output_token_details"), "reasoning"),
+            )
+        )
     return tuple(emitted)
 
 
+def _usage_detail(details: Any, key: str) -> int:
+    if not isinstance(details, Mapping):
+        return 0
+    value = details.get(key)
+    if value is None and key == "cached":
+        value = details.get("cache_read") or details.get("cached_tokens")
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
 def _envelope(
     context: LangGraphAdapterContext,
     occurrence_key: str,

ksadk/events/adapters/langgraph.py

@@ -87,6 +87,7 @@ class LangGraphEventAdapter:
     def __init__(self) -> None:
         self._messages: dict[tuple[str, str], _MessageState] = {}
         self._tools: dict[tuple[str, str], _ToolState] = {}
+        self._tool_occurrences: dict[tuple[str, str], int] = {}
         self._lifecycles: dict[str, _LifecycleState] = {}
 
     async def stream_run(
@@ -331,7 +332,20 @@ class LangGraphEventAdapter:
                     f"LangGraph tool call {call_id!r} started twice",
                 )
             name = _required_string(payload.get("tool_name"), "tools tool_name")
-            item_id = stable_item_id("langgraph", frame.scope_id, "tool_result", call_id)
+            occurrence = self._tool_occurrences.get(state_key, 0)
+            self._tool_occurrences[state_key] = occurrence + 1
+            item_id = (
+                stable_item_id("langgraph", frame.scope_id, "tool_result", call_id)
+                if occurrence == 0
+                else stable_item_id(
+                    "langgraph",
+                    frame.scope_id,
+                    "tool_result",
+                    call_id,
+                    "occurrence",
+                    frame.occurrence_key,
+                )
+            )
             self._tools[state_key] = _ToolState(
                 scope_id=frame.scope_id,
                 parent_scope_id=frame.parent_scope_id,

ksadk/events/canonical_store.py

@@ -158,7 +158,9 @@ class RuntimeEventStore:
             self._typed_session_id = session_id
         else:
             self._event_store = None
-            self._service = store
+            # A live-first session wrapper may expose one durable authority for
+            # canonical facts without claiming that its dual writes are atomic.
+            self._service = getattr(store, "canonical_event_service", store)
             self._typed_session_id = session_id
 
     @property

ksadk/events/projections.py

@@ -23,7 +23,7 @@ canonical store（``ksadk/events/canonical_store.py`` 及 ``canonical.py`` 的
 | Responses 历史 | ``conversations/context.py::project_responses_history`` | Responses API 请求回放 input | OpenAI Responses input items（``type``/``call_id``/``output``/role 消息），仅可靠 call_id 的 tool 项 |
 | 模型 history | ``conversations/context.py::project_model_messages`` | 运行时模型上下文（内部投喂） | ``role``/``content`` 消息列表；control 事件不进入上下文 |
 | server checkpoint payload | ``server/routes/projection.py::_checkpoint_event_to_action_payload`` | REST 断点续跑/预览接口 | ``EventId``/``SessionId``/``RunId``/``CheckpointId``/``Framework``/``FrameworkRef``/``IsResumable``/``ResumeStatus``/``IsTerminal``/``NextNode``（经 ``run_checkpoint`` 元数据或 ``continuation.created`` 投影） |
-| server 动作事件 payload | ``server/routes/projection.py::_event_to_action_payload`` | REST 会话动作接口（事件原始形态透传） | ``EventId``/``SessionId``/``Author``/``EventType``/``Content``/``Timestamp``/``SeqId``（可选 ``InvocationId``）——序列化存储形态本身，非 canonical 派生 |
+| server 动作事件 payload | ``server/routes/projection.py::_event_to_action_payload`` | REST 会话动作接口（事件原始形态透传） | ``EventId``/``SessionId``/``Author``/``EventType``/``Content``/``Timestamp``/``SeqId``（可选 ``InvocationId``）——序列化存储形态本身，非 canonical 派生；canonical runtime 事件额外注入 ``Content.parts[0].text`` 兼容旧前端 |
 
 内部不保证（任何投影都不承诺、消费方不得依赖）：
 - ``seq``/``run_seq`` 的具体数值与连续性（仅保序语义）；

ksadk/events/session_event.py

@@ -1,4 +1,4 @@
-"""Generic single-log SessionEvent store port（Phase 1 Task 2）。
+"""Generic single-log SessionEvent store port（Kernel Task 2）。
 
 把 control/runtime/workflow 等 family 的 ``SessionEventEnvelope/v1`` 收敛进
 同一个 session event log，复用 Session backend 的原子 per-session seq。
@@ -79,7 +79,7 @@ def validate_write_guard(
     """Typed write permission: no bare booleans, no nullable fences.
 
     AdmissionWriteGuard 只允许 admission 产生的 ``control.command_accepted`` /
-    ``control.command_rejected``。ActivationWriteGuard 在 Phase 1 允许
+    ``control.command_rejected``。ActivationWriteGuard 在 Kernel 允许
     worker/control/runtime facts；activation_id/fencing_token 与 lease 的
     事务内比较由 Task 3 的 AgentKernelStore 承接。
     """

ksadk/harness/__init__.py

@@ -22,10 +22,24 @@ _EXPORTS = {
     "HarnessReasoningTurn": ("ksadk.harness.reasoner", "HarnessReasoningTurn"),
     "HarnessToolCall": ("ksadk.harness.reasoner", "HarnessToolCall"),
     "LiteLLMHarnessReasoner": ("ksadk.harness.reasoner", "LiteLLMHarnessReasoner"),
+    "AcceptanceCheck": ("ksadk.harness.run_control", "AcceptanceCheck"),
+    "MilestoneSpec": ("ksadk.harness.run_control", "MilestoneSpec"),
+    "RunControlSpec": ("ksadk.harness.run_control", "RunControlSpec"),
+    "RunLimits": ("ksadk.harness.run_control", "RunLimits"),
+    "StagnationPolicy": ("ksadk.harness.run_control", "StagnationPolicy"),
     "HarnessRuntime": ("ksadk.harness.runtime", "HarnessRuntime"),
     "HarnessRuntimeAdapter": ("ksadk.harness.runtime", "HarnessRuntimeAdapter"),
     "HarnessSandboxExecutor": ("ksadk.harness.sandbox", "HarnessSandboxExecutor"),
     "SandboxPolicyDenied": ("ksadk.harness.sandbox", "SandboxPolicyDenied"),
+    "ToolDeliverySemantics": (
+        "ksadk.harness.tool_reliability",
+        "ToolDeliverySemantics",
+    ),
+    "ToolReliability": ("ksadk.harness.tool_reliability", "ToolReliability"),
+    "classify_tool_reliability": (
+        "ksadk.harness.tool_reliability",
+        "classify_tool_reliability",
+    ),
 }
 
 __all__ = list(_EXPORTS)

ksadk/harness/app.py

@@ -10,6 +10,7 @@ from typing import Any, Callable, Optional, Protocol, Sequence
 from fastapi import FastAPI
 
 from ksadk.harness.config import HarnessConfig
+from ksadk.harness.insights import HarnessInsightsRegistry, mount_insights
 from ksadk.harness.reasoner import HarnessReasoner
 from ksadk.harness.runtime import HarnessRuntimeAdapter
 from ksadk.runtime import (
@@ -88,6 +89,8 @@ class HarnessApp:
         registry = RuntimeRegistry()
         registry.register(self._runtime_type, lambda _context: self.adapter())
         self._executor = RuntimeExecutor(registry)
+        # P3 补强：长任务洞察登记处（Studio 经 /insights API 消费）。
+        self._insights = HarnessInsightsRegistry()
 
         from ksadk.sessions import create_session_service
 
@@ -120,6 +123,11 @@ class HarnessApp:
     def executor(self) -> RuntimeExecutor:
         return self._executor
 
+    @property
+    def insights(self) -> HarnessInsightsRegistry:
+        """长任务洞察登记处（context-trace / token-report 的数据源）。"""
+        return self._insights
+
     @property
     def launch_context(self) -> RuntimeLaunchContext:
         return self._launch_context
@@ -260,6 +268,9 @@ class HarnessApp:
         )
         app.state.runtime.session_service = self._session_service
         app.state.runtime.harness_capabilities = self._capabilities
+        # P3 补强：Studio 消费端（长任务方案 §3.2）——/insights/runs/...
+        # 的 context-trace / token-report / compaction-trace 纯 dict 投影。
+        mount_insights(app, self._insights)
         for plugin in self._plugins:
             plugin.after_build(app, self._config)
         self._fastapi_app = app