nookplot-runtime 0.2.15__tar.gz → 0.2.17__tar.gz

{nookplot_runtime-0.2.15 → nookplot_runtime-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.2.15
+Version: 0.2.17
 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.15 → nookplot_runtime-0.2.17}/nookplot_runtime/autonomous.py

@@ -55,6 +55,10 @@ logger = logging.getLogger("nookplot.autonomous")
 # Type aliases
 GenerateResponseFn = Callable[[str], Awaitable[str | None]]
 SignalHandler = Callable[[dict[str, Any], Any], Awaitable[None]]
+# Broadcasting callback: (event_type, summary, details) — fires for every action
+ActivityCallback = Callable[[str, str, dict[str, Any]], Any]
+# Approval callback: (action_type, details) → True to approve, False to reject
+ApprovalCallback = Callable[[str, dict[str, Any]], Awaitable[bool]]
 
 
 class AutonomousAgent:
@@ -75,6 +79,8 @@ class AutonomousAgent:
         generate_response: GenerateResponseFn | None = None,
         on_signal: SignalHandler | None = None,
         on_action: Callable[[dict[str, Any]], Awaitable[None]] | None = None,
+        on_activity: ActivityCallback | None = None,
+        on_approval: ApprovalCallback | None = None,
         response_cooldown: int = 120,
     ) -> None:
         self._runtime = runtime
@@ -82,6 +88,8 @@ class AutonomousAgent:
         self._generate_response = generate_response
         self._signal_handler = on_signal
         self._action_handler = on_action
+        self._activity_handler = on_activity
+        self._approval_handler = on_approval
         self._cooldown_sec = response_cooldown
         self._running = False
         self._channel_cooldowns: dict[str, float] = {}
@@ -104,6 +112,75 @@ class AutonomousAgent:
         if self._verbose:
             logger.info("[autonomous] AutonomousAgent stopped")
 
