@calimero-network/agent-skills 0.2.0 → 0.4.0

package/skills/calimero-core/references/websocket-events.md

@@ -0,0 +1,142 @@
+# WebSocket Events
+
+The Calimero node pushes real-time events to subscribers over WebSocket.
+
+## Connect and subscribe
+
+```text
+ws://localhost:2428/ws
+```
+
+After connecting, send:
+
+```json
+{ "action": "subscribe", "contextIds": ["<context-id-1>", "<context-id-2>"] }
+```
+
+You can subscribe to multiple context IDs in one message.
+
+---
+
+## Event types
+
+| Type             | When fired                                            | Payload                        |
+| ---------------- | ----------------------------------------------------- | ------------------------------ |
+| `ExecutionEvent` | App called `app::emit!()` (Rust) or `env.emit()` (JS) | `{ events: ExecutionEvent[] }` |
+| `StateMutation`  | Any context member mutated shared state               | `{ newRoot: string }`          |
+
+---
+
+## ExecutionEvent schema
+
+```typescript
+interface WsMessage {
+  contextId: string;
+  type: 'ExecutionEvent';
+  data: {
+    events: Array<{
+      kind: string; // matches Rust enum variant name or JS event name
+      data: number[] | object; // byte array (UTF-8 JSON) or plain object
+    }>;
+  };
+}
+```
+
+`data` is typically a UTF-8 JSON byte array when coming from a Rust app. Decode it:
+
+```typescript
+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 as number[])));
+    } catch {
+      return data; // leave as-is if not valid JSON
+    }
+  }
+  return data;
+}
+```
+
+Full consumption pattern:
+
+```typescript
+ws.onmessage = (msg) => {
+  const envelope = JSON.parse(msg.data);
+  if (envelope.type === 'ExecutionEvent') {
+    for (const e of envelope.data.events) {
+      const payload = decodeEventData(e.data);
+      switch (e.kind) {
+        case 'PostCreated':
+          handlePostCreated(payload);
+          break;
+        case 'PostDeleted':
+          handlePostDeleted(payload);
+          break;
+      }
+    }
+  }
+  if (envelope.type === 'StateMutation') {
+    // A peer mutated shared state — refetch data if needed
+    refreshData();
+  }
+};
+```
+
+---
+
+## StateMutation schema
+
+```typescript
+interface WsMessage {
+  contextId: string;
+  type: 'StateMutation';
+  data: {
+    newRoot: string; // hex hash of the new CRDT state root after merge
+  };
+}
+```
+
+Use `StateMutation` to know when to refetch state from the node — it fires on every mutation from
+any member, including the local node's own mutations.
+
+---
+
+## Unsubscribe
+
+```json
+{ "action": "unsubscribe", "contextIds": ["<context-id>"] }
+```
+
+---
+
+## Emitting events from Rust
+
+```rust
+#[app::event]
+pub enum Event<'a> {
+    PostCreated { title: &'a str },
+    PostDeleted { id: u32 },
+}
+
+#[app::logic]
+impl AppState {
+    pub fn create_post(&mut self, title: String) -> app::Result<()> {
+        // ...
+        app::emit!(Event::PostCreated { title: &title });
+        Ok(())
+    }
+}
+```
+
+The `kind` field in the WebSocket message will be `"PostCreated"` or `"PostDeleted"`.
+
+## Emitting events from TypeScript (SDK JS)
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+set(key: string, value: string): void {
+  this.items.set(key, value);
+  env.emit({ kind: 'ItemSet', data: { key, value } });
+}
+```

package/skills/calimero-core/rules/context-is-not-app.md

@@ -0,0 +1,35 @@
+# Rule: Application ≠ Context
+
+**An application is not a context. Installing an app does not create a context.**
+
+## What this means
+
+- `meroctl app install` → registers the WASM binary. Returns an `application-id`. No state exists
+  yet. No context exists yet.
+- `meroctl context create --application-id <id>` → creates a context. Calls `init()`. State now
+  exists. The context has a `context-id`.
+
+These are always **two separate commands**. You cannot skip the first step and jump straight to
+calling methods.
+
+## Why this matters
+
+When a developer says "install and run my app", the correct sequence is:
+
+```bash
+meroctl app install --path app.wasm          # → application-id
+meroctl context create --application-id <id> # → context-id
+meroctl call <context-id> my_method --args '{}'
+```
+
+Not:
+
+```bash
+meroctl app install --path app.wasm
+meroctl call ???                             # WRONG — no context yet
+```
+
+## Analogy
+
+Think of an Application as a class definition and a Context as an instance of that class. You can
+have many contexts (instances) from one application (class), each with completely isolated state.

package/skills/calimero-core/rules/crdt-types-only.md

@@ -0,0 +1,55 @@
+# Rule: CRDT Types Only for Shared State
+
+**Never use `std::collections` (Rust) or plain `Map`/`Array` (JS/TS) for shared application state.**
+
+## Forbidden for state fields
+
+```rust
+// WRONG — will compile but cause data loss on concurrent writes:
+struct AppState {
+    items: std::collections::HashMap<String, String>,  // ❌
+    log:   Vec<String>,                                // ❌
+    seen:  std::collections::HashSet<String>,          // ❌
+}
+```
+
+```typescript
+// WRONG — same problem in TypeScript:
+@State
+class AppState {
+  items: Map<string, string> = new Map(); // ❌
+  log: string[] = []; // ❌
+}
+```
+
+## Required: use CRDT collections
+
+```rust
+// CORRECT:
+use calimero_storage::collections::{UnorderedMap, Vector, LwwRegister};
+
+struct AppState {
+    items: UnorderedMap<String, LwwRegister<String>>,  // ✓
+    log:   Vector<String>,                              // ✓
+}
+```
+
+```typescript
+// CORRECT:
+import { UnorderedMap, Vector } from '@calimero-network/calimero-sdk-js/collections';
+
+@State
+class AppState {
+  items: UnorderedMap<string, string> = new UnorderedMap(); // ✓
+  log: Vector<string> = new Vector(); // ✓
+}
+```
+
+## Why
+
+Standard collections have no merge semantics. When two context members both write to a `HashMap`
+while offline, merging their states is undefined — the CRDT engine cannot resolve conflicts
+automatically and data will be silently lost or overwritten.
+
+CRDT collections are designed for exactly this scenario: they guarantee that all members converge to
+the same state regardless of write order or network partitions.

package/skills/calimero-desktop/SKILL.md

@@ -1,24 +1,30 @@
 # calimero-desktop — Agent Instructions
 
-You are helping a developer integrate their app frontend with **Calimero Desktop SSO**.
+You are helping a developer integrate their app frontend with **Calimero Desktop SSO** — the flow
+where users open an app from the Desktop and are automatically logged in without a manual auth
+screen.
+
+> **NOT this skill** if the developer just needs to authenticate manually via the login form — that
+> is handled entirely by `calimero-client-js`. This skill is specifically for reading SSO tokens
+> that Calimero Desktop passes in the URL hash.
 
 ## What Desktop does
 
-Calimero Desktop opens app frontends in a browser window and passes auth tokens via the
-URL hash — so users are automatically logged in without going through the manual auth flow.
+Calimero Desktop opens app frontends in a browser window and passes auth tokens via the URL hash —
+so users are automatically logged in without going through the manual auth flow.
 
 ## Hash parameters passed by Desktop
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `access_token` | string | JWT for authenticated node calls |
-| `refresh_token` | string | Token to obtain a new access token |
-| `node_url` | string | URL of the local node (`http://localhost:PORT`) |
-| `application_id` | string | The installed app's ID on this node |
+| Parameter        | Type   | Description                                     |
+| ---------------- | ------ | ----------------------------------------------- |
+| `access_token`   | string | JWT for authenticated node calls                |
+| `refresh_token`  | string | Token to obtain a new access token              |
+| `node_url`       | string | URL of the local node (`http://localhost:PORT`) |
+| `application_id` | string | The installed app's ID on this node             |
 
 ## Example URL
 
