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

ksadk/codex/runtime.py

@@ -107,11 +107,13 @@ class CodexRuntimeAdapter(RuntimeAdapter):
         *,
         sandbox_read_only: bool = True,
         turn_timeout_seconds: Optional[float] = None,
+        bound_skill_paths: Mapping[str, str] | None = None,
     ) -> None:
         super().__init__(_CodexAsBaseRuntime(client))
         self._client = client
         self._sandbox_read_only = sandbox_read_only
         self._turn_timeout_seconds = turn_timeout_seconds
+        self._bound_skill_paths = dict(bound_skill_paths or {})
         self._threads: dict[str, _CodexThread] = {}
         self._requests: dict[str, StartRequest] = {}
         self._known_threads: set[str] = set()
@@ -147,6 +149,7 @@ 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",
         )
 
     # ---- 六动词 ----
@@ -154,6 +157,25 @@ class CodexRuntimeAdapter(RuntimeAdapter):
     async def start(self, request: StartRequest) -> RunHandle:
         # 新 thread 由后端分配真实 thread_id(thread_start);metadata 携带的 thread_id
         # 表示接入既有 thread(resume 语义,run_turn 时按 resume 接入)。
+        if self._bound_skill_paths:
+            skills = request.config.get("skills") if request.config else None
+            if isinstance(skills, list):
+                projected_skills = []
+                for item in skills:
+                    if not isinstance(item, dict):
+                        continue
+                    name = str(item.get("name") or "").strip()
+                    projected_skills.append(
+                        {
+                            **item,
+                            "path": self._bound_skill_paths.get(
+                                name, str(item.get("path") or "")
+                            ),
+                        }
+                    )
+                request = request.model_copy(
+                    update={"config": {**request.config, "skills": projected_skills}}
+                )
         provided = request.metadata.get("thread_id")
         if provided:
             thread_id = str(provided)
@@ -353,23 +375,43 @@ class CodexRuntimeAdapter(RuntimeAdapter):
         )
 
     async def close(self, handle: RunHandle) -> None:
