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

ksadk/codex/projection.py

@@ -0,0 +1,24 @@
+"""Native input projection contract consumed by the Codex lifecycle adapter."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from ksadk.runtime.adapter import ResumePayload, StartRequest
+
+
+@dataclass(frozen=True)
+class ProjectedCodexTurn:
+    """SDK-ready turn input; contains no lifecycle or execution behavior."""
+    input: Any
+
+
+class CodexTurnProjection(Protocol):
+    def prepare(self, request: StartRequest) -> StartRequest: ...
+
+    def project(
+        self, request: StartRequest | None, payload: ResumePayload | None,
+    ) -> ProjectedCodexTurn: ...
+
+    def close(self) -> None: ...

ksadk/codex/runtime.py

@@ -19,19 +19,15 @@
 from __future__ import annotations
 
 import asyncio
-import base64
-import binascii
-import hashlib
 import json
 import logging
-import re
 import time
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from pathlib import Path
 from typing import Any, AsyncIterator, Optional
 
-from ksadk.codex.client import CodexClient
+from ksadk.codex.client import CodexClient, CodexPluginBootstrap
+from ksadk.codex.projection import CodexTurnProjection
 from ksadk.events.adapters.codex import CodexAdapterContext, CodexEventAdapter
 from ksadk.events.canonical import (
     ErrorInfo,
@@ -107,11 +103,26 @@ class CodexRuntimeAdapter(RuntimeAdapter):
         *,
         sandbox_read_only: bool = True,
         turn_timeout_seconds: Optional[float] = None,
+        bound_skill_paths: Mapping[str, str] | None = None,
+        plugin_bootstrap: CodexPluginBootstrap | None = None,
+        turn_projector: CodexTurnProjection | None = None,
     ) -> None:
         super().__init__(_CodexAsBaseRuntime(client))
         self._client = client
         self._sandbox_read_only = sandbox_read_only
         self._turn_timeout_seconds = turn_timeout_seconds
+        if turn_projector is not None and bound_skill_paths:
+            raise ValueError("Skill paths must be owned by the supplied turn projector")
+        if turn_projector is None:
+            # Compatibility for direct SDK construction; production factories inject
+            # the same official projector, never a second input implementation.
+            from ksadk.plugins.providers.codex_turn import CodexTurnProjector
+
+            turn_projector = CodexTurnProjector(bound_skill_paths=bound_skill_paths)
+        self._turn_projector = turn_projector
+        self._plugin_bootstrap = plugin_bootstrap
+        self._plugin_bootstrap_lock = asyncio.Lock()
+        self._plugins_bootstrapped = False
         self._threads: dict[str, _CodexThread] = {}
         self._requests: dict[str, StartRequest] = {}
         self._known_threads: set[str] = set()
@@ -147,13 +158,19 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             goal=RuntimeCapability(supported=True, mode="native"),
             loop=_unavailable("codex_loop_requires_run_control_spec"),
             plan=RuntimeCapability(supported=True, mode="native"),
+            interaction_mode="live_submit",
         )
 
     # ---- 六动词 ----
 
     async def start(self, request: StartRequest) -> RunHandle:
+        # A failed bootstrap must leave no native thread behind. The success
+        # bit is set only after marketplace/add, every plugin/install, and the
+        # enabled-inventory reconciliation all complete on this same client.
+        await self._bootstrap_plugins_once()
         # 新 thread 由后端分配真实 thread_id(thread_start);metadata 携带的 thread_id
         # 表示接入既有 thread(resume 语义,run_turn 时按 resume 接入)。
+        request = self._turn_projector.prepare(request)
         provided = request.metadata.get("thread_id")
         if provided:
             thread_id = str(provided)
@@ -197,6 +214,16 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             native_ref={"thread_id": thread_id, "user_id": request.user_id},
         )
 
+    async def _bootstrap_plugins_once(self) -> None:
+        config = self._plugin_bootstrap
+        if config is None or self._plugins_bootstrapped:
+            return
+        async with self._plugin_bootstrap_lock:
+            if self._plugins_bootstrapped:
+                return
+            await self._client.bootstrap_plugins(config)
+            self._plugins_bootstrapped = True
+
     def stream(self, handle: RunHandle) -> AsyncIterator[RuntimeEvent]:
         return self._stream_events(handle)
 
@@ -276,7 +303,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
         elif payload.kind == "hitl_answer":
             resolved = await self._client.resolve_interaction(
                 payload.call_id,
-                {key: value for key, value in raw.items() if key != "decision"},
+                raw,
             )
         else:
             raise ValueError("Codex live submit requires approval_decision or hitl_answer")
@@ -353,23 +380,50 @@ class CodexRuntimeAdapter(RuntimeAdapter):
         )
 
     async def close(self, handle: RunHandle) -> None:
+        self._do_not_persist.add(handle.run_id)
+        await self.close_all()
+
+    async def compact_session(self, thread_id: str, config: dict[str, Any]) -> dict[str, Any]:
+        """Compact an existing native session using this build's client."""
+        await self._bootstrap_plugins_once()
+        await self._client.resume_thread(thread_id, config)
+        return await self._client.compact_thread(thread_id)
+
+    async def close_all(self) -> None:
+        """Dispose every thread and the activation-owned App Server process.
+
+        One ``CodexRuntimeAdapter`` owns one client transport. Closing any
+        attached Kernel handle therefore closes the transport as a unit; this
+        additive helper also lets a draining AgentProvider clean up a runtime
+        that has been created but not started yet.
+        """
+
         if self._closed:
             return
         self._closed = True
