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

ksadk/studio/run_submission_receipts.py

@@ -0,0 +1,68 @@
+"""Read original submission facts; never infer delivery from the latest turn."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ksadk.studio.contracts import OperationKind, OperationStatus, RunStatus, RunSubmissionRef
+from ksadk.studio.errors import StudioError
+
+
+def submission_receipt(studio: Any, ref: RunSubmissionRef) -> dict[str, Any]:
+    studio._require_direct_session(ref.session_id)
+    identity = {
+        "SchemaVersion": 1,
+        "AgentId": ref.agent_id,
+        "SessionId": ref.session_id,
+        "InvocationId": ref.client_invocation_id,
+    }
+    records = studio.event_store.list_runs(session_id=ref.session_id, agent_id=ref.agent_id)
+    matched = [
+        record
+        for record in records
+        if record.submission_ref == ref or record.id == ref.client_invocation_id
+    ]
+    if not matched:
+        # Legacy completed submissions already have a durable correlation key.
+        # Looking it up is not a RunAgent retry and cannot start an operation.
+        operation = studio.operations.find_by_idempotency_key(
+            f"responses:{ref.client_invocation_id}"
+        )
+        if operation is not None and operation.kind == OperationKind.RUN:
+            matched = [record for record in records if record.id == operation.resource_id]
+    if len(matched) > 1:
+        raise StudioError(
+            "RUN_SUBMISSION_AMBIGUOUS", "原请求对应多个运行，不能确定投递结果", status_code=409
+        )
+    if matched:
+        record = matched[0]
+        studio._require_direct_run(record.id)
+        return {
+            **identity,
+            "RunId": record.id,
+            "Status": RunStatus(record.status).value.lower(),
+            "Source": "run",
+        }
+    # A queued request has no RunRecord yet. The original operation stores the
+    # correlation at submission, before starting or waiting for admission.
+    operations = [
+        operation
+        for operation in studio.operations.list(kind=OperationKind.RUN)
+        if operation.metadata.get("submission_ref") == ref.model_dump()
+    ]
+    if len(operations) > 1:
+        raise StudioError(
+            "RUN_SUBMISSION_AMBIGUOUS", "原请求对应多个操作，不能确定投递结果", status_code=409
+        )
+    if operations:
+        operation = operations[0]
+        state = OperationStatus(operation.status).value.lower()
+        if state in {"queued", "running", "failed", "cancelled", "interrupted"}:
+            return {
+                **identity,
+                "RunId": "",
+                "Status": state,
+                "Source": "operation",
+            }
+    # Missing evidence never proves non-delivery, success or permission to retry.
+    return {**identity, "RunId": "", "Status": "unknown", "Source": "unavailable"}

ksadk/studio/runtime_catalog.py

@@ -5,10 +5,16 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as package_version
 
+from ksadk.harness.runtime_capabilities import managed_harness_native_capabilities
 from ksadk.managed_runtime import installed_runtime_version
 from ksadk.runtime import RuntimeExecutor
 
 _RUNTIMES = {
+    "harness": {
+        "package": "ksadk",
+        "displayName": "KsADK Harness",
+        "adapter": "ManagedHarnessRuntimeAdapter",
+    },
     "codex": {
         "package": "openai-codex",
         "displayName": "Codex",
@@ -45,7 +51,43 @@ _RUNTIMES = {
 }
 
 
-def inspect_runtime_catalog(executor: RuntimeExecutor) -> list[dict]:
+def _harness_capabilities() -> dict:
+    """从 DSH Provider 实际装配的 Managed Harness Runtime 读取真实能力声明。
+
+    进程内 resume/checkpoint 为既有实现；跨进程持久性取决于装配档位
+    （Workspace 状态目录 / Checkpoint DSN），目录如实标注当前声明。
+    """
+
+    # StudioPluginRuntime always supplies a Workspace state directory to the
+    # shipped DSH Harness provider. The catalog describes that product path,
+    # not a separately constructed in-memory SDK adapter.
+    native = managed_harness_native_capabilities(durable=True)
+    checkpoint = native.get("checkpoint") or {}
+    session_continuity = native.get("session_continuity") or {}
+    return {
+        "session": True,
+        "cancel": bool((native.get("cancel") or {}).get("supported")),
+        "resume": (
+            "checkpoint_id" if session_continuity.get("durable")
+            else "in_process" if native.get("resume", {}).get("supported")
+            else "not_supported"
+        ),
+        "checkpoint": (
+            "workspace" if session_continuity.get("durable")
+            else "in_process" if checkpoint.get("supported")
+            else "not_supported"
+        ),
+        "checkpointGranularity": checkpoint.get("granularity"),
+        "durableAcrossProcess": bool(session_continuity.get("durable")),
+    }
+
+
+def inspect_runtime_catalog(
+    executor: RuntimeExecutor,
+    *,
+    native_harness_default: bool = False,
+    native_harness_durable: bool = False,
+) -> list[dict]:
     items: list[dict] = []
     for runtime_type in executor.registered_runtime_types():
         metadata = _RUNTIMES[runtime_type]
@@ -54,20 +96,40 @@ def inspect_runtime_catalog(executor: RuntimeExecutor) -> list[dict]:
             installed = (
                 installed_runtime_version("codex")
                 if runtime_type == "codex"
+                else package_version("ksadk")
+                if runtime_type == "harness"
                 else package_version(package)
             )
         except PackageNotFoundError:
             installed = ""
-        items.append(
-            {
-                "runtimeType": runtime_type,
-                **metadata,
-                "installed": bool(installed),
-                "version": installed or None,
-                "status": "ready" if installed else "missing-dependency",
-                "installCommand": f"pip install 'ksadk[{runtime_type}]'",
-            }
-        )
+        entry = {
+            "runtimeType": runtime_type,
+            **metadata,
+            "installed": bool(installed),
+            "version": installed or None,
+            "status": "ready" if installed else "missing-dependency",
+            "installCommand": (
+                "pip install ksadk" if runtime_type == "harness"
+                else f"pip install 'ksadk[{runtime_type}]'"
+            ),
+        }
+        if runtime_type == "harness":
+            if native_harness_default:
+                from ksadk.harness.native_runtime import NativeRuntime
+
+                declared = NativeRuntime(durable=native_harness_durable).native_capabilities()
+                entry["adapter"] = "NativeRuntimeAdapter"
+                entry["capabilities"] = {
+                    "session": True,
+                    "cancel": declared["cancel"]["supported"],
+                    "resume": "ledger_run_id" if native_harness_durable else "in_process",
+                    "checkpoint": "not_supported",
+                    "checkpointGranularity": None,
+                    "durableAcrossProcess": declared["session_continuity"]["durable"],
+                }
+            else:
+                entry["capabilities"] = _harness_capabilities()
+        items.append(entry)
     return items
 
 

ksadk/studio/runtime_prewarm.py

@@ -0,0 +1,22 @@
+"""Prewarm immutable host wiring without claiming a future user turn."""
+
+import logging
+
+from ksadk.plugins.host import PluginHostError
+
+logger = logging.getLogger(__name__)
+
+
+async def prewarm_runtime_build(studio, build_id: str) -> None:
+    try:
+        spec = studio.resolve_run_spec(build_id)
+        runtime = studio.run_service.plugin_runtime
+        if runtime is None or spec.plugin_bundle_root is None:
+            return
+        # Session activation claims include selected model, reasoning and
+        # approval settings. Only the actual Run may pin those claims.
+        entry = await runtime._admission.resolve(lambda: runtime._host_for(spec.plugin_bundle_root))
+        if entry.agent_id != spec.agent_id:
+            raise PluginHostError("plugin_bundle_agent_mismatch", "prewarm Build Agent mismatch")
+    except Exception as error:
+        logger.info("runtime prewarm for Build %s skipped: %s", build_id, error)

ksadk/studio/runtime_source.py

@@ -94,7 +94,7 @@ def _configured_model(catalog: LocalResourceCatalog, draft: AgentDraft) -> str:
         return resolved.model
     if draft.spec.model is not None:
         return draft.spec.model.model
-    return str(draft.metadata.labels.get("agentkit.ksyun.com/model") or "glm-5.1")
+    return str(draft.metadata.labels.get("agentkit.ksyun.com/model") or "deepseek-v4.1-flash")
 
 
 def _runtime_inputs(

ksadk/studio/scheduler_assistant.py

@@ -41,7 +41,10 @@ _SCHEDULE_TOPIC = re.compile(
     r"定时|周期|自动化|计划任务|每天|每日|每周|每星期|每月|工作日|"
     r"每(?:隔)?\s*[\d一二两三四五六七八九十百半几多少]+\s*(?:分|小时|天|日|周)|"
     r"(?:明天|后天|今晚|今天).{0,16}(?:点|时|[:：])|"
-    r"\b(?:schedul\w*|automation\w*|cron|every\s|daily|weekly|hourly|tomorrow)\b",
+    r"\b(?:schedul\w*|automation\w*|cron|daily|weekly|hourly|tomorrow)\b|"
+    r"\bevery\s+(?:\d+\s+)?(?:seconds?|minutes?|hours?|days?|weeks?|months?|"
+    r"weekdays?|mondays?|tuesdays?|wednesdays?|thursdays?|fridays?|"
+    r"saturdays?|sundays?)\b",
     re.IGNORECASE,
 )
 

ksadk/studio/scheduler_runtime.py

@@ -1,31 +1,7 @@
-"""Build-pinned AgentKernel runtimes owned by the local Studio scheduler.
-
-The ordinary Studio conversation path may keep using its historical direct
-RuntimeExecutor or an independently enabled HTTP Kernel.  Scheduler Lite owns
-neither of those lifecycles.  Instead it lazily starts one in-process Kernel
-runtime for each immutable Build referenced by a local scheduled task.
-
-This is intentionally a registry rather than another process-global Kernel:
-one AgentKernelWorker has one concrete RuntimeAdapter factory, so reusing a
-single global worker for multiple Studio Builds can execute the wrong Agent.
-The registry keeps ``Build -> instance -> Runtime`` exact and dispatches every
-occurrence through that runtime's AgentControl Inbox and canonical
-SessionEvent log.
-"""
+"""Scheduler-specific target, title and event adapters for the Build registry."""
 
 from __future__ import annotations
 
-import asyncio
-import hashlib
-from collections.abc import Callable
-from dataclasses import dataclass
-from uuid import uuid4
-
-from ksadk.kernel.bootstrap import (
-    AgentKernelRuntime,
-    AgentKernelRuntimeConfig,
-    build_agent_kernel_runtime,
-)
 from ksadk.kernel.contracts import (
     AgentControlCommand,
     AgentControlPermit,
@@ -33,200 +9,29 @@ from ksadk.kernel.contracts import (
     SessionEventSubscription,
 )
 from ksadk.kernel.ingress import trusted_context
-from ksadk.runtime import RuntimeAdapter
 from ksadk.scheduler.contracts import ScheduledTaskTarget, ScheduleOccurrence
-from ksadk.sessions.base import BaseSessionService
-from ksadk.studio.run_service import StudioRunSpec
-
-ResolveBuild = Callable[[str], StudioRunSpec]
-ResolveAdapterProvider = Callable[
-    [StudioRunSpec], Callable[[], RuntimeAdapter]
-]
+from ksadk.studio.kernel_registry import (
+    ResolveAdapterProvider,
+    ResolveBuild,
+    StudioBuildKernelError,
+    StudioBuildKernelRegistry,
+    StudioBuildRuntimeTarget,
+)
 
 
-class StudioSchedulerRuntimeError(RuntimeError):
+class StudioSchedulerRuntimeError(StudioBuildKernelError):
     """Stable local scheduling failure safe to persist on an occurrence."""
 
-    def __init__(self, code: str, message: str) -> None:
-        super().__init__(message)
-        self.code = code
-
-
-@dataclass(frozen=True)
-class StudioScheduledRuntimeTarget:
-    """Server-owned immutable routing facts persisted on ScheduledTask/v1."""
-
-    build_id: str
-    agent_id: str
-    tenant_id: str
-    agent_instance_id: str
-
-
-@dataclass
-class _RuntimeEntry:
-    target: StudioScheduledRuntimeTarget
-    spec: StudioRunSpec
-    runtime: AgentKernelRuntime
-
 
-class StudioScheduledKernelRegistry:
-    """Own exact per-Build Kernel runtimes for one Studio process.
+StudioScheduledRuntimeTarget = StudioBuildRuntimeTarget
 
