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

ksadk/events/adapters/_codex_validators.py

@@ -8,15 +8,19 @@ from typing import Any, Literal, NoReturn, cast
 
 from pydantic import JsonValue
 
-_CODEX_ERROR_INFO_VALUES = frozenset("""
+_CODEX_ERROR_INFO_VALUES = frozenset(
+    """
     contextWindowExceeded sessionBudgetExceeded usageLimitExceeded serverOverloaded
     cyberPolicy internalServerError unauthorized badRequest threadRollbackFailed
     sandboxError other
-    """.split())
-_CODEX_ERROR_INFO_VARIANTS = frozenset("""
+    """.split()
+)
+_CODEX_ERROR_INFO_VARIANTS = frozenset(
+    """
     httpConnectionFailed responseStreamConnectionFailed responseStreamDisconnected
     responseTooManyFailedAttempts activeTurnNotSteerable
-    """.split())
+    """.split()
+)
 
 
 class CodexMappingError(ValueError):
@@ -151,16 +155,23 @@ def _question_schema(
                     )
                 )
                 option_details.append(_json_value(option))
+        multiple = bool(question.get("isMultiSelect", False))
+        allow_other = bool(question.get("isOther", False))
         property_schema: dict[str, JsonValue] = {
-            "type": "string",
+            "type": "array" if multiple else "string",
             "title": header,
             "description": prompt,
             "x-codex-options": option_details,
             "x-codex-is-secret": is_secret,
             "x-codex-is-other": bool(question.get("isOther", False)),
         }
-        if labels:
-            property_schema["enum"] = cast(JsonValue, labels)
+        value_schema: dict[str, JsonValue] = {"type": "string", "minLength": 1}
+        if labels and not allow_other:
+            value_schema["enum"] = cast(JsonValue, labels)
+        if multiple:
+            property_schema.update({"items": value_schema, "minItems": 1, "uniqueItems": True})
+        else:
+            property_schema.update(value_schema)
         properties[question_id] = property_schema
         required.append(question_id)
         prompts.append(prompt)

ksadk/events/adapters/langgraph.py

@@ -87,6 +87,7 @@ class LangGraphEventAdapter:
     def __init__(self) -> None:
         self._messages: dict[tuple[str, str], _MessageState] = {}
         self._tools: dict[tuple[str, str], _ToolState] = {}
+        self._tool_occurrences: dict[tuple[str, str], int] = {}
         self._lifecycles: dict[str, _LifecycleState] = {}
 
     async def stream_run(
@@ -331,7 +332,20 @@ class LangGraphEventAdapter:
                     f"LangGraph tool call {call_id!r} started twice",
                 )
             name = _required_string(payload.get("tool_name"), "tools tool_name")
