pyb-agent-sdk 0.1.0__tar.gz

pyb_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: pyb-agent-sdk
+Version: 0.1.0
+Summary: Protocol-first Python skeleton for PYB Agent SDK
+Author: PYB-XC
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# PYB Agent SDK Python
+
+Protocol-first Python skeleton for the PYB Agent SDK.
+
+Current scope:
+
+- `AgentSession` main entry skeleton
+- `ProtocolSessionBackend`
+- runtime event projection
+- protocol honesty boundaries for unimplemented bridges

pyb_agent_sdk-0.1.0/README.md

@@ -0,0 +1,10 @@
+# PYB Agent SDK Python
+
+Protocol-first Python skeleton for the PYB Agent SDK.
+
+Current scope:
+
+- `AgentSession` main entry skeleton
+- `ProtocolSessionBackend`
+- runtime event projection
+- protocol honesty boundaries for unimplemented bridges

pyb_agent_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyb-agent-sdk"
+version = "0.1.0"
+description = "Protocol-first Python skeleton for PYB Agent SDK"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "PYB-XC" }]
+dependencies = ["httpx>=0.27", "websockets>=12.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

pyb_agent_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyb_agent_sdk-0.1.0/src/pyb_agent_sdk/__init__.py

@@ -0,0 +1,87 @@
+from .agent_compaction import (
+    AgentCompactionAdapter,
+    AgentCompactionEvent,
+    AgentCompactionState,
+    create_agent_compaction_adapter,
+)
+from .agent_hooks import (
+    AGENT_HOOK_EVENT_NAMES,
+    AGENT_HOOK_TYPES,
+    AgentHookAdapter,
+    AgentSubagentLifecycleEvent,
+    create_agent_hook_adapter,
+)
+from .agent_mcp import (
+    AgentMcpAdapter,
+    AgentMcpCapabilityState,
+    AgentMcpEvent,
+    create_agent_mcp_adapter,
+    create_default_mcp_adapter_from_pyb_client,
+)
+from .agent_session import (
+    AgentSession,
+    AgentSessionInput,
+    CreateAgentSessionOptions,
+    QueryOnceResult,
+    create_agent_session,
+    query_once,
+)
+from .client import ClientOptions, PybAgentClient, SessionLostError
+from .permissions import OnPermissionLost, PermissionManager, PermissionRequest
+from .protocol import (
+    ProtocolError,
+    ServerMessage,
+    decode_envelope,
+    decode_server_message,
+    encode_client_message,
+)
+from .protocol_session_backend import (
+    DefaultProtocolSessionClient,
+    DefaultSSEClient,
+    ProtocolSessionBackend,
+    create_protocol_session_backend,
+)
+from .runtime_events import RuntimeEvent, RuntimeEventDomain, project_legacy_event_to_runtime_event
+from .transport import HybridTransport, TransportConfig
+
+__all__ = [
+    "AgentCompactionState",
+    "AgentCompactionAdapter",
+    "AgentCompactionEvent",
+    "AGENT_HOOK_EVENT_NAMES",
+    "AGENT_HOOK_TYPES",
+    "AgentHookAdapter",
+    "AgentMcpAdapter",
+    "AgentMcpCapabilityState",
+    "AgentMcpEvent",
+    "AgentSession",
+    "AgentSessionInput",
+    "AgentSubagentLifecycleEvent",
+    "ClientOptions",
+    "CreateAgentSessionOptions",
+    "DefaultProtocolSessionClient",
+    "DefaultSSEClient",
+    "ProtocolSessionBackend",
+    "ProtocolError",
+    "PermissionManager",
+    "PermissionRequest",
+    "PybAgentClient",
+    "SessionLostError",
+    "OnPermissionLost",
+    "HybridTransport",
+    "TransportConfig",
+    "QueryOnceResult",
+    "RuntimeEvent",
+    "RuntimeEventDomain",
+    "create_agent_session",
+    "create_agent_compaction_adapter",
+    "create_agent_hook_adapter",
+    "create_agent_mcp_adapter",
+    "create_default_mcp_adapter_from_pyb_client",
+    "create_protocol_session_backend",
+    "decode_envelope",
+    "decode_server_message",
+    "encode_client_message",
+    "project_legacy_event_to_runtime_event",
+    "query_once",
+]

pyb_agent_sdk-0.1.0/src/pyb_agent_sdk/agent_compaction.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+
+@dataclass(slots=True)
+class AgentCompactionState:
+    mode: str | None = None
+    trigger_strategy: str | None = None
+    summary_present: bool = False
+    has_restore_seeds: bool = False
+
+
+@dataclass(slots=True)
+class AgentCompactionEvent:
+    type: str
+    session_id: str
+    timestamp: float
+    data: dict[str, object]
+
+
+class AgentCompactionAdapter(Protocol):
+    def get_state(self) -> object: ...
+
+    def get_summary(self) -> object: ...
+
+    async def compact(self, input_data: dict[str, object] | None = None) -> object: ...
+
+    def subscribe(
+        self,
+        listener: Callable[[AgentCompactionEvent], None],
+    ) -> Callable[[], None]: ...
+
+
+class _AgentCompactionAdapter:
+    def __init__(
+        self,
+        *,
+        get_state: Callable[[], object],
+        get_summary: Callable[[], object],
+        compact: Callable[[dict[str, object] | None], object],
+        subscribe: Callable[[Callable[[AgentCompactionEvent], None]], Callable[[], None]],
+    ) -> None:
+        self._get_state = get_state
+        self._get_summary = get_summary
+        self._compact = compact
+        self._subscribe = subscribe
+
+    def get_state(self) -> object:
+        return self._get_state()
+
+    def get_summary(self) -> object:
+        return self._get_summary()
+
+    async def compact(self, input_data: dict[str, object] | None = None) -> object:
+        result = self._compact(input_data)
+        if hasattr(result, "__await__"):
+            return await result  # type: ignore[misc]
+        return result
+
+    def subscribe(
+        self,
+        listener: Callable[[AgentCompactionEvent], None],
+    ) -> Callable[[], None]:
+        return self._subscribe(listener)
+
+
+def create_agent_compaction_adapter(
+    *,
+    get_state: Callable[[], object],
+    get_summary: Callable[[], object],
+    compact: Callable[[dict[str, object] | None], object],
+    subscribe: Callable[[Callable[[AgentCompactionEvent], None]], Callable[[], None]],
+) -> AgentCompactionAdapter:
+    return _AgentCompactionAdapter(
+        get_state=get_state,
+        get_summary=get_summary,
+        compact=compact,
+        subscribe=subscribe,
+    )

pyb_agent_sdk-0.1.0/src/pyb_agent_sdk/agent_hooks.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Literal, Protocol, Sequence
+
+AGENT_HOOK_EVENT_NAMES = {
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "PermissionDenied",
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "Stop",
+    "PreCompact",
+    "PostCompact",
+    "Elicitation",
+    "ElicitationResult",
+    "Notification",
+    "SubagentStart",
+    "SubagentStop",
+    "ConfigChange",
+}
+AGENT_HOOK_TYPES = {"command", "prompt"}
+
+
+AgentHookType = Literal["command", "prompt"]
+
+
+@dataclass(slots=True)
+class AgentSubagentLifecycleEvent:
+    type: str
+    session_id: str
+    timestamp: float
+    data: dict[str, object]
+
+
+class AgentHookAdapter(Protocol):
+    def register_hooks(self, hooks: Sequence[dict[str, object]]) -> None: ...
+
+    def get_runtime_state(self) -> object: ...
+
+    def subscribe_subagent_lifecycle(
+        self,
+        listener: Callable[[AgentSubagentLifecycleEvent], None],
+    ) -> Callable[[], None]: ...
+
+
+class _AgentHookAdapter:
+    def __init__(
+        self,
+        *,
+        register_hooks: Callable[[Sequence[dict[str, object]]], None] | None = None,
+        get_runtime_state: Callable[[], object] | None = None,
+        subscribe_subagent_lifecycle: Callable[
+            [Callable[[AgentSubagentLifecycleEvent], None]], Callable[[], None]
+        ]
+        | None = None,
+    ) -> None:
+        self._register_hooks = register_hooks
+        self._get_runtime_state = get_runtime_state
+        self._subscribe_subagent_lifecycle = subscribe_subagent_lifecycle
+
+    def register_hooks(self, hooks: Sequence[dict[str, object]]) -> None:
+        if self._register_hooks is None:
+            return
+        self._register_hooks(hooks)
+
+    def get_runtime_state(self) -> object:
+        if self._get_runtime_state is None:
+            return None
+        return self._get_runtime_state()
+
+    def subscribe_subagent_lifecycle(
+        self,
+        listener: Callable[[AgentSubagentLifecycleEvent], None],
+    ) -> Callable[[], None]:
+        if self._subscribe_subagent_lifecycle is None:
+            return lambda: None
+        return self._subscribe_subagent_lifecycle(listener)
+
+
+def create_agent_hook_adapter(
+    *,
+    register_hooks: Callable[[Sequence[dict[str, object]]], None] | None = None,
+    get_runtime_state: Callable[[], object] | None = None,
+    subscribe_subagent_lifecycle: Callable[
+        [Callable[[AgentSubagentLifecycleEvent], None]], Callable[[], None]
+    ]
+    | None = None,
+) -> AgentHookAdapter:
+    return _AgentHookAdapter(
+        register_hooks=register_hooks,
+        get_runtime_state=get_runtime_state,
+        subscribe_subagent_lifecycle=subscribe_subagent_lifecycle,
+    )
+
+
+def validate_hook_descriptors(hooks: Sequence[dict[str, object]]) -> None:
+    for hook in hooks:
+        hook_type = hook.get("type")
+        hook_event = hook.get("event")
+        if hook_type not in AGENT_HOOK_TYPES:
+            raise RuntimeError("AGENT_SESSION_HOOK_TYPE_UNSUPPORTED")
+        if hook_event not in AGENT_HOOK_EVENT_NAMES:
+            raise RuntimeError("AGENT_SESSION_HOOK_EVENT_UNSUPPORTED")

pyb_agent_sdk-0.1.0/src/pyb_agent_sdk/agent_mcp.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Protocol
+
+
+@dataclass(slots=True)
+class AgentMcpCapabilityState:
+    servers: list[dict[str, object]] = field(default_factory=list)
+    capabilities: list[dict[str, object]] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class AgentMcpEvent:
+    type: str
+    session_id: str
+    timestamp: float
+    data: dict[str, object]
+
+
+class AgentMcpAdapter(Protocol):
+    async def list_servers(self) -> object: ...
+
+    async def connect_server(self, server_id: str) -> object: ...
+
+    async def disconnect_server(self, server_id: str) -> object: ...
+
+    async def reconnect_server(self, server_id: str) -> object: ...
+
+    def get_capability_state(self) -> object: ...
+
+    def get_semantic_state(self) -> object: ...
+
+    def get_deep_runtime_state(self) -> object: ...
+
+    def subscribe(
+        self,
+        listener: Callable[[AgentMcpEvent], None],
+    ) -> Callable[[], None]: ...
+
+
+class _AgentMcpAdapter:
+    def __init__(
+        self,
+        *,
+        list_servers: Callable[[], object],
+        connect_server: Callable[[str], object],
+        disconnect_server: Callable[[str], object],
+        reconnect_server: Callable[[str], object] | None = None,
+        get_capability_state: Callable[[], object] | None = None,
+        get_semantic_state: Callable[[], object] | None = None,
+        get_deep_runtime_state: Callable[[], object] | None = None,
+        subscribe: Callable[[Callable[[AgentMcpEvent], None]], Callable[[], None]] | None = None,
+    ) -> None:
+        self._list_servers = list_servers
+        self._connect_server = connect_server
+        self._disconnect_server = disconnect_server
+        self._reconnect_server = reconnect_server
+        self._get_capability_state = get_capability_state
+        self._get_semantic_state = get_semantic_state
+        self._get_deep_runtime_state = get_deep_runtime_state
+        self._subscribe = subscribe
+
+    async def list_servers(self) -> object:
+        return await _maybe_await(self._list_servers())
+
+    async def connect_server(self, server_id: str) -> object:
+        return await _maybe_await(self._connect_server(server_id))
+
+    async def disconnect_server(self, server_id: str) -> object:
+        return await _maybe_await(self._disconnect_server(server_id))
+
+    async def reconnect_server(self, server_id: str) -> object:
+        if self._reconnect_server is None:
+            raise RuntimeError("AGENT_SESSION_MCP_RECONNECT_UNAVAILABLE")
+        return await _maybe_await(self._reconnect_server(server_id))
+
+    def get_capability_state(self) -> object:
+        if self._get_capability_state is None:
+            return None
+        return self._get_capability_state()
+
+    def get_semantic_state(self) -> object:
+        if self._get_semantic_state is None:
+            return None
+        return self._get_semantic_state()
+
+    def get_deep_runtime_state(self) -> object:
+        if self._get_deep_runtime_state is None:
+            return None
+        return self._get_deep_runtime_state()
+
+    def subscribe(
+        self,
+        listener: Callable[[AgentMcpEvent], None],
+    ) -> Callable[[], None]:
+        if self._subscribe is None:
+            return lambda: None
+        return self._subscribe(listener)
+
+
+def create_agent_mcp_adapter(
+    *,
+    list_servers: Callable[[], object],
+    connect_server: Callable[[str], object],
+    disconnect_server: Callable[[str], object],
+    reconnect_server: Callable[[str], object] | None = None,
+    get_capability_state: Callable[[], object] | None = None,
+    get_semantic_state: Callable[[], object] | None = None,
+    get_deep_runtime_state: Callable[[], object] | None = None,
+    subscribe: Callable[[Callable[[AgentMcpEvent], None]], Callable[[], None]] | None = None,
+) -> AgentMcpAdapter:
+    return _AgentMcpAdapter(
+        list_servers=list_servers,
+        connect_server=connect_server,
+        disconnect_server=disconnect_server,
+        reconnect_server=reconnect_server,
+        get_capability_state=get_capability_state,
+        get_semantic_state=get_semantic_state,
+        get_deep_runtime_state=get_deep_runtime_state,
+        subscribe=subscribe,
+    )
+
+
+def create_default_mcp_adapter_from_pyb_client(pyb_client: object | None) -> AgentMcpAdapter | None:
+    mcp = getattr(pyb_client, "mcp", None) if pyb_client is not None else None
+    if mcp is None:
+        return None
+    if not all(hasattr(mcp, name) for name in ("list", "connect", "disconnect")):
+        return None
+    return create_agent_mcp_adapter(
+        list_servers=lambda: mcp.list(),
+        connect_server=lambda server_id: mcp.connect(server_id),
+        disconnect_server=lambda server_id: mcp.disconnect(server_id),
+        reconnect_server=(lambda server_id: mcp.reconnect(server_id))
+        if hasattr(mcp, "reconnect")
+        else None,
+    )
+
+
+async def _maybe_await(value: object) -> object:
+    if hasattr(value, "__await__"):
+        return await value  # type: ignore[misc]
+    return value