-```
+```text
 https://your-app.com/#access_token=eyJ...&refresh_token=eyJ...&node_url=http://localhost:2428&application_id=abc123
 ```
 
@@ -38,10 +44,15 @@ if (accessToken && nodeUrl) {
 
 ## Critical rule
 
-Always fall back to manual login when hash params are absent. The app must work when
-opened in a regular browser, not only from Desktop.
+Always fall back to manual login when hash params are absent. The app must work when opened in a
+regular browser, not only from Desktop.
+
+## Related skills
+
+- **`calimero-client-js`** — mero-js / mero-react API for auth, RPC, and WebSocket subscriptions
+- **`calimero-core`** — auth flow (JWT tokens, login, refresh) and JSON-RPC protocol detail
 
 ## References
 
-See `references/` for full integration pattern and how Desktop discovers app URLs.
-See `rules/` for the fallback requirement.
+See `references/` for full integration pattern and how Desktop discovers app URLs. See `rules/` for
+the fallback requirement.

package/skills/calimero-desktop/references/sso-integration.md

@@ -2,28 +2,39 @@
 
 ## Full startup flow
 
+Use the storage helpers from `@calimero-network/calimero-client` — do **not** write to
+`localStorage` directly. The helpers ensure correct key names and extract contextId +
+executorPublicKey from the JWT automatically.
+
 ```typescript
