borgee-plugin-sdk 0.1.2__py3-none-any.whl

borgee_plugin_sdk/_wire/__init__.py

@@ -0,0 +1,5 @@
+"""Generated BPP wire declarations."""
+
+from .frames_generated import BPP_FRAME_DIRECTIONS, BPP_FRAME_TYPES
+
+__all__ = ["BPP_FRAME_DIRECTIONS", "BPP_FRAME_TYPES"]

borgee_plugin_sdk/_wire/frames_generated.py

@@ -0,0 +1,272 @@
+# Code generated by cmd/bpp-tsgen; DO NOT EDIT.
+#
+# Source of truth: packages/server-go/internal/bpp/envelope.go
+# Regenerate:      cd packages/server-go && go run ./cmd/bpp-tsgen
+#                  (or: go generate ./internal/bpp/...)
+
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypeAlias, TypedDict
+
+BppDirection: TypeAlias = Literal["server_to_plugin", "plugin_to_server"]
+
+
+class InboundAttachment(TypedDict):
+    url: str
+    filename: NotRequired[str]
+    content_type: str
+    size_bytes: NotRequired[int]
+
+
+class AgentConfigUpdateFrame(TypedDict):
+    type: Literal["agent_config_update"]
+    cursor: int
+    agent_id: str
+    schema_version: int
+    blob: str
+    idempotency_key: str
+    created_at: int
+
+
+class AgentToggleFrame(TypedDict):
+    type: Literal["agent_toggle"]
+    agent_id: str
+    action: str
+    reason: str
+
+
+class InboundMessageFrame(TypedDict):
+    type: Literal["inbound_message"]
+    cursor: int
+    agent_id: str
+    channel_id: str
+    channel_type: str
+    kind: str
+    message_id: str
+    author_id: str
+    author_name: str
+    body: str
+    content_type: str
+    msg_type: str
+    attachments: NotRequired[list[InboundAttachment]]
+    created_at: int
+    emoji: str
+    reactor_id: str
+    reaction_added: bool
+
+
+class PermissionDeniedFrame(TypedDict):
+    type: Literal["permission_denied"]
+    cursor: int
+    agent_id: str
+    request_id: str
+    attempted_action: str
+    required_capability: str
+    current_scope: str
+    denied_at: int
+
+
+class SemanticActionResultFrame(TypedDict):
+    type: Literal["semantic_action_result"]
+    nonce: str
+    cursor: int
+    status: str
+    payload: str
+    error: str
+
+
+class SessionResumeAck(TypedDict):
+    type: Literal["session.resume_ack"]
+    replay_mode: str
+    count: int
+    high_water: int
+    reset: bool
+    reason: str
+
+
+class SessionSummaryFrame(TypedDict):
+    type: Literal["session.summary"]
+    cursor: int
+    missed_count: int
+    since_cursor: int
+    through_cursor: int
+    summary: str
+
+
+class ConnectFrame(TypedDict):
+    type: Literal["connect"]
+    plugin_id: str
+    token: str
+    version: str
+    capabilities: str
+
+
+class AgentRegisterFrame(TypedDict):
+    type: Literal["agent_register"]
+    plugin_id: str
+    agent_ids: list[str]
+
+
+class RuntimeSchemaAdvertiseFrame(TypedDict):
+    type: Literal["runtime_schema_advertise"]
+    plugin_id: str
+    models: str
+    blob_keys: str
+    schema_ver: int
+
+
+class HeartbeatFrame(TypedDict):
+    type: Literal["heartbeat"]
+    plugin_id: str
+    agent_id: str
+    status: str
+    reason: str
+    timestamp: int
+
+
+class SemanticActionFrame(TypedDict):
+    type: Literal["semantic_action"]
+    agent_id: str
+    action: str
+    payload: str
+    nonce: str
+
+
+class ErrorReportFrame(TypedDict):
+    type: Literal["error_report"]
+    agent_id: str
+    kind: str
+    detail: str
+
+
+class AgentConfigAckFrame(TypedDict):
+    type: Literal["agent_config_ack"]
+    cursor: int
+    agent_id: str
+    schema_version: int
+    idempotency_key: str
+    status: str
+    reason: str
+    applied_at: int
+
+
+class TaskStartedFrame(TypedDict):
+    type: Literal["task_started"]
+    task_id: str
+    agent_id: str
+    channel_id: str
+    subject: str
+    started_at: int
+
+
+class TaskFinishedFrame(TypedDict):
+    type: Literal["task_finished"]
+    task_id: str
+    agent_id: str
+    channel_id: str
+    outcome: str
+    reason: str
+    finished_at: int
+
+
+class ColdStartHandshakeFrame(TypedDict):
+    type: Literal["cold_start_handshake"]
+    plugin_id: str
+    agent_id: str
+    restart_at: int
+    restart_reason: str
+
+
+class SessionResumeRequest(TypedDict):
+    type: Literal["session.resume"]
+    replay_mode: str
+    since_cursor: int
+    latest_n: NotRequired[int]
+
+
+BppServerToPluginFrame: TypeAlias = (
+    AgentConfigUpdateFrame
+    | AgentToggleFrame
+    | InboundMessageFrame
+    | PermissionDeniedFrame
+    | SemanticActionResultFrame
+    | SessionResumeAck
+    | SessionSummaryFrame
+)
+
+BppPluginToServerFrame: TypeAlias = (
+    ConnectFrame
+    | AgentRegisterFrame
+    | RuntimeSchemaAdvertiseFrame
+    | HeartbeatFrame
+    | SemanticActionFrame
+    | ErrorReportFrame
+    | AgentConfigAckFrame
+    | TaskStartedFrame
+    | TaskFinishedFrame
+    | ColdStartHandshakeFrame
+    | SessionResumeRequest
+)
+
+BppFrame: TypeAlias = (
+    AgentConfigUpdateFrame
+    | AgentToggleFrame
+    | InboundMessageFrame
+    | PermissionDeniedFrame
+    | SemanticActionResultFrame
+    | SessionResumeAck
+    | SessionSummaryFrame
+    | ConnectFrame
+    | AgentRegisterFrame
+    | RuntimeSchemaAdvertiseFrame
+    | HeartbeatFrame
+    | SemanticActionFrame
+    | ErrorReportFrame
+    | AgentConfigAckFrame
+    | TaskStartedFrame
+    | TaskFinishedFrame
+    | ColdStartHandshakeFrame
+    | SessionResumeRequest
+)
+
+BPP_FRAME_TYPES: dict[str, str] = {
+    "AgentConfigUpdateFrame": "agent_config_update",
+    "AgentToggleFrame": "agent_toggle",
+    "InboundMessageFrame": "inbound_message",
+    "PermissionDeniedFrame": "permission_denied",
+    "SemanticActionResultFrame": "semantic_action_result",
+    "SessionResumeAck": "session.resume_ack",
+    "SessionSummaryFrame": "session.summary",
+    "ConnectFrame": "connect",
+    "AgentRegisterFrame": "agent_register",
+    "RuntimeSchemaAdvertiseFrame": "runtime_schema_advertise",
+    "HeartbeatFrame": "heartbeat",
+    "SemanticActionFrame": "semantic_action",
+    "ErrorReportFrame": "error_report",
+    "AgentConfigAckFrame": "agent_config_ack",
+    "TaskStartedFrame": "task_started",
+    "TaskFinishedFrame": "task_finished",
+    "ColdStartHandshakeFrame": "cold_start_handshake",
+    "SessionResumeRequest": "session.resume",
+}
+
+BPP_FRAME_DIRECTIONS: dict[str, BppDirection] = {
+    "agent_config_update": "server_to_plugin",
+    "agent_toggle": "server_to_plugin",
+    "inbound_message": "server_to_plugin",
+    "permission_denied": "server_to_plugin",
+    "semantic_action_result": "server_to_plugin",
+    "session.resume_ack": "server_to_plugin",
+    "session.summary": "server_to_plugin",
+    "connect": "plugin_to_server",
+    "agent_register": "plugin_to_server",
+    "runtime_schema_advertise": "plugin_to_server",
+    "heartbeat": "plugin_to_server",
+    "semantic_action": "plugin_to_server",
+    "error_report": "plugin_to_server",
+    "agent_config_ack": "plugin_to_server",
+    "task_started": "plugin_to_server",
+    "task_finished": "plugin_to_server",
+    "cold_start_handshake": "plugin_to_server",
+    "session.resume": "plugin_to_server",
+}

