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

ksadk/conversations/reducer.py

@@ -0,0 +1,98 @@
+"""Identity-aware reducer for a ConversationItem surface.
+
+This reducer deliberately does not deduplicate by author or text.  Providers
+may emit the same content in two different items, and both are user-visible
+truth.  Reconnect de-duplication is limited to a previously applied source
+event for the same item.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from ksadk.conversations.contracts import ConversationItem
+
+
+class ConversationItemReducer:
+    """Apply append/replace/completed operations while preserving item identity."""
+
+    def __init__(self) -> None:
+        self._items: OrderedDict[str, ConversationItem] = OrderedDict()
+        self._source_events: set[tuple[str, str]] = set()
+
+    def apply(self, item: ConversationItem) -> bool:
+        """Apply one item operation and return whether this changed the view."""
+
+        keys = {(item.item_id, source_id) for source_id in item.source_event_ids}
+        if keys and keys.issubset(self._source_events):
+            return False
+
+        existing = self._items.get(item.item_id)
+        if existing is not None and _terminal(existing) and not _terminal(item):
+            # A reconnect may replay an older delta after the terminal snapshot
+            # has already arrived on the live connection.  Remember its event
+            # identity, but never regress a completed item back to streaming or
+            # append the stale delta a second time.
+            self._source_events.update(keys)
+            return False
+        if existing is None:
+            merged = item
+        elif item.operation == "append":
+            merged = item.model_copy(
+                update={
+                    "payload": _append_payload(existing.payload, item.payload),
+                    "source_event_ids": _merge_sources(
+                        existing.source_event_ids,
+                        item.source_event_ids,
+                    ),
+                }
+            )
+        else:
+            merged = item.model_copy(
+                update={
+                    "source_event_ids": _merge_sources(
+                        existing.source_event_ids,
+                        item.source_event_ids,
+                    )
+                }
+            )
+        self._items[item.item_id] = merged
+        self._source_events.update(keys)
+        return True
+
+    def items(self) -> tuple[ConversationItem, ...]:
+        """Return presentation items in first-seen order."""
+
+        return tuple(self._items.values())
+
+
+def _append_payload(
+    existing: dict[str, object],
+    update: dict[str, object],
+) -> dict[str, object]:
+    merged = dict(existing)
+    for key, value in update.items():
+        previous = merged.get(key)
+        if key == "text" and isinstance(previous, str) and isinstance(value, str):
+            merged[key] = previous + value
+        elif key in {"data", "operations"} and isinstance(previous, list) and isinstance(
+            value, list
+        ):
+            merged[key] = [*previous, *value]
+        else:
+            merged[key] = value
+    return merged
+
+
+def _merge_sources(
+    current: tuple[str, ...],
+    incoming: tuple[str, ...],
+) -> tuple[str, ...]:
+    return tuple(dict.fromkeys((*current, *incoming)))
+
+
+def _terminal(item: ConversationItem) -> bool:
+    return item.lifecycle in {"completed", "failed"}
+
+
+__all__ = ["ConversationItemReducer"]

ksadk/events/_v1_compat/projection.py

@@ -370,6 +370,8 @@ def _project_item_completed(
     if text_projection or event.item_kind in {"message", "reasoning"}:
         return text_projection
     if event.item_kind == "data":
+        if event.source.metadata.get("operation_batch") is True:
+            return ()
         ref = _a2ui_surface_ref(event, context)
         if ref is None:
             return ()

ksadk/events/adapters/codex.py

@@ -48,6 +48,7 @@ from ksadk.events.canonical import (
     ContinuationCreated,
     ContinuationResumed,
     ErrorInfo,
+    InteractionRequested,
     ItemCompleted,
     ItemFailed,
     ItemStarted,
@@ -56,10 +57,12 @@ from ksadk.events.canonical import (
     RunCanceled,
     RunCompleted,
     RunFailed,
+    RunInterrupted,
     RunProgress,
     RunStarted,
     RuntimeEvent,
     SourceRef,
+    StructuredInputRequest,
     UsageReported,
 )
 from ksadk.events.content import (
@@ -191,6 +194,20 @@ class CodexEventAdapter(_CodexInteractionMixin):
             return self._map_server_request_resolved(
                 params=params, context=context, cursor=cursor, timestamp=timestamp
             )
+        if method == "a2ui/surface":
+            return self._map_a2ui_surface(
+                params=params,
+                context=context,
+                cursor=cursor,
+                timestamp=timestamp,
+            )
+        if method == "a2ui/interaction":
+            return self._map_a2ui_interaction(
+                params=params,
+                context=context,
+                cursor=cursor,
+                timestamp=timestamp,
+            )
         if method in _CONTROL_INTERACTION_METHODS:
             return self._map_control_interaction_request(
                 message=message,
@@ -255,6 +272,179 @@ class CodexEventAdapter(_CodexInteractionMixin):
             )
         _fail("unsupported_method", "method", f"Unsupported Codex app-server method: {method}")
 
+    @staticmethod
+    def _a2ui_scope(
+        params: Mapping[str, Any],
+        context: CodexAdapterContext,
+        *,
+        surface_id: str,
+    ) -> tuple[str, str, str]:
+        thread_value = params.get("threadId", params.get("thread_id"))
+        turn_value = params.get("turnId", params.get("turn_id"))
+        thread_id = (
+            _required_string(thread_value, "params.threadId")
+            if thread_value is not None
+            else f"runtime:{context.run_id}"
+        )
+        turn_id = (
+            _required_string(turn_value, "params.turnId")
+            if turn_value is not None
+            else "a2ui"
+        )
+        return thread_id, turn_id, stable_scope_id("codex", thread_id, turn_id, surface_id)
+
+    @staticmethod
+    def _a2ui_source(
+        *,
+        method: str,
+        cursor: str,
+        thread_id: str,
+        turn_id: str,
+        native_item_id: str,
+        surface_id: str,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> SourceRef:
+        source = _protocol_source(
+            method=method,
+            cursor=cursor,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=native_item_id,
+            native_event_id=native_item_id,
+        )
+        return source.model_copy(
+            update={
+                "protocol": "a2ui",
+                "metadata": {
+                    **source.metadata,
+                    "surface_id": surface_id,
+                    **dict(metadata or {}),
+                },
+            }
+        )
+
+    def _map_a2ui_surface(
+        self,
+        *,
+        params: Mapping[str, Any],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+    ) -> tuple[RuntimeEvent, ...]:
+        """Map one complete A2UI surface description as an immutable operation batch."""
+
+        surface_id = _required_string(params.get("surface_id"), "params.surface_id")
+        surface = _mapping(params.get("surface"), "params.surface")
+        thread_id, turn_id, scope_id = self._a2ui_scope(
+            params, context, surface_id=surface_id
+        )
+        item_id = stable_item_id("codex", scope_id, "a2ui-surface", surface_id)
+        source = self._a2ui_source(
+            method="a2ui/surface",
+            cursor=cursor,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=surface_id,
+            surface_id=surface_id,
+            metadata={
+                "operation_batch": True,
+                "surface_lifecycle": "begin",
+                "catalog_id": str(surface.get("catalog_id") or surface.get("catalogId") or ""),
+            },
+        )
+        snapshot = ContentSnapshot(
+            parts=(
+                DataContent(
+                    part_id="a2ui-surface",
+                    data={"surface_id": surface_id, **_json_value(surface)},
+                ),
+            )
+        )
+        env = _envelope(context, cursor, timestamp)
+        return (
+            ItemStarted(
+                **env(scope_id, item_id, "item.started", "a2ui-surface", source),
+                item_id=item_id,
+                item_kind="data",
+                initial=snapshot,
+            ),
+            ItemCompleted(
+                **env(scope_id, item_id, "item.completed", "a2ui-surface", source),
+                item_id=item_id,
+                item_kind="data",
+                snapshot=snapshot,
+            ),
+        )
+
+    def _map_a2ui_interaction(
+        self,
+        *,
+        params: Mapping[str, Any],
+        context: CodexAdapterContext,
+        cursor: str,
+        timestamp: float,
+    ) -> tuple[RuntimeEvent, ...]:
+        """Map the client-owned A2UI input request without changing its live call id."""
+
+        surface_id = _required_string(params.get("surface_id"), "params.surface_id")
+        interaction_id = _required_string(
+            params.get("interaction_id"), "params.interaction_id"
+        )
+        kind = _required_string(params.get("kind"), "params.kind")
+        schema = _mapping(params.get("input_schema"), "params.input_schema")
+        is_blocking = params.get("is_blocking", True)
+        if not isinstance(is_blocking, bool):
+            _fail(
+                "invalid_interaction_request",
+                "params.is_blocking",
+                "A2UI is_blocking must be a boolean",
+            )
+        thread_id, turn_id, scope_id = self._a2ui_scope(
+            params, context, surface_id=surface_id
+        )
+        source = self._a2ui_source(
+            method="a2ui/interaction",
+            cursor=cursor,
+            thread_id=thread_id,
+            turn_id=turn_id,
+            native_item_id=interaction_id,
+            surface_id=surface_id,
+            metadata={"kind": kind, "is_blocking": is_blocking},
+        )
+        env = _envelope(context, cursor, timestamp)
+        requested = InteractionRequested(
+            **env(
+                scope_id,
+                interaction_id,
+                "interaction.requested",
+                "structured_input",
+                source,
+            ),
+            interaction_id=interaction_id,
+            interaction_kind="structured_input",
+            request=StructuredInputRequest(prompt=None, schema=_json_value(schema)),
+        )
+        if not is_blocking:
+            return (requested,)
+        return (
+            requested,
+            RunInterrupted(
+                **env(
+                    scope_id,
+                    turn_id,
+                    "run.interrupted",
+                    interaction_id,
+                    source,
+                ),
+                status="interrupted",
+                reason="Codex requires user interaction",
+                interaction_id=interaction_id,
+                continuation_id=self._thread_continuations.setdefault(
+                    thread_id, _thread_continuation_identity(thread_id)[1]
+                ),
+            ),
+        )
+
     def _map_token_usage(
         self,
         *,

ksadk/harness/__init__.py

@@ -1,35 +1,45 @@
-"""HarnessApp — 统一 Runtime 的可部署交付物 / composition root (goal-08)。"""
-
-from ksadk.harness.app import HarnessApp, HarnessCapabilities, HarnessPlugin
-from ksadk.harness.config import (
-    HarnessConfig,
-    HarnessConfigError,
-    McpToolSpec,
-    SandboxPolicy,
-)
-from ksadk.harness.reasoner import (
-    HarnessReasoner,
-    HarnessReasoningTurn,
-    HarnessToolCall,
-    LiteLLMHarnessReasoner,
-)
-from ksadk.harness.runtime import HarnessRuntime, HarnessRuntimeAdapter
-from ksadk.harness.sandbox import HarnessSandboxExecutor, SandboxPolicyDenied
-
-__all__ = [
-    "HarnessApp",
-    "HarnessCapabilities",
-    "HarnessConfig",
-    "HarnessConfigError",
-    "HarnessPlugin",
-    "HarnessReasoner",
-    "HarnessRuntime",
-    "HarnessRuntimeAdapter",
-    "HarnessReasoningTurn",
-    "HarnessSandboxExecutor",
-    "HarnessToolCall",
-    "LiteLLMHarnessReasoner",
-    "McpToolSpec",
-    "SandboxPolicy",
-    "SandboxPolicyDenied",
-]
+"""Public Harness surface without eagerly requiring an ADK runtime.
+
+Studio must be usable for Codex and DSH Providers from a base ``ksadk``
+installation. Harness keeps ADK as an optional execution dependency, so
+importing its configuration types cannot import the full Harness runtime.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "HarnessApp": ("ksadk.harness.app", "HarnessApp"),
+    "HarnessCapabilities": ("ksadk.harness.app", "HarnessCapabilities"),
+    "HarnessPlugin": ("ksadk.harness.app", "HarnessPlugin"),
+    "HarnessConfig": ("ksadk.harness.config", "HarnessConfig"),
+    "HarnessConfigError": ("ksadk.harness.config", "HarnessConfigError"),
+    "McpToolSpec": ("ksadk.harness.config", "McpToolSpec"),
+    "SandboxPolicy": ("ksadk.harness.config", "SandboxPolicy"),
+    "HarnessReasoner": ("ksadk.harness.reasoner", "HarnessReasoner"),
+    "HarnessReasoningTurn": ("ksadk.harness.reasoner", "HarnessReasoningTurn"),
+    "HarnessToolCall": ("ksadk.harness.reasoner", "HarnessToolCall"),
+    "LiteLLMHarnessReasoner": ("ksadk.harness.reasoner", "LiteLLMHarnessReasoner"),
+    "HarnessRuntime": ("ksadk.harness.runtime", "HarnessRuntime"),
+    "HarnessRuntimeAdapter": ("ksadk.harness.runtime", "HarnessRuntimeAdapter"),
+    "HarnessSandboxExecutor": ("ksadk.harness.sandbox", "HarnessSandboxExecutor"),
+    "SandboxPolicyDenied": ("ksadk.harness.sandbox", "SandboxPolicyDenied"),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