+import {
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setApplicationId,
+  setContextAndIdentityFromJWT,
+  getAuthConfig,
+} from '@calimero-network/calimero-client';
+
 interface SSOParams {
   accessToken: string;
-  refreshToken: string;
+  refreshToken: string | null;
   nodeUrl: string;
-  applicationId: string;
+  applicationId: string | null;
 }
 
 function readDesktopSSO(): SSOParams | null {
   const hash = new URLSearchParams(window.location.hash.slice(1));
   const accessToken = hash.get('access_token');
-  const refreshToken = hash.get('refresh_token');
   const nodeUrl = hash.get('node_url');
-  const applicationId = hash.get('application_id');
 
   if (!accessToken || !nodeUrl) return null;
 
   return {
     accessToken,
-    refreshToken: refreshToken ?? '',
+    refreshToken: hash.get('refresh_token'),
     nodeUrl,
-    applicationId: applicationId ?? '',
+    applicationId: hash.get('application_id'),
   };
 }
 
@@ -31,21 +42,29 @@ async function bootstrap() {
   const sso = readDesktopSSO();
 
   if (sso) {
+    // Store tokens via SDK helpers (sets localStorage keys correctly)
+    setAppEndpointKey(sso.nodeUrl);
+    setAccessToken(sso.accessToken);
+    if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+    if (sso.applicationId) setApplicationId(sso.applicationId);
+    // Extracts contextId + executorPublicKey from JWT claims
+    setContextAndIdentityFromJWT(sso.accessToken);
+
     // Clear hash from URL bar (tokens shouldn't sit in browser history)
     history.replaceState(null, '', window.location.pathname + window.location.search);
 
-    // Store for use by the client
-    localStorage.setItem('calimero_node_url', sso.nodeUrl);
-    localStorage.setItem('calimero_jwt', JSON.stringify({
-      access_token: sso.accessToken,
-      refresh_token: sso.refreshToken,
-    }));
-    localStorage.setItem('calimero_app_id', sso.applicationId);
-
-    await renderAuthenticatedApp(sso);
-  } else {
-    renderLoginScreen();
+    renderAuthenticatedApp();
+    return;
+  }
+
+  // No SSO hash — check if already authenticated from a prior session
+  const config = getAuthConfig();
+  if (config.error === null) {
+    renderAuthenticatedApp();
+    return;
   }
+
+  renderLoginScreen();
 }
 
 document.addEventListener('DOMContentLoaded', bootstrap);
@@ -53,7 +72,8 @@ document.addEventListener('DOMContentLoaded', bootstrap);
 
 ## How Desktop discovers your app's frontend URL
 
-Desktop reads the `links.frontend` field from your app's `manifest.json` inside the installed bundle. To ensure Desktop can open your app correctly, set this field:
+Desktop reads the `links.frontend` field from your app's `manifest.json` inside the installed
+bundle. Set this field so Desktop can open your app:
 
 ```json
 {
@@ -70,18 +90,25 @@ Desktop opens this URL and appends the SSO hash params.
 
 ```typescript
 // App.tsx
+import { getAuthConfig, setAccessToken, setAppEndpointKey,
+         setRefreshToken, setApplicationId, setContextAndIdentityFromJWT } from '@calimero-network/calimero-client';
+
 function App() {
   const [authState, setAuthState] = useState<'loading' | 'authenticated' | 'unauthenticated'>('loading');
 
   useEffect(() => {
     const sso = readDesktopSSO();
     if (sso) {
-      storeTokens(sso);
-      setAuthState('authenticated');
-    } else if (hasStoredTokens()) {
+      setAppEndpointKey(sso.nodeUrl);
+      setAccessToken(sso.accessToken);
+      if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+      if (sso.applicationId) setApplicationId(sso.applicationId);
+      setContextAndIdentityFromJWT(sso.accessToken);
+      history.replaceState(null, '', window.location.pathname);
       setAuthState('authenticated');
     } else {
-      setAuthState('unauthenticated');
+      const config = getAuthConfig();
+      setAuthState(config.error === null ? 'authenticated' : 'unauthenticated');
     }
   }, []);
 

package/skills/calimero-desktop/rules/sso-fallback.md

@@ -1,6 +1,7 @@
 # Rule: Always fall back to manual login if hash params are absent
 
 Your app must work in two scenarios:
+
 1. Opened from Calimero Desktop — SSO hash params present
 2. Opened directly in a browser — no hash params
 
@@ -29,5 +30,5 @@ if (token) {
 
 ## Why
 
-Desktop is not the only way users access apps. Developers test in browsers directly.
-Organizations may embed apps in other contexts. The app must be self-sufficient.
+Desktop is not the only way users access apps. Developers test in browsers directly. Organizations
+may embed apps in other contexts. The app must be self-sufficient.