borgee_plugin_sdk/client.py

@@ -0,0 +1,400 @@
+"""Public async Borgee plugin client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ._connection import (
+    BppConnection,
+    ConfigHandler,
+    ConfigObserver,
+    ConnectionOptions,
+    Delivery,
+    ServerRequestHandler,
+)
+from .cursor import CursorStore, MemoryCursorStore
+from .errors import ProtocolError
+from .models import (
+    ConnectionState,
+    CreatedDM,
+    FaultReason,
+    ReplayMode,
+    SentMessage,
+    Task,
+    TaskOutcome,
+    User,
+    task_from_wire,
+    user_from_wire,
+)
+
+
+class _ClientTransport(Protocol):
+    @property
+    def agent_id(self) -> str: ...
+    @property
+    def state(self) -> ConnectionState: ...
+    async def connect(self) -> None: ...
+    async def close(self) -> None: ...
+    async def perform(self, operation: str, payload: dict[str, Any]) -> Any: ...
+    async def report_task_started(self, task_id: str, channel_id: str, subject: str) -> None: ...
+    async def report_task_finished(
+        self, task_id: str, channel_id: str, outcome: str, reason: str
+    ) -> None: ...
+    def send_typing_nowait(self, channel_id: str) -> None: ...
+    def deliveries(self) -> AsyncIterator[Delivery]: ...
+    def state_changes(self) -> AsyncIterator[ConnectionState]: ...
+
+
+@dataclass(slots=True)
+class BorgeePluginOptions:
+    base_url: str
+    api_key: str
+    agent_id: str = ""
+    plugin_id: str = ""
+    cursor_store: CursorStore = field(default_factory=MemoryCursorStore)
+    allow_insecure_loopback: bool = False
+    replay_mode: ReplayMode = ReplayMode.LATEST_N
+    replay_latest_n: int = 200
+    config_update_handler: ConfigHandler | None = None
+    config_update_observer: ConfigObserver | None = None
+    server_request_handler: ServerRequestHandler | None = None
+    logger: logging.Logger = field(default_factory=lambda: logging.getLogger("borgee_plugin_sdk"))
+    action_timeout: float = 30.0
+    config_apply_timeout: float = 5.0
+    auto_reconnect: bool = True
+    reconnect_base: float = 0.5
+    reconnect_max: float = 30.0
+    heartbeat_interval: float = 30.0
+    random_source: random.Random = field(default_factory=random.Random, repr=False)
+
+    def __post_init__(self) -> None:
+        for name in (
+            "action_timeout",
+            "config_apply_timeout",
+            "reconnect_base",
+            "reconnect_max",
+            "heartbeat_interval",
+        ):
+            if getattr(self, name) <= 0:
+                raise ValueError(f"{name} must be positive")
+
+    def to_connection_options(self) -> ConnectionOptions:
+        return ConnectionOptions(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            agent_id=self.agent_id,
+            plugin_id=self.plugin_id,
+            cursor_store=self.cursor_store,
+            allow_insecure_loopback=self.allow_insecure_loopback,
+            replay_mode=self.replay_mode,
+            replay_latest_n=self.replay_latest_n,
+            config_update_handler=self.config_update_handler,
+            config_update_observer=self.config_update_observer,
+            server_request_handler=self.server_request_handler,
+            logger=self.logger,
+            action_timeout=self.action_timeout,
+            config_apply_timeout=self.config_apply_timeout,
+            auto_reconnect=self.auto_reconnect,
+            reconnect_base=self.reconnect_base,
+            reconnect_max=self.reconnect_max,
+            heartbeat_interval=self.heartbeat_interval,
+            random_source=self.random_source,
+        )
+
+
+class BorgeePluginClient:
+    def __init__(self, options: BorgeePluginOptions, transport: _ClientTransport | None = None) -> None:
+        self._options = options
+        self._transport = transport or BppConnection(options.to_connection_options())
+
+    @property
+    def agent_id(self) -> str:
+        return self._transport.agent_id
+
+    @property
+    def state(self) -> ConnectionState:
+        return self._transport.state
+
+    async def connect(self) -> None:
+        await self._transport.connect()
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def __aenter__(self) -> BorgeePluginClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()
+
+    def deliveries(self) -> AsyncIterator[Delivery]:
+        return self._transport.deliveries()
+
+    def subscribe(self) -> AsyncIterator[Delivery]:
+        return self.deliveries()
+
+    def state_changes(self) -> AsyncIterator[ConnectionState]:
+        return self._transport.state_changes()
+
+    async def send_message(
+        self,
+        channel_id: str,
+        body: str,
+        *,
+        reply_to_id: str | None = None,
+    ) -> SentMessage:
+        result = await self._transport.perform(
+            "send_message",
+            {
+                "channel_id": channel_id,
+                "content": body,
+                "reply_to_id": reply_to_id,
+            },
+        )
+        if not isinstance(result, dict) or not isinstance(result.get("message_id"), str):
+            raise ProtocolError("send_message returned an invalid result")
+        cursor = result.get("cursor", 0)
+        if not isinstance(cursor, int) or isinstance(cursor, bool):
+            cursor = 0
+        return SentMessage(result["message_id"], cursor)
+
+    async def edit_message(self, message_id: str, body: str) -> None:
+        await self._transport.perform("edit_message", {"message_id": message_id, "content": body})
+
+    async def delete_message(self, message_id: str) -> None:
+        await self._transport.perform("delete_message", {"message_id": message_id})
+
+    async def react(self, message_id: str, emoji: str) -> None:
+        await self._transport.perform("react", {"message_id": message_id, "emoji": emoji, "removed": False})
+
+    async def unreact(self, message_id: str, emoji: str) -> None:
+        await self._transport.perform("react", {"message_id": message_id, "emoji": emoji, "removed": True})
+
+    async def create_dm(self, user_id: str) -> CreatedDM:
+        result = await self._transport.perform("create_dm", {"user_id": user_id})
+        if not isinstance(result, dict) or not isinstance(result.get("channel_id"), str):
+            raise ProtocolError("create_dm returned an invalid result")
+        return CreatedDM(result["channel_id"])
+
+    async def get_me(self) -> User:
+        return user_from_wire(await self._transport.perform("get_me", {}))
+
+    async def report_task_started(self, task_id: str, channel_id: str, subject: str) -> None:
+        await self._transport.report_task_started(task_id, channel_id, subject)
+
+    async def report_task_finished(
+        self,
+        task_id: str,
+        channel_id: str,
+        outcome: TaskOutcome,
+        reason: FaultReason | None = None,
+    ) -> None:
+        await self._transport.report_task_finished(
+            task_id,
+            channel_id,
+            outcome.value,
+            reason.value if reason is not None else "",
+        )
+
+    # ─── Task CRUD (BPP semantic actions) ───────────────────
+
+    async def create_task(
+        self,
+        channel_id: str,
+        title: str,
+        *,
+        description: str | None = None,
+        assignee_id: str | None = None,
+        heartbeat_interval_ms: int | None = None,
+        heartbeat_prompt: str | None = None,
+    ) -> Task:
+        payload: dict[str, Any] = {"channel_id": channel_id, "title": title}
+        if description is not None:
+            payload["description"] = description
+        if assignee_id is not None:
+            payload["assignee_id"] = assignee_id
+        if heartbeat_interval_ms is not None:
+            payload["heartbeat_interval_ms"] = heartbeat_interval_ms
+        if heartbeat_prompt is not None:
+            payload["heartbeat_prompt"] = heartbeat_prompt
+        result = await self._transport.perform("create_task", payload)
+        return task_from_wire(result)
+
+    async def list_tasks(
+        self,
+        *,
+        channel_id: str | None = None,
+        guild_id: str | None = None,
+    ) -> list[Task]:
+        if (channel_id is None) == (guild_id is None):
+            raise ValueError("list_tasks requires exactly one of channel_id or guild_id")
+        payload: dict[str, Any] = {}
+        if channel_id is not None:
+            payload["channel_id"] = channel_id
+        if guild_id is not None:
+            payload["guild_id"] = guild_id
+        result = await self._transport.perform("list_tasks", payload)
+        if not isinstance(result, list):
+            raise ProtocolError("list_tasks did not return an array")
+        return [task_from_wire(item) for item in result]
+
+    async def get_task(self, task_id: str) -> Task:
+        result = await self._transport.perform("get_task", {"task_id": task_id})
+        return task_from_wire(result)
+
+    async def update_task(
+        self,
+        task_id: str,
+        *,
+        status: str | None = None,
+        assignee_id: str | None = None,
+        title: str | None = None,
+        heartbeat_interval_ms: int | None = None,
+        heartbeat_prompt: str | None = None,
+    ) -> Task:
+        if (
+            status is None
+            and assignee_id is None
+            and title is None
+            and heartbeat_interval_ms is None
+            and heartbeat_prompt is None
+        ):
+            raise ValueError(
+                "update_task requires at least one of: status, assignee_id, title,"
+                " heartbeat_interval_ms, heartbeat_prompt"
+            )
+        payload: dict[str, Any] = {"task_id": task_id}
+        if status is not None:
+            payload["status"] = status
+        if assignee_id is not None:
+            payload["assignee_id"] = assignee_id
+        if title is not None:
+            payload["title"] = title
+        if heartbeat_interval_ms is not None:
+            payload["heartbeat_interval_ms"] = heartbeat_interval_ms
+        if heartbeat_prompt is not None:
+            payload["heartbeat_prompt"] = heartbeat_prompt
+        result = await self._transport.perform("update_task", payload)
+        return task_from_wire(result)
+
+    # ─── Channel management (BPP semantic actions) ─────────
+
+    async def list_channels(self) -> list[dict[str, Any]]:
+        result = await self._transport.perform("list_channels", {})
+        if not isinstance(result, list):
+            raise ProtocolError("list_channels did not return an array")
+        return result
+
+    async def create_channel(
+        self,
+        name: str,
+        *,
+        topic: str | None = None,
+        visibility: str | None = None,
+        member_ids: list[str] | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"name": name}
+        if topic is not None:
+            payload["topic"] = topic
+        if visibility is not None:
+            payload["visibility"] = visibility
+        if member_ids is not None:
+            payload["member_ids"] = member_ids
+        result = await self._transport.perform("create_channel", payload)
+        if not isinstance(result, dict):
+            raise ProtocolError("create_channel did not return an object")
+        return result
+
+    async def update_channel(
+        self,
+        channel_id: str,
+        *,
+        name: str | None = None,
+        visibility: str | None = None,
+        archived: bool | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"channel_id": channel_id}
+        if name is not None:
+            payload["name"] = name
+        if visibility is not None:
+            payload["visibility"] = visibility
+        if archived is not None:
+            payload["archived"] = archived
+        result = await self._transport.perform("update_channel", payload)
+        if not isinstance(result, dict):
+            raise ProtocolError("update_channel did not return an object")
+        return result
+
+    async def set_topic(self, channel_id: str, topic: str) -> None:
+        await self._transport.perform("set_topic", {"channel_id": channel_id, "topic": topic})
+
+    async def delete_channel(self, channel_id: str) -> None:
+        await self._transport.perform("delete_channel", {"channel_id": channel_id})
+
+    async def read_history(
+        self,
+        channel_id: str,
+        *,
+        limit: int | None = None,
+        before: str | None = None,
+        after: str | None = None,
+    ) -> list[dict[str, Any]]:
+        payload: dict[str, Any] = {"channel_id": channel_id}
+        if limit is not None:
+            payload["limit"] = limit
+        if before is not None:
+            payload["before"] = before
+        if after is not None:
+            payload["after"] = after
+        result = await self._transport.perform("read_channel_history", payload)
+        if not isinstance(result, list):
+            raise ProtocolError("read_channel_history did not return an array")
+        return result
+
+    def start_typing(self, channel_id: str) -> _TypingHandle:
+        """Begin a typing indicator loop. Call stop() on the handle to end it."""
+        handle = _TypingHandle(self._transport, channel_id)
+        handle.start()
+        return handle
+
+
+class _TypingHandle:
+    """Sends typing frames every 2s until stop() is called."""
+
+    _INTERVAL = 2.0
+
+    def __init__(self, transport: _ClientTransport, channel_id: str) -> None:
+        self._transport = transport
+        self._channel_id = channel_id
+        self._task: asyncio.Task[None] | None = None
+
+    def start(self) -> None:
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._loop())
+
+    async def _loop(self) -> None:
+        try:
+            while True:
+                self._transport.send_typing_nowait(self._channel_id)
+                await asyncio.sleep(self._INTERVAL)
+        except asyncio.CancelledError:
+            pass
+
+    def stop(self) -> None:
+        """Stop emitting typing indicators."""
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    def __del__(self) -> None:
+        self.stop()
+
+
+def create_borgee_plugin(options: BorgeePluginOptions) -> BorgeePluginClient:
+    return BorgeePluginClient(options)