-        thread = self._threads.pop(handle.run_id, None)
-        self._requests.pop(handle.run_id, None)
-        active = thread is not None and thread.streaming and not thread.done
-        if active:
+        threads = tuple(self._threads.values())
+        active_threads = tuple(thread for thread in threads if thread.streaming and not thread.done)
+        for thread in active_threads:
             thread.interrupt_event.set()
         try:
-            if active:
+            for thread in active_threads:
                 await self._client.interrupt_active_turn(thread.thread_id)
         finally:
             # AsyncCodex.close owns terminate/wait/kill for the app-server child.
-            await self._client.close()
-            self._do_not_persist.add(handle.run_id)
-            self._known_threads.discard(handle.run_id)
-            self._pending_cancels.discard(handle.run_id)
+            try:
+                await self._client.close()
+            finally:
+                self._turn_projector.close()
+            thread_ids = {
+                *self._known_threads,
+                *self._threads,
+                *self._requests,
+            }
+            self._do_not_persist.update(thread_ids)
+            self._threads.clear()
+            self._requests.clear()
+            self._known_threads.clear()
+            self._pending_cancels.clear()
 
     # ---- stream → RuntimeEvent(phase 翻译 + 中断竞速) ----
 
@@ -397,13 +451,10 @@ class CodexRuntimeAdapter(RuntimeAdapter):
 
         request = thread.__dict__.get("_start_request")
         resume_state = thread.__dict__.get("_resume")
-        if request is not None:
-            prompt = _request_prompt(request)
-        elif resume_state is not None:
-            prompt = _resume_prompt(resume_state.get("payload"))
-        else:
-            prompt = ""
-        run_input = _build_run_input(request, prompt)
+        projected = self._turn_projector.project(
+            request, resume_state.get("payload") if resume_state is not None else None,
+        )
+        run_input = projected.input
         thread.streaming = True
         thread.turn_id = thread.turn_id or f"turn_{thread.thread_id}"
         try:
