edgeone 1.5.8 → 1.6.0

package/edgeone-dist/pages/templates/agent-python/runtime.py

@@ -0,0 +1,839 @@
+# src/pages/builder/templates/agent-python/runtime.py
+"""Agent runtime — timeout, cancellation, invoke, active-run tracking."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import os
+import time
+import sys
+from dataclasses import dataclass
+from typing import Any, AsyncIterator, Callable, Awaitable, Optional
+from uuid import uuid4
+
+from .context import AgentContext, AbortActiveRunResult, RequestInfo, SandboxRuntimeError, StreamResponse
+
+
+# LangGraph 通过抛出这些异常实现 graph 暂停 / 控制流跳转，并非业务错误。
+# 非流式 ainvoke 命中 interrupt() 时会抛出 GraphInterrupt（Exception 子类），
+# 不能当 AGENT_RUN_ERROR 返回 500，而应作为「已暂停等待人工」的正常响应。
+_INTERRUPT_EXCEPTION_NAMES = frozenset({
+    "GraphInterrupt",
+    "NodeInterrupt",
+    "ParentCommand",
+})
+
+
+def _is_interrupt_exception(err: BaseException) -> bool:
+    """按类继承链（MRO）匹配 LangGraph 控制流异常名。"""
+    for cls in type(err).__mro__:
+        if cls.__name__ in _INTERRUPT_EXCEPTION_NAMES:
+            return True
+    return False
+
+
+def _json_safe(value: Any) -> Any:
+    """确保对象可被 json 序列化，不行就退化为 default=str。"""
+    try:
+        json.dumps(value)
+        return value
+    except (TypeError, ValueError):
+        try:
+            return json.loads(json.dumps(value, default=str))
+        except Exception:
+            return str(value)
+
+
+def _serialize_interrupt(err: BaseException) -> Any:
+    """尽力从 GraphInterrupt 中提取 interrupt payload 透传给前端。
+
+    GraphInterrupt 通常把一组 Interrupt 对象放在 ``err.args[0]``，每个对象有
+    ``value`` / ``id``（或 ``interrupt_id``）字段。提取失败时退化为 str。
+    """
+    try:
+        args = getattr(err, "args", None) or ()
+        if len(args) == 1 and isinstance(args[0], (list, tuple)):
+            items = list(args[0])
+        elif args:
+            items = list(args)
+        else:
+            return None
+        out = []
+        for it in items:
+            value = getattr(it, "value", it)
+            ident = getattr(it, "id", None) or getattr(it, "interrupt_id", None)
+            entry: dict[str, Any] = {"value": _json_safe(value)}
+            if ident is not None:
+                entry["id"] = _json_safe(ident)
+            out.append(entry)
+        return out
+    except Exception:
+        return str(err)
+
+
+# --- Observability tracer (lazy, no-op if unavailable) ---
+def _get_obs_tracer():
+    """Get the agent tracer (or None if observability not active)."""
+    try:
+        from _platform._observability import get_tracer
+        return get_tracer()
+    except (ImportError, Exception):
+        return None
+
+
+@dataclass
+class RouteEntry:
+    handler: Callable[[AgentContext], Awaitable[Any]]
+    is_index: bool
+    module_path: str
+
+
+@dataclass
+class RuntimeResult:
+    """Runtime → adapter 的统一结果对象。
+
+    body 可以是：
+      - None / str / dict / list 等 → adapter 一次性发送（旧行为）
+      - StreamResponse 实例         → adapter 多次 send chunk（流式）
+
+    流式响应的 status / headers 必须在第一个 chunk 发送之前就确定，
+    因为 ASGI 的 http.response.start 只能发一次。所以即使 body 是
+    streaming，status/headers 仍然在 RuntimeResult 顶层固定。
+    """
+
+    status: int
+    body: Any
+    headers: dict
+
+    @property
+    def is_streaming(self) -> bool:
+        return isinstance(self.body, StreamResponse)
+
+
+class InvokeError(Exception):
+    def __init__(self, code: str, message: str = "", status: int = 400):
+        self.code = code
+        self.message = message or code
+        self.status = status
+        super().__init__(message)
+
+
+MAX_INVOKE_DEPTH = 6
+
+# 流式响应内部信号头：与 Node `INTERNAL_STREAM_SIGNAL_HEADER` 保持一致，
+# 让上层（CDN / 网关 / 反代）能用 header 而不是 content-type 来判断当前
+# 响应是否为流式，从而做正确的反缓冲处理。业务自定义 headers 不会覆盖
+# 这个值（除非显式重置）。
+INTERNAL_STREAM_SIGNAL_HEADER = "x-content-type-stream"
+
+
+async def _invoke_handler(handler: Callable, context: AgentContext) -> Any:
+    """调用用户 handler，兼容 coroutine function 和 async generator function。
+
+    async generator function 调用后返回 async_generator（不是 coroutine），
+    不能直接传给 asyncio.create_task / asyncio.wait_for。
+    这里统一检测：如果结果是 async generator，直接返回它（让调用方的
+    _coerce_to_stream 识别为流式响应）；否则 await 原始 coroutine 拿到结果。
+    """
+    result = handler(context)
+    if inspect.isasyncgen(result):
+        return result
+    return await result
+
+
+class AgentsApi:
+    def __init__(
+        self,
+        registry: dict[str, RouteEntry],
+        store_resolver: Callable[[str], Any],
+        cancel_fn: Callable[[str], bool] | None = None,
+        store_blob: Any = None,
+        abort_except_fn: Callable[[str, str], AbortActiveRunResult] | None = None,
+    ):
+        self._registry = registry
+        self._store_resolver = store_resolver
+        # runtime.request_cancel 的绑定；AgentsApi 不直接持 AgentRuntime 引用
+        # 避免循环依赖。业务 agent 通过 ctx.agents.abort_active_run(id) 使用。
+        self._cancel_fn = cancel_fn
+        # runtime.abort_active_run_except 的绑定，用于注入 child context 的
+        # ctx.utils.abortActiveRun，确保 child 调用时也能排除自身 run_id。
+        self._abort_except_fn = abort_except_fn
+        self._store_blob = store_blob
+
+    def abort_active_run(self, conversation_id: str) -> bool:
+        """主动取消另一个 conversation 的活跃 run。
+
+        .. deprecated::
+            请改用 ``ctx.utils.abortActiveRun(conversation_id)``，与 Node agent 的
+            ``ctx.utils.abortActiveRun`` 入口/命名一致，返回结构化
+            ``AbortActiveRunResult`` 而非 bool。本方法仅为向后兼容保留，未来移除。
+
+        返回 True 表示确实取消了一个正在运行的任务；False 表示该
+        conversation_id 下没有活跃任务（已完成/id 错/未注册）。
+
+        典型用法（旧）::
+
+            async def handler(ctx):
+                target = ctx.request.body.get("conversation_id")
+                ok = ctx.agents.abort_active_run(target)
+                return {"status": "aborted" if ok else "idle",
+                        "conversation_id": target}
+
+        推荐写法（新，与 Node 一致）::
+
+            async def handler(ctx):
+                target = ctx.request.body.get("conversation_id") or ""
+                r = ctx.utils.abortActiveRun(target)
+                return {"status": "aborted" if r.aborted else "idle",
+                        "conversation_id": r.conversation_id,
+                        "run_id": r.run_id}
+        """
+        if not self._cancel_fn or not conversation_id:
+            return False
+        return self._cancel_fn(conversation_id)
+
+    async def invoke(
+        self,
+        route_path: str,
+        payload: dict,
+        *,
+        _context: AgentContext,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        # 与 Node `agents.invoke` 对齐：仅禁止「直接调用自身路由」的递归。
+        # A→B→A 这种环不在此处拦截，靠 MAX_INVOKE_DEPTH 兜底（避免误伤合理
+        # 场景，例如 router agent 反向回调入口路由处理子任务）。
+        if route_path == _context._call_chain_self:
+            raise InvokeError(
+                "AGENT_INVOKE_SELF_RECURSION",
+                f"Self recursion is not allowed for route: {route_path}",
+            )
+        if _context._depth >= MAX_INVOKE_DEPTH:
+            raise InvokeError("AGENT_INVOKE_DEPTH_EXCEEDED", f"Max depth {MAX_INVOKE_DEPTH} exceeded")
+        remaining = _context._deadline - time.monotonic()
+        if remaining <= 0:
+            raise InvokeError("AGENT_INVOKE_TIMEOUT_EXHAUSTED", "No remaining timeout budget", status=408)
+        entry = self._registry.get(route_path)
+        if not entry:
+            raise InvokeError("AGENT_INVOKE_NOT_FOUND", f"Route {route_path} not found", status=404)
+
+        child_timeout = min(remaining, timeout) if timeout else remaining
+        child_run_id = str(uuid4())
+        # 给 child context 注入排除自身 run_id 的 abortActiveRun 闭包，与 Node
+        # 的 `abortActiveRun: (target) => abortActiveRunExcept(target, run_id)`
+        # 行为一致。
+        if self._abort_except_fn is not None:
+            _child_abort_fn = lambda target, _rid=child_run_id: self._abort_except_fn(  # type: ignore[misc]
+                target, _rid
+            )
+        else:
+            _child_abort_fn = None
+        child_context = AgentContext(
+            conversation_id=_context.conversation_id,
+            run_id=child_run_id,
+            parent_run_id=_context.run_id,
+            request=RequestInfo(
+                body=payload,
+                headers=_context.request.headers,
+                query=_context.request.query,
+                signal=_context.request.signal,
+            ),
+            env=_context.env,
+            kv=self._store_resolver(route_path),
+            agents=self,
+            # active_run_id 不向 child 传递：child 是「当前 run 内部派生的子调用」，
+            # 沿用 parent 的 active_run_id 反而会让业务误以为有冲突。
+            active_run_id=None,
+            _store_blob=self._store_blob,
+            _deadline=time.monotonic() + child_timeout,
+            _depth=_context._depth + 1,
+            _call_chain=_context._call_chain | {route_path},
+            _call_chain_self=route_path,
+            _abort_active_run_fn=_child_abort_fn,
+            _loop=_context._loop,
+        )
+        return await asyncio.wait_for(_invoke_handler(entry.handler, child_context), timeout=child_timeout)
+
+
+def _log(msg: str) -> None:
+    print(msg, file=sys.stderr, flush=True)
+
+
+def _is_sandbox_error(error: Exception) -> bool:
+    code = str(getattr(error, "code", "") or "")
+    operation = str(getattr(error, "operation", "") or "")
+    name = error.__class__.__name__
+    return isinstance(error, SandboxRuntimeError) or code.startswith("SANDBOX_") or name == "SandboxNotAvailableError" or operation in {"acquire", "update"}
+
+
+def _sandbox_error_payload(error: Exception) -> dict:
+    payload = {
+        "code": getattr(error, "code", None),
+        "operation": getattr(error, "operation", None),
+        "status": getattr(error, "status", None),
+        "businessCode": getattr(error, "business_code", getattr(error, "businessCode", None)),
+        "businessMessage": getattr(error, "business_message", getattr(error, "businessMessage", None)),
+        "requestId": getattr(error, "request_id", getattr(error, "requestId", None)),
+        "retryable": getattr(error, "retryable", None),
+        "details": _sanitize_sandbox_details(getattr(error, "details", None)),
+    }
+    return {k: v for k, v in payload.items() if v is not None and v != ""}
+
+
+def _sanitize_sandbox_details(details):
+    if not isinstance(details, dict):
+        return None
+    blocked = {"sandboxToken", "trafficToken", "envdAccessToken", "authToken", "token", "access_token"}
+    return {key: value for key, value in details.items() if key not in blocked}
+
+
+def _resolve_sandbox_api_env(env: dict, configured_api_env: str = "") -> str | None:
+    for value in (
+        env.get("SANDBOX_API_ENV"),
+        configured_api_env,
+        env.get("API_ENV"),
+    ):
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _sandbox_diagnostics(path: str, headers: dict, env: dict, conversation_id_source: str) -> dict:
+    try:
+        from .runtime_config import AGENT_MODE, SANDBOX_API_ENV
+    except Exception:
+        AGENT_MODE = "prod"
+        SANDBOX_API_ENV = ""
+    return {
+        "route_path": path,
+        "mode": AGENT_MODE or "prod",
+        "expected_conversation_id_header": "makers-conversation-id",
+        "conversation_id_source": conversation_id_source,
+        "has_makers_conversation_id_header": bool(_header(headers, "makers-conversation-id")),
+        "has_edgeone_pages_api_token": bool(env.get("EDGEONE_PAGES_API_TOKEN")),
+        "has_project_id": bool(env.get("PROJECT_ID") or env.get("EDGEONE_PROJECT_ID") or env.get("ProjectId") or env.get("PAGES_PROJECT_ID")),
+        "has_deployment_id": bool(env.get("DEPLOYMENT_ID") or env.get("EDGEONE_DEPLOYMENT_ID") or env.get("PAGES_DEPLOYMENT_ID")),
+        "api_env": _resolve_sandbox_api_env(env, SANDBOX_API_ENV),
+        "sandbox_site": env.get("SANDBOX_SITE") or env.get("EDGEONE_PAGES_API_REGION") or None,
+        "sandbox_region": env.get("SANDBOX_REGION") or env.get("TENCENTCLOUD_REGION") or None,
+        "has_sandbox_api_base": bool(env.get("SANDBOX_API_BASE")),
+        "has_sandbox_domain": bool(env.get("SANDBOX_DOMAIN")),
+    }
+
+
+def _sandbox_suggestion(error: Exception, diagnostics: dict) -> str:
+    code = str(getattr(error, "code", "") or "")
+    if code == "SANDBOX_AUTH_TOKEN_MISSING":
+        if diagnostics.get("mode") == "dev":
+            return "Set EDGEONE_PAGES_API_TOKEN in .env and restart edgeone dev."
+        return "Ensure the deployment pipeline runs `edgeone pages replace` so PAGES_SANDBOX_SEALED_TOKEN is injected before publishing."
+    if code == "SANDBOX_INVALID_AUTH_TOKEN":
+        return "Use a Pages-generated sandbox.v1.* sealed token in production; do not inject a raw API token as the sealed token."
+    if code == "SANDBOX_PROJECT_ID_MISSING":
+        return "Set PROJECT_ID or EDGEONE_PROJECT_ID for local API-token mode, or pass project_id when initializing the sandbox SDK."
+    if code == "SANDBOX_CONVERSATION_ID_MISSING" or diagnostics.get("conversation_id_source") == "generated":
+        return "Forward the makers-conversation-id request header to keep sandbox lifecycle and cache stable across requests."
+    if code in {"SANDBOX_API_ENV_INVALID", "SANDBOX_SITE_INVALID", "SANDBOX_API_BASE_INVALID"}:
+        return "Check SANDBOX_API_BASE, SANDBOX_API_ENV/API_ENV, and SANDBOX_SITE/EDGEONE_PAGES_API_REGION. API env must be test, production, or pre."
+    if code in {"SANDBOX_INSTANCE_EXPIRED", "SANDBOX_INSTANCE_NOT_FOUND"}:
+        return "Retry the request. The toolkit has invalidated the cached sandbox instance; increase sandbox timeout if this happens frequently."
+    return "Check sandbox diagnostics and runtime logs. If the error includes requestId, provide it to sandbox backend support."
+
+
+class AgentRuntime:
+    def __init__(
+        self,
+        registry: dict[str, RouteEntry],
+        store_resolver: Callable[[str], Any],
+        timeout: int = 300,
+        store_blob: Any = None,
+        failed_routes: Optional[dict[str, str]] = None,
+    ):
+        self._registry = registry
+        self._store_resolver = store_resolver
+        self._timeout = timeout
+        self._store_blob = store_blob
+        # 加载失败的路由信息：route_path → 失败原因。404 响应时回显，
+        # 帮助用户快速发现"路由文件存在但因依赖缺失/语法错被跳过"的情况。
+        self._failed_routes: dict[str, str] = failed_routes or {}
+        self._active_runs: dict[str, str] = {}  # conversation_id → run_id
+        self._active_tasks: dict[str, asyncio.Task] = {}
+        self._active_signals: dict[str, asyncio.Event] = {}
+        # AgentsApi 初始化时注入 runtime.request_cancel 的绑定方法引用；
+        # 构造完后才能绑，否则 bound-method 指向的是未完全初始化的 self。
+        self._agents_api = AgentsApi(
+            registry,
+            store_resolver,
+            cancel_fn=self.request_cancel,
+            store_blob=store_blob,
+            abort_except_fn=self.abort_active_run_except,
+        )
+
+    async def handle(
+        self,
+        path: str,
+        method: str,
+        headers: dict,
+        query: dict,
+        body: dict,
+    ) -> RuntimeResult:
+        # Route match — user handler takes priority
+        entry = self._registry.get(path)
+
+        # Fallback: runtime built-in health (only if no user handler matched)
+        if not entry and path == "/health":
+            return RuntimeResult(200, {"status": "ok", "route_count": len(self._registry)}, {})
+
+        # Fallback: runtime built-in stop (only if no user handler matched)
+        if not entry and path.endswith("/stop"):
+            return await self._handle_stop(path, body, headers)
+
+        if not entry:
+            # 优先报告"路由文件存在但加载失败"的情况，避免用户面对空 404 摸不着头脑。
+            failure_reason = self._failed_routes.get(path)
+            if failure_reason:
+                _log(f"Agent error: {path} code=AGENT_ROUTE_LOAD_FAILED reason={failure_reason}")
+                return RuntimeResult(503, {
+                    "code": "AGENT_ROUTE_LOAD_FAILED",
+                    "message": (
+                        f"Route '{path}' exists but failed to load: {failure_reason}. "
+                        "Check server startup logs and ensure all required dependencies are installed."
+                    ),
+                    "path": path,
+                    "reason": failure_reason,
+                }, {})
+            return RuntimeResult(404, {"code": "AGENT_NOT_FOUND", "message": f"No handler for {path}"}, {})
+
+        # Parse IDs
+        # 与 Node runtime 对齐：当前请求自身的 conversation_id 只从 header 读，
+        # **不再回退** ``body.conversation_id`` —— 否则 /stop 这种请求自然会把
+        # body 里的「目标 conversation_id」当成自己的 conversation，进而覆盖
+        # active_signals 里被取消方的注册，导致 ctx.utils.abortActiveRun 失效。
+        # （body 里的 conversation_id 应该由业务 handler 自行解析作为参数。）
+        header_conversation_id = _header(headers, "makers-conversation-id") or _header(headers, "conversation-id")
+        if header_conversation_id:
+            conversation_id = header_conversation_id
+            conversation_id_source = "makers-conversation-id"
+        else:
+            conversation_id = str(uuid4())
+            conversation_id_source = "generated"
+        run_id = str(uuid4())
+        start_time = time.monotonic()
+
+        _log(f"Agent request: {method} {path} conversation={conversation_id} run={run_id}")
+
+        # [业务自管并发]不自动拦截，通过 ctx.active_run_id 暴露同 conversation 的活跃状态
+        existing_active_run_id = self._active_runs.get(conversation_id)
+
+        # Register active run (first-wins: 与 Node `if (isTopLevel && !existing_active_run)` 对齐)
+        cancel_event = asyncio.Event()
+        if entry.is_index and not existing_active_run_id:
+            self._active_runs[conversation_id] = run_id
+            self._active_signals[conversation_id] = cancel_event
+        elif not entry.is_index:
+            # 非 index 路由（如 /stop）不覆盖 _active_signals，避免把正在运行的
+            # index handler 的 cancel signal 覆盖掉，导致 abortActiveRun 失效。
+            # 非 index 路由自身的取消通过独立的 cancel_event 管理（不注册到全局表）。
+            pass
+
+        response_headers = {
+            "makers-conversation-id": conversation_id,
+            "makers-run-id": run_id,
+        }
+
+        # Build context
+        context = AgentContext(
+            conversation_id=conversation_id,
+            run_id=run_id,
+            parent_run_id=None,
+            request=RequestInfo(body=body, headers=headers, query=query, signal=cancel_event),
+            env=dict(os.environ),
+            kv=self._store_resolver(path),
+            agents=self._agents_api,
+            active_run_id=existing_active_run_id,
+            _store_blob=self._store_blob,
+            _tracer=_get_obs_tracer(),
+            _deadline=time.monotonic() + self._timeout,
+            _depth=0,
+            _call_chain=set(),
+            _call_chain_self=path,
+            # 与 Node `abortActiveRun: (target) => abortActiveRunExcept(target, run_id)`
+            # 行为一致：top-level handler 调 ctx.utils.abortActiveRun 时排除自己。
+            _abort_active_run_fn=lambda target, _rid=run_id: self.abort_active_run_except(
+                target, _rid
+            ),
+            _loop=asyncio.get_running_loop(),
+        )
+
+        # Execute with timeout
+        task = asyncio.create_task(_invoke_handler(entry.handler, context))
+        # 只有占据了槽位的 run 才注册 task（与 first-wins 一致）
+        if entry.is_index and not existing_active_run_id:
+            self._active_tasks[conversation_id] = task
+
+        # 流式延后清理标记：handler 返回 streaming 时，由 adapter 在 chunk
+        # 全部 send 完后调用 _release_run；finally 看到这个标记会跳过 pop。
+        # 用 dict 而不是简单变量以便在 finally 闭包里改写（Python 闭包对
+        # 不可变变量是 read-only 的，dict / list 之类的容器就没问题）。
+        _streaming_started = {"v": False}
+
+        try:
+            result = await asyncio.wait_for(task, timeout=self._timeout)
+            duration_ms = int((time.monotonic() - start_time) * 1000)
+
+            # 流式分支：handler 返回 async generator 或显式 StreamResponse。
+            # 这里只完成「响应头部决议」(status / headers / content-type)，
+            # 真正的 chunk 迭代交给 adapter 在 ASGI 层做：
+            #   - adapter 已 send http.response.start 后才开始 async for；
+            #   - 中途异常无法再改 status，只能 logger 记录 + 关闭连接。
+            # 同时把 conversation_id / cancel_event 注入到 RuntimeResult，让
+            # adapter 在 streaming 时能 finally 清理 active_runs（普通响应
+            # 是在 finally 里 pop 的，流式我们 pop 时机要延后到 chunk 流完）。
+            stream_resp = self._coerce_to_stream(result)
+            if stream_resp is not None:
+                _streaming_started["v"] = True
+                _log(f"Agent response (streaming): {path} status={stream_resp.status} headers_decided={duration_ms}ms")
+                stream_headers = dict(response_headers)
+                if stream_resp.headers:
+                    # 业务自定义 headers 覆盖默认（除了 conversation/run id 这两个
+                    # 是诊断用的，业务也允许覆盖 —— 给最大灵活度）。
+                    for k, v in stream_resp.headers.items():
+                        stream_headers[k.lower()] = v
+                if stream_resp.content_type:
+                    stream_headers["content-type"] = stream_resp.content_type
+                # 加上流式信号头，对齐 Node `INTERNAL_STREAM_SIGNAL_HEADER`：
+                # 业务自定义 headers 没显式覆盖时，runtime 强制注入；上游
+                # 网关/反代可凭此头识别流式响应做反缓冲处理。
+                stream_headers.setdefault(INTERNAL_STREAM_SIGNAL_HEADER, "true")
+                # 不在这里 pop active_runs —— 让 adapter 在 chunk 流结束后调
+                # release_active_run。流式期间仍需要保持 active_run 注册，
+                # 这样 /stop 才能拿到 cancel_event 把它打开。
+                streaming_result = RuntimeResult(
+                    status=stream_resp.status,
+                    body=stream_resp,
+                    headers=stream_headers,
+                )
+                # 标记一下，告诉 adapter 流结束后要清理。
+                streaming_result._defer_cleanup = True  # type: ignore[attr-defined]
+                streaming_result._cleanup = lambda cid=conversation_id: self._release_run(cid)  # type: ignore[attr-defined]
+                # 把 cancel_event 传给 adapter，让 /stop 和 abort_active_run
+                # 也能中断流式迭代（不仅仅是 client disconnect）。
+                streaming_result._cancel_signal = cancel_event  # type: ignore[attr-defined]
+                return streaming_result
+
+            runtime_result = self._serialize_result(result, response_headers)
+            _log(f"Agent response: {path} status={runtime_result.status} duration={duration_ms}ms")
+            return runtime_result
+
+        except asyncio.TimeoutError:
+            duration_ms = int((time.monotonic() - start_time) * 1000)
+            # 与 Node runtime 一致：top-level timeout 用 error 级别（用户可感知），
+            # invoke 子调用超时只算 warn（父级 handler 可以捕获 InvokeError 自处理）。
+            # Python runtime 的 handle 入口只会进入 top-level，invoke 子调用的
+            # AGENT_INVOKE_TIMEOUT_EXHAUSTED 是另一条路径。
+            timeout_scope = "top_level"
+            timeout_context = {
+                "timeout_scope": timeout_scope,
+                "route_path": path,
+                "parent_run_id": None,
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+                "timeout_ms": self._timeout * 1000,
+                "duration_ms": duration_ms,
+            }
+            _log(f"Agent runtime timeout: {timeout_context}")
+            return RuntimeResult(408, {
+                "code": "AGENT_RUN_TIMEOUT",
+                "message": f"Agent run timed out after {self._timeout}s",
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+                "timeout_ms": self._timeout * 1000,
+                "timeout_scope": timeout_scope,
+                "route_path": path,
+                "parent_run_id": None,
+            }, response_headers)
+
+        except asyncio.CancelledError:
+            _log(f"Agent error: {path} code=AGENT_RUN_CANCELLED conversation={conversation_id} run={run_id}")
+            return RuntimeResult(499, {
+                "code": "AGENT_RUN_CANCELLED",
+                "message": "Agent run was cancelled",
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+            }, response_headers)
+
+        except InvokeError as e:
+            _log(f"Agent error: {path} code={e.code} conversation={conversation_id} run={run_id}")
+            return RuntimeResult(e.status, {
+                "code": e.code,
+                "message": e.message,
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+            }, response_headers)
+
+        except Exception as e:
+            if _is_interrupt_exception(e):
+                # LangGraph interrupt()：graph 暂停等待人工输入，属正常控制流，
+                # 不是错误。不返回 500，回一个「已暂停」的 200，并透传 interrupt
+                # payload 供前端处理（与流式 __interrupt__ 事件等价）。
+                _log(f"Agent paused (interrupt): {path} conversation={conversation_id} run={run_id}")
+                return RuntimeResult(200, {
+                    "code": "AGENT_RUN_INTERRUPTED",
+                    "message": "Agent run paused awaiting human input",
+                    "conversation_id": conversation_id,
+                    "run_id": run_id,
+                    "interrupt": _serialize_interrupt(e),
+                }, response_headers)
+            if _is_sandbox_error(e):
+                diagnostics = _sandbox_diagnostics(path, headers, context.env, conversation_id_source)
+                _log(f"Agent error: {path} code=AGENT_SANDBOX_ERROR conversation={conversation_id} run={run_id} error={e}")
+                return RuntimeResult(500, {
+                    "code": "AGENT_SANDBOX_ERROR",
+                    "message": str(e),
+                    "conversation_id": conversation_id,
+                    "run_id": run_id,
+                    "sandbox": _sandbox_error_payload(e),
+                    "diagnostics": diagnostics,
+                    "suggestion": _sandbox_suggestion(e, diagnostics),
+                }, response_headers)
+            _log(f"Agent error: {path} code=AGENT_RUN_ERROR conversation={conversation_id} run={run_id} error={e}")
+            return RuntimeResult(500, {
+                "code": "AGENT_RUN_ERROR",
+                "message": str(e),
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+            }, response_headers)
+
+        finally:
+            # 流式响应 finally 不能直接 pop —— streaming chunk 还在迭代中，
+            # active_signals[conv_id] 必须保留让 /stop 能取消。延后到 adapter
+            # 调用 _release_run。普通（非流式）响应仍走立即清理。
+            #
+            # 注意：这个 if 的判断要看实际流向 ——
+            # 1. 抛出异常的分支（TimeoutError/CancelledError/InvokeError/Exception）
+            #    都已 return RuntimeResult 而不是 raise，所以会走进 finally；
+            #    它们都不是 streaming，应该立即清理。
+            # 2. 正常 return 的 streaming 分支带 _defer_cleanup 标记，跳过。
+            #
+            # 我们只能拿到 finally 里 closure 的状态，没有 result 的上下文，
+            # 所以用一个 nonlocal-like 的 _streaming_started 闭包变量来传递。
+            if not _streaming_started["v"]:
+                # 与 Node `releaseActiveRunSlot(conversation_id, run_id)` 对齐：
+                # 只有占据了槽位的 run（run_id 匹配）才清理，避免并发请求误删。
+                if entry.is_index and self._active_runs.get(conversation_id) == run_id:
+                    self._active_runs.pop(conversation_id, None)
+                    self._active_tasks.pop(conversation_id, None)
+                    self._active_signals.pop(conversation_id, None)
+
+    async def _handle_stop(self, path: str, body: dict, headers: dict) -> RuntimeResult:
+        conversation_id = (
+            body.get("conversation_id")
+            or _header(headers, "conversation-id")
+            or _header(headers, "makers-conversation-id")
+            or ""
+        )
+        if not conversation_id:
+            return RuntimeResult(400, {"code": "MISSING_CONVERSATION_ID", "message": "conversation_id is required for stop"}, {})
+
+        # 复用 request_cancel 的判定逻辑：判定 active 看 signal 不看 task，
+        # 因为流式响应的 handler task 在 yield generator 后立即 done，但流
+        # 仍在迭代，signal 仍然有效；这种状态下 /stop 也应该能取消。
+        signal = self._active_signals.get(conversation_id)
+        if signal is not None:
+            run_id = self._active_runs.get(conversation_id, "")
+            # 标准取消序列：set signal → 业务侧 is_cancelled=True；task.cancel
+            # 是非流式场景的兜底（在 await 点抛 CancelledError）。
+            task = self._active_tasks.get(conversation_id)
+            if not signal.is_set():
+                signal.set()
+            if task is not None and not task.done():
+                task.cancel()
+            return RuntimeResult(200, {
+                "status": "aborting",
+                "conversation_id": conversation_id,
+                "run_id": run_id,
+            }, {})
+
+        return RuntimeResult(200, {
+            "status": "idle",
+            "conversation_id": conversation_id,
+        }, {})
+
+    def request_cancel(self, conversation_id: str) -> bool:
+        """主动发起取消（非 HTTP 路径），供 adapter 在 http.disconnect 等
+        情形下调用。
+
+        行为和 _handle_stop 等价：
+          1. 先 set cancel_event → 业务 handler 下次检查 is_cancelled
+             可走优雅返回路径（保存上下文、收尾等）；
+          2. 再 task.cancel() 作为兜底 → 下一次 await 会抛 CancelledError。
+
+        返回 True 表示确实取消了一个活跃 conversation，False 表示该
+        conversation_id 下没有任何活跃状态（可能已完成、已取消、或 id 错）。
+
+        流式响应特殊情况：流式 handler 在第一次 await 时立即 return generator
+        对象，所以 task 早就 done 了，但 active_signals[conv_id] 仍存在
+        （chunk 还在被 adapter 迭代）。这种情况只能 set signal，业务侧靠
+        is_cancelled 检测；task.cancel() 已经无效（task done 后 cancel 是
+        no-op）。所以判定「是否活跃」要看 signal 而不是 task。
+        """
+        if not conversation_id:
+            return False
+        signal = self._active_signals.get(conversation_id)
+        task = self._active_tasks.get(conversation_id)
+        # 没有 signal 就意味着 conversation 整个生命周期都结束了（被 finally
+        # 或 _release_run 清理过），无法再取消。
+        if signal is None:
+            return False
+        if signal.is_set():
+            # 已经被 set 过了，不重复 cancel；返回 True 表达「确实是个活跃 run」。
+            return True
+        signal.set()
+        # task 可能已经 done（流式场景），cancel 是 no-op，不会抛；不过 None
+        # 检查保险一点。
+        if task is not None and not task.done():
+            task.cancel()
+        return True
+
+    def abort_active_run_except(
+        self,
+        conversation_id: str,
+        exclude_run_id: str,
+    ) -> AbortActiveRunResult:
+        """与 Node ``abortActiveRunExcept`` 对齐：取消目标 conversation 的活跃
+        run，但**不取消** ``exclude_run_id`` 自己。
+
+        作为 ``ctx.utils.abortActiveRun`` 的底层实现：每次构造 context 时都
+        会绑定当前 run_id 作为 exclude_run_id，确保业务里调
+        ``ctx.utils.abortActiveRun(self_conv_id)`` 不会误把自己取消。
+
+        Returns:
+            ``AbortActiveRunResult``：
+              - ``aborted=True`` + ``conversation_id`` + ``run_id``：成功触发取消；
+              - ``aborted=False``：目标 conversation 没有活跃 run，或活跃 run
+                就是当前调用方自己（不允许自取消）。
+
+        实现复用 ``request_cancel``：判定活跃看 signal 而非 task（流式场景下
+        handler task 早就 done 了）。
+        """
+        if not conversation_id:
+            return AbortActiveRunResult(aborted=False)
+
+        active_run_id = self._active_runs.get(conversation_id)
+        # 即便不是 index 路由（active_runs 可能没记，但 active_signals 记了），
+        # 我们也允许通过 conversation_id 取消；判定活跃看 signal。
+        signal = self._active_signals.get(conversation_id)
+        if signal is None:
+            return AbortActiveRunResult(aborted=False)
+
+        # 排除自身：只有当 active_run_id 明确等于 exclude_run_id 时才跳过；
+        # 非 index 路由下 active_run_id 可能为 None，此时仍可被取消。
+        if active_run_id is not None and active_run_id == exclude_run_id:
+            return AbortActiveRunResult(aborted=False)
+
+        ok = self.request_cancel(conversation_id)
+        if not ok:
+            return AbortActiveRunResult(aborted=False)
+        return AbortActiveRunResult(
+            aborted=True,
+            conversation_id=conversation_id,
+            run_id=active_run_id,
+        )
+
+    def _serialize_result(self, result: Any, headers: dict) -> RuntimeResult:
+        if result is None:
+            return RuntimeResult(204, None, headers)
+        if isinstance(result, str):
+            headers["content-type"] = "text/plain"
+            return RuntimeResult(200, result, headers)
+        if isinstance(result, dict):
+            # 信封格式：{"status_code": N, "body": ..., "headers": {...}}
+            # 仅当 status_code 是合法 HTTP 状态码（100-599）时才触发，
+            # 避免误判普通业务 dict 里恰好有 status_code 字段。
+            envelope_status = result.get("status_code")
+            if (
+                isinstance(envelope_status, int)
+                and 100 <= envelope_status <= 599
+                and "body" in result
+            ):
+                body = result["body"]
+                status = envelope_status
+                extra_headers = result.get("headers")
+                if isinstance(extra_headers, dict):
+                    for k, v in extra_headers.items():
+                        headers[k.lower()] = str(v)
+                if body is None:
+                    return RuntimeResult(status, None, headers)
+                if isinstance(body, str):
+                    headers.setdefault("content-type", "text/plain")
+                    return RuntimeResult(status, body, headers)
+                try:
+                    json.dumps(body)
+                    return RuntimeResult(status, body, headers)
+                except (TypeError, ValueError):
+                    headers.setdefault("content-type", "text/plain")
+                    return RuntimeResult(status, str(body), headers)
+            # 普通 dict
+            try:
+                json.dumps(result)
+            except (TypeError, ValueError):
+                headers["content-type"] = "text/plain"
+                return RuntimeResult(200, str(result), headers)
+            return RuntimeResult(200, result, headers)
+        # For other types, try to make them JSON-serializable
+        try:
+            json.dumps(result)  # test if serializable
+            return RuntimeResult(200, result, headers)
+        except (TypeError, ValueError):
+            headers["content-type"] = "text/plain"
+            return RuntimeResult(200, str(result), headers)
+
+    def _coerce_to_stream(self, result: Any) -> Optional[StreamResponse]:
+        """识别 handler 返回值是否为流式响应，并归一成 StreamResponse。
+
+        三种合法输入：
+          1. StreamResponse 实例：原样返回（已有自定义 status/headers）。
+          2. async generator (`async def gen(): yield ...`)：包装成默认
+             200 + content-type 自动推断的 StreamResponse。
+          3. async iterator（实现了 __aiter__）：同 2 处理。
+
+        其他普通对象（dict/str/None/list）返回 None，由 _serialize_result
+        走旧的一次性序列化路径。
+
+        注意 list / tuple 不算流式 —— Python 的 list 既可被 iter() 遍历也
+        被 inspect.isasyncgen 识别为 False，但和 async iterator 是不同语义；
+        list 视为「一次性数组响应」更符合用户预期。
+        """
+        if result is None:
+            return None
+        if isinstance(result, StreamResponse):
+            return result
+        # 直接是 async generator
+        if inspect.isasyncgen(result):
+            return StreamResponse(body=result)
+        # 实现了 __aiter__ 的对象（自定义 async iterator）
+        if hasattr(result, "__aiter__") and not isinstance(
+            result, (dict, list, tuple, str, bytes, bytearray)
+        ):
+            return StreamResponse(body=result)
+        return None
+
+    def _release_run(self, conversation_id: str) -> None:
+        """供 adapter 在流式响应 chunk 全部 send 完后调用，清理 active_*。
+
+        分离出来是因为流式响应的生命周期跨越 runtime.handle 返回之后，
+        finally 块那时候已经走完了，不能在那里 pop。
+        """
+        self._active_runs.pop(conversation_id, None)
+        self._active_tasks.pop(conversation_id, None)
+        self._active_signals.pop(conversation_id, None)
+
+
+def _header(headers: dict, name: str) -> Optional[str]:
+    """Case-insensitive header lookup."""
+    name_lower = name.lower()
+    for k, v in headers.items():
+        if k.lower() == name_lower:
+            return v if isinstance(v, str) else v.decode("utf-8") if isinstance(v, bytes) else str(v)
+    return None