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

ksadk/sessions/postgres_service.py

@@ -10,7 +10,14 @@ from typing import Any, Optional
 from urllib.parse import urlsplit, urlunsplit
 
 from ksadk.ids import new_session_id
+from ksadk.sessions._postgres_schema import _PostgresSchemaMixin
+from ksadk.sessions._postgres_tables import (
+    KSADK_PG_EVENTS_TABLE,
+    KSADK_PG_SESSIONS_TABLE,
+    KSADK_PG_STATES_TABLE,
+)
 from ksadk.sessions.base import (
+    CANONICAL_EVENT_STORAGE_CAPABILITIES,
     BaseSessionService,
     Session,
     SessionEvent,
@@ -19,15 +26,12 @@ from ksadk.sessions.base import (
 )
 from ksadk.sessions.errors import SessionBackendUnavailable
 
-KSADK_PG_SESSIONS_TABLE = "ksadk_sessions"
-KSADK_PG_EVENTS_TABLE = "ksadk_events"
-KSADK_PG_STATES_TABLE = "ksadk_states"
-PG_READABLE_EVENTS_VIEW = "ksadk_session_events_readable"
-
 logger = logging.getLogger(__name__)
 
 
-class PostgresSessionService(BaseSessionService):
+class PostgresSessionService(_PostgresSchemaMixin, BaseSessionService):
+    storage_capabilities = CANONICAL_EVENT_STORAGE_CAPABILITIES
+
     def __init__(
         self,
         *,
@@ -304,7 +308,9 @@ class PostgresSessionService(BaseSessionService):
                     seq_id=int(next_seq or 1),
                     invocation_id=event.invocation_id,
                     metadata=dict(event.metadata),
+                    seq_binding=event.seq_binding,
                 )
+                stored.bind_seq_id(int(next_seq or 1))
                 await connection.execute(
                     f"""
                     INSERT INTO {KSADK_PG_EVENTS_TABLE} (
@@ -349,6 +355,52 @@ class PostgresSessionService(BaseSessionService):
                 )
                 return stored
 
+    async def get_event_by_id(self, session_id: str, event_id: str) -> Optional[SessionEvent]:
+        await self._ensure_schema()
+        async with self._pool.acquire() as connection:
+            row = await connection.fetchrow(
+                f"""
+                SELECT id, session_id, author, event_type, content_json, timestamp,
+                       state_delta_json, seq_id, invocation_id, metadata_json
+                FROM {KSADK_PG_EVENTS_TABLE}
+                WHERE namespace = $1 AND session_id = $2 AND id = $3
+                """,
+                self.namespace,
+                session_id,
+                event_id,
+            )
+            return self._event_from_row(row) if row is not None else None
+
+    async def get_events_by_invocation_id(
+        self,
+        session_id: str,
+        invocation_id: str,
+        *,
+        after_seq_id: Optional[int] = None,
+        before_seq_id: Optional[int] = None,
+    ) -> list[SessionEvent]:
+        await self._ensure_schema()
+        conditions = ["namespace = $1", "session_id = $2", "invocation_id = $3"]
+        params: list[Any] = [self.namespace, session_id, invocation_id]
+        if after_seq_id is not None:
+            params.append(after_seq_id)
+            conditions.append(f"seq_id > ${len(params)}")
+        if before_seq_id is not None:
+            params.append(before_seq_id)
+            conditions.append(f"seq_id < ${len(params)}")
+        async with self._pool.acquire() as connection:
+            rows = await connection.fetch(
+                f"""
+                SELECT id, session_id, author, event_type, content_json, timestamp,
+                       state_delta_json, seq_id, invocation_id, metadata_json
+                FROM {KSADK_PG_EVENTS_TABLE}
+                WHERE {" AND ".join(conditions)}
+                ORDER BY seq_id ASC
+                """,
+                *params,
+            )
+            return [self._event_from_row(row) for row in rows]
+
     async def get_events(
         self,
         session_id: str,
@@ -687,148 +739,6 @@ class PostgresSessionService(BaseSessionService):
                     f"could not connect to {mask_postgres_session_dsn(self.dsn)}"
                 ) from exc
 
-    async def _ensure_schema(self) -> None:
-        if self._schema_ready:
-            return
-        async with self._schema_lock:
-            if self._schema_ready:
-                return
-            await self._ensure_pool()
-            async with self._pool.acquire() as connection:
-                await connection.execute(f"""
-                    CREATE TABLE IF NOT EXISTS {KSADK_PG_SESSIONS_TABLE} (
-                        namespace TEXT NOT NULL,
-                        tenant_id TEXT NOT NULL DEFAULT 'default',
-                        workspace_id TEXT NOT NULL DEFAULT 'default',
-                        id TEXT NOT NULL,
-                        agent_id TEXT NOT NULL,
-                        user_id TEXT NOT NULL,
-                        title TEXT NOT NULL DEFAULT '',
-                        title_source TEXT NOT NULL DEFAULT '',
-                        summary TEXT NOT NULL DEFAULT '',
-                        first_prompt TEXT NOT NULL DEFAULT '',
-                        last_prompt TEXT NOT NULL DEFAULT '',
-                        state_json JSONB NOT NULL DEFAULT '{{}}'::jsonb,
-                        created_at DOUBLE PRECISION NOT NULL,
-                        updated_at DOUBLE PRECISION NOT NULL,
-                        version INTEGER NOT NULL DEFAULT 0,
-                        PRIMARY KEY (namespace, id)
-                    );
-
-                    CREATE TABLE IF NOT EXISTS {KSADK_PG_EVENTS_TABLE} (
-                        namespace TEXT NOT NULL,
-                        tenant_id TEXT NOT NULL DEFAULT 'default',
-                        workspace_id TEXT NOT NULL DEFAULT 'default',
-                        id TEXT NOT NULL,
-                        session_id TEXT NOT NULL,
-                        author TEXT NOT NULL,
-                        event_type TEXT NOT NULL,
-                        content_json JSONB NOT NULL DEFAULT '{{}}'::jsonb,
-                        timestamp DOUBLE PRECISION NOT NULL,
-                        state_delta_json JSONB NOT NULL DEFAULT '{{}}'::jsonb,
-                        seq_id INTEGER NOT NULL,
-                        invocation_id TEXT,
-                        metadata_json JSONB NOT NULL DEFAULT '{{}}'::jsonb,
-                        PRIMARY KEY (namespace, id),
-                        UNIQUE (namespace, session_id, seq_id),
-                        FOREIGN KEY (namespace, session_id)
-                            REFERENCES {KSADK_PG_SESSIONS_TABLE}(namespace, id)
-                            ON DELETE CASCADE
-                    );
-
-                    CREATE INDEX IF NOT EXISTS idx_ksadk_pg_events_session_seq
-                    ON {KSADK_PG_EVENTS_TABLE} (namespace, session_id, seq_id);
-
-                    -- 跨会话事件查询（get_events_for_agent）需 JOIN sessions 按
-                    -- s.agent_id 过滤并按 e.timestamp 排序；events 表无 agent_id 列，
-                    -- 覆盖索引 (namespace, session_id, timestamp, id) 服务 JOIN 键
-                    -- s.id=e.session_id + ORDER BY e.timestamp DESC。
-                    CREATE INDEX IF NOT EXISTS idx_ksadk_pg_events_session_ts
-                    ON {KSADK_PG_EVENTS_TABLE} (namespace, session_id, timestamp, id);
-
-                    -- ListSessions 归并按 agent_id 过滤 + updated_at DESC 排序；
-                    -- sessions 表 PK 是 (namespace, id)，缺 agent_id 前缀索引。
-                    CREATE INDEX IF NOT EXISTS idx_ksadk_pg_sessions_agent_updated
-                    ON {KSADK_PG_SESSIONS_TABLE} (namespace, agent_id, updated_at DESC, id);
-
-                    CREATE TABLE IF NOT EXISTS {KSADK_PG_STATES_TABLE} (
-                        namespace TEXT NOT NULL,
-                        tenant_id TEXT NOT NULL DEFAULT 'default',
-                        workspace_id TEXT NOT NULL DEFAULT 'default',
-                        scope TEXT NOT NULL,
-                        agent_id TEXT NOT NULL,
-                        user_id TEXT NOT NULL DEFAULT '',
-                        session_id TEXT NOT NULL DEFAULT '',
-                        state_json JSONB NOT NULL DEFAULT '{{}}'::jsonb,
-                        version INTEGER NOT NULL DEFAULT 0,
-                        updated_at DOUBLE PRECISION NOT NULL,
-                        PRIMARY KEY (namespace, scope, agent_id, user_id, session_id)
-                    );
-
-                    ALTER TABLE {KSADK_PG_SESSIONS_TABLE}
-                    ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
-                    ALTER TABLE {KSADK_PG_SESSIONS_TABLE}
-                    ADD COLUMN IF NOT EXISTS workspace_id TEXT NOT NULL DEFAULT 'default';
-                    ALTER TABLE {KSADK_PG_EVENTS_TABLE}
-                    ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
-                    ALTER TABLE {KSADK_PG_EVENTS_TABLE}
-                    ADD COLUMN IF NOT EXISTS workspace_id TEXT NOT NULL DEFAULT 'default';
-                    ALTER TABLE {KSADK_PG_STATES_TABLE}
-                    ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
-                    ALTER TABLE {KSADK_PG_STATES_TABLE}
-                    ADD COLUMN IF NOT EXISTS workspace_id TEXT NOT NULL DEFAULT 'default';
-                    """)
-                try:
-                    await connection.execute(f"""
-                    CREATE OR REPLACE VIEW {PG_READABLE_EVENTS_VIEW} AS
-                    SELECT
-                        event_row.namespace,
-                        event_row.tenant_id,
-                        event_row.workspace_id,
-                        session_row.agent_id,
-                        session_row.user_id,
-                        session_row.title AS session_title,
-                        event_row.session_id,
-                        event_row.seq_id,
-                        event_row.id AS event_id,
-                        event_row.invocation_id,
-                        event_row.author,
-                        event_row.event_type,
-                        CASE
-                            WHEN event_row.event_type = 'user_message' THEN 'user'
-                            WHEN event_row.event_type IN (
-                                'assistant_message', 'reasoning', 'tool_call'
-                            ) THEN 'assistant'
-                            WHEN event_row.event_type = 'tool_result' THEN 'tool'
-                            ELSE NULL
-                        END AS message_role,
-                        COALESCE(
-                            NULLIF(event_row.content_json #>> '{{parts,0,text}}', ''),
-                            NULLIF(event_row.content_json ->> 'text', ''),
-                            NULLIF(event_row.metadata_json ->> 'reasoning', ''),
-                            NULLIF(event_row.metadata_json ->> 'tool_output', '')
-                        ) AS message_text,
-                        event_row.metadata_json ->> 'tool_name' AS tool_name,
-                        CASE
-                            WHEN event_row.event_type = 'run_status' THEN COALESCE(
-                                event_row.content_json ->> 'status',
-                                event_row.metadata_json ->> 'status'
-                            )
-                            ELSE NULL
-                        END AS lifecycle_status,
-                        to_timestamp(event_row.timestamp) AS created_at,
-                        event_row.content_json,
-                        event_row.state_delta_json,
-                        event_row.metadata_json
-                    FROM {KSADK_PG_EVENTS_TABLE} AS event_row
-                    JOIN {KSADK_PG_SESSIONS_TABLE} AS session_row
-                      ON session_row.namespace = event_row.namespace
-                     AND session_row.id = event_row.session_id;
-                        """)
-                except Exception as exc:
-                    logger.warning("Postgres readable session view unavailable: %s", exc)
-            self._schema_ready = True
-
     async def _get_session_with_connection(
         self,
         connection: Any,

ksadk/sessions/resilient.py

@@ -4,7 +4,12 @@ import asyncio
 import logging
 from typing import Any, Optional, cast
 
-from ksadk.sessions.base import BaseSessionService, Session, SessionEvent, SessionState
+from ksadk.sessions.base import (
+    BaseSessionService,
+    Session,
+    SessionEvent,
+    SessionState,
+)
 from ksadk.sessions.in_memory import InMemorySessionService
 from ksadk.sessions.resilience import is_session_backend_failure
 
@@ -40,6 +45,12 @@ class ResilientSessionService(BaseSessionService):
     def degraded(self) -> bool:
         return not self._primary_enabled
 
+    # This service is intentionally live-first and writes two independently
+    # sequenced stores.  Even when both children can atomically bind a local
+    # seq, the wrapper cannot guarantee one shared physical seq/fact across
+    # both writes, so it inherits BaseSessionService's empty canonical storage
+    # capabilities and RuntimeEventStore fails closed before either write.
+
     async def _call_primary(self, method_name: str, *args: Any, **kwargs: Any) -> tuple[bool, Any]:
         if not self._primary_enabled:
             return False, None
@@ -260,6 +271,29 @@ class ResilientSessionService(BaseSessionService):
         await self._call_primary("append_event", session_id, event)
         return live
 
+    async def get_event_by_id(self, session_id: str, event_id: str) -> Optional[SessionEvent]:
+        if await self.fallback.get_session_metadata(session_id) is None:
+            await self.get_session(session_id)
+        return await self.fallback.get_event_by_id(session_id, event_id)
+
+    async def get_events_by_invocation_id(
+        self,
+        session_id: str,
+        invocation_id: str,
+        *,
+        after_seq_id: Optional[int] = None,
+        before_seq_id: Optional[int] = None,
+    ) -> list[SessionEvent]:
+        # ResilientSessionService is explicitly live-first: hydrate any durable
+        # prefix, then read the indexed in-memory authority used by get_events.
+        await self.get_session(session_id)
+        return await self.fallback.get_events_by_invocation_id(
+            session_id,
+            invocation_id,
+            after_seq_id=after_seq_id,
+            before_seq_id=before_seq_id,
+        )
+
     async def get_events(
         self,
         session_id: str,

ksadk/skills/runtime/backends/e2b.py

@@ -77,7 +77,7 @@ class E2BSkillRuntimeBackend:
     @classmethod
     def from_env(cls) -> "E2BSkillRuntimeBackend":
         try:
-            from e2b import Sandbox  # type: ignore[import-untyped]
+            from e2b import Sandbox  # type: ignore[import-not-found, import-untyped]
         except ImportError as exc:
             raise SkillRuntimeError(
                 "e2b>=2.15.3,<2.25.0 is required for KSADK_SKILL_RUNTIME_BACKEND=e2b"

ksadk/skills/service_client.py

@@ -18,6 +18,12 @@ _KOP_HOSTS = frozenset(
         "aicp.api.ksyun.com",
     }
 )
+_PRIVATE_KOP_HOSTS = frozenset(
+    {
+        "aicp.inner.api.ksyun.com",
+        "aicp.internal.api.ksyun.com",
+    }
+)
 
 
 class SkillServiceClient:
@@ -215,14 +221,18 @@ class SkillServiceClient:
         return self._requests_session
 
     def _is_kop_mode(self) -> bool:
-        """Match only exact, TLS-protected AICP control-plane endpoints.
+        """Match only exact AICP control-plane endpoints.
 
         A user-controlled URL such as ``aicp.api.ksyun.com.attacker.example``
-        must never receive KOP signing headers.
+        must never receive KOP signing headers. Public AICP requires TLS; the
+        private ``inner`` and ``internal`` endpoints also support their existing
+        in-cluster HTTP transport.
         """
         parsed = urlsplit(self.base_url)
         host = (parsed.hostname or "").lower()
-        return parsed.scheme == "https" and host in _KOP_HOSTS
+        return host in _KOP_HOSTS and (
+            parsed.scheme == "https" or (parsed.scheme == "http" and host in _PRIVATE_KOP_HOSTS)
+        )
 
     def _kop_base_url(self) -> str:
         parsed = urlsplit(self.base_url)

ksadk/studio/__init__.py

@@ -0,0 +1,5 @@
+"""Local-first AgentKit Studio control plane."""
+
+from ksadk.studio.contracts import AgentDraft, AgentSpec
+
+__all__ = ["AgentDraft", "AgentSpec"]

ksadk/studio/agent_avatar_assets.py

@@ -0,0 +1,120 @@
+"""Validated, content-addressed assets for Studio Agent avatars."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import re
+import warnings
+from pathlib import Path
+
+from PIL import Image, UnidentifiedImageError
+
+from ksadk.studio.errors import StudioError, not_found
+from ksadk.studio.workspace import Workspace
+
+
+class AgentAvatarAssetStore:
+    MAX_BYTES = 2 * 1024 * 1024
+    MIN_EDGE = 32
+    MAX_EDGE = 2048
+    _ASSET_NAME = re.compile(r"^(?P<digest>[0-9a-f]{64})\.(?P<extension>png|webp)$")
+    _MIME_BY_FORMAT = {"PNG": "image/png", "WEBP": "image/webp"}
+    _EXTENSION_BY_FORMAT = {"PNG": "png", "WEBP": "webp"}
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.workspace = workspace
+
+    def store(self, content: bytes, *, content_type: str) -> dict:
+        if not content:
+            raise StudioError(
+                "AGENT_AVATAR_EMPTY",
+                "头像文件不能为空",
+                status_code=422,
+                field="file",
+            )
+        if len(content) > self.MAX_BYTES:
+            raise StudioError(
+                "AGENT_AVATAR_TOO_LARGE",
+                "头像文件不能超过 2 MiB",
+                status_code=413,
+                field="file",
+                details={"maxBytes": self.MAX_BYTES},
+            )
+        normalized_type = content_type.split(";", 1)[0].strip().lower()
+        if normalized_type not in self._MIME_BY_FORMAT.values():
+            raise StudioError(
+                "AGENT_AVATAR_TYPE_UNSUPPORTED",
+                "头像仅支持 PNG 或 WebP",
+                status_code=415,
+                field="file",
+            )
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("error", Image.DecompressionBombWarning)
+                with Image.open(io.BytesIO(content)) as image:
+                    image.load()
+                    image_format = str(image.format or "").upper()
+                    width, height = image.size
+        except (
+            UnidentifiedImageError,
+            OSError,
+            Image.DecompressionBombError,
+            Image.DecompressionBombWarning,
+        ) as exc:
+            raise StudioError(
+                "AGENT_AVATAR_INVALID",
+                "头像文件不是有效图片",
+                status_code=422,
+                field="file",
+            ) from exc
+
+        expected_type = self._MIME_BY_FORMAT.get(image_format)
+        if expected_type is None or expected_type != normalized_type:
+            raise StudioError(
+                "AGENT_AVATAR_TYPE_MISMATCH",
+                "头像内容与文件类型不一致",
+                status_code=422,
+                field="file",
+            )
+        if width != height:
+            raise StudioError(
+                "AGENT_AVATAR_NOT_SQUARE",
+                "头像必须裁剪为 1:1 正方形",
+                status_code=422,
+                field="file",
+                details={"width": width, "height": height},
+            )
+        if width < self.MIN_EDGE or width > self.MAX_EDGE:
+            raise StudioError(
+                "AGENT_AVATAR_DIMENSIONS_INVALID",
+                "头像边长必须在 32 到 2048 像素之间",
+                status_code=422,
+                field="file",
+                details={"width": width, "height": height},
+            )
+
+        digest = hashlib.sha256(content).hexdigest()
+        extension = self._EXTENSION_BY_FORMAT[image_format]
+        asset_name = f"{digest}.{extension}"
+        path = self.workspace.resolve(Path(".agentkit/assets/agent-avatars") / asset_name)
+        if not path.is_file():
+            self.workspace.atomic_write_bytes(path, content)
+        return {
+            "digest": digest,
+            "url": f"/api/v1/assets/agent-avatars/{asset_name}",
+            "mimeType": expected_type,
+            "size": len(content),
+            "width": width,
+            "height": height,
+        }
+
+    def get(self, asset_name: str) -> tuple[Path, str]:
+        match = self._ASSET_NAME.fullmatch(asset_name)
+        if match is None:
+            raise not_found("agent-avatar", asset_name)
+        extension = match.group("extension")
+        path = self.workspace.resolve(Path(".agentkit/assets/agent-avatars") / asset_name)
+        if not path.is_file():
+            raise not_found("agent-avatar", asset_name)
+        return path, "image/png" if extension == "png" else "image/webp"

ksadk/studio/agent_lifecycle.py

@@ -0,0 +1,51 @@
+"""Recoverable deletion for generic Studio Agents."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ksadk.studio.contracts import RunStatus
+from ksadk.studio.errors import StudioError
+
+
+def delete_framework_agent(studio: Any, agent_id: str, *, purge: bool) -> None:
+    studio.drafts.get(agent_id)
+    running = [
+        run.id
+        for run in studio.event_store.list_runs(agent_id=agent_id)
+        if run.status in {RunStatus.CREATED, RunStatus.RUNNING}
+    ]
+    if running:
+        raise StudioError(
+            "AGENT_RUN_ACTIVE",
+            "Agent 仍有运行中的任务，请等待运行结束后再删除",
+            status_code=409,
+            details={"agentId": agent_id, "runIds": running},
+        )
+    trash_directory = None
+    if not purge:
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+        trash_directory = studio.workspace.resolve(
+            Path(".agentkit/trash/agents") / f"{agent_id}-{timestamp}"
+        )
+        trash_directory.mkdir(parents=True, exist_ok=False)
+    studio.event_store.delete_agent(
+        agent_id,
+        purge=purge,
+        trash_directory=trash_directory,
+    )
+    studio.builds.delete_for_agent(
+        agent_id,
+        purge=purge,
+        trash_directory=trash_directory,
+    )
+    studio.drafts.delete(
+        agent_id,
+        purge=purge,
+        trash_directory=trash_directory,
+    )
+
+
+__all__ = ["delete_framework_agent"]