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

ksadk/resource_runtime/ipc.py

@@ -0,0 +1,142 @@
+"""Bounded resource IPC framing shared by broker and worker pipes.
+
+Transport owners enforce deadlines and connection permissions. No pickle,
+reflection, imports or executable payloads are accepted by this protocol.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import struct
+from typing import BinaryIO, Literal
+
+from pydantic import Field, field_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.contracts import Identifier
+
+MAX_FRAME_BYTES = 1024 * 1024
+ResourceOperation = Literal[
+    "search_knowledge_base",
+    "load_memory",
+    "save_memory",
+    "update_memory",
+    "delete_memory",
+    "memory_status",
+    "list_skill_spaces",
+    "list_skills",
+    "search_skills",
+    "load_skill",
+    "read_skill_resource",
+    "execute_skills",
+    "read_skill_artifact",
+]
+
+
+class ResourceRequest(PluginContractModel):
+    v: Literal[1]
+    request_id: Identifier
+    deadline: int = Field(strict=True, gt=0, description="Absolute Unix time in milliseconds")
+    operation: ResourceOperation
+    handle: str = Field(strict=True, min_length=32, max_length=256, repr=False)
+    arguments: dict = Field(default_factory=dict)
+    check_only: bool = Field(default=False, strict=True)
+
+    @field_validator("v", mode="before")
+    @classmethod
+    def strict_version(cls, value: object) -> object:
+        if type(value) is not int:
+            raise ValueError("IPC version must be an integer")
+        return value
+
+
+class FrameError(ValueError):
+    """Public message is fixed and never includes frame contents."""
+
+
+def _unique_object(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise FrameError("Duplicate IPC object field")
+        result[key] = value
+    return result
+
+
+def _reject_constant(_: str) -> None:
+    raise FrameError("Non-finite IPC number")
+
+
+def _finite_float(value: str) -> float:
+    parsed = float(value)
+    if not math.isfinite(parsed):
+        raise FrameError("Non-finite IPC number")
+    return parsed
+
+
+def encode_frame(payload: dict) -> bytes:
+    if not isinstance(payload, dict):
+        raise FrameError("IPC frame must contain an object")
+    try:
+        body = json.dumps(
+            payload, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+        ).encode("utf-8")
+    except (ValueError, TypeError, RecursionError, UnicodeError):
+        raise FrameError("Invalid IPC object") from None
+    if len(body) > MAX_FRAME_BYTES:
+        raise FrameError("IPC frame exceeds size limit")
+    return struct.pack("!I", len(body)) + body
+
+
+def decode_body(body: bytes) -> dict:
+    if not 0 < len(body) <= MAX_FRAME_BYTES:
+        raise FrameError("Invalid IPC frame length")
+    try:
+        payload = json.loads(
+            body.decode("utf-8"),
+            object_pairs_hook=_unique_object,
+            parse_constant=_reject_constant,
+            parse_float=_finite_float,
+        )
+    except FrameError:
+        raise
+    except (ValueError, UnicodeError, RecursionError):
+        raise FrameError("Invalid IPC JSON") from None
+    if not isinstance(payload, dict):
+        raise FrameError("IPC frame must contain an object")
+    return payload
+
+
+def _read_exact(stream: BinaryIO, size: int, *, clean_eof: bool = False) -> bytes | None:
+    chunks = bytearray()
+    while len(chunks) < size:
+        chunk = stream.read(size - len(chunks))
+        if not chunk:
+            if clean_eof and not chunks:
+                return None
+            raise FrameError("Truncated IPC frame")
+        chunks.extend(chunk)
+    return bytes(chunks)
+
+
+def read_frame(stream: BinaryIO) -> dict | None:
+    prefix = _read_exact(stream, 4, clean_eof=True)
+    if prefix is None:
+        return None
+    (size,) = struct.unpack("!I", prefix)
+    if not 0 < size <= MAX_FRAME_BYTES:
+        raise FrameError("Invalid IPC frame length")
+    body = _read_exact(stream, size)
+    assert body is not None
+    return decode_body(body)
+
+
+def write_frame(stream: BinaryIO, payload: dict) -> None:
+    frame = memoryview(encode_frame(payload))
+    while frame:
+        written = stream.write(frame)
+        if written is None or written <= 0:
+            raise FrameError("IPC transport write failed")
+        frame = frame[written:]
+    stream.flush()

ksadk/resource_runtime/kernel_approval.py

@@ -0,0 +1,165 @@
+"""Resource write authorization from the existing local Kernel interaction ledger."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+from ksadk.interaction.contracts import InteractionPresentation, InteractionRecord
+from ksadk.kernel.contracts import ActivationWriteGuard
+from ksadk.kernel.sqlite_store import SQLiteAgentKernelStore
+from ksadk.resource_runtime.ipc import ResourceRequest
+from ksadk.resource_runtime.leases import ResourceScope
+from ksadk.resource_runtime.memory_provider import MemoryRecordSelector, MemoryUpdate, MemoryWrite
+from ksadk.resource_runtime.skills import SkillExecutionQuery
+
+
+def approval_metadata(request: ResourceRequest, scope: ResourceScope, event_id: str) -> dict:
+    """Host-only metadata for an InteractionRecord, before presenting approval.
+
+    No body or credentials are persisted here. Activation/transport IDs may change
+    on recovery; the bound identity, Build, operation and exact arguments may not.
+    """
+    payload = {
+        "identity": scope.identity.model_dump(mode="json"),
+        "build": scope.build_digest,
+        "binding": scope.binding_id,
+        "snapshot": scope.binding_snapshot_digest,
+        "operation": request.operation,
+        "arguments": request.arguments,
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()
+    ).hexdigest()
+    return {"resourceApproval": {"version": 1, "eventId": event_id, "requestDigest": digest}}
+
+
+class KernelResourceWriteAuthorizer:
+    """Use the existing Kernel ledger; decisions remain owned by its ingress.
+
+    resolve_interaction maps a trusted runtime tool event to its interaction ID.
+    Never implement that mapping from model arguments or browser approval flags.
+    PostgreSQL/remote hosts need an equivalent committed-receipt adapter.
+    """
+
+    def __init__(
+        self,
+        store: SQLiteAgentKernelStore,
+        *,
+        run_id: str,
+        resolve_interaction: Callable[[ResourceRequest, ResourceScope], str | None],
+    ):
+        self.store = store
+        self.run_id = run_id
+        self.resolve_interaction = resolve_interaction
+
+    async def request_memory_approval(
+        self,
+        request: ResourceRequest,
+        scope: ResourceScope,
+        *,
+        interaction_id: str,
+        event_id: str,
+        guard: ActivationWriteGuard,
+    ) -> InteractionRecord:
+        if request.operation != "save_memory":
+            raise ValueError("RESOURCE_SCOPE_DENIED")
+        return await self.request_write_approval(
+            request,
+            scope,
+            interaction_id=interaction_id,
+            event_id=event_id,
+            guard=guard,
+        )
+
+    async def request_write_approval(
+        self,
+        request: ResourceRequest,
+        scope: ResourceScope,
+        *,
+        interaction_id: str,
+        event_id: str,
+        guard: ActivationWriteGuard,
+    ) -> InteractionRecord:
+        """Host-only creation, fenced by the existing Kernel activation lease.
+
+        Presentation contains the proposed operation so users can review the actual
+        write. It follows the host's existing interaction/transcript retention.
+        This method cannot submit an approval decision or execute a write.
+        """
+        scope = ResourceScope.model_validate(scope.model_dump())
+        request = ResourceRequest.model_validate_json(request.model_dump_json())
+        if request.operation not in scope.allowed_operations:
+            raise ValueError("RESOURCE_SCOPE_DENIED")
+        if request.operation == "save_memory":
+            content = MemoryWrite.model_validate(request.arguments).content
+            title = "保存长期记忆"
+        elif request.operation == "update_memory":
+            update = MemoryUpdate.model_validate(request.arguments)
+            if not update.content.strip():
+                raise ValueError("RESOURCE_APPROVAL_REQUEST_INVALID")
+            content = update.memory_id + "\n\n" + update.content
+            title = "更新长期记忆"
+        elif request.operation == "delete_memory":
+            content = MemoryRecordSelector.model_validate(request.arguments).memory_id
+            title = "删除长期记忆（软删除）"
+        elif request.operation == "execute_skills":
+            execution = SkillExecutionQuery.model_validate(request.arguments)
+            if not execution.workflow_prompt.strip():
+                raise ValueError("RESOURCE_APPROVAL_REQUEST_INVALID")
+            content = ", ".join(execution.skill_ids) + "\n\n" + execution.workflow_prompt
+            title = "执行锁定 Skill"
+        else:
+            raise ValueError("RESOURCE_APPROVAL_OPERATION_UNSUPPORTED")
+        if not content.strip() or not isinstance(event_id, str) or not 0 < len(event_id) <= 1024:
+            raise ValueError("RESOURCE_APPROVAL_REQUEST_INVALID")
+        record = InteractionRecord(
+            interaction_id=interaction_id,
+            tenant_id=scope.identity.tenant_ref,
+            agent_instance_id=scope.identity.agent_id,
+            session_id=scope.identity.session_ref,
+            run_id=self.run_id,
+            kind="approval",
+            request_schema={"type": "object", "properties": {}, "additionalProperties": False},
+            created_at=datetime.now(timezone.utc).isoformat(),
+            provider_id="platform-resources",
+            presentation=InteractionPresentation(
+                title=title,
+                description=content,
+            ),
+            continuation_metadata=approval_metadata(request, scope, event_id),
+        )
+        return await self.store.request(record, guard=guard)
+
+    async def authorize(self, request: ResourceRequest, scope: ResourceScope) -> str | None:
+        interaction_id = self.resolve_interaction(request, scope)
+        if not interaction_id:
+            return None
+        lookup = {
+            "tenant_id": scope.identity.tenant_ref,
+            "agent_instance_id": scope.identity.agent_id,
+            "session_id": scope.identity.session_ref,
+            "run_id": self.run_id,
+        }
+        record = await self.store.get(interaction_id, **lookup)
+        if record is None or record.kind != "approval" or record.status != "resolved":
+            return None
+        receipt = await self.store.get_terminal_receipt(interaction_id, **lookup)
+        if (
+            receipt is None
+            or receipt.outcome != "approved"
+            or receipt.revision != record.revision
+            or not receipt.event_id
+        ):
+            return None
+        metadata = (record.continuation_metadata or {}).get("resourceApproval")
+        if not isinstance(metadata, dict):
+            return None
+        event_id = metadata.get("eventId")
+        if not isinstance(event_id, str) or not 0 < len(event_id) <= 1024:
+            return None
+        if metadata != approval_metadata(request, scope, event_id)["resourceApproval"]:
+            return None
+        return event_id

