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

ksadk/studio/runtime_source.py

@@ -30,7 +30,15 @@ def materialize_generated_runtime_source(
     """
 
     runtime = draft.spec.runtime
-    if runtime is None or runtime.type == "codex" or not runtime.project_path:
+    # Only the two legacy Python-framework runtimes own generated source.
+    # Harness and externally installed AgentProviders are bundle compositions;
+    # treating either as the ``else`` branch here would silently generate a
+    # LangGraph project and change the selected provider's execution model.
+    if (
+        runtime is None
+        or runtime.type not in {"adk", "langgraph"}
+        or not runtime.project_path
+    ):
         return
     root = workspace.resolve(runtime.project_path)
     marker = root / _GENERATED_MARKER

ksadk/studio/scheduler_runtime.py

@@ -0,0 +1,374 @@
+"""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.
+"""
+
+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,
+    AgentControlReceipt,
+    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]
+]
+
+
+class StudioSchedulerRuntimeError(RuntimeError):
+    """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.
+
+    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
+
+        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
+
+    async def ensure_target(
+        self, target: ScheduledTaskTarget
+    ) -> StudioScheduledRuntimeTarget:
+        build_id = str(target.agent_version_ref or "").strip()
+        exact = await self.ensure_build(
+            build_id,
+            expected_agent_id=target.agent_id,
+        )
+        if (
+            target.tenant_id != exact.tenant_id
+            or target.agent_instance_id != exact.agent_instance_id
+        ):
+            raise StudioSchedulerRuntimeError(
+                "SCHEDULER_TARGET_MISMATCH",
+                "定时任务目标与不可变 Build 的 Kernel 身份不一致",
+            )
+        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,
+        permit: AgentControlPermit,
+    ) -> 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,
+            )
+        return await entry.runtime.kernel.submit(command, permit=permit)
+
+    async def read_events(
+        self, occurrence: ScheduleOccurrence
+    ) -> tuple[tuple[int, object], ...]:
+        target = occurrence.target
+        if target is None:
+            return ()
+        await self.ensure_target(target)
+        entry = self._entry_for_instance(target.agent_instance_id)
+        trusted = trusted_context(
+            source_kind="scheduler",
+            source_ref=occurrence.occurrence_id,
+            tenant_id=target.tenant_id,
+            agent_instance_id=target.agent_instance_id,
+            session_id=occurrence.session_id,
+            operations=("subscribe_events",),
+        )
+        cursor = occurrence.last_event_seq
+        if cursor is None:
+            cursor = occurrence.accepted_seq or 0
+        subscription = SessionEventSubscription(
+            tenant_id=trusted.tenant_id,
+            agent_instance_id=trusted.agent_instance_id,
+            session_id=occurrence.session_id,
+            authorization_ref=trusted.permit.permit_id,
+            after_seq=cursor,
+        )
+        result: list[tuple[int, object]] = []
+        stream = entry.runtime.kernel.subscribe(
+            subscription,
+            permit=trusted.permit,
+            timeout=0.05,
+        )
+        try:
+            async for envelope in stream:
+                result.append((int(envelope.seq), envelope))
+                if len(result) >= 100:
+                    break
+        finally:
+            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",
+    "StudioScheduledKernelRegistry",
+    "StudioScheduledRuntimeTarget",
+    "StudioSchedulerRuntimeError",
+]

ksadk/studio/scheduler_service.py