-            item_id = stable_item_id("langgraph", frame.scope_id, "tool_result", call_id)
+            occurrence = self._tool_occurrences.get(state_key, 0)
+            self._tool_occurrences[state_key] = occurrence + 1
+            item_id = (
+                stable_item_id("langgraph", frame.scope_id, "tool_result", call_id)
+                if occurrence == 0
+                else stable_item_id(
+                    "langgraph",
+                    frame.scope_id,
+                    "tool_result",
+                    call_id,
+                    "occurrence",
+                    frame.occurrence_key,
+                )
+            )
             self._tools[state_key] = _ToolState(
                 scope_id=frame.scope_id,
                 parent_scope_id=frame.parent_scope_id,

ksadk/events/canonical_store.py

@@ -158,7 +158,9 @@ class RuntimeEventStore:
             self._typed_session_id = session_id
         else:
             self._event_store = None
-            self._service = store
+            # A live-first session wrapper may expose one durable authority for
+            # canonical facts without claiming that its dual writes are atomic.
+            self._service = getattr(store, "canonical_event_service", store)
             self._typed_session_id = session_id
 
     @property

ksadk/events/projections.py

@@ -23,7 +23,7 @@ canonical store（``ksadk/events/canonical_store.py`` 及 ``canonical.py`` 的
 | Responses 历史 | ``conversations/context.py::project_responses_history`` | Responses API 请求回放 input | OpenAI Responses input items（``type``/``call_id``/``output``/role 消息），仅可靠 call_id 的 tool 项 |
 | 模型 history | ``conversations/context.py::project_model_messages`` | 运行时模型上下文（内部投喂） | ``role``/``content`` 消息列表；control 事件不进入上下文 |
 | server checkpoint payload | ``server/routes/projection.py::_checkpoint_event_to_action_payload`` | REST 断点续跑/预览接口 | ``EventId``/``SessionId``/``RunId``/``CheckpointId``/``Framework``/``FrameworkRef``/``IsResumable``/``ResumeStatus``/``IsTerminal``/``NextNode``（经 ``run_checkpoint`` 元数据或 ``continuation.created`` 投影） |
-| server 动作事件 payload | ``server/routes/projection.py::_event_to_action_payload`` | REST 会话动作接口（事件原始形态透传） | ``EventId``/``SessionId``/``Author``/``EventType``/``Content``/``Timestamp``/``SeqId``（可选 ``InvocationId``）——序列化存储形态本身，非 canonical 派生 |
+| server 动作事件 payload | ``server/routes/projection.py::_event_to_action_payload`` | REST 会话动作接口（事件原始形态透传） | ``EventId``/``SessionId``/``Author``/``EventType``/``Content``/``Timestamp``/``SeqId``（可选 ``InvocationId``）——序列化存储形态本身，非 canonical 派生；canonical runtime 事件额外注入 ``Content.parts[0].text`` 兼容旧前端 |
 
 内部不保证（任何投影都不承诺、消费方不得依赖）：
 - ``seq``/``run_seq`` 的具体数值与连续性（仅保序语义）；

ksadk/harness/config.py

@@ -41,8 +41,8 @@ class McpToolSpec:
     """MCP 工具条目(最小子集)。"""
 
     name: str
-    url: str
-    api_key: Optional[str] = None
+    url: str = field(repr=False)
+    api_key: Optional[str] = field(default=None, repr=False)
     tool_filter: tuple[str, ...] = ()
     tool_name_prefix: Optional[str] = None
 

ksadk/harness/runtime.py

@@ -109,6 +109,8 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         self._tool_lock = asyncio.Lock()
         self._mcp_toolsets: list[Any] = []
         self._sessions: dict[tuple[str, str, str], _HarnessSession] = {}
+        self._lifecycle_lock = asyncio.Lock()
+        self._closed = False
 
     @property
     def harness_config(self) -> HarnessConfig:
@@ -123,10 +125,13 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         return self._sandbox.workspace_root
 
     async def start(self, request: StartRequest) -> RunHandle:
-        run_id = str(request.metadata.get("invocation_id") or f"harness_{uuid.uuid4().hex}")
-        if run_id in self._runs:
-            raise ValueError(f"duplicate Harness invocation: {run_id}")
-        self._runs[run_id] = _HarnessRun(request=request)
+        async with self._lifecycle_lock:
+            if self._closed:
+                raise RuntimeError("Harness runtime adapter is closed")
+            run_id = str(request.metadata.get("invocation_id") or f"harness_{uuid.uuid4().hex}")
+            if run_id in self._runs:
+                raise ValueError(f"duplicate Harness invocation: {run_id}")
+            self._runs[run_id] = _HarnessRun(request=request)
         return RunHandle(
             run_id=run_id,
             session_id=request.session_id,
@@ -174,28 +179,29 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         )
 
     async def close(self, handle: RunHandle) -> None:
-        run = self._runs.pop(handle.run_id, None)
+        async with self._lifecycle_lock:
+            run = self._runs.pop(handle.run_id, None)
+            has_runs = bool(self._runs)
         if run is not None and run.task is not None and not run.task.done():
             run.task.cancel()
             await asyncio.gather(run.task, return_exceptions=True)
-        if not self._runs:
+        if not has_runs:
             await self._close_tools()
 
     async def close_all(self) -> None:
         """Dispose every process-local run owned by this adapter instance."""
 
-        for run_id, run in list(self._runs.items()):
-            await self.close(
-                RunHandle(
-                    run_id=run_id,
-                    session_id=run.request.session_id,
-                    runtime_type="harness",
-                    native_ref={
-                        "user_id": run.request.user_id,
-                        "agent_id": run.request.agent_id,
-                    },
-                )
-            )
+        async with self._lifecycle_lock:
+            self._closed = True
+            runs = tuple(self._runs.values())
+            self._runs.clear()
+            self._sessions.clear()
+        tasks = [run.task for run in runs if run.task is not None and not run.task.done()]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        await self._close_tools()
 
     def is_handle_attached(self, handle: RunHandle) -> bool:
         return handle.run_id in self._runs
@@ -305,9 +311,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
 
     def _effective(self, request: StartRequest) -> tuple[str, str]:
         metadata = request.metadata or {}
-        model = str(
-            metadata.get("model_override") or request.model or self._config.model
-        ).strip()
+        model = str(metadata.get("model_override") or request.model or self._config.model).strip()
         prompt = str(
             metadata.get("prompt_override")
             or request.config.get("base_instructions")
@@ -344,9 +348,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 },
             )
 