+        self._do_not_persist.add(handle.run_id)
+        await self.close_all()
+
+    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)
+            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 翻译 + 中断竞速) ----
 

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",
@@ -356,7 +378,10 @@ _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(
@@ -640,7 +665,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 +838,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.4",
     ),
     EnvVarSpec(
         "KSADK_WORKING_SET_MAX_FILES",

ksadk/configs/settings.py

@@ -628,3 +628,12 @@ def setup_environment(agent_path: Path | str):
         setup_proxy_redirect_if_enabled()
     except Exception:  # noqa: BLE001  代理可选,失败不影响主流程(默认关时本就不触发)
         pass
+
+    # 5. 沙箱控制面 URL 内网探测:在 Pod 内探测 198 公共服务网内网地址,
+    # 可达则覆盖 E2B_API_URL 为内网域名,private_only 节点也能访问沙箱控制面。
+    try:
+        from ksadk.sandbox import setup_sandbox_api_url_if_needed
+
+        setup_sandbox_api_url_if_needed()
+    except Exception:  # noqa: BLE001  沙箱可选,失败不影响主流程
+        pass

ksadk/context_engine/contributors.py

@@ -24,6 +24,14 @@ logger = logging.getLogger(__name__)
 ContributorFailureMode = Literal["skip", "warn", "fail"]
 ContributorCacheability = Literal["stable", "turn", "none"]
 
+_TRUST_RANK: dict[ContextTrustLevel, int] = {
+    "untrusted": 0,
+    "user": 1,
+    "resource": 2,
+    "developer": 3,
+    "platform": 4,
+}
+
 
 @dataclass(frozen=True)
 class ContributorCapabilities:
@@ -131,13 +139,15 @@ class WorkspaceRulesContributor(ContextContributor):
             return []
         items: list[ContextItem] = []
         for index, section in enumerate(sections):
+            raw_tokens = section.metadata.get("tokens", 0)
+            tokens = int(raw_tokens) if isinstance(raw_tokens, (int, str)) else 0
             items.append(
                 _make_item(
                     contributor_id=self.capabilities.contributor_id,
                     trust_level=self.capabilities.trust_level,
                     kind="resource_manifest",
                     content=section.content,
-                    tokens=int(section.metadata.get("tokens", 0)) or 1,
+                    tokens=tokens or 1,
                     source=section.source,
                     metadata={"path": section.metadata.get("path"), "kind": "rule_file"},
                 )
@@ -267,6 +277,60 @@ class ContributionResult:
     warnings: tuple[str, ...]
 
 
+def _admit_contribution_items(
+    contributor: ContextContributor,
+    items: object,
+) -> tuple[list[ContextItem], str | None]:
+    """Validate one Contributor result and enforce its declared token ceiling.
+
+    A Contributor is an untrusted capability boundary.  It cannot promote an
+    item above the trust level granted at registration, mark context as
+    required, return duplicate identities, or make the Host confuse token
+    counts with list indexes.  Items that do not fit the declared budget are
+    deterministically omitted while later, smaller items may still fit.
+    """
+
+    if not isinstance(items, list) or not all(isinstance(item, ContextItem) for item in items):
+        raise TypeError("ContextContributor must return a list of ContextItem values")
+
+    capabilities = contributor.capabilities
+    if capabilities.max_tokens < 0:
+        raise ValueError("ContextContributor max_tokens cannot be negative")
+    if capabilities.timeout_ms <= 0:
+        raise ValueError("ContextContributor timeout_ms must be positive")
+
+    admitted: list[ContextItem] = []
+    seen_ids: set[str] = set()
+    used_tokens = 0
+    omitted = 0
+    maximum_trust = _TRUST_RANK[capabilities.trust_level]
+    for item in items:
+        if not item.item_id or item.item_id in seen_ids:
+            raise ValueError("ContextContributor item ids must be non-empty and unique")
+        seen_ids.add(item.item_id)
+        if item.required:
+            raise ValueError("ContextContributor cannot mark context as required")
+        if _TRUST_RANK[item.trust_level] > maximum_trust:
+            raise ValueError(
+                "ContextContributor cannot elevate item trust above its registered level"
+            )
+        if item.estimated_tokens < 0:
+            raise ValueError("ContextContributor estimated_tokens cannot be negative")
+        if used_tokens + item.estimated_tokens > capabilities.max_tokens:
+            omitted += 1
+            continue
+        admitted.append(item)
+        used_tokens += item.estimated_tokens
+
+    warning = None
+    if omitted:
+        warning = (
+            f"{contributor.id()}: omitted {omitted} context item(s) that exceeded "
+            f"the {capabilities.max_tokens}-token contributor budget"
+        )
+    return admitted, warning
+
+
 async def run_contributors(
     contributors: Sequence[ContextContributor],
     request: ContextContributionRequest,
@@ -284,24 +348,25 @@ async def run_contributors(
     async def _run_one(c: ContextContributor) -> tuple[str, list[ContextItem], str, str | None]:
         timeout = max(c.capabilities.timeout_ms, 1) / 1000.0
         try:
-            items = await asyncio.wait_for(c.contribute(request), timeout=timeout)
+            raw_items = await asyncio.wait_for(c.contribute(request), timeout=timeout)
+            items, budget_warning = _admit_contribution_items(c, raw_items)
         except asyncio.TimeoutError:
             return c.id(), [], "timeout", f"{c.id()}: timeout"
         except Exception as exc:  # noqa: BLE001
             if c.capabilities.failure_mode == "fail":
                 raise
-            return c.id(), [], "error", f"{c.id()}: {exc}"
-        # 单 Contributor 总 token 约束
-        if items and sum(i.estimated_tokens for i in items) > c.capabilities.max_tokens:
-            items = items[: c.capabilities.max_tokens]  # best-effort 限条数
-        return c.id(), items, "ok", None
+            warning = f"{c.id()}: {exc}" if c.capabilities.failure_mode == "warn" else None
+            return c.id(), [], "error", warning
+        return c.id(), items, "ok", budget_warning
 
     results = await asyncio.gather(*[_run_one(c) for c in contributors], return_exceptions=True)
     all_items: list[ContextItem] = []
     status: dict[str, str] = {}
     warnings: list[str] = []
     for contributor, r in zip(contributors, results):
-        if isinstance(r, Exception):
+        if isinstance(r, BaseException):
+            if isinstance(r, asyncio.CancelledError):
+                raise r
             if contributor.capabilities.failure_mode == "fail":
                 raise r
             warnings.append(f"{contributor.id()}: {r}")

ksadk/conversations/__init__.py

@@ -11,6 +11,25 @@ def _exports(module: str, *names: str) -> dict[str, tuple[str, str]]:
 
 
 _EXPORTS = {
+    **_exports(
+        "ksadk.conversations.contracts",
+        "ConversationCapability",
+        "ConversationInput",
+        "ConversationAttachmentPart",
+        "ConversationItem",
+        "ConversationSurface",
+        "ConversationTextPart",
+        "validate_conversation_input",
+        "validate_surface_input",
+    ),
+    **_exports(
+        "ksadk.conversations.projector",
+        "project_conversation_item",
+    ),
+    **_exports(
+        "ksadk.conversations.reducer",
+        "ConversationItemReducer",
+    ),
     **_exports(
         "ksadk.conversations.attachments",
         "decode_inline_data",

ksadk/conversations/context.py

@@ -5,6 +5,8 @@ import re
 from collections.abc import Mapping, Sequence
 from typing import Any, Dict, Iterable, List
 
+from ksadk.events.canonical import ItemCompleted, parse_runtime_event
+from ksadk.events.content import TextContent
 from ksadk.sessions.base import SessionEvent
 from ksadk.tools.result_budget import (
     ToolResultBudget,
@@ -99,6 +101,60 @@ def extract_event_text(event: SessionEvent) -> str:
     )
 
 
+def _canonical_completed_message(
+    event: SessionEvent,
+) -> tuple[str, str, tuple[str, str]] | None:
+    """Return one canonical assistant message without flattening its identity.
+
+    Canonical RuntimeEvents are persisted inside the existing ``SessionEvent``
+    carrier.  Legacy transcript projection only inspects carrier-level fields,
+    so an ``item.completed`` message otherwise disappears from the next turn's
+    history.  The canonical event id and ``(scope_id, item_id)`` are both kept:
+    replays are idempotent, while equal text from different items remains
+    distinct.
+    """
+
+    raw = (event.content or {}).get("runtime_event")
+    if not isinstance(raw, Mapping):
+        return None
+    try:
+        canonical = parse_runtime_event(dict(raw))
+    except (TypeError, ValueError):
+        return None
+    if (
+        not isinstance(canonical, ItemCompleted)
+        or canonical.item_kind != "message"
+        or event.event_type != canonical.event_type
+    ):
+        return None
+    text = sanitize_event_text_for_context(
+        "".join(
+            part.text for part in canonical.snapshot.parts if isinstance(part, TextContent)
+        )
+    )
+    if not text:
+        return None
+    return canonical.event_id, text, (canonical.scope_id, canonical.item_id)
+
+
+def _transcript_event_projection(
+    event: SessionEvent,
+) -> tuple[str, str, tuple[str, tuple[str, str]] | None]:
+    canonical_message = _canonical_completed_message(event)
+    if canonical_message is not None:
+        event_id, text, item_identity = canonical_message
+        return "assistant_message", text, (event_id, item_identity)
+    return (
+        canonical_event_type(
+            event.event_type,
+            author=event.author,
+            role=str((event.content or {}).get("role") or ""),
+        ),
+        extract_event_text(event),
+        None,
+    )
+
+
 def canonical_event_type(
     event_type: str | None,
     *,
@@ -276,6 +332,8 @@ def summarize_event_groups(
     因此跨消息提取修正，并在预算上限内保留最新长指令首尾（方案 §9.4）。
     """
     lines: List[str] = []
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     if previous_summary:
         lines.append(previous_summary)
     lines.append("Earlier conversation summary:")
@@ -284,14 +342,18 @@ def summarize_event_groups(
     for group in groups:
         snippets: List[str] = []
         for event in group:
-            event_type = canonical_event_type(
-                event.event_type,
-                author=event.author,
-                role=str((event.content or {}).get("role") or ""),
-            )
+            event_type, text, canonical_identity = _transcript_event_projection(event)
+            if canonical_identity is not None:
+                event_id, item_identity = canonical_identity
+                if (
+                    event_id in seen_canonical_event_ids
+                    or item_identity in seen_canonical_items
+                ):
+                    continue
+                seen_canonical_event_ids.add(event_id)
+                seen_canonical_items.add(item_identity)
             if event_type not in TRANSCRIPT_EVENT_TYPES or event_type == "context_checkpoint":
                 continue
-            text = extract_event_text(event)
             if not text:
                 continue
             if event_type in {"assistant_message", "tool_call"}:
@@ -343,6 +405,9 @@ def project_model_messages(
     """
     projected: List[Dict[str, str]] = []
     placeholder_flags: list[bool] = []
+    identity_boundary_flags: list[bool] = []
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     compacted_until = compacted_until_seq_id(events)
     checkpoint = next(
         (
@@ -362,21 +427,26 @@ def project_model_messages(
                 }
             )
             placeholder_flags.append(False)
+            identity_boundary_flags.append(False)
 
     for event in events:
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type, text, canonical_identity = _transcript_event_projection(event)
         if event.seq_id <= compacted_until and event_type != "context_checkpoint":
             continue
         if event_type not in TRANSCRIPT_EVENT_TYPES:
             continue
         if event_type in {"context_checkpoint", "compaction_boundary"}:
             continue
+        if canonical_identity is not None:
+            event_id, item_identity = canonical_identity
+            if (
+                event_id in seen_canonical_event_ids
+                or item_identity in seen_canonical_items
+            ):
+                continue
+            seen_canonical_event_ids.add(event_id)
+            seen_canonical_items.add(item_identity)
 
-        text = extract_event_text(event)
         if not text:
             continue
 
@@ -405,12 +475,15 @@ def project_model_messages(
             projected
             and projected[-1]["role"] == role
             and not placeholder_flags[-1]
+            and not identity_boundary_flags[-1]
             and not is_placeholder
+            and canonical_identity is None
         ):
             projected[-1]["content"] = f"{projected[-1]['content']}\n{text}".strip()
         else:
             projected.append({"role": role, "content": text})
             placeholder_flags.append(is_placeholder)
+            identity_boundary_flags.append(canonical_identity is not None)
 
     return projected
 
@@ -553,6 +626,8 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
     """
     projected: List[dict[str, Any]] = []
     projected_call_ids: set[str] = set()
+    seen_canonical_event_ids: set[str] = set()
+    seen_canonical_items: set[tuple[str, str]] = set()
     compacted_until = compacted_until_seq_id(events)
     checkpoint = next(
         (
@@ -568,17 +643,22 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
             projected.append(summary_message)
 
     for event in events:
-        event_type = canonical_event_type(
-            event.event_type,
-            author=event.author,
-            role=str((event.content or {}).get("role") or ""),
-        )
+        event_type, text, canonical_identity = _transcript_event_projection(event)
         if event.seq_id <= compacted_until and event_type != "context_checkpoint":
             continue
         if event_type not in TRANSCRIPT_EVENT_TYPES:
             continue
         if event_type in {"context_checkpoint", "compaction_boundary"}:
             continue
+        if canonical_identity is not None:
+            event_id, item_identity = canonical_identity
+            if (
+                event_id in seen_canonical_event_ids
+                or item_identity in seen_canonical_items
+            ):
+                continue
+            seen_canonical_event_ids.add(event_id)
+            seen_canonical_items.add(item_identity)
 
         if event_type == "tool_call":
             item = _response_tool_call_item(event)
@@ -586,25 +666,25 @@ def project_responses_history(events: List[SessionEvent]) -> List[dict[str, Any]
                 projected.append(item)
                 projected_call_ids.add(str(item["call_id"]))
                 continue
-            message = _responses_message("assistant", f"[tool_call] {extract_event_text(event)}")
+            message = _responses_message("assistant", f"[tool_call] {text}")
         elif event_type == "tool_result":
             item = _response_tool_output_item(event)
             if item and str(item["call_id"]) in projected_call_ids:
                 projected.append(item)
                 continue
-            message = _responses_message("user", f"[tool_result] {extract_event_text(event)}")
+            message = _responses_message("user", f"[tool_result] {text}")
         elif event_type == "assistant_message":
-            message = _responses_message("assistant", extract_event_text(event))
+            message = _responses_message("assistant", text)
         elif event_type == "approval_request":
             message = _responses_message(
-                "assistant", f"[approval_request] {extract_event_text(event)}"
+                "assistant", f"[approval_request] {text}"
             )
         elif event_type == "approval_response":
-            message = _responses_message("user", f"[approval_response] {extract_event_text(event)}")
+            message = _responses_message("user", f"[approval_response] {text}")
         elif event_type == "attachment_ref":
-            message = _responses_message("user", f"[attachment] {extract_event_text(event)}")
+            message = _responses_message("user", f"[attachment] {text}")
         else:
-            message = _responses_message("user", extract_event_text(event))
+            message = _responses_message("user", text)
         if message:
             projected.append(message)