borgee-plugin-sdk 0.1.2__tar.gz → 0.2.0__tar.gz

{borgee_plugin_sdk-0.1.2/src/borgee_plugin_sdk.egg-info → borgee_plugin_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: borgee-plugin-sdk
-Version: 0.1.2
+Version: 0.2.0
 Summary: Async Python SDK for Borgee plugin runtimes
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "borgee-plugin-sdk"
-version = "0.1.2"
+version = "0.2.0"
 description = "Async Python SDK for Borgee plugin runtimes"
 readme = "README.md"
 license = "MIT"

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/src/borgee_plugin_sdk/__init__.py

@@ -34,12 +34,15 @@ from .models import (
     SentMessage,
     Task,
     TaskOutcome,
+    TaskPropertyDefinition,
+    TaskPropertyRender,
     User,
     UserRole,
     task_from_wire,
+    task_property_definition_from_wire,
 )
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "MISSING",
@@ -76,8 +79,11 @@ __all__ = [
     "StaleDeliveryError",
     "Task",
     "TaskOutcome",
+    "TaskPropertyDefinition",
+    "TaskPropertyRender",
     "User",
     "UserRole",
     "create_borgee_plugin",
     "task_from_wire",
+    "task_property_definition_from_wire",
 ]

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/src/borgee_plugin_sdk/client.py

@@ -27,8 +27,10 @@ from .models import (
     SentMessage,
     Task,
     TaskOutcome,
+    TaskPropertyDefinition,
     User,
     task_from_wire,
+    task_property_definition_from_wire,
     user_from_wire,
 )
 
@@ -283,6 +285,31 @@ class BorgeePluginClient:
         result = await self._transport.perform("update_task", payload)
         return task_from_wire(result)
 
+    # ─── Task properties (BPP semantic actions) ────────────
+    # One key per call. The server has no whole-object property write, so two
+    # agents writing different keys of the same task never overwrite each other.
+
+    async def set_task_property(self, task_id: str, key: str, value: str) -> Task:
+        result = await self._transport.perform(
+            "set_task_property", {"task_id": task_id, "key": key, "value": value}
+        )
+        return task_from_wire(result)
+
+    async def delete_task_property(self, task_id: str, key: str) -> Task:
+        result = await self._transport.perform("delete_task_property", {"task_id": task_id, "key": key})
+        return task_from_wire(result)
+
+    async def list_task_property_definitions(self) -> list[TaskPropertyDefinition]:
+        """Return the registered property keys with their labels and render kinds.
+
+        Read this rather than hardcoding keys — the server can register a new
+        property without an SDK release.
+        """
+        result = await self._transport.perform("list_task_property_definitions", {})
+        if not isinstance(result, list):
+            raise ProtocolError("list_task_property_definitions did not return an array")
+        return [task_property_definition_from_wire(item) for item in result]
+
     # ─── Channel management (BPP semantic actions) ─────────
 
     async def list_channels(self) -> list[dict[str, Any]]:

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/src/borgee_plugin_sdk/models.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from enum import StrEnum
 from typing import Any, Protocol, TypeAlias, runtime_checkable
@@ -234,6 +235,60 @@ class Task:
     created_at: int
     updated_at: int
     heartbeat_prompt: str
+    # Registered property keys and their values (PR link, issue link, agent
+    # session id). Always a mapping; a task with no properties carries {}.
+    properties: Mapping[str, str]
+
+
+class TaskPropertyRender(StrEnum):
+    """How a client should present a property value; the value is always a string."""
+
+    URL = "url"
+    IDENTIFIER = "identifier"
+    TEXT = "text"
+
+
+@dataclass(frozen=True, slots=True)
+class TaskPropertyDefinition:
+    """One entry of the server's task-property registry.
+
+    Read the registry rather than hardcoding keys: the server can register a new
+    property without an SDK release.
+    """
+
+    key: str
+    label: str
+    render: TaskPropertyRender
+
+
+def task_property_definition_from_wire(value: Any) -> TaskPropertyDefinition:
+    if not isinstance(value, dict):
+        raise TypeError("task property definition must be an object")
+    key = _required_non_empty_string(value.get("key"), "key")
+    render = value.get("render")
+    # An unrecognised render kind means the server registered a presentation
+    # this SDK predates. Fall back to text so the value still shows rather than
+    # the whole definition being dropped.
+    try:
+        parsed_render = TaskPropertyRender(str(render))
+    except ValueError:
+        parsed_render = TaskPropertyRender.TEXT
+    return TaskPropertyDefinition(
+        key=key,
+        label=value.get("label", ""),
+        render=parsed_render,
+    )
+
+
+def _task_properties_from_wire(value: Any) -> dict[str, str]:
+    """Keep only string values.
+
+    A non-string value means the server and this SDK disagree about the shape,
+    so it is dropped rather than coerced into a plausible-looking repr.
+    """
+    if not isinstance(value, dict):
+        return {}
+    return {key: item for key, item in value.items() if isinstance(key, str) and isinstance(item, str)}
 
 
 def task_from_wire(value: Any) -> Task:
@@ -258,6 +313,7 @@ def task_from_wire(value: Any) -> Task:
         created_at=value.get("created_at", 0),
         updated_at=value.get("updated_at", 0),
         heartbeat_prompt=value.get("heartbeat_prompt", ""),
+        properties=_task_properties_from_wire(value.get("properties")),
     )
 
 

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0/src/borgee_plugin_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: borgee-plugin-sdk
-Version: 0.1.2
+Version: 0.2.0
 Summary: Async Python SDK for Borgee plugin runtimes
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/src/borgee_plugin_sdk.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ tests/test_connection_unit.py
 tests/test_cursor_store.py
 tests/test_models_and_client.py
 tests/test_task_crud.py
