agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

ksadk/runners/base_runner.py

@@ -18,7 +18,8 @@ class BaseRunner(ABC):
     def __init__(self, detection_result: Any, project_dir: str):
         self.detection_result = detection_result
         self.project_dir = project_dir
-        self._agent = None
+        # Framework runners populate this with SDK-specific agent/graph objects.
+        self._agent: Any = None
 
     @abstractmethod
     def load_agent(self) -> None:
@@ -38,7 +39,7 @@ class BaseRunner(ABC):
         pass
 
     @abstractmethod
-    async def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
+    def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
         """流式调用 Agent
 
         Args:
@@ -47,7 +48,7 @@ class BaseRunner(ABC):
         Yields:
             流式输出的数据块
         """
-        pass
+        raise NotImplementedError
 
     @staticmethod
     def normalize_requested_model(model: Optional[str]) -> Optional[str]:
@@ -108,23 +109,28 @@ class BaseRunner(ABC):
                     if cancel_supported
                     else ["unsupported"]
                 ),
-                "Reason": ""
-                if cancel_supported
-                else "runner does not implement cooperative cancellation",
+                "Reason": (
+                    "" if cancel_supported else "runner does not implement cooperative cancellation"
+                ),
             },
             "Checkpoint": checkpoint,
             "ResumeRun": {
                 "Supported": checkpoint_supported,
                 "ResumeMode": str(checkpoint.get("ResumeMode") or "none"),
-                "Reason": checkpoint_reason
-                if not checkpoint_supported
-                else str(checkpoint.get("ResumeReason") or ""),
+                "Reason": (
+                    checkpoint_reason
+                    if not checkpoint_supported
+                    else str(checkpoint.get("ResumeReason") or "")
+                ),
             },
             "SessionContinuity": {
                 "Supported": True,
                 "Type": "semantic_replay",
                 "Level": "semantic",
-                "Reason": "conversation transcript can be replayed, but exact runtime checkpoint resume is not available",
+                "Reason": (
+                    "conversation transcript can be replayed, but exact runtime checkpoint "
+                    "resume is not available"
+                ),
             },
         }
 
@@ -193,15 +199,15 @@ class BaseRunner(ABC):
         if isinstance(usage_metadata, Mapping):
             input_tokens = cls._int_usage_value(usage_metadata.get("input_tokens"))
             output_tokens = cls._int_usage_value(usage_metadata.get("output_tokens"))
-            input_token_details = usage_metadata.get("input_token_details")
-            output_token_details = usage_metadata.get("output_token_details")
-            if not any(
-                key in usage_metadata
-                for key in ("input_tokens", "output_tokens", "total_tokens")
-            ) and not (
-                isinstance(input_token_details, Mapping) and input_token_details
-            ) and not (
-                isinstance(output_token_details, Mapping) and output_token_details
+            usage_input_details = usage_metadata.get("input_token_details")
+            usage_output_details = usage_metadata.get("output_token_details")
+            if (
+                not any(
+                    key in usage_metadata
+                    for key in ("input_tokens", "output_tokens", "total_tokens")
+                )
+                and not (isinstance(usage_input_details, Mapping) and usage_input_details)
+                and not (isinstance(usage_output_details, Mapping) and usage_output_details)
             ):
                 return {}
             return {
@@ -211,10 +217,10 @@ class BaseRunner(ABC):
                     usage_metadata.get("total_tokens") or (input_tokens + output_tokens)
                 ),
                 "input_token_details": (
-                    dict(input_token_details) if isinstance(input_token_details, Mapping) else {}
+                    dict(usage_input_details) if isinstance(usage_input_details, Mapping) else {}
                 ),
                 "output_token_details": (
-                    dict(output_token_details) if isinstance(output_token_details, Mapping) else {}
+                    dict(usage_output_details) if isinstance(usage_output_details, Mapping) else {}
                 ),
             }
 
@@ -237,10 +243,14 @@ class BaseRunner(ABC):
                     reasoning_tokens = completion_details.get("reasoning_tokens")
                     if reasoning_tokens is not None:
                         output_token_details["reasoning"] = cls._int_usage_value(reasoning_tokens)
