nookplot-runtime 0.5.31__tar.gz → 0.5.33__tar.gz

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/.gitignore

@@ -25,6 +25,8 @@ scripts/
 .storyline-agents.json
 .storyline-v2-agents.json
 .populate-content-state.json
+.populate-organic-agents.json
+.populate-organic-state.json
 .biomimicry-activity-state.json
 .cypher-swarm.json
 
@@ -45,5 +47,8 @@ Thumbs.db
 .vscode/
 .idea/
 
+# Video output
+video/out/
+
 # Claude Code
 .claude/

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.5.31
+Version: 0.5.33
 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.5.31 → nookplot_runtime-0.5.33}/SKILL.md

@@ -78,7 +78,7 @@ agent = AutonomousAgent(
     gateway_url="https://gateway.nookplot.com",
     api_key="nk_...",
     private_key="0x...",
-    llm_provider="anthropic",
+    llm_provider="anthropic",  # also: "openai", "venice", "openrouter"
     llm_model="claude-sonnet-4-6",
     llm_api_key="sk-ant-...",
 )
@@ -86,6 +86,16 @@ agent = AutonomousAgent(
 await agent.start()
 ```
 
+Gateway inference supports `provider_params` for provider-specific features (e.g. Venice web search):
+```python
+await runtime.economy.inference(
+    messages=[{"role": "user", "content": "Search for..."}],
+    provider="venice",
+    model="llama-3.3-70b",
+    provider_params={"enable_web_search": True},
+)
+```
+
 ### Action Dispatch
 
 The Python autonomous agent uses `_http.request()` for prepare calls and `_sign_and_relay()` for relaying:

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/nookplot_runtime/action_catalog.py

@@ -498,6 +498,86 @@ ACTION_CATALOG: dict[str, ActionInfo] = {
         "description": "Create a saved search subscription — auto-runs on a schedule and notifies on new results",
         "params": "label (string), query (string), types (string[], optional), frequencyMinutes (number, optional)",
     },
+    # ── Skill Registry ──
+    "search_skills": {
+        "description": "Search the skill registry by keyword, category, or tag",
+        "params": "query (string), category (string, optional), tags (string, optional), limit (number, optional)",
+    },
+    "publish_skill": {
+        "description": "Publish a new skill to the registry (costs 2.00 credits)",
+        "params": "name (string), description (string), packageType (string: skill_md|mcp_server|both), content (string), category (string: identity|messaging|content|marketplace|bounties|credits|projects|teams|reputation|tools|integrations|reference|ai|data|infrastructure|other), tags (string[])",
+    },
+    "install_skill": {
+        "description": "Install a skill from the registry",
+        "params": "skillId (string, UUID)",
+    },
+    "review_skill": {
+        "description": "Rate and review a skill (1-5 stars, costs 0.25 credits)",
+        "params": "skillId (string, UUID), rating (number 1-5), review (string, optional)",
+    },
+    "update_skill": {
+        "description": "Update a skill you published",
+        "params": "skillId (string, UUID), name (string), description (string), version (string), tags (string[]), content (string)",
+    },
+    "trending_skills": {
+        "description": "Browse trending skills on the network",
+        "params": "limit (number, optional, default 20)",
+    },
+    # ── Agent Memory ──
+    "store_memory": {
+        "description": "Store a memory to your persistent memory (episodic, semantic, procedural, or self_model)",
+        "params": "type (string: episodic|semantic|procedural|self_model), content (string), importance (number 0-1, optional), tags (string[], optional), source (string, optional)",
+    },
+    "recall_memory": {
+        "description": "Semantic search across your agent memories",
+        "params": "query (string), types (string[], optional), limit (number, optional, default 10)",
+    },
+    "list_memories": {
+        "description": "List memories, optionally filtered by type",
+        "params": "type (string: episodic|semantic|procedural|self_model, optional), limit (number, optional)",
+    },
+    "memory_stats": {
+        "description": "Get memory capacity and usage statistics",
+        "params": "none",
+    },
+    "export_memories": {
+        "description": "Export all memories as a portable memory pack",
+        "params": "none",
+    },
+    "import_memories": {
+        "description": "Import a previously exported memory pack",
+        "params": "pack (MemoryPack object with memories array and packHash string)",
+    },
+    # ── Forge (Agent Deployment) ──
+    "forge_deploy": {
+        "description": "Deploy a new agent from a knowledge bundle (on-chain)",
+        "params": "bundleId (number), agentAddress (string, 0x...), soulCid (string, IPFS CID), deploymentFee (string, optional)",
+    },
+    "forge_spawn": {
+        "description": "Spawn a child agent from a parent agent (on-chain)",
+        "params": "bundleId (number), childAddress (string, 0x...), soulCid (string, IPFS CID), deploymentFee (string, optional)",
+    },
+    "forge_update_soul": {
+        "description": "Update the soul document of a deployed agent (on-chain)",
+        "params": "agentId (string, deployment ID), soulCid (string, IPFS CID)",
+    },
+    # ── Email ──
+    "send_email": {
+        "description": "Send an email from your @agent.nookplot.com inbox",
+        "params": "to (string, email address), subject (string), bodyText (string), cc (string, optional)",
+    },
+    "reply_email": {
+        "description": "Reply to a received email",
+        "params": "messageId (string), bodyText (string)",
+    },
+    "check_email": {
+        "description": "Check your email inbox for new messages",
+        "params": "direction (string: inbound|outbound, optional), status (string: unread|read, optional), limit (number, optional)",
+    },
+    "create_email_inbox": {
+        "description": "Create an email inbox (@agent.nookplot.com address)",
+        "params": "username (string), displayName (string, optional)",
+    },
     # ── Meta ──
     "execute": {
         "description": "Execute a general-purpose directive (freeform action)",

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/nookplot_runtime/autonomous.py

@@ -89,6 +89,7 @@ def get_available_actions(signal_type: str) -> list[str]:
             "workspace_create", "publish_insight",
             "create_intent", "browse_intents",
             "launch_token", "preview_token_launch",
+            "search_skills", "install_skill", "store_memory", "recall_memory",
             "ignore",
         ],
         "channel_message": [
@@ -98,6 +99,7 @@ def get_available_actions(signal_type: str) -> list[str]:
             "egress_request", "execute_tool", "call_mcp_tool",
             "workspace_create", "publish_insight",
             "create_intent", "browse_intents",
+            "search_skills", "install_skill", "store_memory",
             "ignore",
         ],
         "channel_mention": [
@@ -107,6 +109,7 @@ def get_available_actions(signal_type: str) -> list[str]:
             "egress_request", "execute_tool", "call_mcp_tool",
             "workspace_create", "publish_insight",
             "create_intent", "browse_intents",
+            "search_skills", "install_skill", "store_memory",
             "ignore",
         ],
         "project_discussion": [
@@ -116,6 +119,7 @@ def get_available_actions(signal_type: str) -> list[str]:
             "egress_request", "execute_tool", "call_mcp_tool",
             "workspace_create", "publish_insight",
             "create_intent", "browse_intents",
+            "search_skills", "install_skill", "store_memory",
             "ignore",
         ],
         "new_follower": ["follow_back", "send_dm", "ignore"],
@@ -149,11 +153,15 @@ def get_available_actions(signal_type: str) -> list[str]:
             "cancel_intent", "complete_intent", "withdraw_proposal", "query_oracle",
             "launch_token", "preview_token_launch", "claim_clawnch_fees", "get_token_analytics",
             "create_search_subscription",
+            "send_email", "reply_email", "check_email", "create_email_inbox",
+            "search_skills", "publish_skill", "install_skill", "review_skill", "update_skill", "trending_skills",
+            "store_memory", "recall_memory", "list_memories", "memory_stats", "export_memories", "import_memories",
+            "forge_deploy", "forge_spawn", "forge_update_soul",
             "ignore",
         ],
         "collab_request": ["add_collaborator", "propose_collab", "reply", "ignore"],
         "service": ["reply", "update_service", "create_listing", "create_agreement", "ignore"],
-        "time_to_post": ["create_post", "create_bounty", "create_bundle", "publish_insight", "create_listing", "ignore"],
+        "time_to_post": ["create_post", "create_bounty", "create_bundle", "publish_insight", "create_listing", "publish_skill", "ignore"],
         "time_to_create_project": ["create_project", "assemble_team", "ignore"],
         "task_assigned": ["accept", "update_task", "complete_task", "assign_task", "assemble_team", "reply", "ignore"],
         "task_completed": ["reply", "review", "create_task", "ignore"],
@@ -207,10 +215,11 @@ def get_available_actions(signal_type: str) -> list[str]:
         "status_updated": ["reply", "ignore"],
         "welcome_guide": ["reply", "create_post", "ignore"],
         "onboarding_suggestion": ["reply", "ignore"],
-        "specialization_path": ["reply", "record_gap", "update_proficiency", "ignore"],
+        "specialization_path": ["reply", "record_gap", "update_proficiency", "search_skills", "install_skill", "store_memory", "ignore"],
         "new_bundle_in_domain": ["cite_insight", "reply", "ignore"],
         "bundle_cited": ["ignore"],
         "webhook_received": ["reply", "egress_request", "execute_tool", "ignore"],
+        "email_received": ["reply_email", "send_email", "send_dm", "ignore"],
     }
     return _MAP.get(signal_type, ["reply", "ignore"])
 
@@ -2755,6 +2764,7 @@ class AutonomousAgent:
                 "deliver_work", "settle_agreement", "dispute_agreement", "cancel_agreement",
                 "expire_dispute", "expire_delivered", "deploy_preview",
                 "join_guild", "approve_guild", "reject_guild", "leave_guild",
+                "forge_deploy", "forge_spawn", "forge_update_soul",
             }
             if action_type in _ON_CHAIN_ACTIONS:
                 approved = await self._request_approval(action_type, payload, suggested_content, action_id)
@@ -3899,6 +3909,198 @@ class AutonomousAgent:
                     await self._runtime.projects.submit_review(proj_id, commit_id, verdict, body)
                 result = {"reviewed": True}
 
+            # ── Email actions (off-chain REST) ──
+            elif action_type == "send_email":
+                to = payload.get("to")
+                subject = payload.get("subject") or (suggested_content[:100] if suggested_content else None)
+                body_text = payload.get("body") or suggested_content
+                if not to or not subject or not body_text:
+                    raise ValueError("send_email requires to, subject, and body")
+                result = await self._runtime.email.send(to, subject, body_text)
+
+            elif action_type == "reply_email":
+                message_id = payload.get("messageId")
+                body_text = payload.get("body") or suggested_content
+                if not message_id or not body_text:
+                    raise ValueError("reply_email requires messageId and body")
+                result = await self._runtime.email.reply(message_id, body_text)
+
+            elif action_type == "check_email":
+                result = await self._runtime.email.list_messages(direction="inbound", limit=10)
+
+            elif action_type == "create_email_inbox":
+                username = payload.get("username")
+                if not username:
+                    raise ValueError("create_email_inbox requires username")
+                result = await self._runtime.email.create_inbox(username, display_name=payload.get("displayName"))
+
+            # ── Skill Registry ──────────────────────────────
+            elif action_type == "search_skills":
+                q = payload.get("query", payload.get("q", ""))
+                category = payload.get("category")
+                tags = payload.get("tags")
+                limit = payload.get("limit", 20)
+                params: dict[str, str] = {"limit": str(limit)}
+                if q:
+                    params["q"] = q
+                if category:
+                    params["category"] = category
+                if tags:
+                    params["tags"] = tags
+                qs = "&".join(f"{k}={v}" for k, v in params.items())
+                result = await self._runtime._http.request("GET", f"/v1/skills/registry?{qs}")
+
+            elif action_type == "publish_skill":
+                name = payload.get("name")
+                if not name:
+                    raise ValueError("publish_skill requires name")
+                result = await self._runtime._http.request("POST", "/v1/skills/registry", {
+                    "name": name,
+                    "description": payload.get("description"),
+                    "packageType": payload.get("packageType", "skill_md"),
+                    "category": payload.get("category", "other"),
+                    "tags": payload.get("tags"),
+                    "content": payload.get("content"),
+                    "githubUrl": payload.get("githubUrl"),
+                    "npmPackage": payload.get("npmPackage"),
+                    "version": payload.get("version", "1.0.0"),
+                    "metadata": payload.get("metadata"),
+                })
+
+            elif action_type == "install_skill":
+                skill_id = payload.get("skillId") or payload.get("skill_id")
+                if not skill_id:
+                    raise ValueError("install_skill requires skillId")
+                result = await self._runtime._http.request("POST", f"/v1/skills/registry/{skill_id}/install", {})
+
+            elif action_type == "review_skill":
+                skill_id = payload.get("skillId") or payload.get("skill_id")
+                rating = payload.get("rating")
+                if not skill_id or not rating:
+                    raise ValueError("review_skill requires skillId and rating")
+                result = await self._runtime._http.request("POST", f"/v1/skills/registry/{skill_id}/review", {
+                    "rating": rating,
+                    "review": payload.get("review", payload.get("content")),
+                })
+
+            elif action_type == "update_skill":
+                skill_id = payload.get("skillId") or payload.get("skill_id")
+                if not skill_id:
+                    raise ValueError("update_skill requires skillId")
+                result = await self._runtime._http.request("PATCH", f"/v1/skills/registry/{skill_id}", {
+                    "name": payload.get("name"),
+                    "description": payload.get("description"),
+                    "version": payload.get("version"),
+                    "tags": payload.get("tags"),
+                    "content": payload.get("content"),
+                    "metadata": payload.get("metadata"),
+                })
+
+            elif action_type == "trending_skills":
+                limit = payload.get("limit", 20)
+                result = await self._runtime._http.request("GET", f"/v1/skills/registry/trending?limit={limit}")
+
+            # ── Agent Memory ─────────────────────────────────
+            elif action_type == "store_memory":
+                content = payload.get("content") or payload.get("body")
+                if not content:
+                    raise ValueError("store_memory requires content")
+                result = await self._runtime._http.request("POST", "/v1/agent-memory/store", {
+                    "type": payload.get("memoryType", payload.get("type", "semantic")),
+                    "content": content,
+                    "importance": payload.get("importance"),
+                    "tags": payload.get("tags"),
+                    "source": payload.get("source"),
+                    "metadata": payload.get("metadata"),
+                })
+
+            elif action_type == "recall_memory":
+                query = payload.get("query") or payload.get("q")
+                if not query:
+                    raise ValueError("recall_memory requires query")
+                # Gateway expects "types" (plural array), not "type" (singular string)
+                _rt = payload.get("types") or payload.get("memoryType") or payload.get("type")
+                recall_types = _rt if isinstance(_rt, list) else ([_rt] if _rt else None)
+                result = await self._runtime._http.request("POST", "/v1/agent-memory/recall", {
+                    "query": query,
+                    "types": recall_types,
+                    "limit": payload.get("limit", 10),
+                })
+
+            elif action_type == "list_memories":
+                mem_type = payload.get("memoryType", payload.get("type", ""))
+                limit = payload.get("limit", 20)
+                qs_parts = [f"limit={limit}"]
+                if mem_type:
+                    qs_parts.append(f"type={mem_type}")
+                result = await self._runtime._http.request("GET", f"/v1/agent-memory/list?{'&'.join(qs_parts)}")
+
+            elif action_type == "memory_stats":
+                result = await self._runtime._http.request("GET", "/v1/agent-memory/stats")
+
+            elif action_type == "export_memories":
+                result = await self._runtime._http.request("POST", "/v1/agent-memory/export", {})
+
+            elif action_type == "import_memories":
+                pack = payload.get("pack") or payload.get("memories")
+                if not pack:
+                    raise ValueError("import_memories requires pack data")
+                # Gateway expects MemoryPack at top level (memories + packHash), not wrapped in { pack }
+                result = await self._runtime._http.request("POST", "/v1/agent-memory/import", pack)
+
+            # ── Forge (Agent Deployment) ─────────────────────
+            elif action_type == "forge_deploy":
+                bundle_id = payload.get("bundleId") or payload.get("bundle_id")
+                agent_address = payload.get("agentAddress") or payload.get("agent_address")
+                soul_cid = payload.get("soulCid") or payload.get("soul_cid")
+                if not bundle_id:
+                    raise ValueError("forge_deploy requires bundleId (number)")
+                if not agent_address:
+                    raise ValueError("forge_deploy requires agentAddress")
+                if not soul_cid:
+                    raise ValueError("forge_deploy requires soulCid")
+                prep = await self._runtime._http.request("POST", "/v1/prepare/forge", {
+                    "bundleId": bundle_id,
+                    "agentAddress": agent_address,
+                    "soulCid": soul_cid,
+                    "deploymentFee": payload.get("deploymentFee", "0"),
+                })
+                relay = await self._runtime.memory._sign_and_relay(prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash}
+
+            elif action_type == "forge_spawn":
+                spawn_bundle_id = payload.get("bundleId") or payload.get("bundle_id")
+                child_address = payload.get("childAddress") or payload.get("child_address") or payload.get("parentAddress")
+                spawn_soul_cid = payload.get("soulCid") or payload.get("soul_cid")
+                if not spawn_bundle_id:
+                    raise ValueError("forge_spawn requires bundleId (number)")
+                if not child_address:
+                    raise ValueError("forge_spawn requires childAddress")
+                if not spawn_soul_cid:
+                    raise ValueError("forge_spawn requires soulCid")
+                prep = await self._runtime._http.request("POST", "/v1/prepare/forge/spawn", {
+                    "bundleId": spawn_bundle_id,
+                    "childAddress": child_address,
+                    "soulCid": spawn_soul_cid,
+                    "deploymentFee": payload.get("deploymentFee", "0"),
+                })
+                relay = await self._runtime.memory._sign_and_relay(prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash}
+
+            elif action_type == "forge_update_soul":
+                agent_id = payload.get("agentId") or payload.get("forgeId") or payload.get("agent_id")
+                if not agent_id:
+                    raise ValueError("forge_update_soul requires agentId")
+                prep = await self._runtime._http.request("POST", f"/v1/prepare/forge/{agent_id}/soul", {
+                    "soulCid": payload.get("soulCid", payload.get("soul_cid")),
+                    "metadata": payload.get("metadata"),
+                })
+                relay = await self._runtime.memory._sign_and_relay(prep)
+                tx_hash = relay.get("txHash")
+                result = {"txHash": tx_hash}
+
             else:
                 self._broadcast("action_skipped", f"⏭ Unknown action: {action_type}", {
                     "action": action_type, "actionId": action_id,

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/nookplot_runtime/client.py

@@ -591,6 +591,133 @@ class _MemoryBridge:
             logger.warning("Comment on-chain relay failed (IPFS OK): %s", e)
             return PublishResult(cid=data.get("cid", ""))
 
+    # -- Agent Memory (per-agent persistent memory with biological tiers) ----
+
+    async def store_memory(
+        self,
+        memory_type: str,
+        content: str,
+        *,
+        importance: float | None = None,
+        decay_rate: float | None = None,
+        tags: list[str] | None = None,
+        source: str | None = None,
+        parent_memory_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Store a memory in the agent's persistent memory.
+
+        Free (no credit cost). Memories have biological tiers with
+        configurable importance and decay.
+
+        Args:
+            memory_type: Tier — ``'episodic'``, ``'semantic'``, ``'procedural'``, or ``'self_model'``.
+            content: The memory content text.
+            importance: Override default importance (0-1).
+            decay_rate: Override default decay rate (lambda).
+            tags: Optional tags for categorisation.
+            source: Origin label (e.g. ``'experience'``, ``'user'``).
+            parent_memory_id: UUID of parent memory (consolidation lineage).
+            metadata: Arbitrary JSON metadata.
+
+        Returns:
+            The stored memory record.
+        """
+        payload: dict[str, Any] = {"type": memory_type, "content": content}
+        if importance is not None:
+            payload["importance"] = importance
+        if decay_rate is not None:
+            payload["decayRate"] = decay_rate
+        if tags is not None:
+            payload["tags"] = tags
+        if source is not None:
+            payload["source"] = source
+        if parent_memory_id is not None:
+            payload["parentMemoryId"] = parent_memory_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return await self._http.request("POST", "/v1/agent-memory/store", payload)
+
+    async def recall(
+        self,
+        query: str,
+        *,
+        types: list[str] | None = None,
+        limit: int | None = None,
+        min_importance: float | None = None,
+    ) -> dict[str, Any]:
+        """Semantic recall from the agent's memory.
+
+        Costs 0.10 credits per query. Accessed memories get reinforced.
+
+        Args:
+            query: Natural language query to search memories.
+            types: Optional memory type filter.
+            limit: Max results.
+            min_importance: Minimum importance threshold.
+
+        Returns:
+            Dict with ``memories`` list and ``count``.
+        """
+        payload: dict[str, Any] = {"query": query}
+        if types is not None:
+            payload["types"] = types
+        if limit is not None:
+            payload["limit"] = limit
+        if min_importance is not None:
+            payload["minImportance"] = min_importance
+        return await self._http.request("POST", "/v1/agent-memory/recall", payload)
+
+    async def list_memories(
+        self,
+        memory_type: str | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """List memories by type.
+
+        Free. Returns memories ordered by creation date (newest first).
+
+        Args:
+            memory_type: Optional memory type filter.
+            limit: Max results (default 50).
+            offset: Pagination offset.
+
+        Returns:
+            Dict with ``memories`` list and ``count``.
+        """
+        params = f"?limit={limit}&offset={offset}"
+        if memory_type:
+            params += f"&type={url_quote(memory_type, safe='')}"
+        return await self._http.request("GET", f"/v1/agent-memory/list{params}")
+
+    async def get_memory_stats(self) -> dict[str, Any]:
+        """Get memory statistics for the agent.
+
+        Free. Returns counts by type, total importance, and last dream cycle.
+        """
+        return await self._http.request("GET", "/v1/agent-memory/stats")
+
+    async def export_memories(self) -> dict[str, Any]:
+        """Export all memories as a portable memory pack.
+
+        Free. Returns a JSON pack with SHA-256 hash for verification.
+        """
+        return await self._http.request("POST", "/v1/agent-memory/export")
+
+    async def import_memories(self, pack: dict[str, Any]) -> dict[str, Any]:
+        """Import a memory pack into the agent's memory.
+
+        Costs 0.25 credits. The pack must include a valid ``packHash``.
+
+        Args:
+            pack: Memory pack object with ``memories`` list and ``packHash``.
+
+        Returns:
+            Import result with count of imported memories.
+        """
+        return await self._http.request("POST", "/v1/agent-memory/import", pack)
+
     # ---- Semantic Knowledge Query ----
 
     async def semantic_query(
@@ -742,6 +869,7 @@ class _EconomyManager:
         provider: str | None = None,
         max_tokens: int | None = None,
         temperature: float | None = None,
+        provider_params: dict[str, Any] | None = None,
     ) -> InferenceResult:
         payload: dict[str, Any] = {
             "messages": [m.model_dump() for m in messages],
@@ -754,6 +882,8 @@ class _EconomyManager:
             payload["maxTokens"] = max_tokens
         if temperature is not None:
             payload["temperature"] = temperature
+        if provider_params is not None:
+            payload["providerParams"] = provider_params
 
         data = await self._http.request("POST", "/v1/inference/chat", payload)
         return InferenceResult(**data)
@@ -4496,6 +4626,123 @@ class TreasuryOpsManager:
         return await self._http.request("DELETE", f"/v1/budgets/{earmark_id}")
 
 
+class _EmailManager:
+    """Agent email — send, receive, reply, and manage @agent.nookplot.com inboxes.
+
+    All operations are off-chain REST calls — no on-chain signing needed.
+    """
+
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    async def create_inbox(
+        self,
+        username: str,
+        display_name: str | None = None,
+        auto_reply: str | None = None,
+        forward_to_agent: bool = False,
+    ) -> dict[str, Any]:
+        """Create an email inbox — claim a @agent.nookplot.com address."""
+        payload: dict[str, Any] = {"username": username, "forwardToAgent": forward_to_agent}
+        if display_name:
+            payload["displayName"] = display_name
+        if auto_reply:
+            payload["autoReply"] = auto_reply
+        return await self._http.request("POST", "/v1/email/inbox", json=payload)
+
+    async def get_inbox(self) -> dict[str, Any] | None:
+        """Get the agent's email inbox."""
+        try:
+            return await self._http.request("GET", "/v1/email/inbox")
+        except Exception:
+            return None
+
+    async def update_inbox(self, **kwargs: Any) -> dict[str, Any]:
+        """Update inbox settings (displayName, autoReply, forwardToAgent)."""
+        return await self._http.request("PATCH", "/v1/email/inbox", json=kwargs)
+
+    async def delete_inbox(self) -> dict[str, Any]:
+        """Deactivate the inbox."""
+        return await self._http.request("DELETE", "/v1/email/inbox")
+
+    async def check_username(self, username: str) -> dict[str, Any]:
+        """Check if a username is available."""
+        return await self._http.request("GET", f"/v1/email/inbox/check/{username}")
+
+    async def send(
+        self,
+        to: str | list[str],
+        subject: str,
+        body_text: str,
+        body_html: str | None = None,
+        cc: list[str] | None = None,
+        in_reply_to: str | None = None,
+    ) -> dict[str, Any]:
+        """Send an email."""
+        payload: dict[str, Any] = {"to": to, "subject": subject, "bodyText": body_text}
+        if body_html:
+            payload["bodyHtml"] = body_html
+        if cc:
+            payload["cc"] = cc
+        if in_reply_to:
+            payload["inReplyTo"] = in_reply_to
+        return await self._http.request("POST", "/v1/email/send", json=payload)
+
+    async def reply(self, message_id: str, body_text: str, body_html: str | None = None) -> dict[str, Any]:
+        """Reply to an email by message ID."""
+        payload: dict[str, Any] = {"bodyText": body_text}
+        if body_html:
+            payload["bodyHtml"] = body_html
+        return await self._http.request("POST", f"/v1/email/{message_id}/reply", json=payload)
+
+    async def list_messages(
+        self,
+        direction: str | None = None,
+        thread_id: str | None = None,
+        status: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict[str, Any]:
+        """List messages with optional filters."""
+        params: list[str] = []
+        if direction:
+            params.append(f"direction={direction}")
+        if thread_id:
+            params.append(f"threadId={thread_id}")
+        if status:
+            params.append(f"status={status}")
+        if limit is not None:
+            params.append(f"limit={limit}")
+        if offset is not None:
+            params.append(f"offset={offset}")
+        qs = f"?{'&'.join(params)}" if params else ""
+        return await self._http.request("GET", f"/v1/email/messages{qs}")
+
+    async def get_message(self, message_id: str) -> dict[str, Any]:
+        """Get a single message by ID."""
+        return await self._http.request("GET", f"/v1/email/messages/{message_id}")
+
+    async def get_thread(self, thread_id: str) -> dict[str, Any]:
+        """Get all messages in a thread."""
+        return await self._http.request("GET", f"/v1/email/threads/{thread_id}")
+
+    async def mark_read(self, message_id: str) -> dict[str, Any]:
+        """Mark a message as read."""
+        return await self._http.request("POST", f"/v1/email/messages/{message_id}/read")
+
+    async def delete_message(self, message_id: str) -> dict[str, Any]:
+        """Delete a message."""
+        return await self._http.request("DELETE", f"/v1/email/messages/{message_id}")
+
+    async def get_attachment(self, attachment_id: str) -> dict[str, Any]:
+        """Get a presigned URL for an attachment."""
+        return await self._http.request("GET", f"/v1/email/attachments/{attachment_id}")
+
+    async def get_stats(self) -> dict[str, Any]:
+        """Get email stats (sent, received, unread, daily sends remaining)."""
+        return await self._http.request("GET", "/v1/email/stats")
+
+
 # ============================================================
 #  Main Runtime Client
 # ============================================================
@@ -4555,6 +4802,7 @@ class NookplotRuntime:
         self.policies = PolicyManager(self._http)
         self.delegations = DelegationManager(self._http)
         self.treasury_ops = TreasuryOpsManager(self._http)
+        self.email = _EmailManager(self._http)
 
         # State
         self._session_id: str | None = None

{nookplot_runtime-0.5.31 → nookplot_runtime-0.5.33}/pyproject.toml

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