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

ksadk/builders/managed_runtime_builder.py

@@ -28,6 +28,7 @@ _MANIFEST_KEYS = (
     "skills",
     "mcp_servers",
     "plugins",
+    "remote_agents",
     "sandbox",
     "approval_mode",
     "context",
@@ -163,6 +164,17 @@ class ManagedRuntimeBuilder(BaseBuilder):
         runtime_name = str(runtime.get("name") or "").strip().lower()
         if runtime_name != "codex":
             return "当前 ManagedRuntime v1 仅支持 runtime.name: codex"
+        if "remoteAgents" in config:
+            return "ManagedRuntime YAML 请使用 remote_agents 字段，不能静默忽略 remoteAgents"
+        if "remote_agents" in config:
+            from ksadk.plugins.host import PluginHostError
+            from ksadk.plugins.providers.codex import _bundle_a2a_experts
+            try:
+                _bundle_a2a_experts(config)
+            except (ValueError, PluginHostError):
+                # Validation errors can include authored input. Keep the CLI
+                # failure deterministic without echoing manifest data.
+                return "A2A_EXPERT_BINDING_INVALID: 请检查固定绑定、调用方式和执行策略"
         return None
 
     @staticmethod

ksadk/builders/source_provenance.py

@@ -0,0 +1,87 @@
+"""Collect immutable source and installed-package provenance."""
+
+from __future__ import annotations
+
+import importlib.metadata as importlib_metadata
+import json
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _git_provenance(start: Path) -> Optional[dict]:
+    """返回 start 所在 git 仓库的提交信息;非 git 目录返回 None。"""
+
+    def _git(*args: str) -> Optional[str]:
+        try:
+            proc = subprocess.run(
+                ["git", "-C", str(start), *args],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        except Exception:
+            return None
+        if proc.returncode != 0:
+            return None
+        return proc.stdout.strip()
+
+    toplevel = _git("rev-parse", "--show-toplevel")
+    if not toplevel:
+        return None
+    commit = _git("rev-parse", "HEAD")
+    branch = _git("rev-parse", "--abbrev-ref", "HEAD")
+    status = _git("status", "--porcelain")
+    return {
+        "repo_root": toplevel,
+        "commit": commit,
+        "branch": branch or None,
+        "dirty": bool(status),
+    }
+
+
+def _package_provenance(package_name: str, package_root: Path, *, git_reader: Any) -> dict:
+    """采集被 vendored 包的安装来源:dist 元信息 / 本地路径 / git 提交。"""
+
+    info: dict[str, Any] = {
+        "source_dir": str(package_root),
+        "dist_version": None,
+        "installer": None,
+        "direct_url": None,
+        "source_type": "unknown",
+        "git": None,
+    }
+    try:
+        dist = importlib_metadata.distribution(package_name)
+    except Exception:
+        dist = None
+    if dist is not None:
+        info["dist_version"] = dist.version
+        installer = (dist.read_text("INSTALLER") or "").strip()
+        info["installer"] = installer or None
+        raw_direct_url = dist.read_text("direct_url.json")
+        if raw_direct_url:
+            try:
+                direct_url = json.loads(raw_direct_url)
+            except ValueError:
+                direct_url = None
+            if isinstance(direct_url, dict):
+                info["direct_url"] = direct_url.get("url")
+                url = str(direct_url.get("url") or "")
+                dir_info = direct_url.get("dir_info") or {}
+                archive_info = direct_url.get("archive_info") or {}
+                if url.startswith("file://"):
+                    if dir_info.get("editable"):
+                        info["source_type"] = "editable-install"
+                    elif url.endswith(".whl"):
+                        info["source_type"] = "local-wheel"
+                    else:
+                        info["source_type"] = "local-path"
+                elif archive_info:
+                    info["source_type"] = "remote-dist"
+    if info["direct_url"] is None and info["dist_version"] is not None:
+        # pip 从 index 安装的常规 dist 通常不写 direct_url.json
+        info["source_type"] = "installed-dist"
+    if info["source_type"] in {"editable-install", "local-path", "unknown"}:
+        info["git"] = git_reader(package_root)
+    return info

ksadk/cli/cmd_a2a.py

@@ -199,6 +199,49 @@ def register(agent_path: Path, url: str, name: str | None, description: str, ski
     click.echo(MessageToJson(card_obj, indent=2))
 
 
+@a2a.command("register-hosted", context_settings=_HELP)
+@click.option("--agent-id", required=True, help="已通过 deploy 创建的托管运行时 ID")
+@click.option("--space-id", "space_ids", multiple=True, required=True, help="加入的 A2A Space；可重复")
+@click.option("--region", required=True, help="显式选择环境/区域，例如 pre-online")
+def register_hosted(agent_id: str, space_ids: Sequence[str], region: str):
+    """将已部署的 hosted Agent 注册为可被 Space 内其他 Agent 调用的服务。"""
+    from ksadk.api.client import AgentEngineClient
+
+    agent_id, region = agent_id.strip(), region.strip()
+    spaces = list(dict.fromkeys(space.strip() for space in space_ids))
+    if not agent_id or not region or any(not space for space in spaces):
+        raise click.UsageError("agent-id、space-id 和 region 不得为空")
+
+    async def run():
+        client = AgentEngineClient(region=region)
+        try:
+            preview = await client._action_async(
+                "GetAToARuntimeConfig", {"AgentId": agent_id}, preserve_case=True,
+            )
+            card = preview.get("AgentCard")
+            if not isinstance(card, dict) or not card:
+                raise ValueError("Runtime AgentCard unavailable")
+            result = await client._action_async("CreateAToAAgent", {
+                "Source": "hosted", "AgentId": agent_id, "A2ASpaceIds": spaces,
+                "AgentCard": card,
+            })
+        except Exception as exc:
+            # An ambiguous response is not automatically retried: registration
+            # may already exist. Never print private upstream bodies or routes.
+            code = getattr(exc, "code", None)
+            raise click.ClickException(
+                f"Hosted A2A 注册失败（code={code or 'unavailable'}）；请查询注册状态后再重试"
+            ) from None
+        finally:
+            await client.close()
+        click.echo(json.dumps({
+            "a2a_agent_id": result.get("a2_a_agent_id", result.get("A2AAgentId")),
+            "status": result.get("status", result.get("Status")),
+        }, ensure_ascii=False))
+
+    asyncio.run(run())
+
+
 # ---------------------------------------------------------------------------
 # discover / call / status / cancel(Space 内动态发现与调用,经 A2ASpaceClient)
 # ---------------------------------------------------------------------------

ksadk/cli/cmd_build.py

@@ -285,6 +285,15 @@ async def _build_code(
     if not result.success:
         raise validation_error(result.error_message or "构建失败")
 
+    if result.artifact_path is not None:
+        from ksadk.builders.code_builder import _sha256_file, read_code_deployment_contract
+
+        result.metadata["code_checksum"] = _sha256_file(result.artifact_path)
+        contract = read_code_deployment_contract(result.artifact_path)
+        if contract and contract.get("schema") == "ksadk-code-deployment/v1":
+            result.metadata["code_command"] = contract.get("command")
+            result.metadata["code_kernel_contract_digest"] = contract.get("agentKernelContractDigest")
+
     agent_name = result.metadata.get("agent_name", agent_path.name)
 
     # 上传到 KS3

ksadk/cli/cmd_deploy.py

@@ -104,6 +104,8 @@ console = get_console()
     default=None,
     help="Serverless 部署模式；默认从 agentengine.yaml 推断",
 )
+@click.option("--a2a-space-id", help="绑定 A2A Space（Serverless）；省略时保留已有绑定")
+@click.option("--a2a-runtime-profile", type=click.Choice(["managed-a2a", "managed-a2a-basic", "managed-a2a-memory"]), help="A2A 能力配置；需同时指定 --a2a-space-id")
 @click.option("--namespace", default="default", help="K8s 命名空间")
 @click.option("--port", "-p", default=8000, help="服务端口 (default: 8000)")
 @click.option("--registry", help="镜像仓库地址 (k8s/serverless Container 模式)")
@@ -148,6 +150,8 @@ def deploy(
     region: str,
     account_id: str,
     artifact_type: str,
+    a2a_space_id: str | None,
+    a2a_runtime_profile: str | None,
     namespace: str,
     port: int,
     registry: str,
@@ -250,6 +254,8 @@ def deploy(
             repackage=repackage,
             dry_run_context=dry_run_context,
             agent_id=agent_id,
+            a2a_space_id=a2a_space_id,
+            a2a_runtime_profile=a2a_runtime_profile,
         ),
         dry_run=dry_run,
         on_dry_run=render_deploy_dry_run,
@@ -326,11 +332,20 @@ async def _deploy_async(
     *,
     repackage: bool = False,
     agent_id: str | None = None,
+    a2a_space_id: str | None = None,
+    a2a_runtime_profile: str | None = None,
 ):
     """异步部署流程"""
     from ksadk.deployment import DeploymentManager, DeployStatus, DeployTarget
     from ksadk.detection import FrameworkDetector
 
+    if a2a_runtime_profile and not a2a_space_id:
+        raise validation_error("--a2a-runtime-profile requires --a2a-space-id")
+    if a2a_space_id is not None:
+        a2a_space_id = a2a_space_id.strip()
+        if target != "serverless" or not a2a_space_id:
+            raise validation_error("--a2a-space-id 需要非空 Space ID，且仅支持 Serverless 部署")
+
     agent_path = Path(agent_dir).resolve()
     config = _load_config(agent_path)
     try:
@@ -385,6 +400,11 @@ async def _deploy_async(
 
     resolved_runtime = None
     if effective_artifact_type == "ManagedRuntime":
+        if image:
+            raise validation_error(
+                "ManagedRuntime 不支持 --image；镜像由服务端 Runtime catalog 选择。"
+                "请通过 runtime.version 指定已登记的运行时版本。"
+            )
         if detection_result.type.value != "codex":
             raise validation_error("ManagedRuntime v1 目前仅支持 framework: codex")
         if ks3_path:
@@ -443,6 +463,8 @@ async def _deploy_async(
             "runtime_name": resolved_runtime.name if resolved_runtime else "",
             "runtime_version": resolved_runtime.version if resolved_runtime else "",
             "agent_id": agent_id,
+            "a2a_space_id": a2a_space_id,
+            "a2a_runtime_profile": a2a_runtime_profile,
         },
     )
 
@@ -611,7 +633,9 @@ async def _deploy_async(
             # CreateAgent callback may still be pending, so presenting it as a
             # completed deployment is misleading (and hides a broken
             # callback/data-plane handoff).
-            if result.status == DeployStatus.RUNNING:
+            if result.metadata.get("update_accepted"):
+                print_info("Agent 更新请求已提交，服务端将在后台执行，请稍后查看 Agent 状态")
+            elif result.status == DeployStatus.RUNNING:
                 print_success("部署成功")
             else:
                 print_info("部署请求已提交，等待实例就绪")
@@ -631,7 +655,8 @@ async def _deploy_async(
                 print_kv("信息", result.message)
 
             # 9. 自动创建版本快照 (仅热更新时，首次部署平台自动创建 v1)
-            is_update = result.message and "已更新" in result.message
+            is_update = (not result.metadata.get("update_accepted")
+                         and result.message and "已更新" in result.message)
             if result.agent_id and is_update and not no_version and not dry_run:
                 from ksadk.cli.deploy_utils import auto_release_version
 

ksadk/cli/cmd_invoke.py

@@ -36,6 +36,8 @@ from ksadk.hermes_terminal import run_hermes_terminal_session
 from ksadk.terminal_client import run_terminal_session
 from ksadk_runtime_common.workspace_files.constants import DEFAULT_WORKSPACE_MAX_UPLOAD_BYTES
 
+from ksadk.cli.invoke_content import _extract_content, _extract_response_content
+
 console: Any = None
 Markdown: Any = None
 Live: Any = None
@@ -583,6 +585,14 @@ def run_invoke_command(
 
     if message:
         # 单次调用模式
+        if not local and not _is_openclaw_target(next_state, latest_access) and not _is_hermes_target(next_state, latest_access):
+            from ksadk.cli.hosted_invoke import try_invoke_hosted_once
+
+            if try_invoke_hosted_once(
+                endpoint=endpoint, api_key=api_key, session_id=session_id,
+                message=message, model=model, insecure=insecure,
+            ):
+                return
         api_format_resolved = asyncio.run(
             _resolve_remote_api_format(
                 endpoint=endpoint,
@@ -1375,7 +1385,7 @@ async def _invoke_once(
             else:
                 click.echo(content)
     except Exception as e:
-        click.secho(f"\n❌ 调用失败: {e}", fg="red")
+        raise click.ClickException(f"调用失败: {e}") from e
 
 
 async def _chat(
@@ -1485,94 +1495,37 @@ async def _stream_chat(
     async with httpx.AsyncClient(**client_kwargs) as client:
         async with client.stream("POST", url, json=payload, headers=headers) as response:
             response.raise_for_status()
-            try:
-                current_event = ""
-                # Use aiter_lines() for robust UTF-8 decoding and line splitting
-                async for line in response.aiter_lines():
-                    if not line:
-                        continue
-
-                    if line.startswith("event: "):
-                        current_event = line[7:].strip()
-                        continue
-
-                    if line.startswith("data: "):
-                        data_str = line[6:].strip()
-                        if data_str == "[DONE]":
-                            break
-
-                        try:
-                            data = json.loads(data_str)
-                            if not isinstance(data, dict):
-                                continue
-                            if current_event and isinstance(data, dict):
-                                data = {**data, "_event": current_event}
-                            # 直接 yield 解析后的 JSON 数据，让 _extract_content 处理
-                            yield data
-
-                            # Handle events/errors
-                            error = data.get("error")
-                            if error:
-                                click.secho(f"\nError: {error}", fg="red")
-
-                        except json.JSONDecodeError:
-                            pass
-            except Exception as e:
-                click.secho(f"\nStream error: {e}", fg="red")
-
-
-def _extract_content(chunk: dict) -> tuple[str, str]:
-    """从 OpenAI 流式响应中提取内容 (包含 reasoning_content)"""
-    event_name = str(chunk.get("_event") or "")
-    if event_name == "response.output_text.delta":
-        return str(chunk.get("delta") or ""), ""
-    # reasoning delta 有 4 个变体名(与 remote_runner / 前端 chatProtocol 对齐),
-    # 主 runtime 发 reasoning.delta,Studio shared_web 发 reasoning_summary_text.delta。
-    if event_name in {
-        "response.reasoning.delta",
-        "response.reasoning_text.delta",
-        "response.reasoning_summary.delta",
-        "response.reasoning_summary_text.delta",
-    }:
-        return "", str(chunk.get("delta") or chunk.get("text") or "")
-    if event_name == "response.completed":
-        return "", ""
-
-    # OpenAI 格式: {"choices": [{"delta": {"content": "xxx", "reasoning_content": "thought"}}]}
-    try:
-        choices = chunk.get("choices", [])
-        if choices:
-            delta = choices[0].get("delta", {})
-            return delta.get("content", "") or "", delta.get("reasoning_content", "") or ""
-    except (KeyError, IndexError):
-        pass
-
-    if isinstance(chunk.get("output_text"), str):
-        return chunk["output_text"], ""
-    if isinstance(chunk.get("delta"), str):
-        return chunk["delta"], ""
-    return "", ""
-
-
-def _extract_response_content(response: dict) -> str:
-    """从 OpenAI 非流式响应中提取内容"""
-    output_text = response.get("output_text")
-    if output_text:
-        return str(output_text)
-    output = response.get("output") or []
-    for item in output:
-        if not isinstance(item, dict):
-            continue
-        for content in item.get("content") or []:
-            if isinstance(content, dict) and content.get("text"):
-                return str(content["text"])
-
-    # OpenAI 格式: {"choices": [{"message": {"content": "xxx"}}]}
-    try:
-        choices = response.get("choices", [])
-        if choices:
-            message = choices[0].get("message", {})
-            return str(message.get("content") or "")
-    except (KeyError, IndexError):
-        pass
-    return str(response)
+            current_event = ""
+            # Use aiter_lines() for robust UTF-8 decoding and line splitting
+            async for line in response.aiter_lines():
+                if not line:
+                    continue
+
+                if line.startswith("event: "):
+                    current_event = line[7:].strip()
+                    continue
+
+                if line.startswith("data: "):
+                    data_str = line[6:].strip()
+                    if data_str == "[DONE]":
+                        break
+
+                    try:
+                        data = json.loads(data_str)
+                        if not isinstance(data, dict):
+                            continue
+                        if current_event and isinstance(data, dict):
+                            data = {**data, "_event": current_event}
+                        event_type = current_event or data.get("type")
+                        response_payload = data.get("response")
+                        nested_error = (
+                            response_payload.get("error")
+                            if isinstance(response_payload, dict) else None
+                        )
+                        error = data.get("error") or nested_error
+                        if error or event_type in {"error", "response.failed"}:
+                            raise RuntimeError(str(error or data.get("message") or event_type))
+                        yield data
+
+                    except json.JSONDecodeError:
+                        pass

ksadk/cli/cmd_studio.py

@@ -211,7 +211,11 @@ def studio(
             security_enabled=os.environ.get("KSADK_STUDIO_NO_SECURITY") != "1",
         )
         base_url = f"http://127.0.0.1:{port}/"
-        launch_url = f"{base_url}#session={session_token}"
+        # The Core UI is the normal Studio host when profile plugins are
+        # enabled. Do not rely on a fragment surviving the root 307 redirect:
+        # browser implementations may drop it, leaving the page unauthenticated
+        # after every local server restart.
+        launch_url = f"{base_url}studio-core/#session={session_token}"
 
         print_title("启动 AgentKit Local Studio")
         print_kv("工作区", str(root))

ksadk/cli/cmd_web.py

@@ -40,6 +40,8 @@ _SESSION_ENV_NAMES = (
 _CHECKPOINT_ENV_NAMES = (
     "KSADK_CHECKPOINT_BACKEND",
     "KSADK_CHECKPOINT_PATH",
+    "KSADK_CHECKPOINT_DSN",
+    "KSADK_LANGGRAPH_CHECKPOINT_DSN",
 )
 _LOCAL_UI_ENV_NAMES = ("AGENTENGINE_UI_DIR",)
 

ksadk/cli/hosted_invoke.py

@@ -0,0 +1,206 @@
+"""Invoke platform hosted Agents through their admitted Action surface."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+
+import click
+import requests
+
+from ksadk.conversations.message_projection import project_session_messages
+
+
+def try_invoke_hosted_once(*, endpoint, api_key, session_id, message, model, insecure):
+    """Return False for ordinary OpenAI servers; never bypass hosted admission."""
+    with requests.Session() as transport:
+        transport.verify = not insecure
+        if api_key:
+            transport.headers["Authorization"] = "Bearer " + api_key
+
+        def action(name, body, *, missing_ok=False, request_timeout=45):
+            response = transport.post(
+                endpoint.rstrip("/") + "/agentengine/api/v1/" + name,
+                json=body, timeout=request_timeout, allow_redirects=False,
+            )
+            if response.is_redirect:
+                raise click.ClickException("Hosted Action redirected; request was not replayed")
+            if missing_ok and response.status_code == 404:
+                return None
+            response.raise_for_status()
+            envelope = response.json()
+            if missing_ok and envelope.get("Code") == 404:
+                return None
+            if envelope.get("Code") not in (None, 0):
+                raise click.ClickException(str(envelope.get("Message") or "Hosted Action failed"))
+            data = envelope.get("Data", envelope)
+            if not isinstance(data, dict):
+                raise click.ClickException("Hosted Action returned no result")
+            return data
+
+        try:
+            bootstrap = action("GetAgentUiBootstrap", {}, missing_ok=True)
+        except requests.HTTPError as exc:
+            if exc.response.status_code in (404, 405):
+                return False
+            raise click.ClickException("Hosted bootstrap authentication or transport failed") from exc
+        if bootstrap is None:
+            return False
+        agent_id = (bootstrap.get("Agent") or {}).get("AgentId")
+        if (not agent_id or not isinstance(bootstrap.get("HostedRuntime"), dict)
+                or (bootstrap.get("Capabilities") or {}).get("KernelSessionEvents") is not True):
+            return False
+
+        session_body = {"AgentId": agent_id, "SessionId": session_id}
+        session = action("GetSession", session_body, missing_ok=True)
+        if session is None:
+            session = action("CreateSession", session_body)
+        session = session.get("Session", session)
+        session_id = session.get("SessionId") or session.get("Id")
+        if not session_id:
+            raise click.ClickException("CreateSession returned no session identity")
+        body = {
+            "AgentId": agent_id, "SessionId": session_id,
+            "Messages": [{"role": "user", "content": message}],
+            "ApiFormat": "chat_completions", "Stream": False, "Background": True,
+        }
+        if model:
+            body["Model"] = model
+        receipt = action("RunAgent", body)
+        run_id = receipt.get("RunId") or receipt.get("InvocationId")
+        command_id, message_id = receipt.get("CommandId"), receipt.get("MessageId")
+        if not run_id and not (command_id and message_id):
+            raise click.ClickException("Hosted run returned no observable command identity")
+        click.echo(f"Session: {session_id}\nCommand: {command_id or run_id}")
+        cursor = 0
+        cursor_source = None
+        history_epoch = None
+        claimed_message = None
+        events = {}
+        submitted = set()
+        resolved = set()
+        pending = {}
+        terminal = None
+        deadline = time.monotonic() + 900
+        read_interrupted = False
+        while (remaining := deadline - time.monotonic()) > 0:
+            query = {
+                "AgentId": agent_id, "SessionId": session_id,
+                "AfterSeqId": cursor, "Limit": 200, "EventOrder": "session_seq",
+            }
+            if cursor_source:
+                query["CursorSource"] = cursor_source
+            if history_epoch:
+                query["HistoryEpoch"] = history_epoch
+            try:
+                page = action("ListSessionEvents", query, request_timeout=min(45, remaining))
+            except requests.exceptions.SSLError:
+                raise
+            except (requests.ConnectionError, requests.Timeout):
+                # This is an idempotent observation of an already admitted run.
+                # Preserve its cursor and original deadline; never replay a run
+                # or an interaction whose receipt may have been lost.
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                if not read_interrupted:
+                    click.echo("Event read interrupted; retrying within the original wait deadline", err=True)
+                    read_interrupted = True
+                time.sleep(min(1, remaining))
+                continue
+            source = page.get("CursorSource")
+            if (page.get("EventOrder") != "session_seq" or source not in ("runtime", "control")
+                    or type(page.get("HasMore")) is not bool):
+                raise click.ClickException(
+                    "Hosted Runtime does not support forward session event reads; upgrade Runtime. "
+                    f"Run continues. Session: {session_id}, Command: {command_id}, Run: {run_id}"
+                )
+            if cursor_source and source != cursor_source:
+                raise click.ClickException("Hosted event cursor source changed; inspect the session above")
+            page_epoch = page.get("HistoryEpoch")
+            if page_epoch is not None and (not isinstance(page_epoch, str) or not page_epoch):
+                raise click.ClickException("Hosted Runtime returned an invalid history epoch")
+            if cursor_source and page_epoch != history_epoch:
+                raise click.ClickException("Hosted history epoch changed; inspect the session above")
+            history_epoch = page_epoch
+            cursor_source = source
+            rows = page.get("Events")
+            next_cursor = page.get("NextCursor")
+            if (not isinstance(rows, list) or type(next_cursor) is not int
+                    or any(not isinstance(e, dict) or type(e.get("SeqId")) is not int for e in rows)):
+                raise click.ClickException("Hosted Runtime returned an invalid forward event page")
+            rows = sorted(rows, key=lambda e: e["SeqId"])
+            seqs = [e["SeqId"] for e in rows]
+            if (any(seq <= cursor for seq in seqs) or len(set(seqs)) != len(seqs)
+                    or next_cursor != (seqs[-1] if seqs else cursor)
+                    or (page["HasMore"] and not rows)):
+                raise click.ClickException("Hosted Runtime returned a non-progressing forward event page")
+            cursor = next_cursor
+            for event in rows:
+                content = event.get("Content") or {}
+                fact = content.get("runtime_event") or (content.get("session_event") or {}).get("payload") or {}
+                kind = event.get("EventType")
+                if not run_id:
+                    if kind == "control.command_rejected" and fact.get("command_id") == command_id:
+                        raise click.ClickException("Admitted command was rejected by the worker")
+                    if kind == "control.message_claimed":
+                        claimed_message = fact.get("message_id")
+                    # Session worker serializes claim -> pending transition.
+                    # An accepted enqueue has no RunId until its own message is claimed.
+                    if (kind == "control.run_transition" and fact.get("state") == "pending"
+                            and claimed_message == message_id and fact.get("run_id")):
+                        run_id = fact["run_id"]
+                        click.echo(f"Run: {run_id}")
+                    else:
+                        continue
+                if fact.get("run_id", event.get("InvocationId")) != run_id:
+                    continue
+                if not fact.get("parent_scope_id"):
+                    events[event.get("EventId") or str(event["SeqId"])] = event
+                if kind == "interaction.requested":
+                    pending[(fact.get("interaction_id"), fact.get("revision"))] = fact
+                if kind in ("interaction.resolved", "interaction.expired"):
+                    resolved.add(fact.get("interaction_id"))
+                if kind in ("run.completed", "run.failed", "run.canceled") and not fact.get("parent_scope_id"):
+                    terminal = kind
+            # Decisions require the whole available forward window: resolution
+            # or the root terminal may be on a later page than the request.
+            if page["HasMore"]:
+                continue
+            for key, fact in pending.items():
+                interaction_id = fact.get("interaction_id")
+                revision = fact.get("revision")
+                if terminal or key in submitted or interaction_id in resolved:
+                    continue
+                request = fact.get("request") or {}
+                presentation = request.get("presentation") or {}
+                click.echo(presentation.get("title") or "Interaction required")
+                click.echo(presentation.get("description") or "")
+                if request.get("kind") != "approval" or not interaction_id or not revision:
+                    raise click.ClickException("Run requires input; continue in Dashboard using the session above")
+                try:
+                    approved = click.confirm("批准并继续？", default=False)
+                except click.Abort:
+                    raise click.ClickException("Run is waiting for approval; continue in Dashboard using the session above") from None
+                if time.monotonic() >= deadline:
+                    break
+                decision = "approve" if approved else "reject"
+                token = hashlib.sha256(f"{run_id}:{interaction_id}:{revision}:{decision}".encode()).hexdigest()
+                action("SubmitInteraction", {
+                    "AgentId": agent_id, "SessionId": session_id, "RunId": run_id,
+                    "InteractionId": interaction_id, "ExpectedRevision": revision,
+                    "InteractionAction": decision, "Response": {"decision": decision},
+                    "IdempotencyKey": "cli-" + token,
+                })
+                submitted.add(key)
+            if terminal:
+                if terminal != "run.completed":
+                    raise click.ClickException(f"Hosted run ended with {terminal}; Session: {session_id}, Run: {run_id}")
+                projected = project_session_messages(list(events.values()))
+                answers = [m for m in projected if m.get("Role") == "assistant" and (m.get("Content") or {}).get("text")]
+                if not answers:
+                    raise click.ClickException("Completed run has no text result; inspect the session above")
+                click.echo((answers[-1]["Content"] or {})["text"])
+                return True
+            time.sleep(1)
+        raise click.ClickException(f"Waiting timed out; run continues. Session: {session_id}, Command: {command_id}, Run: {run_id}")