-                if not any(
-                    key in token_usage
-                    for key in ("prompt_tokens", "completion_tokens", "total_tokens")
-                ) and not input_token_details and not output_token_details:
+                if (
+                    not any(
+                        key in token_usage
+                        for key in ("prompt_tokens", "completion_tokens", "total_tokens")
+                    )
+                    and not input_token_details
+                    and not output_token_details
+                ):
                     return {}
                 return {
                     "input_tokens": input_tokens,
@@ -295,11 +305,18 @@ class BaseRunner(ABC):
         usage = cls._message_usage(result)
         return usage if usage else {}
 
-
     def run_server(self, port: int = 8000) -> None:
-        """启动 HTTP Server"""
-        from ksadk.server import app, set_runner
+        """启动 HTTP Server(per-app factory,不再依赖 set_runner 全局态)。"""
         import uvicorn
 
-        set_runner(self)
+        from ksadk.agui.config import default_agui_config
+        from ksadk.server.composition import configure_runtime_app
+        from ksadk.server.factory import RuntimeAppConfig, create_runtime_app
+
+        # goal-01/16:经 create_runtime_app 注入 runner(per-app state),替代全局 ``app`` +
+        # ``set_runner`` 全局态。普通 runtime app 装配全部 route group。
+        app = create_runtime_app(
+            RuntimeAppConfig(runner=self, agui=default_agui_config(self)),
+            configure_runtime_app,
+        )
         uvicorn.run(app, host="0.0.0.0", port=port)

ksadk/runners/codex_runner.py

@@ -0,0 +1,132 @@
+"""CodexRunner — 把 codex runtime(CodexRuntime,RuntimeAdapter)适配成 BaseRunner。
+
+让 codex 项目能像 ADK/LangGraph 一样经 `ksadk web` 起 hosted UI:``create_runner``
+返回本 runner → ``run_server`` 走 ``create_runtime_app`` → /run_sse 与 AGUI 都走它。
+
+适配方向:``CodexRuntime.stream`` 产出 ``RuntimeEvent``(TEXT_DELTA/RUN_COMPLETED/…),
+本 runner 反向投射成 ADK-style 扁平 dict(``/run_sse`` 期望的 type 词表
+text/thinking/interrupt/final),与 ``ADKRunner.stream`` 产出形状一致。AGUI 路径经
+``RunnerRuntimeAdapter`` 把本 runner 包回 ``RuntimeAdapter``(``_chunk_to_event`` 已覆盖
+全部 type),无需新代码。
+
+codex thread 是 ephemeral(``ksadk/codex/client.py`` ``ephemeral=True``),不支持 resume。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any, AsyncIterator, Dict
+
+from ksadk.codex.client import AsyncCodexClient
+from ksadk.codex.runtime import CodexRuntime
+from ksadk.events.runtime_event import EventType
+from ksadk.runners.base_runner import BaseRunner
+from ksadk.runtime.adapter import RunHandle, StartRequest
+
+
+class CodexRunner(BaseRunner):
+    """codex 的 BaseRunner 适配。"""
+
+    def __init__(self, detection_result: Any, project_dir: str) -> None:
+        super().__init__(detection_result, project_dir)
+        # opt-in 代理(env KSADK_CODEX_USE_PROXY=1)在 client 构造时自动注入 provider
+        self._client = AsyncCodexClient()
+        self._runtime = CodexRuntime(self._client, sandbox_read_only=True)
+        # invocation_id -> RunHandle(stream 期间持有,cancel 用)
+        self._handles: dict[str, RunHandle] = {}
+
+    def load_agent(self) -> None:
+        # codex 无 root_agent 变量;agent 逻辑由 prompt 承载,无需加载
+        self._agent = True
+
+    async def invoke(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        output = ""
+        usage: dict[str, Any] = {}
+        async for chunk in self.stream(input_data):
+            if chunk.get("type") == "final":
+                output = chunk.get("output", "") or output
+                if chunk.get("usage"):
+                    usage = chunk["usage"]
+        return {"output": output, "usage": usage}
+
+    def stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
+        return self._stream(input_data)
+
+    async def _stream(self, input_data: Dict[str, Any]) -> AsyncIterator[Dict[str, Any]]:
+        prompt = str(input_data.get("input") or "")
+        session_id = str(input_data.get("session_id") or uuid.uuid4().hex)
+        # model:本轮请求优先,fallback 到 yaml(raw_config);prompt:codex 的 base_instructions
+        raw = getattr(self.detection_result, "raw_config", None) or {}
+        model = input_data.get("model") or raw.get("model")
+        base_instructions = raw.get("prompt")
+        if model:
+            self.sync_process_model_env(str(model))
+        config: Dict[str, Any] = {"sandbox_read_only": True}
+        if base_instructions:
+            config["base_instructions"] = str(base_instructions)
+        request = StartRequest(
+            input=prompt,
+            user_id="local",
+            session_id=session_id,
+            model=str(model) if model else None,
+            config=config,
+        )
+        handle = await self._runtime.start(request)
+        self._handles[handle.run_id] = handle
+        try:
+            accumulated = ""          # TEXT_DELTA 累积(流式增量,前端打字机用)
+            completed_text = ""       # 最后一次 TEXT_COMPLETED 的全文(权威,防 delta 丢包)
+            final_sent = False
+            async for event in self._runtime.stream(handle):
+                et = event.event_type
+                payload = event.payload or {}
+                if et == EventType.TEXT_DELTA:
+                    phase = event.phase or "commentary"
+                    delta = payload.get("text", "")
+                    # final_answer 的 delta 当 text 流(前端打字机);commentary 当 thinking
+                    if phase == "final_answer":
+                        accumulated += delta
+                        yield {"type": "text", "delta": delta}
+                    else:
+                        yield {"type": "thinking", "delta": delta}
+                elif et == EventType.TEXT_COMPLETED:
+                    # 收尾全文:权威,记下来给 final 用;不当 delta 发(前端已通过 delta 收到)。
+                    # 只收 final_answer(真正的回复);commentary completed 是思考收尾,忽略。
+                    phase = event.phase or "final_answer"
+                    if phase == "final_answer":
+                        completed_text = payload.get("text", "")
+                elif et == EventType.RUN_COMPLETED:
+                    final_sent = True
+                    # final.output 优先用 completed 全文,fallback accumulated(delta 流)
+                    yield {"type": "final", "output": completed_text or accumulated}
+                elif et == EventType.RUN_FAILED:
+                    final_sent = True
+                    yield {"type": "final", "output": completed_text or accumulated,
+                           "error": payload.get("error", "codex run failed")}
+                elif et == EventType.RUN_INTERRUPTED:
+                    yield {"type": "interrupt", "reason": "interrupted"}
+                elif et == EventType.RUN_CANCELED:
+                    yield {"type": "interrupt", "reason": "canceled"}
+            if not final_sent:
+                yield {"type": "final", "output": completed_text or accumulated}
+        finally:
+            self._handles.pop(handle.run_id, None)
+
+    def request_cancel(self, invocation_id: str) -> str:
+        handle = self._handles.get(invocation_id)
+        if handle is None:
+            return "not_running"
+        result: Any
+        try:
+            result = asyncio.run(self._runtime.cancel(handle))
+        except RuntimeError:
+            # 已有事件循环(异步上下文):用独立线程跑 cancel,避免嵌套 asyncio.run
+            result = asyncio.run(asyncio.to_thread(self._runtime.cancel, handle))
+        return str(getattr(result, "value", result))
+
+    async def close(self) -> None:
+        try:
+            await self._client.close()
+        except Exception:  # noqa: BLE001
+            pass

ksadk/runners/deepagents_runner.py

@@ -10,4 +10,3 @@ from ksadk.runners.langgraph_runner import LangGraphRunner
 
 class DeepAgentsRunner(LangGraphRunner):
     """DeepAgents 运行时（复用 LangGraphRunner）"""
-

ksadk/runners/factory.py

@@ -6,6 +6,7 @@ import importlib
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
+
 from ksadk.detection import DetectionResult, FrameworkType
 from ksadk.runners.base_runner import BaseRunner
 
@@ -15,11 +16,11 @@ if TYPE_CHECKING:
 
 def create_runner(detection_result: DetectionResult, project_dir: str) -> BaseRunner:
     """根据检测结果创建对应的 Runner
-    
+
     Args:
         detection_result: 框架检测结果
         project_dir: 项目目录
-    
+
     Returns:
         对应框架的 Runner 实例
     """
@@ -55,19 +56,30 @@ def create_runner(detection_result: DetectionResult, project_dir: str) -> BaseRu
 
     if detection_result.type == FrameworkType.ADK:
         from ksadk.runners.adk_runner import ADKRunner
+
         return ADKRunner(detection_result, project_dir)
-    
+
     elif detection_result.type == FrameworkType.LANGGRAPH:
         from ksadk.runners.langgraph_runner import LangGraphRunner
+
         return LangGraphRunner(detection_result, project_dir)
-    
+
     elif detection_result.type == FrameworkType.LANGCHAIN:
+        # 新 LangChain(create_agent)= LangGraph 图,经 LangChainRunner 薄壳复用
+        # LangGraphRunner(deepagents 同款);legacy 链在 load_agent 时被薄壳拒绝并给迁移指引。
         from ksadk.runners.langchain_runner import LangChainRunner
+
         return LangChainRunner(detection_result, project_dir)
 
     elif detection_result.type == FrameworkType.DEEPAGENTS:
         from ksadk.runners.deepagents_runner import DeepAgentsRunner
+
         return DeepAgentsRunner(detection_result, project_dir)
-    
+
+    elif detection_result.type == FrameworkType.CODEX:
+        from ksadk.runners.codex_runner import CodexRunner
+
+        return CodexRunner(detection_result, project_dir)
+
     else:
         raise ValueError(f"不支持的框架类型: {detection_result.type}")