@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-client-js/references/websocket-events.md

@@ -6,144 +6,117 @@ Subscribe to real-time events emitted by the application running on the node.
 
 The node sends two kinds of events to subscribers:
 
-| type | when | payload |
-|---|---|---|
-| `StateMutation` | Another member mutated shared state | `{ newRoot: string }` |
-| `ExecutionEvent` | App emitted `app::emit!()` | `{ events: ExecutionEvent[] }` |
+| type             | when                                | payload                        |
+| ---------------- | ----------------------------------- | ------------------------------ |
+| `StateMutation`  | Another member mutated shared state | `{ newRoot: string }`          |
+| `ExecutionEvent` | App emitted `app::emit!()`          | `{ events: ExecutionEvent[] }` |
 
-An `ExecutionEvent` has: `{ kind: string; data: any }` where `kind` matches the Rust event variant name.
+An `ExecutionEvent` entry: `{ kind: string; data: any }` where `kind` matches the Rust event variant
+name and `data` may be a byte array (UTF-8 JSON) or a plain object.
 
 ---
 
-## Connect and subscribe
+## mero-react: useSubscription hook (preferred for React)
 
 ```typescript
-import {
-  WsSubscriptionsClient,
-  getAppEndpointKey,
-  getContextId,
-} from '@calimero-network/calimero-client';
+import { useSubscription } from '@calimero-network/mero-react';
+
+function MyComponent({ contextId }: { contextId: string }) {
+  useSubscription([contextId], (event: { contextId: string; data: unknown }) => {
+    const payload = event.data as any;
+
+    // ExecutionEvent: data has an `events` array
+    if (Array.isArray(payload?.events)) {
+      for (const e of payload.events) {
+        const data = decodeEventData(e.data);
+        switch (e.kind) {
+          case 'Inserted':
+            console.log('inserted', data);
+            break;
+          case 'Removed':
+            console.log('removed', data);
+            break;
+        }
+      }
+    }
+  });
+}
 
-const nodeUrl = getAppEndpointKey()!;
-const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
+// Byte-array payloads are JSON-encoded; decode them:
+function decodeEventData(data: unknown): unknown {
+  if (Array.isArray(data) && data.every((n) => typeof n === 'number')) {
+    try {
+      return JSON.parse(new TextDecoder().decode(new Uint8Array(data)));
+    } catch {
+      return data;
+    }
+  }
+  return data;
+}
+```
 