-        def env_kwargs(
-            item_id: str, event_type: str, part_id: str
-        ) -> dict[str, Any]:
+        def env_kwargs(item_id: str, event_type: str, part_id: str) -> dict[str, Any]:
             n = next_seq()
             return {
                 "schema_version": 2,
@@ -445,9 +447,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 **env_kwargs(message_item_id, "item.completed", "text-0"),
                 item_id=message_item_id,
                 item_kind="message",
-                snapshot=ContentSnapshot(
-                    parts=(TextContent(part_id="text-0", text=text),)
-                ),
+                snapshot=ContentSnapshot(parts=(TextContent(part_id="text-0", text=text),)),
             )
             run.done = True
             yield RunCompleted(

ksadk/harness/tools.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import uuid
 from dataclasses import dataclass
@@ -14,6 +15,13 @@ from ksadk.mcp_runtime import MCPServerConfig, build_mcp_toolset
 
 ToolHandler = Callable[[dict[str, Any], str | None], Awaitable[Any]]
 
+HARNESS_SANDBOX_TOOL_NAMES = frozenset(
+    {
+        "sandbox_read_file",
+        "sandbox_run_command",
+    }
+)
+
 
 @dataclass(frozen=True)
 class HarnessTool:
@@ -89,11 +97,25 @@ async def load_mcp_tools(spec: McpToolSpec) -> tuple[Any, list[HarnessTool]]:
     toolset = build_mcp_toolset(config)
     try:
         native_tools = await toolset.get_tools_with_prefix()
-    except Exception as exc:
-        await toolset.close()
+    except BaseException as error:
+        cleanup = asyncio.create_task(toolset.close())
+        interrupted = False
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                interrupted = True
+        try:
+            cleanup.result()
+        except Exception:
+            pass
+        if interrupted or isinstance(error, asyncio.CancelledError):
+            raise asyncio.CancelledError
+        if not isinstance(error, Exception):
+            raise
         raise RuntimeError(
-            f"Harness MCP server {spec.name!r} at {spec.url!r} failed to start: {exc}"
-        ) from exc
+            f"Harness MCP server {spec.name!r} at {spec.url} failed to start"
+        ) from None
 
     available_names = {str(tool.name) for tool in native_tools}
     expected_names = {
@@ -104,14 +126,11 @@ async def load_mcp_tools(spec: McpToolSpec) -> tuple[Any, list[HarnessTool]]:
     if missing_names:
         await toolset.close()
         raise RuntimeError(
-            f"Harness MCP server {spec.name!r} at {spec.url!r} did not expose configured "
-            f"tool(s): {missing_names}"
+            f"Harness MCP server {spec.name!r} did not expose configured tool(s): {missing_names}"
         )
     if not native_tools:
         await toolset.close()
-        raise RuntimeError(
-            f"Harness MCP server {spec.name!r} at {spec.url!r} exposed no callable tools"
-        )
+        raise RuntimeError(f"Harness MCP server {spec.name!r} exposed no callable tools")
 
     tools: list[HarnessTool] = []
     for native_tool in native_tools:
@@ -139,10 +158,10 @@ async def load_mcp_tools(spec: McpToolSpec) -> tuple[Any, list[HarnessTool]]:
                 context = await _new_tool_context(call_id or _tool_name)
                 result = await _native_tool.run_async(args=arguments, tool_context=context)
                 return _normalize_tool_result(result, context)
-            except Exception as exc:
+            except Exception:
                 raise RuntimeError(
-                    f"Harness MCP tool {_tool_name!r} on server {spec.name!r} failed: {exc}"
-                ) from exc
+                    f"Harness MCP tool {_tool_name!r} on server {spec.name!r} failed"
+                ) from None
 
         tools.append(
             HarnessTool(
@@ -219,4 +238,10 @@ def _normalize_json_schema(value: Any) -> Any:
     return value
 
 
-__all__ = ["HarnessTool", "load_mcp_tools", "sandbox_tools", "tool_result_text"]
+__all__ = [
+    "HARNESS_SANDBOX_TOOL_NAMES",
+    "HarnessTool",
+    "load_mcp_tools",
+    "sandbox_tools",
+    "tool_result_text",
+]

ksadk/interaction/provider.py

@@ -44,6 +44,7 @@ class InteractionResolveContext:
     handle: RunHandle
     activation_id: str
     fencing_token: int
+    session_context: dict | None = None
 
 
 @runtime_checkable

ksadk/interaction/providers/langgraph.py

@@ -47,6 +47,7 @@ class LangGraphInteractionProvider:
             kind=payload_kind,
             call_id=str(native_target.get("call_id") or record.interaction_id),
             data=submission.response,
+            session_context=context.session_context,
         )
         return await context.adapter.resume(
             context.handle,

ksadk/kernel/bootstrap.py

@@ -39,7 +39,7 @@ from ksadk.kernel.contract_fingerprints import (
 )
 from ksadk.kernel.contracts import RuntimeCapabilityMatrix
 from ksadk.kernel.control import AgentKernel, default_capability_matrix
-from ksadk.kernel.errors import InvalidCommandError
+from ksadk.kernel.errors import InvalidCommandError, StaleFenceError
 from ksadk.kernel.recovery import RecoveryCoordinator
 from ksadk.kernel.runtime_identity import runtime_identity
 from ksadk.kernel.store import AgentKernelStore, now_utc
@@ -465,8 +465,25 @@ class AgentKernelRuntime:
                             lease,
                             session_id=session_id,
                         )
-                        if result.outcome != "idle":
+                        if result.outcome in {"claimed", "completed"}:
                             progressed = True
+                        elif result.outcome == "terminal_failure":
+                            if isinstance(result.error, StaleFenceError):
+                                # 当前 activation 已失去 fence，不能继续触碰该
+                                # session，也不应把正常 takeover 误判为坏数据。
+                                self._heartbeat_sessions.discard(session_id)
+                                self._last_renewed.pop(session_id, None)
+                                self.lease_heartbeat.forget(session_id)
+                                continue
+                            failure = result.error or RuntimeError(
+                                "agent kernel command failed without an error detail"
+                            )
+                            if not await self._quarantine_session(
+                                session_id,
+                                failure,
+                                context="command execution",
+                            ):
+                                return
                     self._store_failures = 0
                 except asyncio.CancelledError:
                     raise
@@ -609,7 +626,13 @@ class AgentKernelRuntime:
             return False
         return True
 
-    async def _quarantine_session(self, session_id: str, exc: Exception) -> bool:
+    async def _quarantine_session(
+        self,
+        session_id: str,
+        exc: Exception,
+        *,
+        context: str = "takeover recovery",
+    ) -> bool:
         """隔离一个恢复失败的 session；返回 False 表示已触发进程级降级。
 
         被隔离的 session 不再被本 runtime claim / 恢复 / 续约，其 inbox
@@ -631,9 +654,10 @@ class AgentKernelRuntime:
         self._last_renewed.pop(session_id, None)
         self.lease_heartbeat.forget(session_id)
         logger.warning(
-            "agent kernel session %s quarantined after takeover recovery "
+            "agent kernel session %s quarantined after %s "
             "failed: agent_instance_id=%s error=%s: %s",
             session_id,
+            context,
             self.config.agent_instance_id,
             type(exc).__name__,
             exc,

ksadk/kernel/ingress.py

@@ -94,9 +94,22 @@ def get_agent_kernel() -> Any | None:
 
 
 def kernel_route_active() -> bool:
-    """当前请求是否走 kernel ingress（开关开 且 kernel 已注册）。"""
+    """Whether public compatibility routes may self-admit through the kernel.
+
+    A hosted Runtime accepts AgentControl commands only with a permit issued by
+    Server.  The public ``/v1/responses`` / legacy ``RunAgent`` routes do not
+    carry that permit, so routing them through ``trusted_context`` would create
+    a process-local signature that the hosted verifier must reject.  Keep those
+    authenticated compatibility routes on their established executor path;
+    Server continues to use the dedicated ``/agent-kernel/v1/*`` ingress, which
+    validates the Server-issued permit independently of this selector.
+    """
 
-    return kernel_ingress_enabled() and get_agent_kernel() is not None
+    return (
+        kernel_ingress_enabled()
+        and get_agent_kernel() is not None
+        and authority_mode() != _AUTHORITY_HOSTED
+    )
 
 
 # ---------------------------------------------------------------------------

ksadk/kernel/sqlite_store.py

@@ -1112,6 +1112,33 @@ class SQLiteAgentKernelStore:
             )
         return self._row_to_record(rows[0]) if rows else None
 
+    async def get_terminal_receipt(
+        self, interaction_id: str, *, tenant_id: str, agent_instance_id: str,
+        session_id: str, run_id: str,
+    ) -> InteractionReceipt | None:
+        """Read the committed outcome inside a complete trusted scope.
+
+        Resolved alone does not mean approved. Pending/resolving records never
+        yield an authorization receipt; callers must still match the request.
+        """
+        if not all(isinstance(value, str) and value for value in (
+            interaction_id, tenant_id, agent_instance_id, session_id, run_id
+        )):
+            raise InvalidCommandError("interaction receipt requires a complete trusted scope")
+        row = await self._fetchone(
+            await self._connect(),
+            "SELECT * FROM kernel_interactions WHERE interaction_id=? AND tenant_id=?"
+            " AND agent_instance_id=? AND session_id=? AND run_id=?",
+            (interaction_id, tenant_id, agent_instance_id, session_id, run_id),
+        )
+        if row is None or not is_terminal(row["status"]):
+            return None
+        return InteractionReceipt(
+            interaction_id=row["interaction_id"], revision=int(row["revision"]),
+            status=row["status"], outcome=row["outcome"], event_id=row["event_id"],
+            accepted_seq=row["accepted_seq"],
+        )
+
     async def list_pending_interactions(
         self, tenant_id: str, session_id: str
     ) -> list[InteractionRecord]:

ksadk/kernel/store.py

@@ -54,6 +54,9 @@ def command_digest(command: AgentControlCommand) -> str:
     canonical["source"] = source
 
     payload = dict(canonical.get("payload") or {})
+    # Admission derives this immutable snapshot from the current session. A
+    # retry after a tag update must still resolve to the first accepted command.
+    payload.pop("session_context", None)
     if command.command_type == "submit_interaction":
         payload.pop("token_ref", None)
     canonical["payload"] = payload

ksadk/kernel/worker.py

@@ -109,6 +109,7 @@ class WorkResult:
     message_id: str | None = None
     run_id: str | None = None
     last_seq: int | None = None
+    error: Exception | None = None
 
 
 class AgentKernelWorker:
@@ -294,8 +295,10 @@ class AgentKernelWorker:
             )
             await self._store.discard_claim(message_id, expected_fence=fence)
             return WorkResult(outcome="completed", message_id=message_id)
-        except StaleFenceError:
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+        except StaleFenceError as error:
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
         except AgentKernelError as error:
             if error.code == RUNTIME_INTERACTION_UNAVAILABLE:
                 # typed rejection：provider 诚实声明无法原生送达回包，
@@ -316,16 +319,46 @@ class AgentKernelWorker:
                 await self._store.discard_claim(message_id, expected_fence=fence)
                 return WorkResult(outcome="completed", message_id=message_id)
             if error.retryable:
-                return WorkResult(outcome="retryable_failure", message_id=message_id)
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
-        except Exception:
+                return WorkResult(
+                    outcome="retryable_failure", message_id=message_id, error=error
+                )
+            logger.error(
+                "agent kernel command failed permanently: "
+                "agent_instance_id=%s session_id=%s command_id=%s "
+                "command_type=%s error=%s: %s",
+                command.agent_instance_id,
+                command.session_id,
+                command.command_id,
+                command.command_type,
+                type(error).__name__,
+                error,
+            )
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
+        except Exception as error:
             # 未知异常绝不 ack 为成功：消息保持 claimed。
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+            logger.exception(
+                "agent kernel command raised an unexpected exception: "
+                "agent_instance_id=%s session_id=%s command_id=%s "
+                "command_type=%s error=%s: %s",
+                command.agent_instance_id,
+                command.session_id,
+                command.command_id,
+                command.command_type,
+                type(error).__name__,
+                error,
+            )
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
 
         try:
             await self._store.complete_claim(message_id, expected_fence=fence)
-        except StaleFenceError:
-            return WorkResult(outcome="terminal_failure", message_id=message_id)
+        except StaleFenceError as error:
+            return WorkResult(
+                outcome="terminal_failure", message_id=message_id, error=error
+            )
         return WorkResult(outcome="completed", message_id=message_id, run_id=run_id)
 
     async def _message_id_for(self, command: AgentControlCommand) -> str:
@@ -407,6 +440,11 @@ class AgentKernelWorker:
                 # durable run_id 优先传给 adapter；adapter 不认时以
                 # runtime_run_id 映射显式记录两个 ID 的对应关系。
                 metadata={
+                    **(
+                        {"session_context": command.payload["session_context"]}
+                        if "session_context" in command.payload
+                        else {}
+                    ),
                     "command_id": str(command.command_id),
                     "run_id": run_id,
                     **continuation_metadata,
@@ -746,7 +784,17 @@ class AgentKernelWorker:
             )
         else:
             request_schema = dict(event.request.schema_)
-            native_target = {"call_id": event.interaction_id}
+            # Codex maps the native JSON-RPC request id to a stable canonical
+            # interaction id for replay.  The live client, however, indexes its
+            # pending callback by the original request id.  Preserve that id as
+            # the provider target or SubmitInteraction can find the durable
+            # record but cannot wake the blocked Codex callback.
+            native_call_id = (
+                event.source.native_event_id
+                or event.source.native_item_id
+                or event.interaction_id
+            )
+            native_target = {"call_id": native_call_id}
         for key in ("checkpoint_id", "thread_id"):
             value = execution.handle.native_ref.get(key)
             if value is not None:
@@ -812,7 +860,13 @@ class AgentKernelWorker:
                 kind=RESUME_TARGET_KINDS[target_dict["kind"]],
                 id=str(target_dict["id"]),
             )
-            resumed = await adapter.resume(handle, target, AdapterResumePayload(kind="free_text"))
+            resumed = await adapter.resume(
+                handle,
+                target,
+                AdapterResumePayload(
+                    kind="free_text", session_context=command.payload.get("session_context")
+                ),
+            )
             execution = self._replace_handle(execution, resumed)
             self._start_stream(
                 execution,
@@ -910,6 +964,7 @@ class AgentKernelWorker:
         context = InteractionResolveContext(
             adapter=execution.adapter,
             handle=execution.handle,
+            session_context=command.payload.get("session_context"),
             activation_id=activation.activation_id,
             fencing_token=fence,
         )