+tests/test_task_properties.py
 tests/test_verify_installed_sdk.py
 tests/test_websocket_integration.py
 tests/test_wire_contract.py

borgee_plugin_sdk-0.2.0/tests/test_task_properties.py

@@ -0,0 +1,149 @@
+"""Tests for task properties on BorgeePluginClient and the property wire decoders."""
+
+from __future__ import annotations
+
+import pytest
+
+import borgee_plugin_sdk as sdk
+from borgee_plugin_sdk.errors import ProtocolError
+from borgee_plugin_sdk.testing import FakeTransport, create_test_client
+
+TASK_WIRE: dict = {
+    "id": "task-1",
+    "channel_id": "ch-1",
+    "title": "Write the spec",
+    "properties": {"link.pr": "https://example.test/pr/1"},
+}
+
+
+def _client_and_transport() -> tuple[sdk.BorgeePluginClient, FakeTransport]:
+    options = sdk.BorgeePluginOptions("https://example.com", "secret")
+    transport = FakeTransport()
+    return create_test_client(options, transport), transport
+
+
+# ── task_from_wire: properties ─────────────────────────────────────
+
+
+def test_task_properties_decode() -> None:
+    task = sdk.task_from_wire(TASK_WIRE)
+    assert task.properties == {"link.pr": "https://example.test/pr/1"}
+
+
+def test_task_without_properties_decodes_to_empty_mapping() -> None:
+    """Callers never have to tell "field absent" from "no properties" apart."""
+    task = sdk.task_from_wire({"id": "task-1"})
+    assert task.properties == {}
+
+
+def test_task_properties_drop_non_string_values() -> None:
+    """A non-string value means server and SDK disagree; dropping beats coercing."""
+    wire = {**TASK_WIRE, "properties": {"good": "v", "bad": {"nested": 1}, "also_bad": 7}}
+    assert sdk.task_from_wire(wire).properties == {"good": "v"}
+
+
+# ── task_property_definition_from_wire ─────────────────────────────
+
+
+def test_property_definition_decode() -> None:
+    definition = sdk.task_property_definition_from_wire(
+        {"key": "link.pr", "label": "Pull Request", "render": "url"}
+    )
+    assert definition.key == "link.pr"
+    assert definition.label == "Pull Request"
+    assert definition.render is sdk.TaskPropertyRender.URL
+
+
+def test_property_definition_unknown_render_falls_back_to_text() -> None:
+    """An SDK older than the server still shows the value instead of dropping it."""
+    definition = sdk.task_property_definition_from_wire({"key": "x", "label": "X", "render": "hologram"})
+    assert definition.render is sdk.TaskPropertyRender.TEXT
+
+
+def test_property_definition_rejects_non_dict() -> None:
+    with pytest.raises(TypeError, match="task property definition must be an object"):
+        sdk.task_property_definition_from_wire("not a dict")
+
+
+def test_property_definition_rejects_missing_key() -> None:
+    with pytest.raises(TypeError):
+        sdk.task_property_definition_from_wire({"label": "X", "render": "url"})
+
+
+# ── set_task_property ──────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_set_task_property() -> None:
+    client, transport = _client_and_transport()
+    await client.connect()
+
+    transport.queue_result(TASK_WIRE)
+    task = await client.set_task_property("task-1", "link.pr", "https://example.test/pr/1")
+    assert task.properties["link.pr"] == "https://example.test/pr/1"
+
+    action = transport.actions[-1]
+    assert action.operation == "set_task_property"
+    assert action.payload == {
+        "task_id": "task-1",
+        "key": "link.pr",
+        "value": "https://example.test/pr/1",
+    }
+
+
+@pytest.mark.asyncio
+async def test_set_task_property_sends_empty_value() -> None:
+    """An empty string is "set this key to empty", not "field omitted"."""
+    client, transport = _client_and_transport()
+    await client.connect()
+
+    transport.queue_result(TASK_WIRE)
+    await client.set_task_property("task-1", "link.pr", "")
+    assert transport.actions[-1].payload["value"] == ""
+
+
+# ── delete_task_property ───────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_delete_task_property() -> None:
+    client, transport = _client_and_transport()
+    await client.connect()
+
+    transport.queue_result({**TASK_WIRE, "properties": {}})
+    task = await client.delete_task_property("task-1", "link.pr")
+    assert task.properties == {}
+
+    action = transport.actions[-1]
+    assert action.operation == "delete_task_property"
+    assert action.payload == {"task_id": "task-1", "key": "link.pr"}
+
+
+# ── list_task_property_definitions ─────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_list_task_property_definitions() -> None:
+    client, transport = _client_and_transport()
+    await client.connect()
+
+    transport.queue_result(
+        [
+            {"key": "link.pr", "label": "Pull Request", "render": "url"},
+            {"key": "agent.session_id", "label": "Agent Session", "render": "identifier"},
+        ]
+    )
+    definitions = await client.list_task_property_definitions()
+    assert [d.key for d in definitions] == ["link.pr", "agent.session_id"]
+    assert definitions[1].render is sdk.TaskPropertyRender.IDENTIFIER
+    assert transport.actions[-1].operation == "list_task_property_definitions"
+
+
+@pytest.mark.asyncio
+async def test_list_task_property_definitions_rejects_non_array() -> None:
+    client, transport = _client_and_transport()
+    await client.connect()
+
+    transport.queue_result({"definitions": []})
+    with pytest.raises(ProtocolError, match="did not return an array"):
+        await client.list_task_property_definitions()

{borgee_plugin_sdk-0.1.2 → borgee_plugin_sdk-0.2.0}/tests/test_verify_installed_sdk.py

@@ -8,7 +8,7 @@ from scripts import verify_installed_sdk as verifier
 @pytest.fixture
 def valid_runtime(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(verifier, "_python_version", lambda: "3.12")
-    monkeypatch.setattr(verifier, "_sdk_distribution_version", lambda: "0.1.2")
+    monkeypatch.setattr(verifier, "_sdk_distribution_version", lambda: "0.2.0")
     monkeypatch.setattr(verifier, "_websockets_distribution_version", lambda: "15.0.1")
     monkeypatch.setattr(verifier, "_py_typed_exists", lambda: True)
     monkeypatch.setattr(verifier, "_resume_frame_type", lambda: "session.resume_ack")
@@ -21,7 +21,7 @@ def valid_runtime(monkeypatch: pytest.MonkeyPatch) -> None:
         (
             "_sdk_distribution_version",
             "9.9.9",
-            "SDK distribution version mismatch: expected 0.1.2, found 9.9.9.",
+            "SDK distribution version mismatch: expected 0.2.0, found 9.9.9.",
         ),
         (
             "_websockets_distribution_version",