@@ -438,14 +489,12 @@ class CodexRuntimeAdapter(RuntimeAdapter):
     ) -> AsyncIterator[RuntimeEvent]:
         request = thread.__dict__.get("_start_request") or thread.__dict__.get("_request_config")
         adapter = CodexEventAdapter(
-            known_thread_ids=(thread.thread_id,)
-            if thread.continuation_preexisting
-            else (),
+            known_thread_ids=(thread.thread_id,) if thread.continuation_preexisting else (),
         )
         context = CodexAdapterContext(run_id=self._event_run_id(handle))
         run_config: dict[str, Any] = {"sandbox_read_only": self._sandbox_read_only}
         if request is not None and request.config:
-            for key in ("sandbox", "approval_mode", "summary", "collaboration_mode"):
+            for key in ("sandbox", "approval_mode", "summary", "collaboration_mode", "effort"):
                 value = request.config.get(key)
                 if key == "approval_mode" and value == "manual":
                     continue
@@ -512,8 +561,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
                     # finish promptly, close the transport *before* awaiting
                     # the waiter so MessageRouter.fail_all can release it.
                     drain_deadline = (
-                        asyncio.get_running_loop().time()
-                        + _INTERRUPT_DRAIN_TIMEOUT_SECONDS
+                        asyncio.get_running_loop().time() + _INTERRUPT_DRAIN_TIMEOUT_SECONDS
                     )
                     while True:
                         drain_remaining = max(
@@ -557,9 +605,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
                 # autoApprovalReview 不产生 canonical 事件(adapter 静默),但
                 # cancel 级联丢弃审批的契约依赖 runtime 的 pending 跟踪。
                 chunk_method = (
-                    str((chunk or {}).get("method") or "")
-                    if isinstance(chunk, dict)
-                    else ""
+                    str((chunk or {}).get("method") or "") if isinstance(chunk, dict) else ""
                 )
                 if chunk_method in {
                     "item/autoApprovalReview/started",
@@ -567,9 +613,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
                 }:
                     review_params = chunk.get("params") or {}
                     review_id = str(
-                        review_params.get("reviewId")
-                        or review_params.get("review_id")
-                        or ""
+                        review_params.get("reviewId") or review_params.get("review_id") or ""
                     )
                     if review_id:
                         if chunk_method.endswith("started"):
@@ -643,9 +687,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             framework="codex",
             native_run_id=handle.run_id,
             metadata={
-                "agent_id": (
-                    str(request.agent_id or "codex") if request is not None else "codex"
-                ),
+                "agent_id": (str(request.agent_id or "codex") if request is not None else "codex"),
                 "user_id": (
                     request.user_id
                     if request is not None
@@ -670,8 +712,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             "user_id": str(getattr(request, "user_id", "") or "user"),
             "session_id": str(getattr(request, "session_id", "") or ""),
             "invocation_id": str(
-                (getattr(request, "metadata", None) or {}).get("invocation_id")
-                or ""
+                (getattr(request, "metadata", None) or {}).get("invocation_id") or ""
             ),
         }
         merged = {**caller_scope, **dict(event.source.metadata or {})}
@@ -706,9 +747,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             "source": self._make_source(handle),
         }
 
-    def _make_run_canceled(
-        self, handle: RunHandle, *, reason: str | None = None
-    ) -> RunCanceled:
+    def _make_run_canceled(self, handle: RunHandle, *, reason: str | None = None) -> RunCanceled:
         framework = "codex"
         run_id = self._event_run_id(handle)
         scope_id = stable_scope_id(framework, run_id)
@@ -744,9 +783,7 @@ class CodexRuntimeAdapter(RuntimeAdapter):
             reason=reason,
         )
 
-    def _make_run_failed(
-        self, handle: RunHandle, error_message: str
-    ) -> RunFailed:
+    def _make_run_failed(self, handle: RunHandle, error_message: str) -> RunFailed:
         framework = "codex"
         run_id = self._event_run_id(handle)
         scope_id = stable_scope_id(framework, run_id)