ksadk/harness/runtime.py

@@ -72,6 +72,19 @@ class _HarnessRun:
     done: bool = False
 
 
+@dataclass
+class _HarnessSession:
+    """Process-local transcript and serialization boundary for one Session.
+
+    The public capability matrix deliberately advertises process-scoped,
+    non-durable continuity.  Keeping this state on the adapter makes that
+    declaration true without pretending that a restart can recover it.
+    """
+
+    messages: list[dict[str, Any]]
+    lock: asyncio.Lock
+
+
 class HarnessRuntimeAdapter(RuntimeAdapter):
     """Execute a YAML Harness config directly as RuntimeEvent streams."""
 
@@ -95,6 +108,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         self._tools: tuple[HarnessTool, ...] | None = None
         self._tool_lock = asyncio.Lock()
         self._mcp_toolsets: list[Any] = []
+        self._sessions: dict[tuple[str, str, str], _HarnessSession] = {}
 
     @property
     def harness_config(self) -> HarnessConfig:
@@ -167,16 +181,43 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         if not self._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,
+                    },
+                )
+            )
+
     def is_handle_attached(self, handle: RunHandle) -> bool:
         return handle.run_id in self._runs
 
     async def execute_request(self, request: StartRequest) -> dict[str, Any]:
+        session = self._session_for(request)
+        async with session.lock:
+            return await self._execute_session_request(request, session)
+
+    async def _execute_session_request(
+        self,
+        request: StartRequest,
+        session: _HarnessSession,
+    ) -> dict[str, Any]:
         tools = await self._ensure_tools()
         model, prompt = self._effective(request)
         messages: list[dict[str, Any]] = [
             {"role": "system", "content": prompt},
-            {"role": "user", "content": str(request.input or "")},
+            *[dict(message) for message in session.messages],
         ]
