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

ksadk/cli/cmd_studio.py

@@ -5,6 +5,9 @@ from __future__ import annotations
 import logging
 import os
 import secrets
+import socket
+import threading
+import time
 import webbrowser
 from pathlib import Path
 
@@ -13,6 +16,8 @@ import uvicorn
 
 from ksadk.cli.env_options import load_env_file
 from ksadk.cli.ui import print_info, print_kv, print_success, print_title
+from ksadk.studio.api import create_studio_app
+from ksadk.studio.service import StudioService
 
 # veadk 风格：日志行带模块名与行号（filename:lineno），本地排障时能直接定位代码。
 _LOG_FORMAT = "%(asctime)s %(levelname)s %(name)s %(filename)s:%(lineno)d %(message)s"
@@ -44,8 +49,6 @@ _STUDIO_LOG_CONFIG = {
     "root": {"handlers": ["default"], "level": "INFO"},
 }
 
-from ksadk.studio.api import create_studio_app
-from ksadk.studio.service import StudioService
 
 # 模型环境变量白名单。OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名，两者都接受；
 # 加载时做别名归一（见 studio()），运行时统一 OPENAI_BASE_URL 优先（与 cmd_config/cmd_model
@@ -56,12 +59,12 @@ _MODEL_ENV_KEYS = (
     "OPENAI_API_KEY",
     "OPENAI_MODEL_NAME",
 )
-# Cloud-control credentials are intentionally process-only as well.  Studio
-# needs them to use the Server Action API for a deployed Agent, but they must
-# never become browser settings, workspace files, or runtime environment.
+# Explicit env-file credentials are process-only overrides. They are never
+# copied into the workspace store or exposed as browser settings.
 _CLOUD_CONTROL_ENV_KEYS = (
     "KSYUN_ACCESS_KEY",
     "KSYUN_SECRET_KEY",
+    "KSYUN_ACCOUNT_ID",
     "KSYUN_REGION",
     "AGENTENGINE_REGION",
     "AGENTENGINE_SERVER_URL",
@@ -71,11 +74,30 @@ _CLOUD_CONTROL_ENV_KEYS = (
     "KS3_ACCESS_KEY",
     "KS3_SECRET_KEY",
 )
-_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS)
+_WEB_SEARCH_ENV_KEYS = (
+    "KSADK_WEB_SEARCH_PROVIDER",
+    "KSADK_WEB_SEARCH_API_KEY",
+    "KSADK_WEB_SEARCH_BASE_URL",
+    "KSADK_WEB_SEARCH_SCOPE",
+)
+_STUDIO_ENV_FILE_KEYS = (*_MODEL_ENV_KEYS, *_CLOUD_CONTROL_ENV_KEYS, *_WEB_SEARCH_ENV_KEYS)
 # 别名归一：两者任一有值时，把另一个也设上，保证下游无论读哪个都命中。
 _MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
 
 
+def _open_browser_when_ready(url: str, port: int, *, timeout: float = 90.0) -> None:
+    """Open Studio only after Uvicorn accepts loopback connections."""
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.5):
+                webbrowser.open(url)
+                return
+        except OSError:
+            time.sleep(0.2)
+
+
 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
 @click.argument("workspace", default=".", type=click.Path())
 @click.option("--port", "-p", default=8080, type=click.IntRange(1, 65535))
@@ -84,7 +106,7 @@ _MODEL_BASE_URL_ALIASES = ("OPENAI_BASE_URL", "OPENAI_API_BASE")
     "--env-file",
     type=click.Path(exists=True, dir_okay=False),
     help=(
-        "本地模型与云端控制环境文件；只读取允许的 OPENAI/KSYUN/KS3 "
+        "本地模型、云端控制与搜索环境文件；只读取允许的 OPENAI/KSYUN/KS3/KSADK_WEB_SEARCH "
         "字段，且仅保留在 Studio 进程"
     ),
 )