@@ -800,243 +837,6 @@ async def _anext_or_stop(gen: AsyncIterator[Any]) -> Any:
         return _STREAM_STOP
 
 
-def _resume_prompt(payload: Optional[ResumePayload]) -> Any:
-    if payload is None:
-        return ""
-    if isinstance(payload.data, str):
-        return payload.data
-    return json.dumps(payload.data, ensure_ascii=False, sort_keys=True)
-
-
-def _coerce_prompt_text(value: Any) -> Any:
-    """把 canonical message 形态的 input 压成 SDK 可接受的文本。
-
-    ``openai-codex`` 0.147 的 run input 只接受 TextInput/str;请求侧没有
-    conversation preprocessing 时 ``request.input`` 可能是
-    ``[{role, content}]`` 历史列表,直接透传会 ``unsupported input item``。
-    """
-    if isinstance(value, str) or value is None:
-        return value
-    if isinstance(value, dict):
-        content = value.get("content") if "role" in value else value.get("text")
-        if isinstance(content, str):
-            return content
-        if isinstance(content, dict):
-            text = content.get("text") or content.get("content")
-            if isinstance(text, str):
-                return text
-        return str(value)
-    if isinstance(value, list):
-        texts = [
-            text
-            for text in (_coerce_prompt_text(item) for item in value)
-            if isinstance(text, str) and text
-        ]
-        return "\n".join(texts) if texts else str(value)
-    return str(value)
-
-
-def _request_prompt(request: StartRequest) -> Any:
-    """Render canonical conversation history for a native Codex turn.
-
-    只传 user 消息历史 + 当前 input，不传 assistant 的完整回复（避免 codex 复述历史）。
-    assistant 回复用简短摘要代替，仅维持对话结构。
-    """
-    # A resumed Codex thread already owns its transcript. Re-sending Studio's
-    # transport-neutral history would duplicate every prior turn after refresh.
-    if str(request.metadata.get("thread_id") or "").strip():
-        return (
-            request.input
-            if _is_structured_turn_input(request.input)
-            else _coerce_prompt_text(request.input)
-        )
-
-    conversation = request.conversation_preprocessing()
-    if conversation is None or not conversation.messages:
-        # Keep native text/image/mention parts intact for _build_run_input().
-        # Flattening this list turns an image dict into user-visible text.
-        return (
-            request.input
-            if _is_structured_turn_input(request.input)
-            else _coerce_prompt_text(request.input)
-        )
-
-    lines: list[str] = []
-    for message in conversation.messages:
-        content = message.get("content")
-        if not isinstance(content, str):
-            continue
-        role = str(message.get("role") or "user").strip().lower()
-        if role == "assistant":
-            # 不传完整回复，只标注"已回复"，避免 codex 复述
-            summary = content[:80] + ("..." if len(content) > 80 else "")
-            lines.append(f"[上一轮已回复: {summary}]")
-        elif role == "user":
-            lines.append(f"User: {content}")
-    return "\n".join(lines) or request.input
-
-
-def _is_structured_turn_input(value: Any) -> bool:
-    return isinstance(value, list) and any(
-        isinstance(item, dict) and isinstance(item.get("type"), str)
-        for item in value
-    )
-
-
-def _build_run_input(request: Optional[StartRequest], prompt: Any) -> Any:
-    """Compose Codex skills and native text/image/mention turn input."""
-    try:
-        from openai_codex import ImageInput, LocalImageInput, MentionInput, SkillInput, TextInput
-    except ImportError:
-        return prompt
-    skills: list[SkillInput] = []
-    if request is not None:
-        raw = request.config.get("skills") if request.config else None
-        if isinstance(raw, list):
-            for item in raw:
-                if not isinstance(item, dict):
-                    continue
-                name = str(item.get("name") or "").strip()
-                path = str(item.get("path") or "").strip()
-                if name and path:
-                    skills.append(SkillInput(name=name, path=path))
-    native_items: list[Any] = []
-    raw_input = request.input if request is not None else prompt
-    if isinstance(raw_input, list):
-        text_replaced = False
-        for item in raw_input:
-            if not isinstance(item, dict):
-                continue
-            kind = str(item.get("type") or "")
-            if not kind and "role" in item:
-                # canonical conversation message({role, content});当前 input
-                # 已由 prompt(或 conversation preprocessing)承载,跳过历史项。
-                continue
-            if kind in {"text", "input_text"}:
-                text = str(
-                    prompt
-                    if not text_replaced and isinstance(prompt, str)
-                    else item.get("text") or ""
-                )
-                text_replaced = True
-                if text:
-                    native_items.append(TextInput(text=text))
-            elif kind in {"image", "input_image"} and (
-                item.get("url") or item.get("image_url")
-            ):
-                native_items.append(
-                    ImageInput(url=str(item.get("url") or item.get("image_url")))
-                )
-            elif kind == "localImage" and item.get("path"):
-                native_items.append(LocalImageInput(path=str(item["path"])))
-            elif kind == "input_file" and (
-                item.get("file_data")
-                or str(item.get("file_url") or "").startswith("data:")
-            ):
-                file_path = _materialize_inline_file(
-                    str(item.get("file_data") or item.get("file_url")),
-                    str(item.get("filename") or "attachment"),
-                )
-                if file_path is not None:
-                    # App Server's ``mention`` input is presentation metadata:
-                    # current Codex versions do not include it in the model's
-                    # user message.  Always add an explicit model-visible
-                    # attachment context as well.  Small textual files are
-                    # inlined deterministically; binary/large files expose a
-                    # sandbox-readable path that Codex can inspect with tools.
-                    native_items.append(
-                        TextInput(text=_attachment_context_text(file_path, item))
-                    )
-                    native_items.append(
-                        MentionInput(name=file_path.name, path=str(file_path))
-                    )
-            elif kind == "mention" and item.get("path"):
-                native_items.append(
-                    MentionInput(
-                        name=str(item.get("name") or item["path"]),
-                        path=str(item["path"]),
-                    )
-                )
-    else:
-        text = prompt if isinstance(prompt, str) else str(prompt or "")
-        if text:
-            native_items.append(TextInput(text=text))
-    combined = [*skills, *native_items]
-    if not combined:
-        return prompt
-    if len(combined) == 1 and isinstance(combined[0], TextInput) and not skills:
-        return combined[0].text
-    return combined
-
-
-def _materialize_inline_file(data_url: str, filename: str) -> Path | None:
-    """Materialize a bounded Studio inline attachment for native Codex."""
-
-    match = re.fullmatch(r"data:([^;,]+)?;base64,([A-Za-z0-9+/=\s]+)", data_url)
-    encoded = match.group(2) if match is not None else data_url.strip()
-    try:
-        payload = base64.b64decode(encoded, validate=True)
-    except (ValueError, binascii.Error):
-        return None
-    if not payload or len(payload) > 10 * 1024 * 1024:
-        return None
-    safe_name = re.sub(r"[^A-Za-z0-9._-]+", "-", Path(filename).name).strip(".-")
-    safe_name = safe_name[:120] or "attachment"
-    digest = hashlib.sha256(payload).hexdigest()
-    path = Path("/tmp/ksadk-codex-attachments") / digest / safe_name
-    path.parent.mkdir(parents=True, exist_ok=True)
-    if not path.exists():
-        path.write_bytes(payload)
-    return path
-
-
-_MAX_INLINE_ATTACHMENT_TEXT_BYTES = 64 * 1024
-_TEXT_ATTACHMENT_SUFFIXES = {
-    ".csv",
-    ".html",
-    ".htm",
-    ".ini",
-    ".json",
-    ".jsonl",
-    ".log",
-    ".md",
-    ".py",
-    ".rst",
-    ".toml",
-    ".tsv",
-    ".txt",
-    ".xml",
-    ".yaml",
-    ".yml",
-}
-
-
-def _attachment_context_text(path: Path, item: Mapping[str, Any]) -> str:
-    """Build model-visible context for a materialized Responses input file."""
-
-    name = str(item.get("filename") or path.name).replace('"', "'")
-    inline_data = item.get("inlineData")
-    inline_mime = inline_data.get("mimeType") if isinstance(inline_data, Mapping) else None
-    mime_type = str(item.get("mime_type") or inline_mime or "").strip().lower()
-    source = str(item.get("file_data") or item.get("file_url") or "")
-    data_url_match = re.match(r"data:([^;,]+)", source)
-    if not mime_type and data_url_match is not None:
-        mime_type = data_url_match.group(1).strip().lower()
-    is_text = mime_type.startswith("text/") or path.suffix.lower() in _TEXT_ATTACHMENT_SUFFIXES
-    header = f'<uploaded_attachment name="{name}" path="{path}">'
-    if not is_text:
-        return (
-            f"{header}\n"
-            "The uploaded file is available at the path above. Read it with an appropriate "
-            "tool before answering questions about its contents.\n"
-            "</uploaded_attachment>"
-        )
-
-    raw = path.read_bytes()
-    truncated = len(raw) > _MAX_INLINE_ATTACHMENT_TEXT_BYTES
-    text = raw[:_MAX_INLINE_ATTACHMENT_TEXT_BYTES].decode("utf-8", errors="replace")
-    suffix = "\n[attachment content truncated]" if truncated else ""
-    return f"{header}\n{text}{suffix}\n</uploaded_attachment>"
 
 
 __all__ = ["CodexRuntimeAdapter"]

