@calimero-network/agent-skills 0.2.0 → 0.4.0

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,41 +1,79 @@
-# Rule: Always handle 401 with token refresh
+# Rule: rpcClient handles token refresh automatically — but not all 401s
 
-Access tokens expire. Any RPC call or WebSocket connection can return `401 Unauthorized`. Never let this surface as an unhandled error.
+`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.**
 
-## Pattern
+What you DO need to handle: 401s that cannot be refreshed.
+
+## WRONG — manual refresh wrapper (not needed for rpcClient):
 
 ```typescript
-async function callWithRefresh<T>(callFn: () => Promise<T>): Promise<T> {
+// ✗ Don't do this — rpcClient already retries on token_expired
+async function callWithRefresh<T>(fn: () => Promise<T>) {
   try {
-    return await callFn();
+    return await fn();
   } catch (err: any) {
-    if (err?.code === 401 || err?.status === 401) {
-      await refreshAccessToken();
-      return callFn(); // retry once
+    if (err?.code === 401) {
+      await refreshAccessToken(); // rpcClient already does this
+      return fn();
     }
     throw err;
   }
 }
+```
+
+## CORRECT — handle only non-refreshable auth failures:
+
+```typescript
+const response = await rpcClient.execute({ ... });
+
+if (response.error) {
+  const authError = response.error.headers?.['x-auth-error'];
 
-async function refreshAccessToken() {
-  const jwt = getJWTObject();
-  if (!jwt?.refresh_token) {
-    // No refresh token — redirect to login
-    window.location.href = '/login';
+  if (response.error.code === 401) {
+    if (authError === 'token_revoked' || authError === 'invalid_token') {
+      // Token is invalid — cannot be refreshed. Send user to login.
+      clientLogout();
+      return;
+    }
+    // token_expired: rpcClient already retried and the retry failed.
+    // This means the refresh token is also expired — send to login.
+    clientLogout();
     return;
   }
 
-  const newTokens = await client.refreshToken(jwt.refresh_token);
-  localStorage.setItem('calimero_jwt', JSON.stringify(newTokens));
+  throw new Error(response.error.error.cause.info?.message ?? 'Unknown error');
 }
 ```
 
-## Why
+## 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:
 
-Access tokens are short-lived by design. Without refresh handling, users will see
-random authentication errors mid-session. The refresh token is longer-lived and
-should be used to silently re-authenticate.
+```typescript
+async function connectWithAuth() {
+  const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
+  try {
+    await ws.connect();
+    ws.subscribe([getContextId()!]);
+    ws.addCallback(handleEvent);
+  } catch (err: any) {
+    if (err?.status === 401) {
+      // Token expired before WS connect — logout and re-authenticate
+      clientLogout();
+    }
+    throw err;
+  }
+}
+```
 
-## What to do if refresh also fails
+## Summary
 
-Redirect to login. Do not retry the refresh indefinitely.
+| 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,15 +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.
 
 ## 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
@@ -17,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
@@ -30,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.

package/skills/calimero-client-py/rules/stable-node-name.md

@@ -1,7 +1,7 @@
 # Rule: node_name must be stable and unique per node
 
-`node_name` is used to derive the token cache filename. Changing it between runs
-means the client can't find the cached tokens and will fail to authenticate.
+`node_name` is used to derive the token cache filename. Changing it between runs means the client
+can't find the cached tokens and will fail to authenticate.
 
 ## WRONG — dynamic or None:
 
@@ -29,11 +29,11 @@ connection = create_connection(api_url=url, node_name=node_name)
 
 ## Why
 
-Token cache files are named `{sanitized_node_name}-{hash}.json` in `~/.merobox/auth_cache/`.
-If `node_name` varies, a new cache file is created each run and existing tokens are never
-reused — forcing re-authentication on every invocation.
+Token cache files are named `{sanitized_node_name}-{hash}.json` in `~/.merobox/auth_cache/`. If
+`node_name` varies, a new cache file is created each run and existing tokens are never reused —
+forcing re-authentication on every invocation.
 
 ## Also: unique per remote node
 
-If you connect to multiple nodes in the same script, use a different `node_name` for each.
-Sharing a `node_name` across two different nodes will mix up their token caches.
+If you connect to multiple nodes in the same script, use a different `node_name` for each. Sharing a
+`node_name` across two different nodes will mix up their token caches.