+        user_message = {"role": "user", "content": str(request.input or "")}
+        messages.append(user_message)
         execution_log: list[dict[str, Any]] = []
 
         for _turn_number in range(_MAX_REASONING_TURNS):
@@ -235,6 +276,12 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 raise RuntimeError(
                     "Harness reasoner returned neither a final response nor a tool call"
                 )
+            final_message = {"role": "assistant", "content": turn.final_text}
+            messages.append(final_message)
+            # Failed or cancelled turns never commit a partial transcript.
+            # A successful turn atomically replaces the process-local history
+            # while the per-session lock is still held.
+            session.messages[:] = [dict(message) for message in messages[1:]]
             return {
                 "output": turn.final_text,
                 "model": model,
@@ -244,6 +291,18 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
             }
         raise RuntimeError(f"Harness reasoning exceeded {_MAX_REASONING_TURNS} turns")
 
+    def _session_for(self, request: StartRequest) -> _HarnessSession:
+        key = (
+            str(request.agent_id or self._agent_name),
+            str(request.user_id),
+            str(request.session_id),
+        )
+        session = self._sessions.get(key)
+        if session is None:
+            session = _HarnessSession(messages=[], lock=asyncio.Lock())
+            self._sessions[key] = session
+        return session
+
     def _effective(self, request: StartRequest) -> tuple[str, str]:
         metadata = request.metadata or {}
         model = str(

ksadk/kernel/contract_fingerprints.py

@@ -15,7 +15,7 @@ from typing import Any
 
 AGENT_KERNEL_V1_CONTRACT_SET = "agent-kernel/v1"
 AGENT_KERNEL_V1_AGGREGATE_DIGEST = (
-    "47e1003e03d97abeba232cc3e03a14b9cbcf78b1109870ccd2ce371f073b6211"
+    "b610a25aae957306b9f84a2cc2c948b30d1ce6218585cfd2a91f96736b92d102"
 )
 
 
@@ -23,12 +23,13 @@ def runtime_capability_matrix_wire_value(matrix: Any) -> dict[str, Any]:
     """Serialize the additive matrix without materializing absent v2 modes.
 
     Pydantic includes optional ``None`` defaults in ``model_dump``.  Omitting
-    those three top-level keys preserves the exact pre-extension wire value and
-    capability digest for runtimes that do not publish goal/loop/plan.
+    those additive top-level keys preserves the exact pre-extension wire value
+    and capability digest for runtimes that do not publish execution controls
+    or an interaction delivery mode.
     """
 
     dump = matrix.model_dump(mode="json")
-    for key in ("goal", "loop", "plan"):
+    for key in ("interaction_mode", "goal", "loop", "plan"):
         if dump.get(key) is None:
             dump.pop(key, None)
     return dump

ksadk/kernel/contracts.py

@@ -309,6 +309,14 @@ class RuntimeCapabilityMatrix(WireModel):
     inject: RuntimeCapability
     checkpoint: RuntimeCapability
     durable_restore: RuntimeCapability
+    # Interaction delivery is deliberately separate from the verb matrix:
+    # ``submit_interaction`` alone does not tell a caller whether the reply
+    # reaches a live process, resumes a checkpoint, or has no native route.
+    # It remains optional so a v1 consumer can read records emitted before
+    # this additive declaration without inventing support.
+    interaction_mode: Literal[
+        "live_submit", "durable_resume", "unavailable"
+    ] | None = None
     # Runtime v2 execution controls are additive optional capabilities. Older
     # runtimes omit them; a runtime must never infer support from UI presence.
     # ``loop`` specifically means an externally bounded, eval-driven

ksadk/kernel/control.py

@@ -57,6 +57,7 @@ def default_capability_matrix() -> RuntimeCapabilityMatrix:
         inject=_unavailable("runtime_no_native_inject"),
         checkpoint=_unavailable(),
         durable_restore=_unavailable(),
+        interaction_mode="unavailable",
     )
 
 