ksadk/common/auth.py

@@ -49,6 +49,8 @@ class AWSV4Auth:
         secret_access_key: str = "",
         region: str = "cn-beijing-6",
         service: str = "aicp",
+        *,
+        allow_env_fallback: bool = True,
     ):
         """初始化签名器
 
@@ -57,17 +59,21 @@ class AWSV4Auth:
             secret_access_key: 访问密钥 (SK)，默认从环境变量读取
             region: 区域 ID (如 cn-beijing-6)
             service: 服务名称 (如 kmr, aicp, iam 等)
+            allow_env_fallback: 显式运行时连接设为 False，禁止继承宿主凭证
         """
-        self.access_key_id = (
-            access_key_id
-            or os.environ.get("KSYUN_ACCESS_KEY")
-            or os.environ.get("KS3_ACCESS_KEY", "")
-        )
-        self.secret_access_key = (
-            secret_access_key
-            or os.environ.get("KSYUN_SECRET_KEY")
-            or os.environ.get("KS3_SECRET_KEY", "")
-        )
+        self.access_key_id = access_key_id
+        self.secret_access_key = secret_access_key
+        if allow_env_fallback:
+            self.access_key_id = (
+                self.access_key_id
+                or os.environ.get("KSYUN_ACCESS_KEY")
+                or os.environ.get("KS3_ACCESS_KEY", "")
+            )
+            self.secret_access_key = (
+                self.secret_access_key
+                or os.environ.get("KSYUN_SECRET_KEY")
+                or os.environ.get("KS3_SECRET_KEY", "")
+            )
         self.region = region
         self.service = service
 