ksadk/resource_runtime/knowledge.py

@@ -0,0 +1,114 @@
+"""Bound knowledge retrieval, owned by one resource worker activation."""
+
+from __future__ import annotations
+
+from threading import Lock
+from typing import Literal
+
+from pydantic import Field
+
+from ksadk.knowledge_base.client import KnowledgeBaseClient
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.contracts import ResourceConfig, RetrievalPolicy
+
+
+class KnowledgeQuery(PluginContractModel):
+    query: str = Field(strict=True, min_length=1, max_length=16000)
+    top_k: int | None = Field(default=None, strict=True, ge=1)
+
+
+class KnowledgeItem(PluginContractModel):
+    document_id: str = Field(max_length=4096)
+    document_name: str = Field(max_length=4096)
+    segment_id: str = Field(max_length=4096)
+    content: str
+    score: float = Field(allow_inf_nan=False)
+
+
+class KnowledgeReply(PluginContractModel):
+    status: Literal["ok", "empty", "failed"]
+    binding_id: str
+    items: tuple[KnowledgeItem, ...] = ()
+    truncated: bool = False
+    request_id: str = Field(default="", max_length=256)
+    error_code: Literal["KNOWLEDGE_RETRIEVAL_FAILED", "RESOURCE_FORBIDDEN"] | None = None
+
+    def text(self) -> str:
+        if self.status == "failed":
+            return "Knowledge retrieval failed."
+        if self.status == "empty":
+            return "No matching knowledge found."
+        return "\n\n".join(
+            f"[{item.document_name or item.document_id}] {item.content}" for item in self.items
+        )
+
+
+class BoundKnowledgeService:
+    """The worker owns this service and its client exclusively.
+
+    The lock includes both the blocking SDK call and copying its mutable
+    last_* fields. IPC concurrency must not interleave those two steps.
+    Identity/lease authorization occurs in the broker before this service.
+    """
+
+    def __init__(self, config: ResourceConfig, client: KnowledgeBaseClient):
+        resource = config.binding.resource
+        if resource.kind != "knowledge-base":
+            raise ValueError("Knowledge service requires a knowledge-base binding")
+        if client.dataset_id != resource.id or client.region != resource.region:
+            raise ValueError("Knowledge client does not match its frozen binding")
+        self._config = config
+        self._client = client
+        self._lock = Lock()
+
+    def search(self, arguments: dict) -> KnowledgeReply:
+        query = KnowledgeQuery.model_validate(arguments)
+        policy = self._config.retrieval or RetrievalPolicy()
+        top_k = min(query.top_k if query.top_k is not None else policy.top_k, policy.top_k)
+        with self._lock:
+            try:
+                records = self._client.search(query.query, top_k=top_k)
+                if self._client.last_error:
+                    return self._failed()
+                budget = policy.max_chars
+                items = []
+                truncated = len(records) > top_k
+                for record in records[:top_k]:
+                    if budget == 0:
+                        truncated = True
+                        break
+                    content = record.content[:budget]
+                    truncated = truncated or len(content) < len(record.content)
+                    budget -= len(content)
+                    items.append(
+                        KnowledgeItem(
+                            document_id=record.document_id,
+                            document_name=record.document_name,
+                            segment_id=record.segment_id,
+                            content=content,
+                            score=record.score,
+                        )
+                    )
+                return KnowledgeReply(
+                    status="ok" if records else "empty",
+                    binding_id=self._config.binding.id,
+                    items=tuple(items),
+                    truncated=truncated,
+                    request_id=self._client.last_request_id,
+                )
+            except Exception:
+                # Raw upstream exceptions may include credentials, signed URLs or
+                # knowledge text. Only the fixed public failure code crosses IPC.
+                return self._failed()
+
+    def _failed(self) -> KnowledgeReply:
+        return KnowledgeReply(
+            status="failed",
+            binding_id=self._config.binding.id,
+            request_id=self._client.last_request_id,
+            error_code=(
+                "RESOURCE_FORBIDDEN"
+                if self._client.last_http_status in {401, 403}
+                else "KNOWLEDGE_RETRIEVAL_FAILED"
+            ),
+        )