-// Connect first, then subscribe and add callback
-await ws.connect();
-ws.subscribe([getContextId()!]);
-ws.addCallback((event) => {
-  console.log('Event received:', event);
+## Subscribe to multiple contexts
+
+```typescript
+// Subscribe to game context + lobby context simultaneously
+useSubscription([gameContextId, lobbyContextId], (event) => {
+  console.log('event from context:', event.contextId);
 });
 ```
 
 ---
 
-## Handling ExecutionEvents from app logic
+## Legacy calimero-client: WsSubscriptionsClient
 
 ```typescript
-import type {
-  NodeEvent,
-  ExecutionEventPayload,
-  StateMutationPayload,
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
 } from '@calimero-network/calimero-client';
 
-ws.addCallback((event: NodeEvent) => {
+const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
+await ws.connect();
+ws.subscribe([getContextId()!]);
+ws.addCallback((event) => {
   if (event.type === 'ExecutionEvent') {
     for (const e of event.data.events) {
-      // e.kind matches the Rust event variant name, e.g. 'ItemAdded'
-      // e.data contains the event payload
-      switch (e.kind) {
-        case 'ItemAdded':
-          console.log('Item added:', e.data);
-          addItemToUI(e.data.key, e.data.value);
-          break;
-        case 'ItemRemoved':
-          removeItemFromUI(e.data.key);
-          break;
-      }
+      console.log(e.kind, e.data);
     }
   }
-
   if (event.type === 'StateMutation') {
-    // Another member changed shared state — refresh data from node
-    console.log('State root changed:', event.data.newRoot);
     refreshDataFromNode();
   }
 });
 ```
 
----
-
-## Subscribe to multiple contexts
-
-```typescript
-ws.subscribe([contextId1, contextId2]);
-// Events include event.contextId to identify which context emitted them
-```
-
----
-
-## Cleanup
+Cleanup:
 
 ```typescript
-// Remove a specific callback
 ws.removeCallback(myCallback);
-
-// Unsubscribe from specific contexts
 ws.unsubscribe([contextId]);
-
-// Close connection entirely
 ws.disconnect();
 ```
 
 ---
 
-## Connection errors and reconnection
-
-`WsSubscriptionsClient` does **not** reconnect automatically. If the connection drops
-or the initial connect fails, you must retry manually.
-
-```typescript
-async function connectWithRetry(ws: WsSubscriptionsClient, contextId: string, retries = 3): Promise<void> {
-  for (let i = 0; i < retries; i++) {
-    try {
-      await ws.connect();
-      ws.subscribe([contextId]);
-      return;
-    } catch (err: any) {
-      if (err?.status === 401) {
-        // Token expired — cannot reconnect until re-authenticated
-        clientLogout();
-        return;
-      }
-      if (i === retries - 1) throw err;
-      await new Promise(r => setTimeout(r, 1000 * (i + 1))); // exponential backoff
-    }
-  }
-}
-```
-
-To detect drops after the connection is established, check if events stop arriving and
-reconnect periodically, or listen to `ws.onClose` if exposed.
-
-> WebSocket tokens are **not** auto-refreshed unlike `rpcClient` RPC calls.
-> See `rules/token-refresh.md` for details.
-
----
-
-## React hook pattern
+## React hook for legacy client
 
 ```typescript
 import { useEffect } from 'react';
-import { WsSubscriptionsClient, getAppEndpointKey, getContextId } from '@calimero-network/calimero-client';
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
+} from '@calimero-network/calimero-client';
 
-function useNodeEvents(onEvent: (event: NodeEvent) => void) {
+function useNodeEvents(onEvent: (event: any) => void) {
   useEffect(() => {
     const nodeUrl = getAppEndpointKey();
     const contextId = getContextId();
     if (!nodeUrl || !contextId) return;
 
     const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
-
     ws.connect().then(() => {
       ws.subscribe([contextId]);
       ws.addCallback(onEvent);
@@ -157,3 +130,11 @@ function useNodeEvents(onEvent: (event: NodeEvent) => void) {
   }, [onEvent]);
 }
 ```
+
+---
+
+## Connection notes
+
+- `WsSubscriptionsClient` does **not** reconnect automatically — handle reconnect manually
+- `useSubscription` from `mero-react` manages the connection lifecycle for you
+- WebSocket tokens are **not** auto-refreshed unlike `rpcClient` HTTP calls

package/skills/calimero-client-js/rules/camelcase-api.md

@@ -1,13 +1,14 @@
 # Rule: mero-js v2 uses camelCase — not snake_case
 
-`@calimero-network/mero-js` v2 (`>=2.0.0-beta.1`) changed all request object field names from `snake_case` to `camelCase`.
+`@calimero-network/mero-js` v2 (`>=2.0.0-beta.1`) changed all request object field names from
+`snake_case` to `camelCase`.
 
 ## WRONG (v1 / old code):
 
 ```typescript
 await client.generateClientKey({
-  context_id: contextId,        // ✗
-  context_identity: identity,   // ✗
+  context_id: contextId, // ✗
+  context_identity: identity, // ✗
 });
 ```
 
@@ -15,8 +16,8 @@ await client.generateClientKey({
 
 ```typescript
 await client.generateClientKey({
-  contextId: contextId,         // ✓
-  contextIdentity: identity,    // ✓
+  contextId: contextId, // ✓
+  contextIdentity: identity, // ✓
 });
 ```
 
@@ -27,11 +28,13 @@ await client.generateClientKey({
 
 ## Why this matters
 
-The v2 mero-js package does not alias the old snake_case keys. Passing `context_id` silently
-sends `undefined` to the server, which returns a cryptic error rather than a clear "wrong field name" message.
+The v2 mero-js package does not alias the old snake_case keys. Passing `context_id` silently sends
+`undefined` to the server, which returns a cryptic error rather than a clear "wrong field name"
+message.
 
 ## How to detect if a codebase is on v1 or v2
 
 Check `package.json`:
+
 - `"@calimero-network/mero-js": "^2.0.0-beta.1"` or higher → v2, use camelCase
 - `"@calimero-network/calimero-client": "..."` → original client, check its docs

package/skills/calimero-client-js/rules/token-refresh.md

@@ -1,8 +1,8 @@
 # Rule: rpcClient handles token refresh automatically — but not all 401s
 
-`rpcClient` (from `@calimero-network/calimero-client`) automatically retries with a
-refreshed token when the server returns `401 token_expired`. **You do not need to
-implement a refresh wrapper around `rpcClient.execute()` calls.**
+`rpcClient` (from `@calimero-network/calimero-client`) automatically retries with a refreshed token
+when the server returns `401 token_expired`. **You do not need to implement a refresh wrapper around
+`rpcClient.execute()` calls.**
 
 What you DO need to handle: 401s that cannot be refreshed.
 
@@ -49,8 +49,8 @@ if (response.error) {
 
 ## WebSocket connections are different — no auto-refresh
 
-`WsSubscriptionsClient` does **not** auto-refresh tokens. If the token expires while
-a WebSocket connection is open, events will stop arriving silently. Reconnect manually:
+`WsSubscriptionsClient` does **not** auto-refresh tokens. If the token expires while a WebSocket
+connection is open, events will stop arriving silently. Reconnect manually:
 
 ```typescript
 async function connectWithAuth() {
@@ -71,9 +71,9 @@ async function connectWithAuth() {
 
 ## Summary
 
-| Scenario | Handled by |
-| --- | --- |
-| `401 token_expired` on RPC call | `rpcClient` automatically (transparent retry) |
-| `401 token_revoked` on RPC call | You — redirect to login |
-| `401 invalid_token` on RPC call | You — redirect to login |
-| Auth failure on WebSocket connect | You — catch and redirect to login |
+| Scenario                          | Handled by                                    |
+| --------------------------------- | --------------------------------------------- |
+| `401 token_expired` on RPC call   | `rpcClient` automatically (transparent retry) |
+| `401 token_revoked` on RPC call   | You — redirect to login                       |
+| `401 invalid_token` on RPC call   | You — redirect to login                       |
+| Auth failure on WebSocket connect | You — catch and redirect to login             |

package/skills/calimero-client-py/SKILL.md

@@ -1,19 +1,23 @@
 # calimero-client-py — Agent Instructions
 
-You are helping a developer use the **Calimero Python client** (`calimero-client-py`) to
-interact with a Calimero node from Python — automation scripts, backend services, or CLI tools.
+You are helping a developer use the **Calimero Python client** (`calimero-client-py`) to interact
+with a Calimero node from Python — automation scripts, backend services, or CLI tools.
 
-> **NOT this skill** if the developer is building the application logic that runs on the
-> node — that is `calimero-rust-sdk` (Rust/WASM) or `calimero-sdk-js` (TypeScript/WASM).
-> This skill is for Python code that *calls* the node from outside.
+> **NOT this skill** if the developer is building the application logic that runs on the node — that
+> is `calimero-rust-sdk` (Rust/WASM) or `calimero-sdk-js` (TypeScript/WASM). This skill is for
+> Python code that _calls_ the node from outside.
 
 ## What it is
 
 `calimero-client-py` is a Python package built with PyO3 (Rust bindings). It provides:
-- Full async API for managing contexts, applications, identities, blobs
+
+- Full API for managing contexts, applications, identities, blobs, namespaces, and groups
 - Automatic JWT token caching and refresh (tokens stored in `~/.merobox/auth_cache/`)
 - A CLI for common node operations
 
+> **All methods are synchronous** — the Tokio runtime is managed internally by the Rust bindings. Do
+> NOT use `await` with any client methods.
+
 ## Install
 
 ```bash
@@ -21,6 +25,7 @@ pip install calimero-client-py
 ```
 
 **Build from source (requires Rust 1.70+ and maturin):**
+
 ```bash
 pip install maturin
 git clone https://github.com/calimero-network/calimero-client-py
@@ -34,24 +39,31 @@ maturin develop --release
 import asyncio
 from calimero_client_py import create_connection, create_client
 
-async def main():
+def main():
     connection = create_connection(
         api_url="http://localhost:2428",
         node_name="my-local-node"   # must be stable — see rules/
     )
     client = create_client(connection)
-    contexts = await client.list_contexts()
+    contexts = client.list_contexts()   # no await — methods are synchronous
     print(contexts)
 
-asyncio.run(main())
+main()
 ```
 
 ## Critical: `node_name` must be stable
 
-`node_name` is used to derive the token cache filename. If it changes between runs,
-the client loses its stored tokens and will need to re-authenticate.
+`node_name` is used to derive the token cache filename. If it changes between runs, the client loses
+its stored tokens and will need to re-authenticate.
+
+## Related skills
+
+- **`calimero-core`** — context/app model and JSON-RPC protocol that the Python client wraps
+- **`calimero-merod`** — `merod` daemon setup if the developer is also running the node
+- **`calimero-meroctl`** — `meroctl` CLI reference for quick manual operations alongside Python
+  scripts
 
 ## References
 
-See `references/` for the full API, authentication flow, and CLI commands.
-See `rules/` for the `node_name` stability requirement and async usage.
+See `references/` for the full API, authentication flow, and CLI commands. See `rules/` for the
+`node_name` stability requirement and sync API usage.

package/skills/calimero-client-py/references/api.md

@@ -1,5 +1,8 @@
 # Python Client API Reference
 
+> All methods are **synchronous** — no `await` needed. The async Tokio runtime is managed internally
+> by the Rust bindings.
+
 ## Setup
 
 ```python
@@ -16,52 +19,55 @@ client = create_client(connection)
 
 ```python
 # List all contexts
-contexts = await client.list_contexts()
+contexts = client.list_contexts()
 
 # Get a specific context
-context = await client.get_context(context_id="abc123")
+context = client.get_context(context_id="abc123")
 
 # Create a context (instance of an installed app)
-context = await client.create_context(
+context = client.create_context(
     application_id="app-id",
     protocol="near",          # "near" | "ethereum" | "icp" | "starknet"
     params=None               # optional JSON string
 )
 
 # Delete a context
-await client.delete_context(context_id="abc123")
+client.delete_context(context_id="abc123")
+
+# Join a context (by context ID)
+client.join_context(context_id="abc123")
 
 # Sync a context with peers
-await client.sync_context(context_id="abc123")
+client.sync_context(context_id="abc123")
 
 # Sync all contexts
-await client.sync_all_contexts()
+client.sync_all_contexts()
 ```
 
 ## Application management
 
 ```python
 # List installed apps
-apps = await client.list_applications()
+apps = client.list_applications()
 
 # Get a specific app
-app = await client.get_application(app_id="app-id")
+app = client.get_application(app_id="app-id")
 
 # Install from URL (registry or direct)
-result = await client.install_application(
+result = client.install_application(
     url="https://registry.calimero.network/myapp/1.0.0",
     hash=None,        # optional content hash for verification
     metadata=None     # optional bytes
 )
 
 # Install from local path (dev mode)
-result = await client.install_dev_application(
+result = client.install_dev_application(
     path="./target/wasm32-unknown-unknown/release/myapp.wasm",
     metadata=None
 )
 
 # Uninstall
-await client.uninstall_application(app_id="app-id")
+client.uninstall_application(app_id="app-id")
 ```
 
 ## Calling app methods
@@ -70,7 +76,7 @@ await client.uninstall_application(app_id="app-id")
 import json
 
 # Execute a method (mutation or view)
-result = await client.execute_function(
+result = client.execute_function(
     context_id="ctx-id",
     method="set",
     args=json.dumps({"key": "hello", "value": "world"}),
@@ -78,59 +84,51 @@ result = await client.execute_function(
 )
 ```
 
-## Context membership
-
-```python
-# Invite a member
-invitation = await client.invite_to_context(
-    context_id="ctx-id",
-    inviter_id="inviter-public-key",
-    invitee_id="invitee-public-key"
-)
-
-# Join a context (on the invitee's node)
-await client.join_context(
-    context_id="ctx-id",
-    invitee_id="invitee-public-key",
-    invitation_payload=invitation["payload"]
-)
-```
-
 ## Identity management
 
 ```python
 # Generate a new context identity
-identity = await client.generate_context_identity()
+identity = client.generate_context_identity()
 # Returns: { "public_key": "...", "private_key": "..." }
 
 # List identities for a context
-identities = await client.get_context_identities(context_id="ctx-id")
+identities = client.get_context_identities(context_id="ctx-id")
 
 # Get client keys for a context
-keys = await client.get_context_client_keys(context_id="ctx-id")
+keys = client.get_context_client_keys(context_id="ctx-id")
 ```
 
 ## Blob management
 
 ```python
-blobs = await client.list_blobs()
-info = await client.get_blob_info(blob_id="blob-id")
-await client.delete_blob(blob_id="blob-id")
+blobs = client.list_blobs()
+info = client.get_blob_info(blob_id="blob-id")
+client.delete_blob(blob_id="blob-id")
+
+# Upload bytes
+result = client.upload_blob(data=b"hello", context_id=None)
+
+# Download bytes
+data = client.download_blob(blob_id="blob-id", context_id=None)
 ```
 
 ## Alias management
 
 ```python
 # Create aliases for easier reference
-await client.create_context_alias(alias="my-context", context_id="ctx-id")
-await client.create_application_alias(alias="my-app", application_id="app-id")
-await client.create_context_identity_alias(
+client.create_context_alias(alias="my-context", context_id="ctx-id")
+client.create_application_alias(alias="my-app", application_id="app-id")
+client.create_context_identity_alias(
     context_id="ctx-id", alias="alice", public_key="pubkey"
 )
 
 # Delete aliases
-await client.delete_context_alias(alias="my-context")
-await client.delete_context_identity_alias(alias="alice", context_id="ctx-id")
+client.delete_context_alias(alias="my-context")
+client.delete_context_identity_alias(alias="alice", context_id="ctx-id")
+
+# Lookup / resolve aliases
+client.lookup_context_alias(alias="my-context")
+client.resolve_context_alias(alias="my-context")
 ```
 
 ## Utility
@@ -140,8 +138,8 @@ await client.delete_context_identity_alias(alias="alice", context_id="ctx-id")
 url = client.get_api_url()
 
 # Get connected peers count
-peers = await client.get_peers_count()
+peers = client.get_peers_count()
 
 # Get context storage info
-storage = await client.get_context_storage(context_id="ctx-id")
+storage = client.get_context_storage(context_id="ctx-id")
 ```

package/skills/calimero-client-py/references/auth.md

@@ -1,11 +1,11 @@
 # Authentication & Token Caching
 
-The Python client automatically manages JWT tokens — loading from cache, using them in
-requests, and refreshing on 401.
+The Python client automatically manages JWT tokens — loading from cache, using them in requests, and
+refreshing on 401.
 
 ## Token cache location
 
-```
+```text
 ~/.merobox/auth_cache/{sanitized_node_name}-{hash}.json
 ```
 
@@ -18,8 +18,8 @@ path = get_token_cache_path("my-node")
 
 ## First-time authentication
 
-On the first run there are no cached tokens. You need to complete an auth flow (login via
-the admin dashboard or meroctl) and then seed the cache manually:
+On the first run there are no cached tokens. You need to complete an auth flow (login via the admin
+dashboard or meroctl) and then seed the cache manually:
 
 ```python
 import json
@@ -54,8 +54,8 @@ client = create_client(connection)
 
 ## Token refresh
 
-The client automatically retries with a refreshed token on `401 Unauthorized`.
-Refreshed tokens are written back to the cache file automatically.
+The client automatically retries with a refreshed token on `401 Unauthorized`. Refreshed tokens are
+written back to the cache file automatically.
 
 ## CI / automated environments
 

package/skills/calimero-client-py/rules/async-usage.md

@@ -1,52 +1,48 @@
-# Rule: All client methods are async — must be awaited
+# Rule: All client methods are synchronous — do NOT use await
 
-All `client.*` methods return coroutines. They must be called with `await` inside an
-`async` function, and the event loop must be running.
+Despite being built on an async Rust/Tokio runtime internally, all `client.*` methods are
+**synchronous** from Python's perspective. Do NOT use `async`/`await`.
 
 ## WRONG:
 
 ```python
-# ✗ Missing await — returns a coroutine object, not the result
-contexts = client.list_contexts()
-print(contexts)  # prints <coroutine object ...>
-
-# ✗ Calling outside async context
-def main():
-    client.list_contexts()  # won't run
+# ✗ Adding await — methods are not coroutines
+async def main():
+    contexts = await client.list_contexts()  # TypeError: object is not awaitable
 ```
 
 ## CORRECT:
 
 ```python
-# ✓ Always await
-async def main():
-    contexts = await client.list_contexts()
+# ✓ Call methods directly — no await needed
+def main():
+    conn = create_connection(api_url="http://localhost:2428", node_name="dev")
+    client = create_client(conn)
+    contexts = client.list_contexts()   # synchronous, returns result directly
     print(contexts)
 
-asyncio.run(main())
+main()
 ```
 
 ## In scripts
 
 ```python
-import asyncio
 from calimero_client_py import create_connection, create_client
-
-async def main():
-    conn = create_connection(api_url="http://localhost:2428", node_name="dev")
-    client = create_client(conn)
-    result = await client.execute_function(
-        context_id="ctx-id",
-        method="get",
-        args='{"key":"hello"}',
-        executor_public_key="pubkey"
-    )
-    print(result)
-
-asyncio.run(main())
+import json
+
+conn = create_connection(api_url="http://localhost:2428", node_name="dev")
+client = create_client(conn)
+
+result = client.execute_function(
+    context_id="ctx-id",
+    method="get",
+    args=json.dumps({"key": "hello"}),
+    executor_public_key="pubkey"
+)
+print(result)
 ```
 
-## Note: `create_connection` and `create_client` are synchronous
+## Note
 
-Only the API methods on the `client` object are async. The setup functions are regular
-synchronous calls.
+The Tokio async runtime is embedded in the Rust bindings and blocks internally. From Python's view,
+every call is a normal blocking function call.