ksadk/configs/env_registry.py

@@ -232,6 +232,28 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "Isolate native Codex state under the project workspace; set to 0 for debugging only.",
         "1",
     ),
+    EnvVarSpec(
+        "KSADK_DSH_BIN",
+        "plugins",
+        (
+            "Optional absolute path to the managed DSH command; must match the pinned "
+            "toolchain version."
+        ),
+    ),
+    EnvVarSpec(
+        "KSADK_DSH_HOME",
+        "plugins",
+        (
+            "Directory containing the isolated DSH Profile; defaults to .agentkit/dsh-home "
+            "in the workspace."
+        ),
+    ),
+    EnvVarSpec(
+        "KSADK_DSH_PROFILE",
+        "plugins",
+        "DSH Profile name used by Studio and the plugin bridge.",
+        "studio",
+    ),
     EnvVarSpec(
         "KSADK_STUDIO_NO_SECURITY",
         "studio",
@@ -347,6 +369,12 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         sensitive=True,
     ),
     EnvVarSpec("KSADK_KB_TOP_K", "knowledge_base", "Knowledge-base retrieval result count.", "5"),
+    EnvVarSpec(
+        "KSADK_CHECKPOINT_DSN",
+        "sessions",
+        "Framework-agnostic PostgreSQL checkpoint DSN.",
+        sensitive=True,
+    ),
     EnvVarSpec(
         "KSADK_LANGGRAPH_CHECKPOINT_DSN",
         "sessions",
@@ -356,9 +384,17 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_LANGGRAPH_AUTO_CHECKPOINT",
         "sessions",
-        "Allow a hosted LangGraph runner to rebuild a factory-exported graph with the managed PostgreSQL saver.",
+        (
+            "Allow a hosted LangGraph runner to rebuild a factory-exported graph with the "
+            "managed PostgreSQL saver."
+        ),
         "false",
     ),