-    The registry does not register anything in ``ksadk.kernel.ingress`` and
-    therefore cannot redirect normal conversations or hosted HTTP traffic.
-    Scheduler dispatch uses :meth:`submit` and :meth:`read_events` directly,
-    while still crossing the frozen AgentControl permit/admission boundary.
-    """
 
-    def __init__(
-        self,
-        *,
-        resolve_build: ResolveBuild,
-        resolve_adapter_provider: ResolveAdapterProvider,
-        session_service: BaseSessionService,
-        runtime_executor: object | None = None,
-        tenant_id: str = "local-studio",
-        workspace_id: str = "studio-scheduler",
-        poll_interval: float = 0.05,
-        lease_ttl_seconds: float = 30.0,
-    ) -> None:
-        self._resolve_build = resolve_build
-        self._resolve_adapter_provider = resolve_adapter_provider
-        self._session_service = session_service
-        self._runtime_executor = runtime_executor
-        self._tenant_id = tenant_id
-        self._workspace_id = workspace_id
-        self._poll_interval = poll_interval
-        self._lease_ttl_seconds = lease_ttl_seconds
-        self._owner_id = uuid4().hex
-        self._entries_by_build: dict[str, _RuntimeEntry] = {}
-        self._build_by_instance: dict[str, str] = {}
-        self._lock = asyncio.Lock()
-        self._started = False
-
-    @property
-    def started(self) -> bool:
-        return self._started
-
-    @property
-    def active_runtime_count(self) -> int:
-        return len(self._entries_by_build)
-
-    async def start(self) -> None:
-        self._started = True
-
-    async def ensure_build(
-        self,
-        build_id: str,
-        *,
-        expected_agent_id: str | None = None,
-    ) -> StudioScheduledRuntimeTarget:
-        """Start or return the exact Runtime owned by one immutable Build."""
-
-        normalized = str(build_id).strip()
-        if not normalized:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_BUILD_REQUIRED",
-                "定时任务缺少不可变 Build 标识",
-            )
-        if not self._started:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_RUNTIME_NOT_STARTED",
-                "Studio Scheduler Runtime 尚未启动",
-            )
-        existing = self._entries_by_build.get(normalized)
-        if existing is not None:
-            self._require_agent(existing.spec, expected_agent_id)
-            return existing.target
+class StudioScheduledKernelRegistry(StudioBuildKernelRegistry):
+    """Add Scheduler references and session presentation to shared Build Kernels."""
 
-        async with self._lock:
-            existing = self._entries_by_build.get(normalized)
-            if existing is not None:
-                self._require_agent(existing.spec, expected_agent_id)
-                return existing.target
-            try:
-                spec = self._resolve_build(normalized)
-            except Exception as error:
-                raise StudioSchedulerRuntimeError(
-                    "SCHEDULER_BUILD_UNAVAILABLE",
-                    f"定时任务绑定的 Build {normalized!r} 不可用",
-                ) from error
-            if spec.build_id != normalized:
-                raise StudioSchedulerRuntimeError(
-                    "SCHEDULER_BUILD_MISMATCH",
-                    "Build 解析结果与定时任务绑定不一致",
-                )
-            self._require_agent(spec, expected_agent_id)
-            try:
-                adapter_provider = self._resolve_adapter_provider(spec)
-            except Exception as error:
-                raise StudioSchedulerRuntimeError(
-                    "SCHEDULER_PROVIDER_UNAVAILABLE",
-                    f"Build {normalized!r} 的 AgentProvider 不可用",
-                ) from error
-
-            # ``build_agent_kernel_runtime`` asks the provider once to snapshot
-            # capabilities.  Retain that exact adapter for the first worker or
-            # recovery acquisition instead of constructing and discarding a
-            # resource-owning Codex/Harness adapter during registration.
-            retained_first_adapter: RuntimeAdapter | None = None
-            first_adapter_borrowed = False
-
-            def checked_adapter_provider() -> RuntimeAdapter:
-                nonlocal retained_first_adapter, first_adapter_borrowed
-                if retained_first_adapter is not None and not first_adapter_borrowed:
-                    first_adapter_borrowed = True
-                    adapter = retained_first_adapter
-                    retained_first_adapter = None
-                    return adapter
-                adapter = adapter_provider()
-                if not isinstance(adapter, RuntimeAdapter):
-                    raise StudioSchedulerRuntimeError(
-                        "SCHEDULER_PROVIDER_INVALID",
-                        "AgentProvider 没有返回 RuntimeAdapter",
-                    )
-                if retained_first_adapter is None and not first_adapter_borrowed:
-                    retained_first_adapter = adapter
-                return adapter
-
-            instance_id = self._instance_id(normalized)
-            config = AgentKernelRuntimeConfig(
-                agent_instance_id=instance_id,
-                authority_mode="local",
-                driver="memory",
-                durability_tier="ephemeral",
-                adapter_provider=checked_adapter_provider,
-                session_service=self._session_service,
-                runtime_executor=self._runtime_executor,
-                launch_context=spec.launch_context,
-                start_request_defaults=self._start_defaults(spec),
-                tenant_id=self._tenant_id,
-                workspace_id=self._workspace_id,
-                poll_interval=self._poll_interval,
-                lease_ttl_seconds=self._lease_ttl_seconds,
-                activation_id=f"studio-scheduler:{self._owner_id}:{instance_id}",
-                runtime_type=spec.launch_context.runtime_type,
-                bundle_digest=spec.manifest_sha256 or normalized,
-            )
-            runtime = build_agent_kernel_runtime(config)
-            try:
-                await runtime.start()
-            except Exception:
-                await runtime.close()
-                raise
-            target = StudioScheduledRuntimeTarget(
-                build_id=normalized,
-                agent_id=spec.agent_id,
-                tenant_id=self._tenant_id,
-                agent_instance_id=instance_id,
-            )
-            self._entries_by_build[normalized] = _RuntimeEntry(
-                target=target,
-                spec=spec,
-                runtime=runtime,
-            )
-            self._build_by_instance[instance_id] = normalized
-            return target
+    @classmethod
+    def _error(cls, code: str, message: str) -> StudioSchedulerRuntimeError:
+        return StudioSchedulerRuntimeError(f"SCHEDULER_{code}", message)
 
     async def ensure_target(
         self, target: ScheduledTaskTarget
@@ -246,15 +51,6 @@ class StudioScheduledKernelRegistry:
             )
         return exact
 
-    def runtime_for_build(self, build_id: str) -> AgentKernelRuntime:
-        entry = self._entries_by_build.get(str(build_id))
-        if entry is None:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_TARGET_UNAVAILABLE",
-                "定时任务目标 Kernel 未注册",
-            )
-        return entry.runtime
-
     async def submit(
         self,
         command: AgentControlCommand,
@@ -262,26 +58,23 @@ class StudioScheduledKernelRegistry:
     ) -> AgentControlReceipt:
         entry = self._entry_for_instance(command.agent_instance_id)
         if command.tenant_id != entry.target.tenant_id:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_TARGET_MISMATCH",
-                "AgentControl tenant 与 Build Kernel 不一致",
-            )
-        if await self._session_service.get_session(command.session_id) is None:
-            await self._session_service.create_session(
-                agent_id=entry.target.agent_id,
-                user_id=command.tenant_id,
-                session_id=command.session_id,
-            )
-            prompt = command.payload.get("content")
-            if isinstance(prompt, str) and prompt.strip():
-                await self._session_service.update_session_metadata(
-                    command.session_id,
-                    title=f"定时任务 · {prompt[:40]}",
-                    title_source="scheduler",
-                    first_prompt=prompt,
-                    last_prompt=prompt,
-                )
-        return await entry.runtime.kernel.submit(command, permit=permit)
+            raise self._error("TARGET_MISMATCH", "AgentControl tenant 与 Build Kernel 不一致")
+        prompt = command.payload.get("content")
+        has_prompt = isinstance(prompt, str) and bool(prompt.strip())
+        await self.ensure_session(
+            entry.target.build_id,
+            command.session_id,
+            # Studio sessions are owned by the authenticated local principal;
+            # the scheduler tenant is an authority scope, not a user id.
+            "local-user",
+            title=f"定时任务 · {prompt[:40]}" if has_prompt else None,
+            metadata={
+                "title_source": "scheduler",
+                "first_prompt": prompt,
+                "last_prompt": prompt,
+            } if has_prompt else None,
+        )
+        return await self.submit_control(command, permit)
 
     async def read_events(
         self, occurrence: ScheduleOccurrence
@@ -324,56 +117,6 @@ class StudioScheduledKernelRegistry:
             await stream.aclose()
         return tuple(result)
 
-    async def close(self) -> None:
-        async with self._lock:
-            entries = list(self._entries_by_build.values())
-            self._entries_by_build.clear()
-            self._build_by_instance.clear()
-            self._started = False
-        first_error: BaseException | None = None
-        for entry in reversed(entries):
-            try:
-                await entry.runtime.close()
-            except BaseException as error:  # cleanup must continue for other Builds
-                if first_error is None:
-                    first_error = error
-        if first_error is not None:
-            raise first_error
-
-    def _entry_for_instance(self, instance_id: str) -> _RuntimeEntry:
-        build_id = self._build_by_instance.get(str(instance_id))
-        entry = self._entries_by_build.get(build_id or "")
-        if entry is None:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_TARGET_UNAVAILABLE",
-                "定时任务目标 Kernel 未注册",
-            )
-        return entry
-
-    def _instance_id(self, build_id: str) -> str:
-        digest = hashlib.sha256(build_id.encode("utf-8")).hexdigest()[:24]
-        return f"studio-schedule-{digest}"
-
-    @staticmethod
-    def _require_agent(spec: StudioRunSpec, expected_agent_id: str | None) -> None:
-        if expected_agent_id and spec.agent_id != expected_agent_id:
-            raise StudioSchedulerRuntimeError(
-                "SCHEDULER_AGENT_MISMATCH",
-                "定时任务 Agent 与不可变 Build 不一致",
-            )
-
-    @staticmethod
-    def _start_defaults(spec: StudioRunSpec) -> dict[str, object]:
-        defaults: dict[str, object] = {
-            "agent_id": spec.agent_id,
-            "config": dict(spec.request_config),
-        }
-        if spec.model:
-            defaults["model"] = spec.model
-            defaults["allowed_models"] = [spec.model]
-        return defaults
-
-
 __all__ = [
     "ResolveAdapterProvider",
     "ResolveBuild",