ksadk/kernel/ingress.py

@@ -421,6 +421,26 @@ def map_studio_request(
     )
 
 
+def map_scheduler_request(
+    *,
+    session_id: str,
+    idempotency_key: str,
+    content: Any,
+    occurrence_id: str,
+    trusted: TrustedRuntimeContext,
+) -> AgentControlCommand:
+    """Scheduler occurrence -> enqueue with durable source and correlation IDs."""
+
+    return _command(
+        trusted=trusted,
+        command_type="enqueue",
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        payload={"content": content},
+        correlation_id=occurrence_id,
+    )
+
+
 def map_control_request(
     *,
     command_type: str,
@@ -1091,6 +1111,7 @@ __all__ = [
     "map_control_request",
     "map_responses_request",
     "map_run_request",
+    "map_scheduler_request",
     "map_studio_request",
     "receipt_error_payload",
     "receipt_http_status",

ksadk/kernel/memory_store.py

@@ -1124,6 +1124,7 @@ class InMemoryAgentKernelStore:
                         "fencing_token": int(expected_fence),
                     },
                     run_id=run.run_id,
+                    causation_id=str(run.metadata.get("command_id") or "") or None,
                 ),
                 activation_row=activation,
             )

ksadk/kernel/postgres_store.py

@@ -1647,6 +1647,7 @@ class PostgresAgentKernelStore:
                             "fencing_token": int(expected_fence),
                         },
                         run_id=run.run_id,