+    EnvVarSpec(
+        "KSADK_LANGGRAPH_POSTGRES_REQUIREMENTS",
+        "builders",
+        "Internal bundled LangGraph PostgreSQL checkpointer requirement constant.",
+    ),
     EnvVarSpec(
         "KSADK_LOCAL_SKILLS_DIR", "skills", "Local directory containing extracted Skill packages."
     ),
@@ -436,6 +472,18 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "model_proxy",
         "Comma-separated model allowlist for the experimental model proxy.",
     ),
+    EnvVarSpec(
+        "KSADK_PERSISTENCE_PROBE_CACHE_TTL",
+        "sessions",
+        "PostgreSQL persistence readiness cache TTL seconds.",
+        "30",
+    ),
+    EnvVarSpec(
+        "KSADK_PERSISTENCE_PROBE_TIMEOUT",
+        "sessions",
+        "PostgreSQL persistence readiness timeout seconds.",
+        "2",
+    ),
     EnvVarSpec("KSADK_PG_EVENTS_TABLE", "sessions", "Internal PostgreSQL events table constant."),
     EnvVarSpec(
         "KSADK_PG_SESSIONS_TABLE", "sessions", "Internal PostgreSQL sessions table constant."
@@ -473,6 +521,11 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "skills",
         "Comma-separated public Skill Space ids appended after user spaces.",
     ),
+    EnvVarSpec(
+        "KSADK_RESOURCE_IAM_ENDPOINT",
+        "platform_resources",
+        "Operator-owned IAM endpoint used to authorize Studio platform-resource bindings.",
+    ),
     EnvVarSpec(
         "KSADK_RESPONSES_SESSION_HEADER",
         "runners",
@@ -640,7 +693,10 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
     EnvVarSpec(
         "KSADK_AGENT_KERNEL",
         "kernel",
-        "Opt in to Agent Kernel ingress locally; managed deployment may use AGENT_KERNEL_ENABLED instead.",
+        (
+            "Opt in to Agent Kernel ingress locally; managed deployment may use "
+            "AGENT_KERNEL_ENABLED instead."
+        ),
         "false",
     ),
     EnvVarSpec("KSADK_SESSION_PATH", "sessions", "Conversation local SQLite database path."),
@@ -810,7 +866,7 @@ _ENV_VAR_REGISTRY_ITEMS: tuple[EnvVarSpec, ...] = (
         "KSADK_WEB_VERSION",
         "web",
         "Published KsADK Web npm version used for a reproducible wheel build.",
-        "0.3.2",
+        "0.3.7",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",