@@ -112,6 +134,7 @@ def studio(
     managed_keys = (*_STUDIO_ENV_FILE_KEYS, "KSADK_CODEX_USE_PROXY")
     previous = {key: os.environ.get(key) for key in managed_keys}
     previously_present = {key for key in managed_keys if key in os.environ}
+    configuration_overrides: dict[str, str] = {}
     try:
         if env_file:
             try:
@@ -120,27 +143,36 @@ def studio(
                 raise click.ClickException(str(exc)) from exc
             loaded_models = 0
             loaded_cloud_control = 0
+            loaded_search = 0
             for key, value in values.items():
                 if key not in _STUDIO_ENV_FILE_KEYS or not value:
                     continue
                 if key in _MODEL_ENV_KEYS:
                     loaded_models += 1
+                elif key in _WEB_SEARCH_ENV_KEYS:
+                    loaded_search += 1
                 else:
                     loaded_cloud_control += 1
                 # An explicit --env-file is the operator's selected cloud
-                # identity.  Do not silently reuse inherited AK/SK from the
-                # shell, which can point Studio at another tenant.  Model
-                # values keep their historical shell-first precedence.
-                if key in _CLOUD_CONTROL_ENV_KEYS or key not in os.environ:
-                    os.environ[key] = value
+                # identity and model configuration; it overrides inherited
+                # and saved values consistently for this process.
+                os.environ[key] = value
+                configuration_overrides[key] = os.environ[key]
             # 别名归一（方案 §2.4 第 5 点）：OPENAI_BASE_URL 与 OPENAI_API_BASE 互为别名。
             # 加载后任一有值则把另一个也设上，保证下游无论读哪个都命中；OPENAI_BASE_URL 优先。
-            resolved_base_url = os.environ.get("OPENAI_BASE_URL") or os.environ.get(
-                "OPENAI_API_BASE"
+            resolved_base_url = (
+                configuration_overrides.get("OPENAI_BASE_URL")
+                or configuration_overrides.get("OPENAI_API_BASE")
+                or os.environ.get("OPENAI_BASE_URL")
+                or os.environ.get("OPENAI_API_BASE")
             )
             if resolved_base_url:
                 os.environ["OPENAI_BASE_URL"] = resolved_base_url
                 os.environ["OPENAI_API_BASE"] = resolved_base_url
+                if any(key in configuration_overrides for key in _MODEL_BASE_URL_ALIASES):
+                    configuration_overrides.update(
+                        dict.fromkeys(_MODEL_BASE_URL_ALIASES, resolved_base_url)
+                    )
                 # base_url 至少算一次，避免显示 0/4 误导。
                 loaded_models = max(loaded_models, 2)
             print_kv(
@@ -154,15 +186,23 @@ def studio(
                     f"{loaded_cloud_control}/{len(_CLOUD_CONTROL_ENV_KEYS)} 个字段"
                     "（仅本地进程）",
                 )
+            if loaded_search:
+                print_kv("联网搜索", f"已安全加载 {loaded_search} 个字段（仅本地进程）")
         if codex_proxy == "forced":
             os.environ["KSADK_CODEX_USE_PROXY"] = "1"
         elif codex_proxy == "direct":
             os.environ["KSADK_CODEX_USE_PROXY"] = "0"
         elif codex_proxy == "auto":
             os.environ.pop("KSADK_CODEX_USE_PROXY", None)
+        if codex_proxy != "inherit":
+            configuration_overrides["KSADK_CODEX_USE_PROXY"] = {
+                "forced": "1",
+                "direct": "0",
+                "auto": "",
+            }[codex_proxy]
         session_token = os.environ.get("KSADK_STUDIO_SESSION_TOKEN") or secrets.token_urlsafe(32)
         csrf_token = secrets.token_urlsafe(24)
-        service = StudioService(root)
+        service = StudioService(root, configuration_overrides=configuration_overrides)
         app = create_studio_app(
             root,
             service=service,
@@ -171,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))
@@ -179,7 +223,12 @@ def studio(
         print_success("构建与运行均在本地执行")
         print_info("按 Ctrl+C 停止")
         if not no_open:
-            webbrowser.open(launch_url)
+            threading.Thread(
+                target=_open_browser_when_ready,
+                args=(launch_url, port),
+                daemon=True,
+                name="studio-browser-launcher",
+            ).start()
         # 业务日志（ksadk.*）走 root handler，同样带 filename:lineno。
         logging.basicConfig(level=logging.INFO, format=_LOG_FORMAT)
         uvicorn.run(
@@ -187,6 +236,9 @@ def studio(
             host="127.0.0.1",
             port=port,
             log_level="info",
+            # Lifespan cleanup releases local authority only after HTTP draining.
+            # Bound long-lived/stalled streams so a restart can acquire that authority.
+            timeout_graceful_shutdown=10,
             # Access logging stays enabled through the Studio log config while
             # retaining filename/line-number context for both API and business
             # logs.  This preserves master's observability intent and the

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}")

ksadk/cli/invoke_content.py

@@ -0,0 +1,60 @@
+"""Extract display text from supported remote response payloads."""
+
+from __future__ import annotations
+
+
+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)

ksadk/cli/openclaw_env.py

@@ -248,7 +248,7 @@ def _build_openclaw_env_vars(
     api_key = model_api_key or _resolve_env(
         "OPENCLAW_MODEL_API_KEY", "OPENAI_API_KEY", "LLM_API_KEY", "MODEL_API_KEY"
     )
-    model = model_preference or "glm-5.2"
+    model = model_preference or "deepseek-v4.1-flash"
     explicit_provider_id = model_provider_id or _resolve_env("OPENCLAW_MODEL_PROVIDER_ID")
     inferred_provider_id = explicit_provider_id
     if not inferred_provider_id and model and "/" in model:

ksadk/cli/resource_common.py

@@ -26,6 +26,32 @@ CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
 _CONSOLE = get_console()
 
 
+def build_component_config(
+    *,
+    skill_space_ids: Sequence[str] = (),
+    sandbox_template_id: str | None = None,
+    sandbox_api_key: str | None = None,
+) -> dict[str, dict[str, str]] | None:
+    """Build component_config payload for skill center + sandbox injection.
+
+    When the CLI passes this dict in the deploy/update payload, the server-side
+    build_component_runtime_env injects SKILL_SPACE_ID, KSADK_SKILL_RUNTIME_BACKEND,
+    KSADK_SANDBOX_* and E2B_* environment variables into the runtime pod.
+    """
+    # Keys MUST be PascalCase to match the server-side ComponentConfigSchema
+    # (Pydantic v2 is case-sensitive; snake_case keys are silently ignored).
+    component_config: dict[str, dict[str, str]] = {}
+    resolved = [sid.strip() for sid in skill_space_ids if sid and sid.strip()]
+    if resolved:
+        component_config["SkillWorkspace"] = {"Id": ",".join(resolved)}
+    if sandbox_template_id:
+        sandbox: dict[str, str] = {"Id": sandbox_template_id}
+        if sandbox_api_key:
+            sandbox["ApiKey"] = sandbox_api_key
+        component_config["Sandbox"] = sandbox
+    return component_config or None
+
+
 @dataclass(frozen=True)
 class ResourceActionDescriptor:
     """Explicit resource action metadata shared by help, hints and JSON output."""

ksadk/cli/runtime_bootstrap.py

@@ -16,13 +16,18 @@ from ksadk.server.factory import RuntimeAppConfig, create_runtime_app
 
 
 def _managed_a2a_card() -> Any:
-    """Build the managed discovery-only card when the runtime opts in.
+    """Build discovery first, then the full composition after platform readiness.
 
-    Import is deferred so the A2A package is only loaded when
-    ``KSADK_A2A_RUNTIME_ID`` is configured.
+    ``KSADK_A2A_RUNTIME_ID`` is available before registration so the control
+    plane can fetch the discovery card.  Operator sets the separate bootstrap
+    marker only after the complete managed projection and Secret mounts exist.
     """
     if not os.getenv("KSADK_A2A_RUNTIME_ID", "").strip():
         return None
+    if os.getenv("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true":
+        from ksadk.a2a.platform import build_managed_a2a_bootstrap_from_env
+
+        return build_managed_a2a_bootstrap_from_env()
     from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
 
     return build_managed_a2a_card_if_configured()
@@ -53,18 +58,35 @@ def create_runtime_web_app(detection: Any, agent_path: Path) -> FastAPI:
         from ksadk.resource_runtime.managed_projection import apply_managed_platform_resources
 
         apply_managed_platform_resources(config)
+    if str(detection.type.value) == "codex":
+        from ksadk.plugins.providers.codex import _bundle_a2a_experts
+        experts = _bundle_a2a_experts(config)
+        if "a2a_experts" in config and config["a2a_experts"] != experts:
+            raise ValueError("A2A_BINDING_MANIFEST_CONFLICT")
+        if experts:
+            config["a2a_experts"] = experts
     context = RuntimeLaunchContext(
         runtime_type=str(detection.type.value),
         project_dir=agent_path,
         detection=detection,
         config=config,
     )
+    managed_a2a = _managed_a2a_card()
+    executor = RuntimeExecutor(build_default_runtime_registry())
+    adapter = None
+    if (
+        managed_a2a is not None
+        and os.getenv("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true"
+    ):
+        executor.configure_managed_a2a(managed_a2a)
+        adapter = executor.create_adapter(context)
     return create_runtime_app(
         RuntimeAppConfig(
-            runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
+            runtime_executor=executor,
             launch_context=context,
             agui=agui_config_for_detection(detection),
-            a2a=_managed_a2a_card(),
+            a2a=managed_a2a,
+            a2a_runtime_adapter=adapter,
         ),
         configure_runtime_app,
     )

ksadk/codex/_expert_request_reader.py

@@ -0,0 +1,48 @@
+"""Keep the pinned SDK reader live while a managed expert waits for input."""
+from __future__ import annotations
+
+import threading
+
+
+def install_expert_request_reader(sync_client) -> None:
+    """Install before transport startup, only for fixed-expert clients.
+
+    openai-codex 0.154 dispatches server requests synchronously on its sole
+    reader. A waiting expert therefore also blocks unrelated RPC responses and
+    notifications. Writes remain serialized by the SDK's existing write lock;
+    request ownership, validation and completion remain in its handler.
+    """
+    if getattr(sync_client, '_reader_thread', None) is not None:
+        raise ValueError('A2A_CODEX_EXPERT_READER_ALREADY_STARTED')
+    required = ('_read_message', '_write_message', '_handle_server_request',
+                '_coerce_notification', '_router')
+    if any(not hasattr(sync_client, name) for name in required):
+        raise ValueError('A2A_CODEX_EXPERT_READER_UNSUPPORTED')
+
+    def respond(message):
+        try:
+            result = sync_client._handle_server_request(message)
+            sync_client._write_message({'id': message['id'], 'result': result})
+        except BaseException as exc:
+            sync_client._router.fail_all(exc)
+
+    def read():
+        try:
+            while True:
+                message = sync_client._read_message()
+                if 'method' in message and 'id' in message:
+                    # close() releases all pending bridge/approval waiters before
+                    # closing the transport. Daemon workers never own a process.
+                    threading.Thread(target=respond, args=(message,),
+                                     name='codex-expert-request', daemon=True).start()
+                elif 'method' in message:
+                    method = message['method']
+                    if isinstance(method, str):
+                        sync_client._router.route_notification(
+                            sync_client._coerce_notification(method, message.get('params')))
+                else:
+                    sync_client._router.route_response(message)
+        except BaseException as exc:
+            sync_client._router.fail_all(exc)
+
+    sync_client._reader_loop = read