@@ -0,0 +1,211 @@
+"""Studio-facing lifecycle for the local Scheduler Lite backend.
+
+This service owns only local scheduling intent and occurrence history.  It
+does not silently start a second runtime or submit prompts directly: when the
+local AgentKernel route is unavailable it reports that condition explicitly.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from ksadk.kernel.ingress import kernel_route_active
+from ksadk.scheduler import (
+    AgentControlSchedulerDispatcher,
+    SchedulerDispatchError,
+    SchedulerEngine,
+    SchedulerSQLiteStore,
+    next_schedule_time,
+)
+from ksadk.scheduler.contracts import ScheduledTask, ScheduledTaskTarget, ScheduleOccurrence
+from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.workspace import Workspace
+
+if TYPE_CHECKING:
+    from ksadk.studio.scheduler_runtime import StudioScheduledKernelRegistry
+
+
+class StudioSchedulerService:
+    """CRUD and explicit local process lifecycle for ``ScheduledTask/v1``."""
+
+    def __init__(
+        self,
+        workspace: Workspace,
+        *,
+        runtime_registry: StudioScheduledKernelRegistry | None = None,
+    ) -> None:
+        self.workspace = workspace
+        self.runtime_registry = runtime_registry
+        self.store = SchedulerSQLiteStore(
+            workspace.resolve(".agentkit/scheduler/scheduler.sqlite3")
+        )
+        dispatcher = (
+            AgentControlSchedulerDispatcher(
+                runtime_registry.submit,
+                event_reader=runtime_registry.read_events,
+                target_preparer=self._prepare_target,
+            )
+            if runtime_registry is not None
+            else AgentControlSchedulerDispatcher()
+        )
+        self.engine = SchedulerEngine(
+            self.store,
+            dispatcher,
+            # Keep the local monitor alive when Studio starts before a Runtime.
+            # It observes availability on every scan and never claims work while
+            # the trusted Kernel route is absent.
+            tick_guard=self._runtime_available,
+        )
+
+    def availability(self) -> dict[str, object]:
+        active = self._runtime_available()
+        engine = self.engine.status()
+        return {
+            "available": active,
+            "scope": "local_studio_process",
+            "alwaysOn": False,
+            "reason": "agent_kernel_route_inactive" if not active else None,
+            "triggerActive": bool(active and engine["running"]),
+            "store": "sqlite",
+            **engine,
+        }
+
+    def list_tasks(self) -> list[ScheduledTask]:
+        return [task for task, _generation in self.store.list_tasks()]
+
+    def get_task(self, task_id: str) -> ScheduledTask:
+        item = self.store.get_task(task_id)
+        if item is None:
+            raise not_found("schedule", task_id)
+        return item[0]
+
+    def list_occurrences(self, task_id: str, *, limit: int = 50) -> list[ScheduleOccurrence]:
+        # A deleted task intentionally retains occurrence history, so query the
+        # history table directly rather than requiring a live task row.
+        return self.store.list_occurrences(task_id, limit=limit)
+
+    def list_all_occurrences(self, *, limit: int = 200) -> list[ScheduleOccurrence]:
+        return self.store.list_all_occurrences(limit=limit)
+
+    def create_task(self, task: ScheduledTask) -> ScheduledTask:
+        if self.store.get_task(task.task_id) is not None:
+            raise StudioError(
+                "SCHEDULE_ALREADY_EXISTS",
+                "该定时任务已存在",
+                status_code=409,
+                details={"id": task.task_id},
+            )
+        prepared = self._prepare(task)
+        self.store.put_task(prepared, generation=1)
+        return prepared
+
+    def update_task(self, task_id: str, task: ScheduledTask) -> ScheduledTask:
+        if task.task_id != task_id:
+            raise StudioError(
+                "SCHEDULE_ID_IMMUTABLE",
+                "定时任务 ID 不可修改",
+                status_code=422,
+                field="taskId",
+            )
+        existing = self.store.get_task(task_id)
+        if existing is None:
+            raise not_found("schedule", task_id)
+        old, generation = existing
+        prepared = self._prepare(
+            task.model_copy(update={"created_at": old.created_at}),
+            reset_next_run=True,
+        )
+        self.store.put_task(prepared, generation=generation + 1)
+        return prepared
+
+    def delete_task(self, task_id: str) -> None:
+        if not self.store.delete_task(task_id):
+            raise not_found("schedule", task_id)
+
+    async def run_now(self, task_id: str) -> ScheduleOccurrence:
+        self._require_kernel_route()
+        try:
+            return await self.engine.run_now(task_id)
+        except KeyError as exc:
+            raise not_found("schedule", task_id) from exc
+        except SchedulerDispatchError as exc:
+            raise StudioError(
+                exc.code,
+                exc.detail,
+                status_code=409 if exc.code in {"TASK_DISABLED", "CONCURRENCY_FORBID"} else 422,
+            ) from exc
+
+    async def tick(self) -> list[ScheduleOccurrence]:
+        self._require_kernel_route()
+        return await self.engine.tick()
+
+    async def start_if_available(self) -> bool:
+        # The monitor is process-local and cheap. Starting it unconditionally
+        # is what lets a Runtime launched after Studio startup begin scheduling
+        # without a daemon restart. The engine's tick_guard is the fail-closed
+        # admission boundary while no Kernel route exists.
+        if self.runtime_registry is not None:
+            await self.runtime_registry.start()
+        await self.engine.start()
+        return self._runtime_available()
+
+    async def stop(self) -> None:
+        try:
+            await self.engine.stop()
+        finally:
+            if self.runtime_registry is not None:
+                await self.runtime_registry.close()
+
+    def _prepare(self, task: ScheduledTask, *, reset_next_run: bool = False) -> ScheduledTask:
+        now = datetime.now(timezone.utc)
+        next_run_at = task.next_run_at
+        if reset_next_run or next_run_at is None:
+            next_run_at = next_schedule_time(
+                task.schedule,
+                after=now,
+                anchor_at=task.created_at,
+            )
+        if task.enabled and next_run_at is None:
+            raise StudioError(
+                "SCHEDULE_NOT_FUTURE",
+                "启用的单次任务必须指定未来的触发时间",
+                status_code=422,
+                field="schedule.at",
+            )
+        return task.model_copy(update={"next_run_at": next_run_at, "updated_at": now})
+
+    def _runtime_available(self) -> bool:
+        if self.runtime_registry is not None:
+            return self.runtime_registry.started
+        return kernel_route_active()
+
+    def _require_kernel_route(self) -> None:
+        if not self._runtime_available():
+            raise StudioError(
+                "SCHEDULER_RUNTIME_UNAVAILABLE",
+                "本地 Agent Kernel 未启用，定时任务不会伪装为已运行",
+                status_code=409,
+            )
+
+    async def _prepare_target(self, target: ScheduledTaskTarget) -> object:
+        """Resolve the build-pinned Kernel target, preserving typed failures.
+
+        StudioScheduledKernelRegistry.ensure_target raises
+        StudioSchedulerRuntimeError (for example SCHEDULER_BUILD_UNAVAILABLE
+        when agent_version_ref is not a real immutable Build id).  Without this
+        adapter the SchedulerEngine generic except Exception collapses every such
+        failure into an opaque DISPATCH_FAILED occurrence, hiding the real reason.
+        Re-raise it as a SchedulerDispatchError so the durable occurrence keeps
+        the actionable error code instead of the catch-all.
+        """
+
+        from ksadk.studio.scheduler_runtime import StudioSchedulerRuntimeError
+
+        try:
+            return await self.runtime_registry.ensure_target(target)  # type: ignore[union-attr]
+        except StudioSchedulerRuntimeError as error:
+            raise SchedulerDispatchError(error.code, str(error)) from error
+
+
+__all__ = ["StudioSchedulerService"]