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

ksadk/resource_runtime/leases.py

@@ -0,0 +1,191 @@
+"""Ephemeral broker handles minted only by the trusted runtime host.
+
+This is not an upstream authorization database. The host must first verify
+admission, connection identity and Build permissions. Restart loses all handles.
+"""
+
+from __future__ import annotations
+
+import secrets
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from pydantic import model_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.contracts import Digest, Identifier, InvocationIdentity
+from ksadk.resource_runtime.ipc import ResourceOperation
+
+
+class ResourceScope(PluginContractModel):
+    profile_digest: Digest
+    generation_id: Identifier
+    activation_id: Identifier
+    build_digest: Digest
+    binding_snapshot_digest: Digest
+    identity: InvocationIdentity
+    binding_id: Identifier
+    allowed_operations: tuple[ResourceOperation, ...]
+
+    @model_validator(mode="after")
+    def unique_operations(self) -> ResourceScope:
+        if not self.allowed_operations or len(self.allowed_operations) != len(
+            set(self.allowed_operations)
+        ):
+            raise ValueError("Scope requires unique explicit operations")
+        return self
+
+
+@dataclass(frozen=True)
+class ResourceLease:
+    handle: str = field(repr=False)
+    scope: ResourceScope
+    expires_at: float
+
+
+class LeaseRejected(PermissionError):
+    def __init__(self):
+        super().__init__("RESOURCE_SCOPE_INVALID")
+
+
+class ResourceLeaseRegistry:
+    def __init__(self, *, clock: Callable[[], float] = time.monotonic, capacity: int = 4096):
+        if capacity < 1:
+            raise ValueError("Lease capacity must be positive")
+        self._clock = clock
+        self._capacity = capacity
+        self._leases: dict[str, ResourceLease] = {}
+        self._lock = threading.RLock()
+
+    def issue(self, scope: ResourceScope, *, lifetime: int = 600) -> ResourceLease:
+        """Host-only entry point; never expose scope issuance as an IPC operation."""
+        if type(lifetime) is not int or not 1 <= lifetime <= 600:
+            raise ValueError("Resource lease lifetime must be 1..600 seconds")
+        with self._lock:
+            now = self._clock()
+            self._leases = {
+                key: lease for key, lease in self._leases.items() if lease.expires_at > now
+            }
+            if len(self._leases) >= self._capacity:
+                raise RuntimeError("RESOURCE_LEASE_CAPACITY")
+            # Round-trip validates even models constructed with unchecked model_copy.
+            validated = ResourceScope.model_validate(scope.model_dump())
+            for existing in self._leases.values():
+                other = existing.scope
+                if other.activation_id == validated.activation_id and (
+                    other.identity != validated.identity
+                    or other.generation_id != validated.generation_id
+                    or other.build_digest != validated.build_digest
+                    or other.profile_digest != validated.profile_digest
+                    or other.binding_snapshot_digest != validated.binding_snapshot_digest
+                ):
+                    raise ValueError("An activation cannot change identity or frozen Build")
+            lease = ResourceLease(secrets.token_urlsafe(32), validated, now + lifetime)
+            self._leases[lease.handle] = lease
+            return lease
+
+    def authorize(
+        self, handle: str, *, operation: ResourceOperation, generation_id: str, activation_id: str
+    ) -> ResourceScope:
+        with self._lock:
+            lease = self._current(handle)
+            if (
+                lease.scope.generation_id != generation_id
+                or lease.scope.activation_id != activation_id
+                or operation not in lease.scope.allowed_operations
+            ):
+                raise LeaseRejected()
+            return lease.scope
+
+    def renew(self, handle: str, *, lifetime: int = 600) -> ResourceLease:
+        """Host revalidates upstream authorization first; renewal cannot widen scope.
+
+        Renewal rotates the opaque handle and invalidates the previous handle.
+        Both actions are atomic relative to dispatch authorization and revocation.
+        """
+        return self.renew_many((handle,), lifetime=lifetime)[0]
+
+    def renew_many(
+        self, handles: tuple[str, ...], *, lifetime: int = 600
+    ) -> tuple[ResourceLease, ...]:
+        """Rotate one activation's handles atomically, after host revalidation."""
+        with self._lock:
+            if not handles or len(handles) != len(set(handles)):
+                raise ValueError("Renewal requires unique existing handles")
+            if type(lifetime) is not int or not 1 <= lifetime <= 600:
+                raise ValueError("Resource lease lifetime must be 1..600 seconds")
+            leases = tuple(self._current(handle) for handle in handles)
+            if len({lease.scope.activation_id for lease in leases}) != 1:
+                raise ValueError("Renewal cannot mix activations")
+            now = self._clock()
+            if any(lease.expires_at <= now for lease in leases):
+                raise LeaseRejected()
+            renewed = tuple(
+                ResourceLease(secrets.token_urlsafe(32), lease.scope, now + lifetime)
+                for lease in leases
+            )
+            for handle in handles:
+                del self._leases[handle]
+            self._leases.update({lease.handle: lease for lease in renewed})
+            return renewed
+
+    def resolve(
+        self, handle: str, *, operation: ResourceOperation, generation_id: str
+    ) -> ResourceScope:
+        """Resolve caller identity from the opaque handle, not request arguments."""
+        with self._lock:
+            scope = self._current(handle).scope
+            if scope.generation_id != generation_id or operation not in scope.allowed_operations:
+                raise LeaseRejected()
+            return scope
+
+    def revoke_activation(self, activation_id: str) -> None:
+        with self._lock:
+            self._leases = {
+                key: lease
+                for key, lease in self._leases.items()
+                if lease.scope.activation_id != activation_id
+            }
+
+    def remaining_lifetime(self, handles: tuple[str, ...]) -> float:
+        """Observe the longest current lease for lifecycle cleanup, without renewal.
+
+        Missing/revoked/expired handles contribute zero. Uses the issuance clock
+        so a supervisor does not compare monotonic deadlines with wall time.
+        This is not an authorization check for an operation.
+        """
+        with self._lock:
+            now = self._clock()
+            return max(0.0, max((
+                self._leases[handle].expires_at - now
+                for handle in handles if handle in self._leases
+            ), default=0.0))
+
+    def revoke_binding(self, activation_id: str, binding_id: str) -> None:
+        """Revoke one upstream resource without disabling unrelated bindings."""
+        with self._lock:
+            self._leases = {
+                key: lease
+                for key, lease in self._leases.items()
+                if (lease.scope.activation_id, lease.scope.binding_id)
+                != (activation_id, binding_id)
+            }
+
+    def revoke_generation(self, generation_id: str) -> None:
+        with self._lock:
+            self._leases = {
+                key: lease
+                for key, lease in self._leases.items()
+                if lease.scope.generation_id != generation_id
+            }
+
+    def _current(self, handle: str) -> ResourceLease:
+        lease = self._leases.get(handle)
+        if lease is None:
+            raise LeaseRejected()
+        if lease.expires_at <= self._clock():
+            del self._leases[handle]
+            raise LeaseRejected()
+        return lease