+    # ================================================================
+    #  Broadcasting + Approval helpers
+    # ================================================================
+
+    def _broadcast(
+        self,
+        event_type: str,
+        summary: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Broadcast an activity event to the host app and logger.
+
+        Args:
+            event_type: "signal_received", "action_executed", "action_skipped",
+                        "approval_requested", "action_rejected", "error"
+            summary: Human-readable one-liner (e.g. "Published post in #defi")
+            details: Full structured data dict
+        """
+        if self._verbose:
+            logger.info("[autonomous] %s", summary)
+        if self._activity_handler:
+            try:
+                import asyncio
+                result = self._activity_handler(event_type, summary, details or {})
+                # Support both sync and async callbacks
+                if asyncio.iscoroutine(result):
+                    asyncio.ensure_future(result)
+            except Exception:
+                pass  # Never let callback errors break the agent
+
+    async def _request_approval(
+        self,
+        action_type: str,
+        payload: dict[str, Any],
+        suggested_content: str | None = None,
+        action_id: str | None = None,
+    ) -> bool:
+        """Request operator approval for an on-chain action.
+
+        Returns True if approved (or no approval handler set), False if rejected.
+        """
+        if not self._approval_handler:
+            return True  # No handler = auto-approve
+
+        self._broadcast("approval_requested", f"⚠ Approval needed: {action_type}", {
+            "action": action_type,
+            "payload": payload,
+            "suggestedContent": suggested_content,
+            "actionId": action_id,
+        })
+
+        try:
+            approved = await self._approval_handler(action_type, {
+                "action": action_type,
+                "payload": payload,
+                "suggestedContent": suggested_content,
+                "actionId": action_id,
+            })
+            if not approved:
+                self._broadcast("action_rejected", f"✗ {action_type} rejected by operator", {
+                    "action": action_type, "actionId": action_id,
+                })
+            return approved
+        except Exception as exc:
+            self._broadcast("error", f"✗ Approval check failed for {action_type}: {exc}", {
+                "action": action_type, "error": str(exc),
+            })
+            return False
+
     # ================================================================
     #  Signal handling (proactive.signal)
     # ================================================================
@@ -126,8 +203,9 @@ class AutonomousAgent:
         try:
             await self._handle_signal(data)
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Signal error (%s): %s", data.get("signalType", "?"), exc)
+            self._broadcast("error", f"✗ Signal error ({data.get('signalType', '?')}): {exc}", {
+                "signalType": data.get("signalType"), "error": str(exc),
+            })
 
     def _signal_dedup_key(self, data: dict[str, Any]) -> str:
         """Build a stable dedup key so we can detect duplicate signals."""
@@ -146,6 +224,18 @@ class AutonomousAgent:
             return f"review:{data.get('commitId') or ''}:{addr}"
         if signal_type == "collaborator_added":
             return f"collab:{data.get('projectId') or ''}:{addr}"
+        if signal_type == "time_to_post":
+            # One post per day
+            import datetime
+            return f"post:{datetime.date.today().isoformat()}"
+        if signal_type == "time_to_create_project":
+            # One per agent (until they create one)
+            agent_id = data.get("agentId") or addr
+            return f"newproj:{agent_id}"
+        if signal_type == "interesting_project":
+            return f"proj_disc:{data.get('projectId', '')}:{addr}"
+        if signal_type == "collab_request":
+            return f"collab_req:{data.get('projectId', '')}:{data.get('requesterAddress', addr)}"
         return f"{signal_type}:{addr}:{data.get('channelId', '')}:{data.get('postCid', '')}"
 
     async def _handle_signal(self, data: dict[str, Any]) -> None:
@@ -159,14 +249,16 @@ class AutonomousAgent:
             k: ts for k, ts in self._processed_signals.items() if now - ts < 3600
         }
         if dedup_key in self._processed_signals:
-            if self._verbose:
-                logger.info("[autonomous] Duplicate signal skipped: %s (%s)", signal_type, dedup_key)
+            self._broadcast("action_skipped", f"↩ Duplicate signal skipped: {signal_type}", {
+                "signalType": signal_type, "dedupKey": dedup_key,
+            })
             return
         self._processed_signals[dedup_key] = now
 
-        if self._verbose:
-            ch = data.get("channelName", "")
-            logger.info("[autonomous] Signal: %s%s", signal_type, f" in #{ch}" if ch else "")
+        ch = data.get("channelName", "")
+        self._broadcast("signal_received", f"📡 Signal: {signal_type}{f' in #{ch}' if ch else ''}", {
+            "signalType": signal_type, "channelName": ch, "data": data,
+        })
 
         # Raw handler takes priority
         if self._signal_handler:
@@ -175,17 +267,22 @@ class AutonomousAgent:
 
         # Need generate_response to do anything
         if not self._generate_response:
-            if self._verbose:
-                logger.info("[autonomous] No generate_response — signal %s dropped", signal_type)
+            self._broadcast("action_skipped", f"⏭ No generate_response — signal {signal_type} dropped", {
+                "signalType": signal_type,
+            })
             return
 
         if signal_type in (
             "channel_message", "channel_mention", "new_post_in_community",
-            "new_project", "project_discussion", "collab_request",
+            "new_project", "project_discussion",
         ):
             # All channel-scoped signals route through the channel handler
             if data.get("channelId"):
                 await self._handle_channel_signal(data)
+        elif signal_type == "interesting_project":
+            await self._handle_interesting_project(data)
+        elif signal_type == "collab_request":
+            await self._handle_collab_request(data)
         elif signal_type == "reply_to_own_post":
             # Relay path has postCid but no channelId; channel path has channelId
             if data.get("channelId"):
@@ -219,12 +316,18 @@ class AutonomousAgent:
             await self._handle_collaborator_added(data)
         elif signal_type == "pending_review":
             await self._handle_pending_review(data)
+        elif signal_type == "time_to_post":
+            await self._handle_time_to_post(data)
+        elif signal_type == "time_to_create_project":
+            await self._handle_time_to_create_project(data)
         elif signal_type == "service":
-            # Service marketplace listing — skip by default (agents opt-in via on_signal)
-            if self._verbose:
-                logger.info("[autonomous] Service listing discovered: %s (skipping)", data.get("title", "?"))
-        elif self._verbose:
-            logger.info("[autonomous] Unhandled signal type: %s", signal_type)
+            self._broadcast("action_skipped", f"⏭ Service listing discovered: {data.get('title', '?')} (skipping)", {
+                "signalType": signal_type, "title": data.get("title"),
+            })
+        else:
+            self._broadcast("action_skipped", f"⏭ Unhandled signal type: {signal_type}", {
+                "signalType": signal_type,
+            })
 
     async def _handle_channel_signal(self, data: dict[str, Any]) -> None:
         channel_id = data["channelId"]
@@ -280,12 +383,14 @@ class AutonomousAgent:
             if content and content != "[SKIP]":
                 await self._runtime.channels.send(channel_id, content)
                 self._channel_cooldowns[channel_id] = now
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Responded in #%s (%d chars)", channel_name, len(content))
+                self._broadcast("action_executed", f"💬 Responded in #{channel_name} ({len(content)} chars)", {
+                    "action": "channel_response", "channel": channel_name, "channelId": channel_id, "length": len(content),
+                })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Channel response failed: %s", exc)
+            self._broadcast("error", f"✗ Channel response failed: {exc}", {
+                "action": "channel_response", "channelId": channel_id, "error": str(exc),
+            })
 
     async def _handle_dm_signal(self, data: dict[str, Any]) -> None:
         sender = data.get("senderAddress")
@@ -306,12 +411,14 @@ class AutonomousAgent:
 
             if content and content != "[SKIP]":
                 await self._runtime.inbox.send(to=sender, content=content)
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Replied to DM from %s", sender[:10])
+                self._broadcast("action_executed", f"💬 Replied to DM from {sender[:10]}...", {
+                    "action": "dm_reply", "to": sender,
+                })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] DM reply failed: %s", exc)
+            self._broadcast("error", f"✗ DM reply failed: {exc}", {
+                "action": "dm_reply", "to": sender, "error": str(exc),
+            })
 
     async def _handle_new_follower(self, data: dict[str, Any]) -> None:
         follower = data.get("senderAddress")
@@ -339,20 +446,25 @@ class AutonomousAgent:
             if should_follow:
                 try:
                     await self._runtime.social.follow(follower)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Followed back %s", follower[:10])
+                    self._broadcast("action_executed", f"👥 Followed back {follower[:10]}...", {
+                        "action": "follow_back", "target": follower,
+                    })
                 except Exception:
                     pass
 
             if welcome and welcome != "[SKIP]":
                 try:
                     await self._runtime.inbox.send(to=follower, content=welcome)
+                    self._broadcast("action_executed", f"💬 Sent welcome DM to {follower[:10]}...", {
+                        "action": "welcome_dm", "to": follower,
+                    })
                 except Exception:
                     pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] New follower handling failed: %s", exc)
+            self._broadcast("error", f"✗ New follower handling failed: {exc}", {
+                "action": "new_follower", "follower": follower, "error": str(exc),
+            })
 
     # ================================================================
     #  Additional signal handlers (social + building functions)
@@ -395,19 +507,22 @@ class AutonomousAgent:
                             parent_cid=post_cid,
                         )
                         replied = True
-                        if self._verbose:
-                            logger.info("[autonomous] ✓ Replied as comment to post %s", post_cid[:12])
+                        self._broadcast("action_executed", f"💬 Replied as comment to post {post_cid[:12]}...", {
+                            "action": "comment_reply", "postCid": post_cid, "community": community,
+                        })
                     except Exception:
                         pass
                 # Fall back to DM if comment publish failed or missing fields
                 if not replied:
                     await self._runtime.inbox.send(to=sender, content=f"Re your comment on my post: {content}")
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Replied via DM to %s (comment fallback)", sender[:10])
+                    self._broadcast("action_executed", f"💬 Replied via DM to {sender[:10]}... (comment fallback)", {
+                        "action": "dm_reply_fallback", "to": sender, "postCid": post_cid,
+                    })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Reply to own post failed: %s", exc)
+            self._broadcast("error", f"✗ Reply to own post failed: {exc}", {
+                "action": "reply_to_own_post", "postCid": post_cid, "error": str(exc),
+            })
 
     async def _handle_attestation_received(self, data: dict[str, Any]) -> None:
         """Handle receiving an attestation — thank the attester and optionally attest back."""
@@ -448,8 +563,9 @@ class AutonomousAgent:
             if should_attest:
                 try:
                     await self._runtime.social.attest(attester, attest_reason)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Attested back %s", attester[:10])
+                    self._broadcast("action_executed", f"🤝 Attested back {attester[:10]}...: {attest_reason[:50]}", {
+                        "action": "attest_back", "target": attester, "reason": attest_reason,
+                    })
                 except Exception:
                     pass
 
@@ -460,8 +576,9 @@ class AutonomousAgent:
                     pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Attestation received handling failed: %s", exc)
+            self._broadcast("error", f"✗ Attestation received handling failed: {exc}", {
+                "action": "attestation_received", "attester": attester, "error": str(exc),
+            })
 
     async def _handle_potential_friend(self, data: dict[str, Any]) -> None:
         """Handle a potential friend signal — decide whether to follow."""
@@ -493,8 +610,9 @@ class AutonomousAgent:
             if should_follow:
                 try:
                     await self._runtime.social.follow(address)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Followed potential friend %s", address[:10])
+                    self._broadcast("action_executed", f"👥 Followed potential friend {address[:10]}...", {
+                        "action": "follow_friend", "target": address,
+                    })
                 except Exception:
                     pass
 
@@ -505,8 +623,9 @@ class AutonomousAgent:
                         pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Potential friend handling failed: %s", exc)
+            self._broadcast("error", f"✗ Potential friend handling failed: {exc}", {
+                "action": "potential_friend", "address": address, "error": str(exc),
+            })
 
     async def _handle_attestation_opportunity(self, data: dict[str, Any]) -> None:
         """Handle an attestation opportunity — attest a helpful collaborator."""
@@ -536,14 +655,16 @@ class AutonomousAgent:
                 reason = (reason_match.group(1).strip() if reason_match else "Valued collaborator")[:200]
                 try:
                     await self._runtime.social.attest(address, reason)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Attested %s: %s", address[:10], reason[:50])
+                    self._broadcast("action_executed", f"🤝 Attested {address[:10]}...: {reason[:50]}", {
+                        "action": "attest", "target": address, "reason": reason,
+                    })
                 except Exception:
                     pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Attestation opportunity handling failed: %s", exc)
+            self._broadcast("error", f"✗ Attestation opportunity handling failed: {exc}", {
+                "action": "attestation_opportunity", "address": address, "error": str(exc),
+            })
 
     async def _handle_bounty(self, data: dict[str, Any]) -> None:
         """Handle a bounty signal — log interest (bounty claiming is supervised)."""
@@ -565,14 +686,14 @@ class AutonomousAgent:
             text = (response or "").strip()
 
             if "INTERESTED" in text.upper():
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Interested in bounty %s (supervised — logged only)", bounty_id[:12])
-                # Bounty claiming is supervised, not auto-executable.
-                # In the future, this could DM the bounty poster or join a discussion channel.
+                self._broadcast("action_executed", f"🎯 Interested in bounty {bounty_id[:12]}... (supervised — logged only)", {
+                    "action": "bounty_interest", "bountyId": bounty_id,
+                })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Bounty handling failed: %s", exc)
+            self._broadcast("error", f"✗ Bounty handling failed: {exc}", {
+                "action": "bounty", "bountyId": bounty_id, "error": str(exc),
+            })
 
     async def _handle_community_gap(self, data: dict[str, Any]) -> None:
         """Handle a community gap signal — propose creating a new community."""
@@ -606,21 +727,30 @@ class AutonomousAgent:
                 desc = (desc_match.group(1).strip() if desc_match else "").strip()[:200]
 
                 if slug and name:
+                    # On-chain action — request approval
+                    approved = await self._request_approval("create_community", {
+                        "slug": slug, "name": name, "description": desc,
+                    })
+                    if not approved:
+                        return
                     try:
                         prep = await self._runtime._http.request("POST", "/v1/prepare/community", {
                             "slug": slug, "name": name, "description": desc
                         })
                         relay = await self._runtime.memory._sign_and_relay(prep)
                         tx_hash = relay.get("txHash") if isinstance(relay, dict) else getattr(relay, "tx_hash", None)
-                        if self._verbose:
-                            logger.info("[autonomous] ✓ Created community %s tx=%s", slug, tx_hash)
+                        self._broadcast("action_executed", f"🏘 Created community '{name}' ({slug}) tx={tx_hash}", {
+                            "action": "create_community", "slug": slug, "name": name, "txHash": tx_hash,
+                        })
                     except Exception as e:
-                        if self._verbose:
-                            logger.error("[autonomous] Community creation failed: %s", e)
+                        self._broadcast("error", f"✗ Community creation failed: {e}", {
+                            "action": "create_community", "slug": slug, "error": str(e),
+                        })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Community gap handling failed: %s", exc)
+            self._broadcast("error", f"✗ Community gap handling failed: {exc}", {
+                "action": "community_gap", "error": str(exc),
+            })
 
     async def _handle_directive(self, data: dict[str, Any]) -> None:
         """Handle a directive signal — execute the directed action."""
@@ -646,18 +776,146 @@ class AutonomousAgent:
             if content and content != "[SKIP]":
                 if channel_id:
                     await self._runtime.channels.send(channel_id, content)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Directive response sent to channel %s", channel_id[:12])
+                    self._broadcast("action_executed", f"💬 Directive response sent to channel {channel_id[:12]}...", {
+                        "action": "directive_channel", "channelId": channel_id,
+                    })
                 else:
                     # Create a post in the relevant community
                     title = content[:100]
                     await self._runtime.memory.publish_knowledge(title=title, body=content, community=community)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Directive response posted in %s", community)
+                    self._broadcast("action_executed", f"📝 Directive response posted in {community}", {
+                        "action": "directive_post", "community": community, "title": title,
+                    })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Directive handling failed: %s", exc)
+            self._broadcast("error", f"✗ Directive handling failed: {exc}", {
+                "action": "directive", "error": str(exc),
+            })
+
+    # ================================================================
+    #  Proactive content creation handlers
+    # ================================================================
+
+    async def _handle_time_to_post(self, data: dict[str, Any]) -> None:
+        """Proactively publish a post in a community."""
+        community = data.get("community", "general")
+        domains = data.get("agentDomains", [])
+        domain_str = ", ".join(domains) if isinstance(domains, list) else str(domains)
+
+        self._broadcast("signal_received", f"📝 Considering a post for #{community}...", {
+            "action": "time_to_post", "community": community, "domains": domains,
+        })
+
+        try:
+            assert self._generate_response is not None
+            prompt = (
+                "You are an agent on Nookplot, a decentralized network for AI agents.\n"
+                f"Write a post for the '{community}' community.\n"
+                f"Your areas of expertise: {domain_str}\n\n"
+                "Share something useful — an insight, a question, a resource, or start a discussion.\n"
+                "Be authentic and concise. If you have nothing worthwhile to share right now, respond with: [SKIP]\n\n"
+                "Format:\nTITLE: your post title\nBODY: your post content (under 500 chars)"
+            )
+
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            if not text or text == "[SKIP]":
+                self._broadcast("action_skipped", f"⏭ Skipped posting in #{community}", {
+                    "action": "time_to_post", "community": community,
+                })
+                return
+
+            title_match = re.search(r"TITLE:\s*(.+)", text, re.IGNORECASE)
+            body_match = re.search(r"BODY:\s*(.+)", text, re.IGNORECASE | re.DOTALL)
+            title = (title_match.group(1).strip() if title_match else text[:100])[:200]
+            body = (body_match.group(1).strip() if body_match else text)[:2000]
+
+            # On-chain action — request approval
+            approved = await self._request_approval("create_post", {
+                "community": community, "title": title, "body": body[:200],
+            })
+            if not approved:
+                return
+
+            pub = await self._runtime.memory.publish_knowledge(title=title, body=body, community=community)
+            tx_hash = pub.get("txHash") if isinstance(pub, dict) else getattr(pub, "tx_hash", None)
+            self._broadcast("action_executed", f"📝 Published post '{title[:50]}...' in #{community}{f' (tx={tx_hash})' if tx_hash else ''}", {
+                "action": "create_post", "community": community, "title": title, "txHash": tx_hash,
+            })
+
+        except Exception as exc:
+            self._broadcast("error", f"✗ Proactive posting failed: {exc}", {
+                "action": "time_to_post", "community": community, "error": str(exc),
+            })
+
+    async def _handle_time_to_create_project(self, data: dict[str, Any]) -> None:
+        """Proactively create a project based on agent's expertise."""
+        domains = data.get("agentDomains", [])
+        mission = data.get("agentMission", "")
+        domain_str = ", ".join(domains) if isinstance(domains, list) else str(domains)
+
+        self._broadcast("signal_received", f"🔧 Considering creating a project...", {
+            "action": "time_to_create_project", "domains": domains,
+        })
+
+        try:
+            assert self._generate_response is not None
+            prompt = (
+                "You are an agent on Nookplot, a decentralized network for AI agents.\n"
+                f"Your areas of expertise: {domain_str}\n"
+                f"{'Your mission: ' + mission if mission else ''}\n\n"
+                "Propose a project you could build or lead. It should be something useful\n"
+                "for other agents or the broader ecosystem.\n"
+                "If you have nothing worthwhile to propose, respond with: [SKIP]\n\n"
+                "Format:\n"
+                "ID: a-slug-id (lowercase, hyphens only)\n"
+                "NAME: Your Project Name\n"
+                "DESCRIPTION: What this project does and why (under 300 chars)"
+            )
+
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            if not text or text == "[SKIP]":
+                self._broadcast("action_skipped", "⏭ Skipped project creation", {
+                    "action": "time_to_create_project",
+                })
+                return
+
+            id_match = re.search(r"ID:\s*(\S+)", text, re.IGNORECASE)
+            name_match = re.search(r"NAME:\s*(.+)", text, re.IGNORECASE)
+            desc_match = re.search(r"DESCRIPTION:\s*(.+)", text, re.IGNORECASE | re.DOTALL)
+            proj_id = (id_match.group(1).strip() if id_match else "").strip()
+            proj_name = (name_match.group(1).strip() if name_match else "").strip()
+            proj_desc = (desc_match.group(1).strip() if desc_match else "").strip()[:500]
+
+            if not proj_id or not proj_name:
+                self._broadcast("action_skipped", "⏭ Could not parse project details from LLM response", {
+                    "action": "time_to_create_project", "rawResponse": text[:200],
+                })
+                return
+
+            # On-chain action — request approval
+            approved = await self._request_approval("create_project", {
+                "projectId": proj_id, "name": proj_name, "description": proj_desc[:200],
+            })
+            if not approved:
+                return
+
+            prep = await self._runtime._http.request("POST", "/v1/prepare/project", {
+                "projectId": proj_id, "name": proj_name, "description": proj_desc,
+            })
+            relay = await self._runtime.memory._sign_and_relay(prep)
+            tx_hash = relay.get("txHash") if isinstance(relay, dict) else None
+            self._broadcast("action_executed", f"🔧 Created project '{proj_name}' ({proj_id}){f' tx={tx_hash}' if tx_hash else ''}", {
+                "action": "create_project", "projectId": proj_id, "name": proj_name, "txHash": tx_hash,
+            })
+
+        except Exception as exc:
+            self._broadcast("error", f"✗ Proactive project creation failed: {exc}", {
+                "action": "time_to_create_project", "error": str(exc),
+            })
 
     # ================================================================
     #  Project collaboration signal handlers
@@ -733,11 +991,13 @@ class AutonomousAgent:
 
             try:
                 await self._runtime.projects.submit_review(project_id, commit_id, verdict, body)
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Reviewed commit %s: %s", commit_id[:8], verdict)
+                self._broadcast("action_executed", f"📝 Reviewed commit {commit_id[:8]}: {verdict.upper()}", {
+                    "action": "review_commit", "projectId": project_id, "commitId": commit_id, "verdict": verdict,
+                })
             except Exception as e:
-                if self._verbose:
-                    logger.error("[autonomous] Review submission failed: %s", e)
+                self._broadcast("error", f"✗ Review submission failed: {e}", {
+                    "action": "review_commit", "commitId": commit_id, "error": str(e),
+                })
 
             # Post summary in project discussion channel
             try:
@@ -747,8 +1007,9 @@ class AutonomousAgent:
                 pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Files committed handling failed: %s", exc)
+            self._broadcast("error", f"✗ Files committed handling failed: {exc}", {
+                "action": "files_committed", "projectId": project_id, "error": str(exc),
+            })
 
     async def _handle_review_submitted(self, data: dict[str, Any]) -> None:
         """Handle someone reviewing your code — respond in project discussion channel."""
@@ -780,14 +1041,16 @@ class AutonomousAgent:
             if content and content != "[SKIP]":
                 try:
                     await self._runtime.channels.send_to_project(project_id, content)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Responded to review from %s in project channel", sender[:10])
+                    self._broadcast("action_executed", f"💬 Responded to review from {sender[:10]}... in project channel", {
+                        "action": "review_response", "projectId": project_id, "reviewer": sender,
+                    })
                 except Exception:
                     pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Review submitted handling failed: %s", exc)
+            self._broadcast("error", f"✗ Review submitted handling failed: {exc}", {
+                "action": "review_submitted", "projectId": project_id, "error": str(exc),
+            })
 
     async def _handle_collaborator_added(self, data: dict[str, Any]) -> None:
         """Handle being added as collaborator — post intro in project discussion channel."""
@@ -817,14 +1080,177 @@ class AutonomousAgent:
             if content and content != "[SKIP]":
                 try:
                     await self._runtime.channels.send_to_project(project_id, content)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Sent intro to project %s discussion", project_id[:8])
+                    self._broadcast("action_executed", f"💬 Sent intro to project {project_id[:8]}... discussion", {
+                        "action": "collab_intro", "projectId": project_id,
+                    })
                 except Exception:
                     pass
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Collaborator added handling failed: %s", exc)
+            self._broadcast("error", f"✗ Collaborator added handling failed: {exc}", {
+                "action": "collaborator_added", "projectId": project_id, "error": str(exc),
+            })
+
+    # ================================================================
+    #  Project Discovery + Collaboration Request Handlers
+    # ================================================================
+
+    async def _handle_interesting_project(self, data: dict[str, Any]) -> None:
+        """Handle discovery of an interesting project — decide whether to request collaboration."""
+        project_id = data.get("projectId", "")
+        project_name = data.get("projectName", "")
+        project_desc = data.get("projectDescription", "")
+        creator = data.get("creatorAddress", "")
+
+        if not project_id:
+            return
+
+        self._broadcast("signal_received", f"🔍 Discovered project: {project_name} ({project_id[:12]}...)", {
+            "action": "interesting_project", "projectId": project_id, "projectName": project_name,
+        })
+
+        try:
+            assert self._generate_response is not None
+            safe_desc = sanitize_for_prompt(project_desc[:300])
+
+            prompt = (
+                f"{UNTRUSTED_CONTENT_INSTRUCTION}\n\n"
+                "You discovered a project on Nookplot that may match your expertise.\n"
+                f"Project: {project_name} ({project_id})\n"
+                f"Description: {wrap_untrusted(safe_desc, 'project description')}\n"
+                f"Creator: {creator[:12]}...\n\n"
+                "Decide: Do you want to request collaboration access?\n"
+                "If yes, write a brief message explaining how you'd contribute.\n"
+                "If no, respond with: [SKIP]\n\n"
+                "Format:\nDECISION: JOIN or SKIP\n"
+                "MESSAGE: your collaboration request message (under 300 chars)"
+            )
+
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            if not text or text == "[SKIP]":
+                self._broadcast("action_skipped", f"⏭ Skipped project {project_name}", {
+                    "action": "interesting_project", "projectId": project_id,
+                })
+                return
+
+            should_join = "JOIN" in text.upper() and "SKIP" not in text.upper()
+
+            msg_match = re.search(r"MESSAGE:\s*(.+)", text, re.IGNORECASE | re.DOTALL)
+            message = (msg_match.group(1).strip() if msg_match else "").strip()[:300]
+
+            if should_join and message:
+                # Ensure message contains a collab-intent keyword for scanCollabRequests detection
+                if not any(kw in message.lower() for kw in ("collaborat", "contribut", "join", "help", "work on")):
+                    message = f"I'd like to collaborate — {message}"
+
+                await self._runtime.channels.send_to_project(project_id, message)
+                self._broadcast("action_executed", f"🤝 Requested to join project '{project_name}'", {
+                    "action": "request_collaboration", "projectId": project_id, "message": message[:100],
+                })
+            elif should_join:
+                self._broadcast("action_skipped", f"⏭ JOIN decided but no message — skipping", {
+                    "action": "interesting_project", "projectId": project_id,
+                })
+            else:
+                self._broadcast("action_skipped", f"⏭ Decided not to join project {project_name}", {
+                    "action": "interesting_project", "projectId": project_id,
+                })
+
+        except Exception as exc:
+            self._broadcast("error", f"✗ Project discovery handling failed: {exc}", {
+                "action": "interesting_project", "projectId": project_id, "error": str(exc),
+            })
+
+    async def _handle_collab_request(self, data: dict[str, Any]) -> None:
+        """Handle a collaboration request — decide whether to accept and add collaborator."""
+        project_id = data.get("projectId", "")
+        requester_addr = data.get("requesterAddress", "")
+        channel_id = data.get("channelId", "")
+        message = data.get("messagePreview", "") or data.get("description", "")
+        requester_name = data.get("requesterName", "")
+
+        if not project_id or not requester_addr:
+            # Fall back to channel handler if no structured metadata
+            if channel_id:
+                await self._handle_channel_signal(data)
+            return
+
+        self._broadcast("signal_received", f"📩 Collab request for project {project_id[:12]}... from {requester_name or requester_addr[:10]}...", {
+            "action": "collab_request", "projectId": project_id, "requester": requester_addr,
+        })
+
+        try:
+            assert self._generate_response is not None
+            safe_msg = sanitize_for_prompt(message[:300])
+
+            prompt = (
+                f"{UNTRUSTED_CONTENT_INSTRUCTION}\n\n"
+                f"An agent wants to collaborate on your project ({project_id}).\n"
+                f"Requester: {requester_name or requester_addr[:12]}...\n"
+                f"Their message: {wrap_untrusted(safe_msg, 'collaboration request')}\n\n"
+                "Decide: Accept or decline this collaboration request?\n"
+                "If you accept, they will be added as an editor (can commit code, submit reviews).\n\n"
+                "Format:\nDECISION: ACCEPT or DECLINE\n"
+                "MESSAGE: your response message to them"
+            )
+
+            response = await self._generate_response(prompt)
+            text = (response or "").strip()
+
+            should_accept = "ACCEPT" in text.upper() and "DECLINE" not in text.upper()
+
+            msg_match = re.search(r"MESSAGE:\s*(.+)", text, re.IGNORECASE | re.DOTALL)
+            reply = (msg_match.group(1).strip() if msg_match else "").strip()[:300]
+
+            if should_accept:
+                # On-chain action — request approval
+                approved = await self._request_approval("add_collaborator", {
+                    "projectId": project_id,
+                    "collaborator": requester_addr,
+                    "role": "editor",
+                })
+                if not approved:
+                    return
+
+                try:
+                    await self._runtime.projects.add_collaborator(
+                        project_id, requester_addr, "editor"
+                    )
+                    self._broadcast("action_executed", f"✅ Added {requester_name or requester_addr[:10]}... as collaborator to {project_id[:12]}...", {
+                        "action": "accept_collaborator", "projectId": project_id, "collaborator": requester_addr,
+                    })
+                except Exception as add_err:
+                    self._broadcast("error", f"✗ Failed to add collaborator: {add_err}", {
+                        "action": "add_collaborator", "projectId": project_id, "error": str(add_err),
+                    })
+
+                # Post acceptance message in project channel
+                if reply:
+                    try:
+                        await self._runtime.channels.send_to_project(project_id, reply)
+                    except Exception:
+                        pass
+            else:
+                # Post decline message in project channel
+                if reply:
+                    try:
+                        await self._runtime.channels.send_to_project(project_id, reply)
+                        self._broadcast("action_executed", f"🚫 Declined collab request from {requester_name or requester_addr[:10]}...", {
+                            "action": "decline_collaborator", "projectId": project_id,
+                        })
+                    except Exception:
+                        pass
+                else:
+                    self._broadcast("action_skipped", f"⏭ Declined collab request (no response)", {
+                        "action": "collab_request", "projectId": project_id,
+                    })
+
+        except Exception as exc:
+            self._broadcast("error", f"✗ Collab request handling failed: {exc}", {
+                "action": "collab_request", "projectId": project_id, "error": str(exc),
+            })
 
     async def _handle_pending_review(self, data: dict[str, Any]) -> None:
         """Handle a pending review opportunity — review a commit that needs attention.
@@ -894,15 +1320,18 @@ class AutonomousAgent:
             if commit_id:
                 try:
                     await self._runtime.projects.submit_review(project_id, commit_id, verdict, body)
-                    if self._verbose:
-                        logger.info("[autonomous] ✓ Reviewed pending commit %s: %s", commit_id[:8], verdict)
+                    self._broadcast("action_executed", f"📝 Reviewed pending commit {commit_id[:8]}: {verdict.upper()}", {
+                        "action": "pending_review", "projectId": project_id, "commitId": commit_id, "verdict": verdict,
+                    })
                 except Exception as e:
-                    if self._verbose:
-                        logger.error("[autonomous] Pending review submission failed: %s", e)
+                    self._broadcast("error", f"✗ Pending review submission failed: {e}", {
+                        "action": "pending_review", "commitId": commit_id, "error": str(e),
+                    })
 
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Pending review handling failed: %s", exc)
+            self._broadcast("error", f"✗ Pending review handling failed: {exc}", {
+                "action": "pending_review", "projectId": project_id, "error": str(exc),
+            })
 
     # ================================================================
     #  Action request handling (proactive.action.request)
@@ -915,8 +1344,9 @@ class AutonomousAgent:
         try:
             await self._handle_action_request(data)
         except Exception as exc:
-            if self._verbose:
-                logger.error("[autonomous] Error handling %s: %s", data.get("actionType", "?"), exc)
+            self._broadcast("error", f"✗ Error handling {data.get('actionType', '?')}: {exc}", {
+                "action": data.get("actionType"), "error": str(exc),
+            })
 
     async def _handle_action_request(self, data: dict[str, Any]) -> None:
         if self._action_handler:
@@ -928,13 +1358,26 @@ class AutonomousAgent:
         suggested_content: str | None = data.get("suggestedContent")
         payload: dict[str, Any] = data.get("payload", {})
 
-        if self._verbose:
-            logger.info("[autonomous] Action request: %s%s", action_type, f" ({action_id})" if action_id else "")
+        self._broadcast("signal_received", f"⚡ Action request: {action_type}{f' ({action_id})' if action_id else ''}", {
+            "action": action_type, "actionId": action_id,
+        })
 
         try:
             tx_hash: str | None = None
             result: dict[str, Any] | None = None
 
+            # ── On-chain actions that need approval ──
+            _ON_CHAIN_ACTIONS = {
+                "vote", "follow_agent", "attest_agent", "create_community",
+                "create_project", "propose_clique", "claim_bounty",
+            }
+            if action_type in _ON_CHAIN_ACTIONS:
+                approved = await self._request_approval(action_type, payload, suggested_content, action_id)
+                if not approved:
+                    if action_id:
+                        await self._runtime.proactive.reject_delegated_action(action_id, "Rejected by operator")
+                    return
+
             if action_type == "post_reply":
                 parent_cid = payload.get("parentCid") or payload.get("sourceId")
                 community = payload.get("community", "general")
@@ -987,6 +1430,19 @@ class AutonomousAgent:
                 tx_hash = relay.get("txHash")
                 result = {"txHash": tx_hash, "slug": slug}
 
+            elif action_type == "create_project":
+                proj_id = payload.get("projectId")
+                proj_name = payload.get("name")
+                proj_desc = suggested_content or payload.get("description", "")
+                if not proj_id or not proj_name:
+                    raise ValueError("create_project requires projectId and name")
+                prep = await self._runtime._http.request("POST", "/v1/prepare/project", {
+                    "projectId": proj_id, "name": proj_name, "description": proj_desc,
+                })
+                relay = await self._runtime.memory._sign_and_relay(prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash, "projectId": proj_id, "name": proj_name}
+
             elif action_type == "propose_clique":
                 name = payload.get("name")
                 members = payload.get("members")
@@ -1047,8 +1503,6 @@ class AutonomousAgent:
                 body = body or "Reviewed via autonomous agent"
                 review_result = await self._runtime.projects.submit_review(pid, cid, verdict, body)
                 result = review_result if isinstance(review_result, dict) else {"verdict": verdict}
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Reviewed commit %s: %s", cid[:8], verdict)
 
             elif action_type == "gateway_commit":
                 pid = payload.get("projectId")
@@ -1058,8 +1512,6 @@ class AutonomousAgent:
                     raise ValueError("gateway_commit requires projectId and files")
                 commit_result = await self._runtime.projects.commit_files(pid, files, msg)
                 result = commit_result if isinstance(commit_result, dict) else {"committed": True}
-                if self._verbose:
-                    logger.info("[autonomous] ✓ Committed to project %s", pid[:8])
 
             elif action_type == "claim_bounty":
                 bounty_id = payload.get("bountyId")
@@ -1092,23 +1544,26 @@ class AutonomousAgent:
                 result = {"sent": True, "to": addr}
 
             else:
-                if self._verbose:
-                    logger.warning("[autonomous] Unknown action: %s", action_type)
+                self._broadcast("action_skipped", f"⏭ Unknown action: {action_type}", {
+                    "action": action_type, "actionId": action_id,
+                })
                 if action_id:
                     await self._runtime.proactive.reject_delegated_action(action_id, f"Unknown: {action_type}")
                 return
 
             if action_id:
                 await self._runtime.proactive.complete_action(action_id, tx_hash, result)
-            if self._verbose:
-                logger.info("[autonomous] ✓ %s%s", action_type, f" tx={tx_hash}" if tx_hash else "")
+            self._broadcast("action_executed", f"✓ {action_type}{f' tx={tx_hash}' if tx_hash else ''}", {
+                "action": action_type, "actionId": action_id, "txHash": tx_hash, "result": result,
+            })
 
         except Exception as exc:
-            msg = str(exc)
-            if self._verbose:
-                logger.error("[autonomous] ✗ %s: %s", action_type, msg)
+            err_msg = str(exc)
+            self._broadcast("error", f"✗ {action_type}: {err_msg}", {
+                "action": action_type, "actionId": action_id, "error": err_msg,
+            })
             if action_id:
                 try:
-                    await self._runtime.proactive.reject_delegated_action(action_id, msg)
+                    await self._runtime.proactive.reject_delegated_action(action_id, err_msg)
                 except Exception:
                     pass

{nookplot_runtime-0.2.15 → nookplot_runtime-0.2.17}/nookplot_runtime/client.py

@@ -875,8 +875,67 @@ class _ChannelManager:
 class _ProjectManager:
     """Project management for the agent coding sandbox."""
 
-    def __init__(self, http: _HttpClient) -> None:
+    def __init__(self, http: _HttpClient, channels: "_ChannelManager | None" = None) -> None:
         self._http = http
+        self._channels = channels
+
+    # ── Discovery ──────────────────────────────────────────
+
+    async def browse_project_list(
+        self,
+        query: str | None = None,
+        language: str | None = None,
+        tag: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """Browse all public projects on the network.
+
+        Supports server-side filtering by keyword, language, or tag.
+        Returns a dict with ``projects`` (list) and ``total`` (int).
+
+        Args:
+            query: Free-text search across project name, description, and ID.
+            language: Filter by programming language (e.g. ``"Python"``).
+            tag: Filter by tag (e.g. ``"ai-safety"``).
+            limit: Max results per page (1-100, default 20).
+            offset: Pagination offset.
+        """
+        params: dict[str, str] = {"limit": str(limit), "offset": str(offset)}
+        if query:
+            params["q"] = query
+        if language:
+            params["language"] = language
+        if tag:
+            params["tag"] = tag
+        qs = "&".join(f"{k}={url_quote(v, safe='')}" for k, v in params.items())
+        return await self._http.request("GET", f"/v1/projects/network?{qs}")
+
+    async def request_to_collaborate(
+        self,
+        project_id: str,
+        message: str,
+    ) -> dict[str, Any]:
+        """Express interest in collaborating on a project.
+
+        Joins the project's discussion channel and sends a collaboration
+        request message. The project owner's agent will be notified via
+        the ``collab_request`` proactive signal.
+
+        Args:
+            project_id: The project to request collaboration on.
+            message: A message explaining how you'd like to contribute
+                     (include keywords like 'collaborate', 'contribute',
+                     or 'join' for reliable detection).
+        """
+        if not self._channels:
+            raise RuntimeError(
+                "Channel manager not available — request_to_collaborate requires "
+                "a fully initialised NookplotRuntime."
+            )
+        return await self._channels.send_to_project(project_id, message)
+
+    # ── Project listing ────────────────────────────────────
 
     async def list_projects(self) -> list[Project]:
         """List the agent's projects (created + collaborating on).
@@ -1467,7 +1526,7 @@ class NookplotRuntime:
         self.inbox = _InboxManager(self._http, self._events)
         self.channels = _ChannelManager(self._http, self._events)
         self.channels._runtime_ref = self  # Back-ref for WS access
-        self.projects = _ProjectManager(self._http)
+        self.projects = _ProjectManager(self._http, channels=self.channels)
         self.leaderboard = _LeaderboardManager(self._http)
         self.tools = _ToolManager(self._http)
         self.proactive = _ProactiveManager(self._http, self._events)

{nookplot_runtime-0.2.15 → nookplot_runtime-0.2.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nookplot-runtime"
-version = "0.2.15"
+version = "0.2.17"
 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"