ksadk/resource_runtime/langgraph.py

@@ -0,0 +1,94 @@
+"""Explicit LangGraph tools backed by the existing Core's scoped MCP endpoint.
+
+The trusted runner supplies admitted leases and owns this async context for the
+whole graph invocation. Never put the connector, leases or session in graph
+state/checkpoints. This does not mutate compiled graphs or supply memory hooks.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+
+import httpx
+from langchain_core.tools import BaseTool, StructuredTool, ToolException
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+from ksadk.plugins.providers.dsh_capabilities import DshMcpConnectorLease
+from ksadk.resource_runtime.leases import ResourceLease
+
+
+@asynccontextmanager
+async def create_bound_resource_tools(
+    connector: DshMcpConnectorLease,
+    leases: Sequence[ResourceLease],
+    *,
+    tool_aliases: Mapping[str, str],
+) -> AsyncIterator[tuple[BaseTool, ...]]:
+    """Open scoped tools for explicit graph factory/ToolNode/model.bind_tools use.
+
+    Uses the installed MCP SDK transport and LangChain tool contract. Closing the
+    context invalidates escaped tools. Renewal requires reopening at a safe graph
+    boundary with fresh host-issued leases; this helper cannot grant permissions.
+    Writes still require the broker's host approval/event authorizer.
+    """
+    aliases = dict(tool_aliases)
+    token = connector.resource_bearer_token(aliases, leases)
+    opened = False
+    async with httpx.AsyncClient(
+        headers={"Authorization": "Bearer " + token},
+        trust_env=False,
+        follow_redirects=False,
+        timeout=httpx.Timeout(60, connect=10),
+    ) as client:
+        async with streamable_http_client(connector.endpoint, http_client=client) as streams:
+            async with ClientSession(streams[0], streams[1]) as session:
+                await session.initialize()
+                inventory = await session.list_tools()
+                by_name = {tool.name: tool for tool in inventory.tools}
+                if (
+                    inventory.nextCursor
+                    or len(by_name) != len(inventory.tools)
+                    or set(by_name) != set(aliases)
+                ):
+                    raise RuntimeError("RESOURCE_TOOL_INVENTORY_MISMATCH")
+                opened = True
+                tools = []
+
+                def make_tool(name):
+                    descriptor = by_name[name]
+
+                    async def invoke(**arguments):
+                        if not opened:
+                            raise ToolException("RESOURCE_SESSION_CLOSED")
+                        try:
+                            result = await session.call_tool(name, arguments)
+                        except Exception:
+                            raise ToolException("RESOURCE_MCP_CALL_FAILED") from None
+                        payload = result.model_dump(mode="json", by_alias=True, exclude_none=True)
+                        if result.isError:
+                            # Preserve structured diagnostics and tell ToolNode the
+                            # call failed. Never return a failed business call as success.
+                            raise ToolException(json.dumps(payload, ensure_ascii=False))
+                        content = "\n".join(
+                            item.text for item in result.content if item.type == "text"
+                        )
+                        return content, payload
+
+                    return StructuredTool.from_function(
+                        coroutine=invoke,
+                        name=name,
+                        description=descriptor.description or name,
+                        args_schema=descriptor.inputSchema,
+                        infer_schema=False,
+                        response_format="content_and_artifact",
+                        handle_tool_error=True,
+                    )
+
+                try:
+                    for name in aliases:
+                        tools.append(make_tool(name))
+                    yield tuple(tools)
+                finally:
+                    opened = False