ksadk/resource_runtime/managed_projection.py

@@ -0,0 +1,186 @@
+"""Project frozen platform-resource bindings into a managed-runtime MCP server.
+
+The projection is provider-neutral: a managed Agent keeps the resource declarations
+in its immutable manifest and receives one local MCP connector. Credentials remain
+workload environment variables and never enter the manifest or artifact.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from typing import Any
+
+from ksadk.resource_runtime.contracts import ResourceConfig, validate_resource_bindings
+from ksadk.resource_runtime.plugin_config import resource_plugin_config
+
+_SERVER_NAME = "platform-resources"
+_CREDENTIAL_ENV_NAMES = (
+    "KSYUN_ACCESS_KEY",
+    "KSYUN_SECRET_KEY",
+    "KSYUN_SESSION_TOKEN",
+    "KSYUN_ACCESS_KEY_ID",
+    "KSYUN_SECRET_ACCESS_KEY",
+)
+
+
+def native_codex_plugin_bindings(manifest: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Return enabled native Codex bindings, excluding DSH resource declarations."""
+
+    bindings: list[dict[str, Any]] = []
+    raw = manifest.get("plugins") or []
+    if not isinstance(raw, (list, tuple)):
+        return bindings
+    for item in raw:
+        if not isinstance(item, Mapping) or not item.get("enabled", True):
+            continue
+        if str(item.get("ecosystem") or "").strip().lower() == "codex":
+            bindings.append(dict(item))
+    return bindings
+
+
+def _resource_configs(manifest: Mapping[str, Any]) -> tuple[ResourceConfig, ...]:
+    resources: list[ResourceConfig] = []
+    raw = manifest.get("plugins") or []
+    if not isinstance(raw, (list, tuple)):
+        return ()
+    for item in raw:
+        if not isinstance(item, Mapping) or not item.get("enabled", True):
+            continue
+        parsed = resource_plugin_config(
+            str(item.get("plugin_ref") or item.get("pluginRef") or ""),
+            str(item.get("ecosystem") or ""),
+            item.get("config") if isinstance(item.get("config"), Mapping) else {},
+            enabled=True,
+        )
+        if parsed is not None:
+            resources.append(parsed)
+    validate_resource_bindings(tuple(resources))
+    return tuple(resources)
+
+
+def _memory_write_enabled(
+    manifest: Mapping[str, Any], resources: tuple[ResourceConfig, ...]
+) -> bool:
+    memory_configs = [item for item in resources if item.binding.resource.kind == "memory-instance"]
+    if not memory_configs:
+        return False
+    memory = manifest.get("memory")
+    context = manifest.get("context")
+    if not isinstance(memory, Mapping) or not bool(memory.get("enabled")):
+        return False
+    if str(memory.get("providerRef") or memory.get("provider_ref") or "") != (
+        "binding://" + memory_configs[0].binding.id
+    ):
+        return False
+    write = memory.get("write")
+    rollout = context.get("rollout") if isinstance(context, Mapping) else None
+    mode = str(write.get("mode") or "off") if isinstance(write, Mapping) else "off"
+    rollout_mode = (
+        str(rollout.get("memoryWrite") or rollout.get("memory_write") or "off")
+        if isinstance(rollout, Mapping)
+        else "off"
+    )
+    return mode in {"explicit_only", "candidate"} and rollout_mode == "enabled"
+
+
+def project_managed_platform_resources(
+    manifest: Mapping[str, Any],
+    *,
+    process_env: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Return runtime config additions for official platform resources."""
+
+    resources = _resource_configs(manifest)
+    if not resources:
+        return {}
+    source_env = process_env if process_env is not None else os.environ
+    projected_env: dict[str, str] = {
+        "KSADK_AICP_ENDPOINT_MODE": "inner",
+        "KSADK_PLATFORM_RESOURCE_KINDS": ",".join(
+            sorted(item.binding.resource.kind for item in resources)
+        ),
+        "KSADK_PLATFORM_RESOURCE_AGENT_ID": str(
+            source_env.get("AGENTENGINE_PLUGIN_AGENT_ID")
+            or source_env.get("AGENTENGINE_RESOURCE_AGENT_ID")
+            or manifest.get("name")
+            or "managed-agent"
+        ),
+        "KSADK_PLATFORM_RESOURCE_SUBJECT": str(
+            source_env.get("AGENTENGINE_RESOURCE_ACTOR_REF")
+            or source_env.get("AGENTENGINE_PLUGIN_AGENT_ID")
+            or manifest.get("name")
+            or "managed-agent"
+        ),
+        "KSADK_PLATFORM_RESOURCE_MEMORY_WRITE": (
+            "true" if _memory_write_enabled(manifest, resources) else "false"
+        ),
+    }
+    for item in resources:
+        resource = item.binding.resource
+        if resource.kind == "memory-instance":
+            projected_env.update(
+                {
+                    "KSADK_LTM_BACKEND": "sdk",
+                    "KSADK_LTM_NAMESPACE": resource.id,
+                    "KSADK_LTM_REGION": resource.region,
+                    "KSADK_LTM_AGENT_ID": projected_env["KSADK_PLATFORM_RESOURCE_AGENT_ID"],
+                }
+            )
+        elif resource.kind == "knowledge-base":
+            policy = item.retrieval
+            projected_env.update(
+                {
+                    "KSADK_KB_DATASET_ID": resource.id,
+                    "KSADK_KB_REGION": resource.region,
+                    "KSADK_KB_TOP_K": str(policy.top_k if policy is not None else 5),
+                }
+            )
+        elif resource.kind == "skill-space":
+            projected_env.update(
+                {
+                    "KSADK_SKILL_SPACE_IDS": resource.id,
+                    "KSADK_SKILL_SERVICE_REGION": resource.region,
+                }
+            )
+            if item.include_public:
+                projected_env["KSADK_PUBLIC_SKILL_SPACE_IDS"] = "public"
+
+    env_refs = {name: name for name in (*projected_env, *_CREDENTIAL_ENV_NAMES)}
+    return {
+        "env": projected_env,
+        "mcp_server": {
+            "name": _SERVER_NAME,
+            "transport": "stdio",
+            "command": sys.executable,
+            "args": ["-m", "ksadk.resource_runtime.mcp_server"],
+            "env_refs": env_refs,
+        },
+    }
+
+
+def apply_managed_platform_resources(config: dict[str, Any]) -> dict[str, Any]:
+    """Apply projection without overwriting user MCP or environment values."""
+
+    projected = project_managed_platform_resources(config)
+    if not projected:
+        return config
+    servers = list(config.get("mcp_servers") or [])
+    if any(isinstance(item, Mapping) and item.get("name") == _SERVER_NAME for item in servers):
+        raise ValueError("mcp server name 'platform-resources' is reserved")
+    servers.append(projected["mcp_server"])
+    env = dict(config.get("env") or {})
+    if set(env).intersection(projected["env"]):
+        raise ValueError("managed platform-resource environment is reserved")
+    env.update(projected["env"])
+    config["mcp_servers"] = servers
+    config["env"] = env
+    return config
+
+
+__all__ = [
+    "apply_managed_platform_resources",
+    "native_codex_plugin_bindings",
+    "project_managed_platform_resources",
+]

ksadk/resource_runtime/mcp_server.py

@@ -0,0 +1,138 @@
+"""Private stdio MCP adapter for frozen managed-runtime platform resources."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import asdict
+from uuid import uuid4
+
+from mcp.server.fastmcp import FastMCP
+
+
+def _enabled(kind: str) -> bool:
+    return kind in {
+        item.strip()
+        for item in os.environ.get("KSADK_PLATFORM_RESOURCE_KINDS", "").split(",")
+        if item.strip()
+    }
+
+
+def _subject() -> str:
+    value = os.environ.get("KSADK_PLATFORM_RESOURCE_SUBJECT", "").strip()
+    if not value or any(character.isspace() for character in value):
+        raise ValueError("trusted platform-resource subject is unavailable")
+    return value
+
+
+def create_server() -> FastMCP:
+    server = FastMCP("KsADK Platform Resources")
+
+    if _enabled("memory-instance"):
+        from ksadk.memory.service import LongTermMemoryService, format_memory_entries
+
+        @server.tool()
+        def load_memory(query: str, top_k: int = 5) -> dict:
+            """Search the Agent's bound long-term memory for relevant user facts."""
+
+            service = LongTermMemoryService.from_env()
+            entries = service.search_entries(user_id=_subject(), query=query, top_k=top_k)
+            if service.last_error:
+                return {"ok": False, "error": service.last_error, "items": []}
+            return {
+                "ok": True,
+                "items": entries,
+                "formatted_text": format_memory_entries(entries),
+            }
+
+        if os.environ.get("KSADK_PLATFORM_RESOURCE_MEMORY_WRITE", "").lower() == "true":
+
+            @server.tool()
+            def save_memory(content: str) -> dict:
+                """Persist one explicit, self-contained user fact in bound long-term memory."""
+
+                service = LongTermMemoryService.from_env()
+                session_id = "mcp-" + uuid4().hex
+                ok = service.save_text(
+                    user_id=_subject(),
+                    content=content,
+                    metadata={
+                        "agent_id": os.environ.get("KSADK_PLATFORM_RESOURCE_AGENT_ID", ""),
+                        "session_id": session_id,
+                        "runner_type": "managed-runtime-mcp",
+                        "flush": True,
+                    },
+                    session_id=session_id,
+                    flush=True,
+                )
+                if not ok:
+                    return {
+                        "ok": False,
+                        "status": "failed",
+                        "error": service.last_error or "memory write was not acknowledged",
+                    }
+                status = None
+                for attempt in range(6):
+                    status = service.get_extraction_status(
+                        user_id=_subject(),
+                        session_id=session_id,
+                        confirm_searchable=True,
+                        expected_content=content,
+                    )
+                    if status.status in {"extracted", "duplicate_skipped", "failed"}:
+                        break
+                    if attempt < 5:
+                        time.sleep(1)
+                return {
+                    "ok": status is not None and status.status != "failed",
+                    "status": status.status if status is not None else "accepted_not_extracted",
+                    "searchable": bool(status and status.searchable),
+                    "session_id": session_id,
+                }
+
+            @server.tool()
+            def memory_status(session_id: str, expected_content: str = "") -> dict:
+                """Check extraction and search visibility for a prior explicit memory write."""
+
+                service = LongTermMemoryService.from_env()
+                status = service.get_extraction_status(
+                    user_id=_subject(),
+                    session_id=session_id,
+                    confirm_searchable=bool(expected_content.strip()),
+                    expected_content=expected_content,
+                )
+                return {"ok": not status.error_code, **asdict(status)}
+
+    if _enabled("knowledge-base"):
+        from ksadk.knowledge_base.service import KnowledgeBaseService
+
+        @server.tool()
+        def search_knowledge_base(query: str, top_k: int = 5) -> dict:
+            """Search the Agent's bound knowledge base."""
+
+            service = KnowledgeBaseService.from_env()
+            results = service.search(query, top_k)
+            if service.last_error:
+                return {"ok": False, "error": service.last_error, "items": []}
+            return {"ok": True, "items": [item.model_dump() for item in results]}
+
+    if _enabled("skill-space"):
+        from ksadk.toolsets.skills import list_skill_spaces, list_skills, load_skill, search_skills
+
+        server.tool()(list_skill_spaces)
+        server.tool()(list_skills)
+        server.tool()(search_skills)
+        server.tool()(load_skill)
+
+    return server
+
+
+def main() -> None:
+    create_server().run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()
+
+
+__all__ = ["create_server", "main"]