+                        causation_id=str(run.metadata.get("command_id") or "") or None,
                     ),
                     activation,
                     expected_fence,

ksadk/kernel/sqlite_store.py

@@ -1400,6 +1400,7 @@ class SQLiteAgentKernelStore:
                     "fencing_token": int(expected_fence),
                 },
                 run_id=run.run_id,
+                causation_id=str(run.metadata.get("command_id") or "") or None,
             ),
             activation,
             expected_fence,

ksadk/kernel/worker.py

@@ -356,6 +356,17 @@ class AgentKernelWorker:
             agent_instance_id=command.agent_instance_id,
             session_id=command.session_id,
             state=RunState.PENDING,
+            # Keep the admitted control identity on the durable run.  This is
+            # not user-supplied metadata: it is copied from the trusted
+            # command that the worker actually claimed.  Consumers such as the
+            # local Scheduler can therefore reconcile a runtime terminal fact
+            # back to one occurrence without matching text or wall-clock time.
+            metadata={
+                "command_id": str(command.command_id),
+                "source_kind": command.source.kind,
+                "source_ref": command.source.ref,
+                "correlation_id": command.correlation_id,
+            },
         )
         created = await self._store.save_run_transition(pending, expected_fence=fence)
         continuation_metadata = await self._session_continuation_metadata(command.session_id)

ksadk/memory/providers/local_sqlite.py

@@ -141,6 +141,13 @@ class SqliteMemoryProvider:
         workspace_id: str = "local",
     ) -> None:
         self._db_path = str(db_path)
+        if self._db_path != ":memory:":
+            # A fresh local Studio has not created its session directory yet.
+            # SQLite creates the database file, but not missing parents.
+            Path(self._db_path).expanduser().resolve().parent.mkdir(
+                parents=True,
+                exist_ok=True,
+            )
         self._tenant_id = tenant_id
         self._workspace_id = workspace_id
         self._lock = threading.Lock()