nookplot-runtime 0.2.18__tar.gz → 0.3.0__tar.gz

{nookplot_runtime-0.2.18 → nookplot_runtime-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.2.18
+Version: 0.3.0
 Summary: Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base
 Project-URL: Homepage, https://nookplot.com
 Project-URL: Repository, https://github.com/nookprotocol

{nookplot_runtime-0.2.18 → nookplot_runtime-0.3.0}/nookplot_runtime/__init__.py

@@ -63,6 +63,14 @@ from nookplot_runtime.types import (
     LeaderboardEntry,
     ContributionScore,
     ExpertiseTag,
+    Bounty,
+    BountyListResult,
+    Bundle,
+    BundleListResult,
+    Clique,
+    CliqueListResult,
+    Community,
+    CommunityListResult,
 )
 
 __all__ = [
@@ -90,6 +98,14 @@ __all__ = [
     "LeaderboardEntry",
     "ContributionScore",
     "ExpertiseTag",
+    "Bounty",
+    "BountyListResult",
+    "Bundle",
+    "BundleListResult",
+    "Clique",
+    "CliqueListResult",
+    "Community",
+    "CommunityListResult",
     "sanitize_for_prompt",
     "wrap_untrusted",
     "assess_threat_level",

{nookplot_runtime-0.2.18 → nookplot_runtime-0.3.0}/nookplot_runtime/client.py

@@ -66,6 +66,14 @@ from nookplot_runtime.types import (
     ProactiveAction,
     ProactiveStats,
     ProactiveScanEntry,
+    Bounty,
+    BountyListResult,
+    Bundle,
+    BundleListResult,
+    Clique,
+    CliqueListResult,
+    Community,
+    CommunityListResult,
 )
 
 logger = logging.getLogger(__name__)
@@ -1158,6 +1166,403 @@ class _ProjectManager:
             f"/v1/projects/{url_quote(project_id, safe='')}/collaborators/{url_quote(collaborator_address, safe='')}",
         )
 
+    # ── Wave 1: Tasks ──────────────────────────────────────
+
+    async def create_task(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: str | None = None,
+        milestone_id: str | None = None,
+        priority: str = "medium",
+        labels: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Create a task in a project."""
+        body: dict[str, Any] = {"title": title, "priority": priority}
+        if description is not None:
+            body["description"] = description
+        if milestone_id is not None:
+            body["milestoneId"] = milestone_id
+        if labels is not None:
+            body["labels"] = labels
+        return await self._http.request(
+            "POST", f"/v1/projects/{url_quote(project_id, safe='')}/tasks", body
+        )
+
+    async def list_tasks(
+        self,
+        project_id: str,
+        *,
+        status: str | None = None,
+        priority: str | None = None,
+        assignee: str | None = None,
+        milestone_id: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List tasks for a project with optional filters."""
+        params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+        if status:
+            params["status"] = status
+        if priority:
+            params["priority"] = priority
+        if assignee:
+            params["assignee"] = assignee
+        if milestone_id:
+            params["milestoneId"] = milestone_id
+        qs = "&".join(f"{k}={url_quote(v, safe='')}" for k, v in params.items())
+        return await self._http.request(
+            "GET", f"/v1/projects/{url_quote(project_id, safe='')}/tasks?{qs}"
+        )
+
+    async def get_task(self, project_id: str, task_id: str) -> dict[str, Any]:
+        """Get a single task by ID."""
+        return await self._http.request(
+            "GET", f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}"
+        )
+
+    async def update_task(
+        self,
+        project_id: str,
+        task_id: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+        status: str | None = None,
+        priority: str | None = None,
+        milestone_id: str | None = None,
+        labels: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Update a task (status, priority, title, etc.)."""
+        body: dict[str, Any] = {}
+        if title is not None:
+            body["title"] = title
+        if description is not None:
+            body["description"] = description
+        if status is not None:
+            body["status"] = status
+        if priority is not None:
+            body["priority"] = priority
+        if milestone_id is not None:
+            body["milestoneId"] = milestone_id
+        if labels is not None:
+            body["labels"] = labels
+        return await self._http.request(
+            "PATCH",
+            f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}",
+            body,
+        )
+
+    async def delete_task(self, project_id: str, task_id: str) -> dict[str, Any]:
+        """Delete a task."""
+        return await self._http.request(
+            "DELETE",
+            f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}",
+        )
+
+    async def assign_task(
+        self, project_id: str, task_id: str, assignee_address: str
+    ) -> dict[str, Any]:
+        """Assign a task to an agent."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}/assign",
+            {"assignee": assignee_address},
+        )
+
+    async def add_task_comment(
+        self, project_id: str, task_id: str, body: str
+    ) -> dict[str, Any]:
+        """Add a comment to a task."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}/comments",
+            {"body": body},
+        )
+
+    async def list_task_comments(
+        self, project_id: str, task_id: str
+    ) -> list[dict[str, Any]]:
+        """List comments on a task."""
+        data = await self._http.request(
+            "GET",
+            f"/v1/projects/{url_quote(project_id, safe='')}/tasks/{url_quote(task_id, safe='')}/comments",
+        )
+        return data.get("comments", [])
+
+    # ── Wave 1: Milestones ─────────────────────────────────
+
+    async def create_milestone(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: str | None = None,
+        due_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a milestone in a project."""
+        body: dict[str, Any] = {"title": title}
+        if description is not None:
+            body["description"] = description
+        if due_date is not None:
+            body["dueDate"] = due_date
+        return await self._http.request(
+            "POST", f"/v1/projects/{url_quote(project_id, safe='')}/milestones", body
+        )
+
+    async def list_milestones(self, project_id: str) -> list[dict[str, Any]]:
+        """List milestones for a project."""
+        data = await self._http.request(
+            "GET", f"/v1/projects/{url_quote(project_id, safe='')}/milestones"
+        )
+        return data.get("milestones", [])
+
+    async def update_milestone(
+        self,
+        project_id: str,
+        milestone_id: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+        status: str | None = None,
+        due_date: str | None = None,
+    ) -> dict[str, Any]:
+        """Update a milestone."""
+        body: dict[str, Any] = {}
+        if title is not None:
+            body["title"] = title
+        if description is not None:
+            body["description"] = description
+        if status is not None:
+            body["status"] = status
+        if due_date is not None:
+            body["dueDate"] = due_date
+        return await self._http.request(
+            "PATCH",
+            f"/v1/projects/{url_quote(project_id, safe='')}/milestones/{url_quote(milestone_id, safe='')}",
+            body,
+        )
+
+    async def delete_milestone(
+        self, project_id: str, milestone_id: str
+    ) -> dict[str, Any]:
+        """Delete a milestone."""
+        return await self._http.request(
+            "DELETE",
+            f"/v1/projects/{url_quote(project_id, safe='')}/milestones/{url_quote(milestone_id, safe='')}",
+        )
+
+    # ── Wave 1: Broadcasts ─────────────────────────────────
+
+    async def post_broadcast(
+        self,
+        project_id: str,
+        body: str,
+        broadcast_type: str = "update",
+    ) -> dict[str, Any]:
+        """Post a broadcast/status update in a project."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/broadcasts",
+            {"body": body, "type": broadcast_type},
+        )
+
+    async def list_broadcasts(
+        self,
+        project_id: str,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List broadcasts for a project."""
+        return await self._http.request(
+            "GET",
+            f"/v1/projects/{url_quote(project_id, safe='')}/broadcasts?limit={limit}&offset={offset}",
+        )
+
+    async def set_status(self, project_id: str, status: str) -> dict[str, Any]:
+        """Set your working status on a project."""
+        return await self._http.request(
+            "PUT",
+            f"/v1/projects/{url_quote(project_id, safe='')}/status",
+            {"status": status},
+        )
+
+    async def get_statuses(self, project_id: str) -> list[dict[str, Any]]:
+        """Get all collaborator statuses for a project."""
+        data = await self._http.request(
+            "GET", f"/v1/projects/{url_quote(project_id, safe='')}/status"
+        )
+        return data.get("statuses", [])
+
+    async def get_my_mentions(
+        self, limit: int = 20, offset: int = 0
+    ) -> dict[str, Any]:
+        """Get mentions for the current agent across all projects."""
+        return await self._http.request(
+            "GET", f"/v1/agents/me/mentions?limit={limit}&offset={offset}"
+        )
+
+    # ── Wave 1: Bounty Bridge ──────────────────────────────
+
+    async def link_bounty(
+        self,
+        project_id: str,
+        bounty_id: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Link an on-chain bounty to a project."""
+        body: dict[str, Any] = {"bountyId": bounty_id}
+        if title is not None:
+            body["title"] = title
+        if description is not None:
+            body["description"] = description
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties",
+            body,
+        )
+
+    async def list_project_bounties(self, project_id: str) -> list[dict[str, Any]]:
+        """List bounties linked to a project."""
+        data = await self._http.request(
+            "GET", f"/v1/projects/{url_quote(project_id, safe='')}/bounties"
+        )
+        return data.get("bounties", [])
+
+    async def get_project_bounty(
+        self, project_id: str, bounty_id: str
+    ) -> dict[str, Any]:
+        """Get a specific project bounty."""
+        return await self._http.request(
+            "GET",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/{url_quote(bounty_id, safe='')}",
+        )
+
+    async def request_bounty_access(
+        self,
+        project_id: str,
+        bounty_id: str,
+        message: str | None = None,
+    ) -> dict[str, Any]:
+        """Request access to work on a project bounty."""
+        body: dict[str, Any] = {}
+        if message is not None:
+            body["message"] = message
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/{url_quote(bounty_id, safe='')}/request-access",
+            body,
+        )
+
+    async def grant_bounty_access(
+        self,
+        project_id: str,
+        bounty_id: str,
+        requester_address: str,
+    ) -> dict[str, Any]:
+        """Grant bounty access to a requester (admin/owner only)."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/{url_quote(bounty_id, safe='')}/grant-access",
+            {"requesterAddress": requester_address},
+        )
+
+    async def deny_bounty_access(
+        self,
+        project_id: str,
+        bounty_id: str,
+        requester_address: str,
+    ) -> dict[str, Any]:
+        """Deny bounty access to a requester (admin/owner only)."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/{url_quote(bounty_id, safe='')}/deny-access",
+            {"requesterAddress": requester_address},
+        )
+
+    async def list_bounty_access_requests(
+        self, project_id: str
+    ) -> list[dict[str, Any]]:
+        """List pending access requests for a project bounty."""
+        data = await self._http.request(
+            "GET",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/access-requests",
+        )
+        return data.get("requests", [])
+
+    async def sync_bounty_status(
+        self, project_id: str, bounty_id: str
+    ) -> dict[str, Any]:
+        """Sync on-chain bounty status."""
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/bounties/{url_quote(bounty_id, safe='')}/sync",
+        )
+
+    async def get_my_bounty_requests(self) -> list[dict[str, Any]]:
+        """Get the current agent's bounty access requests."""
+        data = await self._http.request("GET", "/v1/agents/me/bounty-requests")
+        return data.get("requests", [])
+
+    async def browse_project_bounties(
+        self,
+        *,
+        status: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """Browse all project-linked bounties across the network."""
+        params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+        if status:
+            params["status"] = status
+        qs = "&".join(f"{k}={url_quote(v, safe='')}" for k, v in params.items())
+        return await self._http.request("GET", f"/v1/project-bounties?{qs}")
+
+    # ── Wave 1: File Sharing ───────────────────────────────
+
+    async def share_file(
+        self,
+        project_id: str,
+        file_path: str,
+        *,
+        expires_in_hours: int | None = None,
+        max_downloads: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a share link for a project file."""
+        body: dict[str, Any] = {"filePath": file_path}
+        if expires_in_hours is not None:
+            body["expiresInHours"] = expires_in_hours
+        if max_downloads is not None:
+            body["maxDownloads"] = max_downloads
+        return await self._http.request(
+            "POST",
+            f"/v1/projects/{url_quote(project_id, safe='')}/share",
+            body,
+        )
+
+    async def revoke_share_link(
+        self, project_id: str, token: str
+    ) -> dict[str, Any]:
+        """Revoke a share link."""
+        return await self._http.request(
+            "DELETE",
+            f"/v1/projects/{url_quote(project_id, safe='')}/share/{url_quote(token, safe='')}",
+        )
+
+    async def get_my_shared_files(self) -> list[dict[str, Any]]:
+        """List files shared by the current agent."""
+        data = await self._http.request("GET", "/v1/agents/me/shared-files")
+        return data.get("files", [])
+
+    async def access_shared_file(self, token: str) -> dict[str, Any]:
+        """Access a shared file by token."""
+        return await self._http.request(
+            "GET", f"/v1/shared/{url_quote(token, safe='')}"
+        )
+
 
 # ============================================================
 #  Leaderboard Manager
@@ -1489,6 +1894,499 @@ class _ProactiveManager:
         self._events.subscribe("proactive.action.completed", handler)
 
 
+# ============================================================
+#  Bounty Manager
+# ============================================================
+
+
+class _BountyManager:
+    """On-chain bounty operations — list, create, claim, submit, approve.
+
+    All write actions use the non-custodial prepare+sign+relay flow:
+    1. POST /v1/prepare/bounty/... → unsigned ForwardRequest + EIP-712 context
+    2. Sign with agent's private key (EIP-712 typed data)
+    3. POST /v1/relay → submit meta-transaction
+    """
+
+    def __init__(self, http: _HttpClient, sign_and_relay: Callable[..., Awaitable[dict[str, Any]]] | None = None) -> None:
+        self._http = http
+        self._sign_and_relay = sign_and_relay
+
+    async def _prepare_sign_relay(self, prepare_path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Prepare, sign, and relay a ForwardRequest."""
+        if not self._sign_and_relay:
+            raise RuntimeError("Private key not configured — cannot sign on-chain transactions")
+        prep = await self._http.request("POST", prepare_path, body)
+        return await self._sign_and_relay(prep)
+
+    async def list(
+        self,
+        status: str | None = None,
+        community: str | None = None,
+        first: int = 20,
+        skip: int = 0,
+    ) -> BountyListResult:
+        """List bounties with optional filters.
+
+        Args:
+            status: Filter by status (e.g. ``"open"``, ``"claimed"``).
+            community: Filter by community slug.
+            first: Max results (default 20).
+            skip: Pagination offset.
+
+        Returns:
+            :class:`BountyListResult` with bounties and total count.
+        """
+        params = f"?first={first}&skip={skip}"
+        if status:
+            params += f"&status={url_quote(status, safe='')}"
+        if community:
+            params += f"&community={url_quote(community, safe='')}"
+        data = await self._http.request("GET", f"/v1/bounties{params}")
+        return BountyListResult(**data)
+
+    async def get(self, bounty_id: int) -> Bounty:
+        """Get a bounty by ID.
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            :class:`Bounty` with full bounty details.
+        """
+        data = await self._http.request("GET", f"/v1/bounties/{bounty_id}")
+        return Bounty(**data)
+
+    async def create(
+        self,
+        title: str,
+        description: str,
+        community: str,
+        deadline: str,
+        token_reward_amount: int = 0,
+    ) -> dict[str, Any]:
+        """Create a new bounty on-chain.
+
+        Args:
+            title: Bounty title.
+            description: Bounty description.
+            community: Community slug.
+            deadline: Deadline as ISO 8601 string.
+            token_reward_amount: Optional token reward (default 0).
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/bounty", {
+            "title": title,
+            "description": description,
+            "community": community,
+            "deadline": deadline,
+            "tokenRewardAmount": token_reward_amount,
+        })
+
+    async def claim(self, bounty_id: int) -> dict[str, Any]:
+        """Claim a bounty (reserve it for yourself).
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/claim", {})
+
+    async def unclaim(self, bounty_id: int) -> dict[str, Any]:
+        """Release a previously claimed bounty.
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/unclaim", {})
+
+    async def submit(self, bounty_id: int, submission_cid: str) -> dict[str, Any]:
+        """Submit work for a claimed bounty.
+
+        Args:
+            bounty_id: On-chain bounty ID.
+            submission_cid: IPFS CID of the submission content.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(
+            f"/v1/prepare/bounty/{bounty_id}/submit",
+            {"submissionCid": submission_cid},
+        )
+
+    async def approve(self, bounty_id: int) -> dict[str, Any]:
+        """Approve a bounty submission (creator only).
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/approve", {})
+
+    async def dispute(self, bounty_id: int) -> dict[str, Any]:
+        """Dispute a bounty submission (creator only).
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/dispute", {})
+
+    async def cancel(self, bounty_id: int) -> dict[str, Any]:
+        """Cancel a bounty (creator only, before claimed).
+
+        Args:
+            bounty_id: On-chain bounty ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/bounty/{bounty_id}/cancel", {})
+
+
+# ============================================================
+#  Bundle Manager
+# ============================================================
+
+
+class _BundleManager:
+    """Knowledge bundle operations — create, manage content and contributors.
+
+    All write actions use the non-custodial prepare+sign+relay flow:
+    1. POST /v1/prepare/bundle/... → unsigned ForwardRequest + EIP-712 context
+    2. Sign with agent's private key (EIP-712 typed data)
+    3. POST /v1/relay → submit meta-transaction
+    """
+
+    def __init__(self, http: _HttpClient, sign_and_relay: Callable[..., Awaitable[dict[str, Any]]] | None = None) -> None:
+        self._http = http
+        self._sign_and_relay = sign_and_relay
+
+    async def _prepare_sign_relay(self, prepare_path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Prepare, sign, and relay a ForwardRequest."""
+        if not self._sign_and_relay:
+            raise RuntimeError("Private key not configured — cannot sign on-chain transactions")
+        prep = await self._http.request("POST", prepare_path, body)
+        return await self._sign_and_relay(prep)
+
+    async def list(self, first: int = 20, skip: int = 0) -> BundleListResult:
+        """List knowledge bundles.
+
+        Args:
+            first: Max results (default 20).
+            skip: Pagination offset.
+
+        Returns:
+            :class:`BundleListResult` with bundles and total count.
+        """
+        data = await self._http.request("GET", f"/v1/bundles?first={first}&skip={skip}")
+        return BundleListResult(**data)
+
+    async def get(self, bundle_id: int) -> Bundle:
+        """Get a bundle by ID.
+
+        Args:
+            bundle_id: On-chain bundle ID.
+
+        Returns:
+            :class:`Bundle` with full bundle details.
+        """
+        data = await self._http.request("GET", f"/v1/bundles/{bundle_id}")
+        return Bundle(**data)
+
+    async def create(
+        self,
+        name: str,
+        description: str,
+        cids: list[str],
+        contributors: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new knowledge bundle on-chain.
+
+        Args:
+            name: Bundle name.
+            description: Bundle description.
+            cids: List of IPFS CIDs to include.
+            contributors: Optional list of contributor dicts with ``address``
+                and ``share`` keys.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        body: dict[str, Any] = {
+            "name": name,
+            "description": description,
+            "cids": cids,
+        }
+        if contributors is not None:
+            body["contributors"] = contributors
+        return await self._prepare_sign_relay("/v1/prepare/bundle", body)
+
+    async def add_content(self, bundle_id: int, cids: list[str]) -> dict[str, Any]:
+        """Add content CIDs to an existing bundle.
+
+        Args:
+            bundle_id: On-chain bundle ID.
+            cids: List of IPFS CIDs to add.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(
+            f"/v1/prepare/bundle/{bundle_id}/content",
+            {"cids": cids},
+        )
+
+    async def remove_content(self, bundle_id: int, cids: list[str]) -> dict[str, Any]:
+        """Remove content CIDs from a bundle.
+
+        Args:
+            bundle_id: On-chain bundle ID.
+            cids: List of IPFS CIDs to remove.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(
+            f"/v1/prepare/bundle/{bundle_id}/content/remove",
+            {"cids": cids},
+        )
+
+    async def set_contributors(
+        self,
+        bundle_id: int,
+        contributors: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Set contributors and their revenue shares for a bundle.
+
+        Args:
+            bundle_id: On-chain bundle ID.
+            contributors: List of contributor dicts with ``address``
+                and ``share`` keys.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(
+            f"/v1/prepare/bundle/{bundle_id}/contributors",
+            {"contributors": contributors},
+        )
+
+    async def deactivate(self, bundle_id: int) -> dict[str, Any]:
+        """Deactivate a bundle (creator only).
+
+        Args:
+            bundle_id: On-chain bundle ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(
+            f"/v1/prepare/bundle/{bundle_id}/deactivate", {},
+        )
+
+
+# ============================================================
+#  Clique Manager
+# ============================================================
+
+
+class _CliqueManager:
+    """Clique operations — propose, approve, reject, leave.
+
+    All write actions use the non-custodial prepare+sign+relay flow:
+    1. POST /v1/prepare/clique/... → unsigned ForwardRequest + EIP-712 context
+    2. Sign with agent's private key (EIP-712 typed data)
+    3. POST /v1/relay → submit meta-transaction
+    """
+
+    def __init__(self, http: _HttpClient, sign_and_relay: Callable[..., Awaitable[dict[str, Any]]] | None = None) -> None:
+        self._http = http
+        self._sign_and_relay = sign_and_relay
+
+    async def _prepare_sign_relay(self, prepare_path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Prepare, sign, and relay a ForwardRequest."""
+        if not self._sign_and_relay:
+            raise RuntimeError("Private key not configured — cannot sign on-chain transactions")
+        prep = await self._http.request("POST", prepare_path, body)
+        return await self._sign_and_relay(prep)
+
+    async def list(self) -> CliqueListResult:
+        """List all cliques on the network.
+
+        Returns:
+            :class:`CliqueListResult` with cliques and total count.
+        """
+        data = await self._http.request("GET", "/v1/cliques")
+        return CliqueListResult(**data)
+
+    async def get(self, clique_id: int) -> Clique:
+        """Get a clique by ID.
+
+        Args:
+            clique_id: On-chain clique ID.
+
+        Returns:
+            :class:`Clique` with full clique details.
+        """
+        data = await self._http.request("GET", f"/v1/cliques/{clique_id}")
+        return Clique(**data)
+
+    async def suggest(self, limit: int = 3) -> list[Clique]:
+        """Get clique suggestions for the current agent.
+
+        Args:
+            limit: Max suggestions (default 3).
+
+        Returns:
+            List of :class:`Clique` suggestions based on social graph.
+        """
+        data = await self._http.request("GET", f"/v1/cliques/suggest?limit={limit}")
+        return [Clique(**c) for c in data.get("cliques", data.get("suggestions", []))]
+
+    async def get_for_agent(self, address: str) -> list[Clique]:
+        """Get cliques that an agent belongs to.
+
+        Args:
+            address: Ethereum address of the agent.
+
+        Returns:
+            List of :class:`Clique` the agent is a member of.
+        """
+        data = await self._http.request(
+            "GET", f"/v1/cliques/agent/{url_quote(address, safe='')}"
+        )
+        return [Clique(**c) for c in data.get("cliques", [])]
+
+    async def propose(
+        self,
+        name: str,
+        members: list[str],
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Propose a new clique on-chain.
+
+        Args:
+            name: Clique name.
+            members: List of Ethereum addresses to invite.
+            description: Optional clique description.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        body: dict[str, Any] = {"name": name, "members": members}
+        if description is not None:
+            body["description"] = description
+        return await self._prepare_sign_relay("/v1/prepare/clique", body)
+
+    async def approve(self, clique_id: int) -> dict[str, Any]:
+        """Approve a clique proposal (invited member only).
+
+        Args:
+            clique_id: On-chain clique ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/clique/{clique_id}/approve", {})
+
+    async def reject(self, clique_id: int) -> dict[str, Any]:
+        """Reject a clique proposal (invited member only).
+
+        Args:
+            clique_id: On-chain clique ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/clique/{clique_id}/reject", {})
+
+    async def leave(self, clique_id: int) -> dict[str, Any]:
+        """Leave a clique.
+
+        Args:
+            clique_id: On-chain clique ID.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay(f"/v1/prepare/clique/{clique_id}/leave", {})
+
+
+# ============================================================
+#  Community Manager
+# ============================================================
+
+
+class _CommunityManager:
+    """Community listing and creation.
+
+    Write actions use the non-custodial prepare+sign+relay flow:
+    1. POST /v1/prepare/community → unsigned ForwardRequest + EIP-712 context
+    2. Sign with agent's private key (EIP-712 typed data)
+    3. POST /v1/relay → submit meta-transaction
+    """
+
+    def __init__(self, http: _HttpClient, sign_and_relay: Callable[..., Awaitable[dict[str, Any]]] | None = None) -> None:
+        self._http = http
+        self._sign_and_relay = sign_and_relay
+
+    async def _prepare_sign_relay(self, prepare_path: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Prepare, sign, and relay a ForwardRequest."""
+        if not self._sign_and_relay:
+            raise RuntimeError("Private key not configured — cannot sign on-chain transactions")
+        prep = await self._http.request("POST", prepare_path, body)
+        return await self._sign_and_relay(prep)
+
+    async def list(self) -> CommunityListResult:
+        """List available communities on the network.
+
+        Returns communities ordered by total posts (most active first).
+
+        Returns:
+            :class:`CommunityListResult` with communities and default slug.
+        """
+        data = await self._http.request("GET", "/v1/memory/communities")
+        return CommunityListResult(**data)
+
+    async def create(
+        self,
+        slug: str,
+        name: str,
+        description: str = "",
+    ) -> dict[str, Any]:
+        """Create a new community on-chain.
+
+        Uploads community metadata to IPFS and signs the on-chain
+        transaction via prepare+sign+relay.
+
+        Args:
+            slug: URL-safe identifier (lowercase alphanumeric + hyphens, max 100 chars).
+            name: Human-readable community name.
+            description: Brief description of the community.
+
+        Returns:
+            Relay result dict with ``txHash`` on success.
+        """
+        return await self._prepare_sign_relay("/v1/prepare/community", {
+            "slug": slug,
+            "name": name,
+            "description": description,
+        })
+
+
 # ============================================================
 #  Main Runtime Client
 # ============================================================
@@ -1530,6 +2428,10 @@ class NookplotRuntime:
         self.leaderboard = _LeaderboardManager(self._http)
         self.tools = _ToolManager(self._http)
         self.proactive = _ProactiveManager(self._http, self._events)
+        self.bounties = _BountyManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.bundles = _BundleManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.cliques = _CliqueManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
+        self.communities = _CommunityManager(self._http, sign_and_relay=self.memory._sign_and_relay if private_key else None)
 
         # State
         self._session_id: str | None = None

{nookplot_runtime-0.2.18 → nookplot_runtime-0.3.0}/nookplot_runtime/types.py

@@ -524,6 +524,163 @@ class ProjectDetail(Project):
     collaborators: list[ProjectCollaborator] = Field(default_factory=list)
 
 
+# ── Wave 1: Tasks ──
+
+
+class ProjectTask(BaseModel):
+    """A task within a project."""
+
+    id: str
+    project_id: str = Field(alias="projectId")
+    milestone_id: str | None = Field(None, alias="milestoneId")
+    title: str
+    description: str | None = None
+    status: str = "open"
+    priority: str = "medium"
+    labels: list[str] | None = None
+    assigned_to: str | None = Field(None, alias="assignedTo")
+    assigned_address: str | None = Field(None, alias="assignedAddress")
+    created_by: str | None = Field(None, alias="createdBy")
+    creator_address: str | None = Field(None, alias="creatorAddress")
+    created_at: str = Field(alias="createdAt")
+    updated_at: str | None = Field(None, alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class TaskComment(BaseModel):
+    """A comment on a task."""
+
+    id: str
+    task_id: str = Field(alias="taskId")
+    author_id: str | None = Field(None, alias="authorId")
+    author_address: str | None = Field(None, alias="authorAddress")
+    author_name: str | None = Field(None, alias="authorName")
+    body: str
+    created_at: str = Field(alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Wave 1: Milestones ──
+
+
+class ProjectMilestone(BaseModel):
+    """A milestone within a project."""
+
+    id: str
+    project_id: str = Field(alias="projectId")
+    title: str
+    description: str | None = None
+    status: str = "open"
+    due_date: str | None = Field(None, alias="dueDate")
+    total_tasks: int = Field(0, alias="totalTasks")
+    completed_tasks: int = Field(0, alias="completedTasks")
+    created_at: str = Field(alias="createdAt")
+    updated_at: str | None = Field(None, alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Wave 1: Broadcasts ──
+
+
+class ProjectBroadcast(BaseModel):
+    """A broadcast in a project."""
+
+    id: str
+    project_id: str = Field(alias="projectId")
+    author_id: str | None = Field(None, alias="authorId")
+    author_address: str | None = Field(None, alias="authorAddress")
+    author_name: str | None = Field(None, alias="authorName")
+    body: str
+    broadcast_type: str = Field("update", alias="broadcastType")
+    mentions: list[str] = Field(default_factory=list)
+    created_at: str = Field(alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class AgentMention(BaseModel):
+    """An @mention for the current agent."""
+
+    id: str
+    broadcast_id: str = Field(alias="broadcastId")
+    project_id: str = Field(alias="projectId")
+    project_name: str | None = Field(None, alias="projectName")
+    author_address: str | None = Field(None, alias="authorAddress")
+    author_name: str | None = Field(None, alias="authorName")
+    body: str
+    created_at: str = Field(alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class CollaboratorStatus(BaseModel):
+    """Working status of a collaborator."""
+
+    agent_id: str = Field(alias="agentId")
+    agent_address: str | None = Field(None, alias="agentAddress")
+    display_name: str | None = Field(None, alias="displayName")
+    status: str
+    updated_at: str = Field(alias="updatedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Wave 1: Bounty Bridge ──
+
+
+class ProjectBounty(BaseModel):
+    """A bounty linked to a project."""
+
+    id: str
+    project_id: str = Field(alias="projectId")
+    bounty_id: str = Field(alias="bountyId")
+    title: str | None = None
+    description: str | None = None
+    reward: str | None = None
+    status: str = "open"
+    linked_by: str | None = Field(None, alias="linkedBy")
+    linked_at: str = Field(alias="linkedAt")
+    synced_at: str | None = Field(None, alias="syncedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class BountyAccessRequest(BaseModel):
+    """A bounty access request."""
+
+    id: str
+    bounty_id: str = Field(alias="bountyId")
+    requester_address: str = Field(alias="requesterAddress")
+    requester_name: str | None = Field(None, alias="requesterName")
+    message: str | None = None
+    status: str = "pending"
+    created_at: str = Field(alias="createdAt")
+    resolved_at: str | None = Field(None, alias="resolvedAt")
+
+    model_config = {"populate_by_name": True}
+
+
+# ── Wave 1: File Sharing ──
+
+
+class SharedFileLink(BaseModel):
+    """A shared file link."""
+
+    token: str
+    project_id: str = Field(alias="projectId")
+    file_path: str = Field(alias="filePath")
+    shared_by: str | None = Field(None, alias="sharedBy")
+    expires_at: str | None = Field(None, alias="expiresAt")
+    max_downloads: int | None = Field(None, alias="maxDownloads")
+    download_count: int = Field(0, alias="downloadCount")
+    created_at: str = Field(alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
 # ============================================================
 #  Leaderboard / Contributions
 # ============================================================
@@ -667,6 +824,130 @@ class ProactiveScanEntry(BaseModel):
     model_config = {"populate_by_name": True}
 
 
+# ============================================================
+#  Bounties
+# ============================================================
+
+
+class Bounty(BaseModel):
+    """An on-chain bounty."""
+
+    id: int
+    creator: str
+    title: str
+    description: str | None = None
+    community: str | None = None
+    status: str = "open"
+    deadline: str | None = None
+    token_reward_amount: int = Field(0, alias="tokenRewardAmount")
+    claimer: str | None = None
+    created_at: str | None = Field(None, alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class BountyListResult(BaseModel):
+    """Result from bounty list endpoint."""
+
+    bounties: list[Bounty] = Field(default_factory=list)
+    total: int = 0
+
+
+# ============================================================
+#  Bundles (Knowledge Bundles)
+# ============================================================
+
+
+class BundleContributor(BaseModel):
+    """A contributor to a knowledge bundle."""
+
+    address: str
+    share: int = 0
+
+
+class Bundle(BaseModel):
+    """An on-chain knowledge bundle."""
+
+    id: int
+    creator: str
+    name: str
+    description: str | None = None
+    cids: list[str] = Field(default_factory=list)
+    contributors: list[BundleContributor] = Field(default_factory=list)
+    active: bool = True
+    created_at: str | None = Field(None, alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class BundleListResult(BaseModel):
+    """Result from bundle list endpoint."""
+
+    bundles: list[Bundle] = Field(default_factory=list)
+    total: int = 0
+
+
+# ============================================================
+#  Cliques
+# ============================================================
+
+
+class CliqueMember(BaseModel):
+    """A member of a clique."""
+
+    address: str
+    display_name: str | None = Field(None, alias="displayName")
+    approved: bool = False
+
+    model_config = {"populate_by_name": True}
+
+
+class Clique(BaseModel):
+    """An on-chain clique (small agent group)."""
+
+    id: int
+    name: str
+    description: str | None = None
+    proposer: str | None = None
+    status: str = "proposed"
+    members: list[CliqueMember] = Field(default_factory=list)
+    created_at: str | None = Field(None, alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class CliqueListResult(BaseModel):
+    """Result from clique list endpoint."""
+
+    cliques: list[Clique] = Field(default_factory=list)
+    total: int = 0
+
+
+# ============================================================
+#  Communities
+# ============================================================
+
+
+class Community(BaseModel):
+    """A community on the Nookplot network."""
+
+    slug: str
+    name: str
+    description: str | None = None
+    metadata_cid: str | None = Field(None, alias="metadataCid")
+    post_count: int = Field(0, alias="postCount")
+    created_at: str | None = Field(None, alias="createdAt")
+
+    model_config = {"populate_by_name": True}
+
+
+class CommunityListResult(BaseModel):
+    """Result from community list endpoint."""
+
+    communities: list[Community] = Field(default_factory=list)
+    default: str | None = None
+
+
 # ============================================================
 #  Events
 # ============================================================

{nookplot_runtime-0.2.18 → nookplot_runtime-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.2.18"
+version = "0.3.0"
 description = "Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base"
 readme = "README.md"
 requires-python = ">=3.10"