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

ksadk/runtime/usage.py

@@ -0,0 +1,33 @@
+"""Canonical runtime usage projection helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+def canonical_usage_payload(
+    usage: Mapping[str, Any], *, runtime_type: str
+) -> dict[str, Any]:
+    """Normalize provider usage, including nested cache/reasoning details."""
+    input_details = usage.get("input_token_details")
+    output_details = usage.get("output_token_details")
+    cached = (
+        input_details.get("cached")
+        if isinstance(input_details, Mapping)
+        else usage.get("cached_tokens")
+    )
+    reasoning = (
+        output_details.get("reasoning")
+        if isinstance(output_details, Mapping)
+        else usage.get("reasoning_tokens")
+    )
+    input_tokens = int(usage.get("input_tokens") or 0)
+    output_tokens = int(usage.get("output_tokens") or 0)
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "total_tokens": int(usage.get("total_tokens") or input_tokens + output_tokens),
+        "cached_tokens": int(cached or 0),
+        "reasoning_tokens": int(reasoning or 0),
+        "source": str(usage.get("source") or runtime_type),
+    }

ksadk/sandbox/__init__.py

@@ -12,7 +12,7 @@ from ksadk.sandbox.base import (
     SandboxSpec,
     SandboxType,
 )
-from ksadk.sandbox.factory import create_sandbox_backend, sandbox_spec_from_env
+from ksadk.sandbox.factory import create_sandbox_backend, sandbox_spec_from_env, setup_sandbox_api_url_if_needed
 
 __all__ = [
     "E2BSandboxBackend",
@@ -28,4 +28,5 @@ __all__ = [
     "SandboxType",
     "create_sandbox_backend",
     "sandbox_spec_from_env",
+    "setup_sandbox_api_url_if_needed",
 ]

ksadk/sandbox/backends/e2b.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import logging
 import os
 import time
 from typing import Any
@@ -12,10 +13,15 @@ from ksadk.sandbox.base import (
     SandboxSpec,
 )
 
+logger = logging.getLogger(__name__)
+
 _TRANSIENT_STARTUP_ERROR_NAMES = {
     "NotFoundException",
     "FileNotFoundException",
     "SandboxNotFoundException",
+    # create 快速返回后 envd RPC 通道可能尚未就绪 (connection refused / unavailable),
+    # SDK 将其包装为 TimeoutException 抛出, 需按瞬时启动错误重试。
+    "TimeoutException",
 }
 
 
@@ -148,7 +154,7 @@ class E2BSandboxBackend:
             allow_internet_access=self.spec.allow_internet_access,
         )
         session = self._wrap_sandbox(sandbox)
-        self._wait_until_ready(session)
+        self._wait_until_ready(session, runtime_env)
         session.write_files(
             [(item.target_path, item.source.read_bytes()) for item in input_files or []]
         )
@@ -157,6 +163,33 @@ class E2BSandboxBackend:
     def _wrap_sandbox(self, sandbox: Any) -> E2BSandboxSession:
         return E2BSandboxSession(sandbox)
 
-    def _wait_until_ready(self, session: E2BSandboxSession) -> None:
+    def _wait_until_ready(
+        self, session: E2BSandboxSession, env: dict[str, str] | None = None
+    ) -> None:
         _with_startup_retry(lambda: session.run_command("true"))
         _with_startup_retry(lambda: session.write_file("/tmp/.ksadk-sandbox-ready", ""))
+        self._wait_env_applied(session, env or {})
+
+    def _wait_env_applied(self, session: E2BSandboxSession, env: dict[str, str]) -> None:
+        # create 返回后 envd 异步应用 envVars, 实测存在秒级延迟;
+        # 轮询一个非空变量直到值就位, 避免紧随其后的 agent 进程读到缺失的环境。
+        probe = next(((k, v) for k, v in env.items() if v), None)
+        if probe is None:
+            return
+        key, expected = probe
+        attempts = _startup_retry_attempts()
+        delay = _startup_retry_delay()
+        for attempt in range(attempts):
+            result = session.run_command(f"printenv {key} || true")
+            if result.stdout.strip() == expected:
+                return
+            time.sleep(min(delay * (2**attempt), 1.0))
+        # 不 raise: 模板可能预置同名空值覆盖 create 注入 (envd 合并优先级问题),
+        # 此时调用方仍可通过 run_command(env=...) 的 per-command 注入拿到正确值。
+        logger.warning(
+            "E2B sandbox env %s not applied after %d attempts (expected %r); "
+            "template may predefine an empty override",
+            key,
+            attempts,
+            expected,
+        )

ksadk/sandbox/factory.py

@@ -16,11 +16,83 @@ def bool_env(name: str, default: bool = True) -> bool:
     return raw.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _resolve_sandbox_api_url() -> str:
+    """Probe sandbox control-plane URL at runtime (in-Pod).
+
+    agentengine-server injects public E2B_API_URL on the management cluster.
+    public_only compute pods can reach the public address directly; private_only
+    pods have no public egress. Strategy: try the original (public) URL first;
+    if reachable keep it, otherwise fall back to the 198 public-service-net
+    internal address. Mirrors KSPMAS get_kspmas_api_base(): probe runs in-Pod.
+    """
+    raw = (os.environ.get("E2B_API_URL") or "").strip()
+    if not raw:
+        return raw
+
+    from urllib.parse import urlsplit, urlunsplit
+
+    parsed = urlsplit(raw)
+    host = (parsed.hostname or "").lower()
+    if host.endswith(".sdns.ksyun.com"):
+        return raw
+    if not host.endswith(".sandbox.ksyun.com"):
+        return raw
+
+    parts = host.split(".")
+    region = ""
+    if len(parts) >= 4 and parts[0] == "mgr":
+        region = parts[1]
+    elif len(parts) >= 4:
+        region = parts[1] if parts[1] != "sandbox" else ""
+    if not region:
+        return raw
+
+    import socket
+
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+
+    # 1) Try the original (public) URL first; reachable => keep it.
+    try:
+        s = socket.socket()
+        s.settimeout(1.5)
+        s.connect((host, port))
+        s.close()
+        return raw
+    except OSError:
+        pass
+
+    # 2) Public unreachable (e.g. private_only node) => fall back to internal.
+    internal_host = f"sandbox.{region}.sandbox.sdns.ksyun.com"
+    try:
+        s = socket.socket()
+        s.settimeout(1.5)
+        s.connect((internal_host, port))
+        s.close()
+    except OSError:
+        return raw
+
+    internal_url = urlunsplit((parsed.scheme or "https", internal_host, parsed.path, parsed.query, ""))
+    return internal_url
+
+
+def setup_sandbox_api_url_if_needed() -> None:
+    """Override E2B_API_URL to internal address before creating E2B backend.
+
+    Only runs in managed runtime (AGENT_RUNTIME_ID / K8S); local dev unaffected.
+    """
+    if not os.environ.get("AGENT_RUNTIME_ID") and not os.environ.get("KUBERNETES_SERVICE_HOST"):
+        return
+    resolved = _resolve_sandbox_api_url()
+    if resolved != (os.environ.get("E2B_API_URL") or ""):
+        os.environ["E2B_API_URL"] = resolved
+
+
 def create_sandbox_backend(
     backend: str | None = None,
     *,
     sandbox_cls: Any | None = None,
 ) -> SandboxBackend:
+    setup_sandbox_api_url_if_needed()
     resolved = (backend or os.environ.get("KSADK_SANDBOX_BACKEND") or "e2b").strip().lower()
     if resolved in {"local", "local_process"}:
         return LocalProcessSandboxBackend(

ksadk/scheduler/__init__.py

@@ -0,0 +1,18 @@
+"""Local Scheduler Lite contracts and deterministic calendar calculations."""
+
+from ksadk.scheduler.calendar import next_schedule_time
+from ksadk.scheduler.contracts import ScheduledTask, ScheduleOccurrence, ScheduleSpec
+from ksadk.scheduler.dispatcher import AgentControlSchedulerDispatcher
+from ksadk.scheduler.engine import SchedulerDispatchError, SchedulerEngine
+from ksadk.scheduler.sqlite_store import SchedulerSQLiteStore
+
+__all__ = [
+    "ScheduleOccurrence",
+    "ScheduledTask",
+    "ScheduleSpec",
+    "AgentControlSchedulerDispatcher",
+    "SchedulerDispatchError",
+    "SchedulerEngine",
+    "SchedulerSQLiteStore",
+    "next_schedule_time",
+]

ksadk/scheduler/calendar.py

@@ -0,0 +1,102 @@
+"""Deterministic, dependency-free calendar calculations for Scheduler Lite.
+
+The supported cron dialect intentionally stays small and explicit: five fields,
+numeric values, comma lists, ranges and ``*/step``.  It is sufficient for the
+Studio scheduler and avoids inheriting an accidental transitive dependency.
+All matching happens after UTC -> IANA timezone conversion.  That means a
+nonexistent DST local minute is skipped and the repeated fall-back minute runs
+once (the first ``fold`` only).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from zoneinfo import ZoneInfo
+
+from ksadk.scheduler.contracts import ScheduleSpec, _parse_cron
+
+
+def next_schedule_time(
+    schedule: ScheduleSpec,
+    *,
+    after: datetime,
+    anchor_at: datetime | None = None,
+) -> datetime | None:
+    """Return the first scheduled UTC timestamp strictly after ``after``."""
+
+    if after.tzinfo is None:
+        raise ValueError("after must include a timezone")
+    after = after.astimezone(timezone.utc)
+    if schedule.kind == "once":
+        assert schedule.at is not None
+        return schedule.at if schedule.at > after else None
+    if schedule.kind == "interval":
+        assert schedule.every_seconds is not None
+        anchor = (schedule.anchor_at or anchor_at or after).astimezone(timezone.utc)
+        if anchor > after:
+            return anchor
+        elapsed = (after - anchor).total_seconds()
+        step = schedule.every_seconds
+        return anchor + timedelta(seconds=(int(elapsed // step) + 1) * step)
+    assert schedule.expression is not None
+    return _next_cron(schedule.expression, schedule.timezone, after)
+
+
+def _next_cron(expression: str, timezone_name: str, after: datetime) -> datetime:
+    minute, hour, day, month, weekday = _parse_cron(expression)
+    fields = (
+        _expand_field(minute, 0, 59),
+        _expand_field(hour, 0, 23),
+        _expand_field(day, 1, 31),
+        _expand_field(month, 1, 12),
+        _expand_field(weekday, 0, 6),
+    )
+    zone = ZoneInfo(timezone_name)
+    candidate = after.replace(second=0, microsecond=0) + timedelta(minutes=1)
+    # Five years is a deliberate guard against impossible expressions such as
+    # 31 February.  The caller receives a typed validation error rather than a
+    # scheduler loop that runs forever.
+    deadline = candidate + timedelta(days=366 * 5)
+    while candidate <= deadline:
+        local = candidate.astimezone(zone)
+        # datetime.weekday uses Monday=0.  Cron uses Sunday=0.
+        cron_weekday = (local.weekday() + 1) % 7
+        if (
+            local.fold == 0
+            and local.minute in fields[0]
+            and local.hour in fields[1]
+            and local.day in fields[2]
+            and local.month in fields[3]
+            and cron_weekday in fields[4]
+        ):
+            return candidate
+        candidate += timedelta(minutes=1)
+    raise ValueError("cron expression has no matching time within five years")
+
+
+def _expand_field(value: str, minimum: int, maximum: int) -> set[int]:
+    result: set[int] = set()
+    for item in value.split(","):
+        if "/" in item:
+            base, step_text = item.split("/", 1)
+        else:
+            base, step_text = item, None
+        step = int(step_text) if step_text is not None else 1
+        if step <= 0:
+            raise ValueError("cron step must be positive")
+        if base == "*":
+            start, end = minimum, maximum
+        elif "-" in base:
+            start_text, end_text = base.split("-", 1)
+            start, end = int(start_text), int(end_text)
+        else:
+            start = end = int(base)
+        if start < minimum or end > maximum or start > end:
+            raise ValueError("cron field is outside its valid range")
+        result.update(range(start, end + 1, step))
+    if not result:
+        raise ValueError("cron field must not be empty")
+    return result
+
+
+__all__ = ["next_schedule_time"]

ksadk/scheduler/contracts.py

@@ -0,0 +1,254 @@
+"""Versioned Scheduler Lite source contracts (P2-06 foundation)."""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any, Literal
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+def _to_camel(value: str) -> str:
+    head, *tail = value.split("_")
+    return head + "".join(part.capitalize() for part in tail)
+
+
+class ScheduleModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=_to_camel,
+        populate_by_name=True,
+        extra="forbid",
+        frozen=True,
+    )
+
+
+_TASK_ID = re.compile(r"^[a-z][a-z0-9-]{2,62}$")
+ScheduleOccurrenceState = Literal[
+    "claimed",
+    "accepted",
+    "running",
+    "succeeded",
+    "failed",
+    "skipped",
+    "cancelled",
+]
+
+
+class ScheduleSpec(ScheduleModel):
+    kind: Literal["once", "interval", "cron"]
+    timezone: str = "UTC"
+    at: datetime | None = None
+    every_seconds: int | None = Field(default=None, ge=60, le=31_536_000)
+    anchor_at: datetime | None = None
+    expression: str | None = Field(default=None, min_length=9, max_length=128)
+    misfire_policy: Literal["skip", "run_once"] = "skip"
+
+    @field_validator("timezone")
+    @classmethod
+    def validate_timezone(cls, value: str) -> str:
+        try:
+            ZoneInfo(value)
+        except ZoneInfoNotFoundError as error:
+            raise ValueError("timezone must be an IANA timezone") from error
+        return value
+
+    @field_validator("at", "anchor_at")
+    @classmethod
+    def normalize_timestamp(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError("schedule timestamps must include a timezone")
+        return value.astimezone(timezone.utc)
+
+    @model_validator(mode="after")
+    def validate_kind_shape(self) -> "ScheduleSpec":
+        if self.kind == "once":
+            if self.at is None or self.every_seconds is not None or self.expression is not None:
+                raise ValueError("once schedule requires only at")
+        elif self.kind == "interval":
+            if self.every_seconds is None or self.at is not None or self.expression is not None:
+                raise ValueError("interval schedule requires everySeconds and no expression")
+        elif self.kind == "cron":
+            if self.expression is None or self.at is not None or self.every_seconds is not None:
+                raise ValueError("cron schedule requires only expression")
+            _parse_cron(self.expression)
+        return self
+
+
+class ScheduledTaskTarget(ScheduleModel):
+    # ``agent_instance_id`` identifies the concrete Kernel owner which will
+    # consume an Inbox command.  ``agent_id`` is the Studio-facing stable
+    # logical Agent identity used to retain a task on its detail page even when
+    # the task is pinned to an older immutable Build.  It is optional only so
+    # existing v1 SQLite rows remain readable; all Studio-authored tasks set it.
+    agent_id: str | None = Field(default=None, min_length=1, max_length=256)
+    tenant_id: str = Field(min_length=1, max_length=256)
+    agent_instance_id: str = Field(min_length=1, max_length=256)
+    agent_version_ref: str | None = Field(default=None, min_length=1, max_length=256)
+    session_id: str | None = Field(default=None, min_length=1, max_length=256)
+    authorization_ref: str = Field(min_length=1, max_length=512)
+
+
+class ScheduleCommandTemplate(ScheduleModel):
+    """The sole supported Scheduler Lite action: durable enqueue via AgentControl."""
+
+    command_type: Literal["enqueue"] = "enqueue"
+    payload: dict[str, Any]
+
+    @model_validator(mode="after")
+    def validate_payload(self) -> "ScheduleCommandTemplate":
+        if "content" not in self.payload:
+            raise ValueError("scheduled enqueue payload requires content")
+        _reject_clear_secrets(self.payload)
+        return self
+
+
+class ScheduledTask(ScheduleModel):
+    api_version: Literal["schedule.ksadk.io/v1"] = "schedule.ksadk.io/v1"
+    kind: Literal["ScheduledTask"] = "ScheduledTask"
+    schema_version: Literal[1] = 1
+    task_id: str = Field(min_length=3, max_length=63)
+    # A human-facing task label belongs to the durable schedule intent, not a
+    # transient Studio card.  Optional keeps the previously frozen v1 rows
+    # and third-party producers readable during this additive transition.
+    display_name: str | None = Field(default=None, min_length=1, max_length=128)
+    target: ScheduledTaskTarget
+    schedule: ScheduleSpec
+    command: ScheduleCommandTemplate
+    enabled: bool = True
+    continuity: Literal["new_session", "continue_session"] = "new_session"
+    concurrency_policy: Literal["forbid"] = "forbid"
+    next_run_at: datetime | None = None
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @field_validator("task_id")
+    @classmethod
+    def validate_task_id(cls, value: str) -> str:
+        if not _TASK_ID.fullmatch(value):
+            raise ValueError("taskId must be a lowercase stable identifier")
+        return value
+
+    @model_validator(mode="after")
+    def validate_continuity_target(self) -> "ScheduledTask":
+        if self.continuity == "continue_session" and not self.target.session_id:
+            raise ValueError("continue_session schedule requires target.sessionId")
+        return self
+
+    @field_validator("next_run_at", "created_at", "updated_at")
+    @classmethod
+    def normalize_timestamp(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError("scheduler timestamps must include a timezone")
+        return value.astimezone(timezone.utc)
+
+
+class ScheduleOccurrenceTransition(ScheduleModel):
+    """One durable state change displayed by Studio's execution history."""
+
+    state: ScheduleOccurrenceState
+    at: datetime
+    detail: str | None = Field(default=None, max_length=1024)
+    error_code: str | None = Field(default=None, max_length=128)
+
+    @field_validator("at")
+    @classmethod
+    def normalize_timestamp(cls, value: datetime) -> datetime:
+        if value.tzinfo is None:
+            raise ValueError("occurrence transition timestamps must include a timezone")
+        return value.astimezone(timezone.utc)
+
+
+class ScheduleOccurrence(ScheduleModel):
+    api_version: Literal["schedule.ksadk.io/v1"] = "schedule.ksadk.io/v1"
+    kind: Literal["ScheduleOccurrence"] = "ScheduleOccurrence"
+    schema_version: Literal[1] = 1
+    occurrence_id: str = Field(min_length=8, max_length=256)
+    task_id: str = Field(min_length=3, max_length=63)
+    # Keep the execution target as an immutable occurrence snapshot.  Tasks can
+    # later be edited or deleted, but history/reconciliation must still know
+    # exactly which Agent revision accepted this occurrence.
+    target: ScheduledTaskTarget | None = None
+    scheduled_for: datetime
+    session_id: str = Field(min_length=1, max_length=256)
+    trigger: Literal["schedule", "manual"] = "schedule"
+    state: ScheduleOccurrenceState
+    attempt: int = Field(default=1, ge=1, le=100)
+    command_id: str | None = None
+    accepted_seq: int | None = Field(default=None, ge=0)
+    last_event_seq: int | None = Field(default=None, ge=0)
+    run_id: str | None = Field(default=None, min_length=1, max_length=256)
+    claimed_at: datetime | None = None
+    accepted_at: datetime | None = None
+    started_at: datetime | None = None
+    error_code: str | None = Field(default=None, max_length=128)
+    detail: str | None = Field(default=None, max_length=1024)
+    completed_at: datetime | None = None
+    transitions: tuple[ScheduleOccurrenceTransition, ...] = ()
+
+    @field_validator("scheduled_for", "claimed_at", "accepted_at", "started_at", "completed_at")
+    @classmethod
+    def normalize_timestamp(cls, value: datetime | None) -> datetime | None:
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError("occurrence timestamps must include a timezone")
+        return value.astimezone(timezone.utc)
+
+    @model_validator(mode="after")
+    def validate_terminal_fields(self) -> "ScheduleOccurrence":
+        terminal = {"succeeded", "failed", "skipped", "cancelled"}
+        if self.state in terminal and self.completed_at is None:
+            raise ValueError("terminal occurrence requires completedAt")
+        if self.state == "failed" and not self.error_code:
+            raise ValueError("failed occurrence requires errorCode")
+        if self.state == "running" and (not self.run_id or self.started_at is None):
+            raise ValueError("running occurrence requires runId and startedAt")
+        if self.transitions:
+            timestamps = [transition.at for transition in self.transitions]
+            if timestamps != sorted(timestamps):
+                raise ValueError("occurrence transitions must be chronological")
+            if self.transitions[-1].state != self.state:
+                raise ValueError("last occurrence transition must match state")
+        return self
+
+
+def _reject_clear_secrets(value: Any, *, key: str = "payload") -> None:
+    if isinstance(value, dict):
+        for name, item in value.items():
+            lowered = str(name).lower()
+            if any(term in lowered for term in ("secret", "password", "token", "api_key")):
+                if not isinstance(item, str) or not item.startswith(
+                    ("env://", "secret://", "credential://", "vault://")
+                ):
+                    raise ValueError(f"{key}.{name} must be a secret reference, not a value")
+            _reject_clear_secrets(item, key=f"{key}.{name}")
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _reject_clear_secrets(item, key=f"{key}[{index}]")
+
+
+def _parse_cron(expression: str) -> tuple[str, str, str, str, str]:
+    fields = tuple(part for part in expression.split() if part)
+    if len(fields) != 5:
+        raise ValueError("cron expression must use exactly five fields")
+    for value in fields:
+        if not re.fullmatch(r"[0-9*/,-]+", value):
+            raise ValueError("cron fields only support numbers, ranges, lists and steps")
+    return fields  # detailed field grammar is shared with calendar.py
+
+
+__all__ = [
+    "ScheduleCommandTemplate",
+    "ScheduleOccurrence",
+    "ScheduleOccurrenceState",
+    "ScheduleOccurrenceTransition",
+    "ScheduleSpec",
+    "ScheduledTask",
+    "ScheduledTaskTarget",
+]