@storacha/clawracha 0.0.7 → 0.0.9

package/README.md

@@ -23,21 +23,31 @@ openclaw plugins install @storacha/clawracha
 
 Setup is done via slash commands in your chat session with the agent (not CLI commands).
 
-### New workspace (first device)
+### Step 1: Initialize the agent
 
 ```
-/storacha-init <upload-delegation-b64>
+/storacha-init
 ```
 
-Creates a fresh workspace with a new UCN Name. You'll need an upload delegation from a Storacha space owner.
+Generates an agent identity and displays the Agent DID. You'll need this DID to create delegations.
 
-### Join an existing workspace (additional devices)
+### Step 2: Choose your path
+
+**New workspace (first device):**
+
+```
+/storacha-setup <upload-delegation-b64>
+```
+
+Have the space owner create an upload delegation for your Agent DID, then import it. Creates a fresh UCN Name and starts syncing.
+
+**Join an existing workspace (additional devices):**
 
 ```
 /storacha-join <upload-delegation-b64> <name-delegation-b64>
 ```
 
-Joins an existing workspace from another device. Both delegations are required — get them by running `/storacha-grant` on the existing device. The join command pulls all remote files before the watcher starts, so your local workspace is fully synced from the start.
+Get both delegations by running `/storacha-grant` on the existing device. The join command pulls all remote files before the watcher starts, so your local workspace is fully synced from the start.
 
 ### Grant access to another device
 

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAwC7B;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QA6apD"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAyC7B;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAyepD"}

package/dist/plugin.js

@@ -10,6 +10,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { extract as extractDelegation } from "@storacha/client/delegation";
 import { SyncEngine } from "./sync.js";
+import { decodeDelegation, encodeDelegation } from "./utils/delegation.js";
 import { FileWatcher } from "./watcher.js";
 import { createStorachaClient } from "./utils/client.js";
 // Global state
@@ -62,7 +63,7 @@ export default function plugin(api) {
             }
             const deviceConfig = await loadDeviceConfig(workspace);
             if (!deviceConfig || !deviceConfig.setupComplete) {
-                ctx.logger.info("Setup not complete. Run /storacha-init or /storacha-join first.");
+                ctx.logger.info("Setup not complete. Run /storacha-init first, then /storacha-setup or /storacha-join.");
                 return;
             }
             const storachaClient = await createStorachaClient(deviceConfig);
@@ -114,7 +115,7 @@ export default function plugin(api) {
                     content: [
                         {
                             type: "text",
-                            text: "Sync not initialized. Run /storacha-init or /storacha-join first.",
+                            text: "Sync not initialized. Run /storacha-init first, then /storacha-setup or /storacha-join.",
                         },
                     ],
                     details: null,
@@ -140,7 +141,7 @@ export default function plugin(api) {
                     content: [
                         {
                             type: "text",
-                            text: "Sync not initialized. Run /storacha-init or /storacha-join first.",
+                            text: "Sync not initialized. Run /storacha-init first, then /storacha-setup or /storacha-join.",
                         },
                     ],
                     details: null,
@@ -162,42 +163,91 @@ export default function plugin(api) {
     // --- Slash Commands ---
     api.registerCommand({
         name: "storacha-init",
-        description: "Initialize a NEW Storacha workspace (first device). Usage: /storacha-init <upload-delegation-b64>",
+        description: "Generate an agent identity for Storacha sync",
+        handler: async (_ctx) => {
+            const workspace = workspaceDir;
+            if (!workspace)
+                return { text: "No workspace configured." };
+            // Check if already initialized
+            const existing = await loadDeviceConfig(workspace);
+            if (existing?.agentKey) {
+                const { Agent } = await import("@storacha/ucn/pail");
+                const agent = Agent.parse(existing.agentKey);
+                return {
+                    text: [
+                        "Agent already initialized.",
+                        `Agent DID: \`${agent.did()}\``,
+                        "",
+                        existing.setupComplete
+                            ? "Setup is complete. Use `/storacha-status` to check sync state."
+                            : "**Next step — choose one:**",
+                        ...(!existing.setupComplete
+                            ? [
+                                "- **New workspace:** Have the space owner create an upload delegation for this DID, then run `/storacha-setup <upload-b64>`",
+                                "- **Join existing:** Have the other device run `/storacha-grant <this-DID>`, then run `/storacha-join <upload-b64> <name-b64>`",
+                            ]
+                            : []),
+                    ].join("\n"),
+                };
+            }
+            const { Agent } = await import("@storacha/ucn/pail");
+            const agent = await Agent.generate();
+            const agentKey = Agent.format(agent);
+            const config = { agentKey };
+            await saveDeviceConfig(workspace, config);
+            return {
+                text: [
+                    "\u{1f525} Agent initialized!",
+                    `Agent DID: \`${agent.did()}\``,
+                    "",
+                    "**Next step \u2014 choose one:**",
+                    "- **New workspace:** Have the space owner create an upload delegation for this DID, then run `/storacha-setup <upload-b64>`",
+                    "- **Join existing workspace:** Have the other device run `/storacha-grant <this-DID>`, then run `/storacha-join <upload-b64> <name-b64>`",
+                ].join("\n"),
+            };
+        },
+    });
+    api.registerCommand({
+        name: "storacha-setup",
+        description: "Set up a NEW Storacha workspace (first device). Usage: /storacha-setup <upload-delegation-b64>",
         acceptsArgs: true,
         handler: async (_ctx) => {
             const workspace = workspaceDir;
             if (!workspace)
                 return { text: "No workspace configured." };
+            const config = await loadDeviceConfig(workspace);
+            if (!config?.agentKey) {
+                return { text: "Run `/storacha-init` first to generate an agent identity." };
+            }
+            if (config.setupComplete) {
+                return { text: "Setup already complete. Use `/storacha-status` to check sync state." };
+            }
             const b64 = _ctx.args?.trim();
             if (!b64) {
                 return {
                     text: [
-                        "Usage: `/storacha-init <upload-delegation-b64>`",
+                        "Usage: `/storacha-setup <upload-delegation-b64>`",
                         "",
-                        "This creates a **new** workspace. If you're syncing from an existing device, use `/storacha-join` instead.",
+                        "This creates a **new** workspace. If you're joining an existing workspace, use `/storacha-join` instead.",
                     ].join("\n"),
                 };
             }
             // Validate delegation
-            const bytes = Buffer.from(b64, "base64");
+            const bytes = decodeDelegation(b64);
             const { ok: delegation, error } = await extractDelegation(bytes);
             if (!delegation) {
                 return { text: `Invalid delegation: ${error}` };
             }
-            const { Agent } = await import("@storacha/ucn/pail");
-            const agent = await Agent.generate();
-            const agentKey = Agent.format(agent);
             const spaceDID = delegation.capabilities[0]?.with;
-            const config = {
-                agentKey,
-                uploadDelegation: b64,
-                spaceDID: spaceDID ?? undefined,
-                setupComplete: true,
-            };
+            config.uploadDelegation = b64;
+            config.spaceDID = spaceDID ?? undefined;
+            config.setupComplete = true;
             await saveDeviceConfig(workspace, config);
+            const { Agent } = await import("@storacha/ucn/pail");
+            const agent = Agent.parse(config.agentKey);
             return {
                 text: [
-                    "\u{1f525} Storacha workspace initialized!",
+                    "\u{1f525} Storacha workspace ready!",
                     `Agent DID: \`${agent.did()}\``,
                     `Space: \`${spaceDID ?? "unknown"}\``,
                     "",
@@ -211,7 +261,7 @@ export default function plugin(api) {
     });
     api.registerCommand({
         name: "storacha-join",
-        description: "Join an existing Storacha workspace from another device. Usage: /storacha-join <upload-delegation-b64> <name-delegation-b64>",
+        description: "Join an existing Storacha workspace from another device. Run /storacha-init first. Usage: /storacha-join <upload-delegation-b64> <name-delegation-b64>",
         acceptsArgs: true,
         handler: async (_ctx) => {
             const workspace = workspaceDir;
@@ -224,7 +274,7 @@ export default function plugin(api) {
                         "Usage: `/storacha-join <upload-delegation-b64> <name-delegation-b64>`",
                         "",
                         "Get both delegations by running `/storacha-grant` on the existing device.",
-                        "If you're setting up a **new** workspace, use `/storacha-init` instead.",
+                        "If you're setting up a **new** workspace, use `/storacha-setup` instead.",
                     ].join("\n"),
                 };
             }
@@ -242,28 +292,31 @@ export default function plugin(api) {
                 };
             }
             // Validate upload delegation
-            const uploadBytes = Buffer.from(uploadB64, "base64");
+            const uploadBytes = decodeDelegation(uploadB64);
             const { ok: uploadDelegation, error: uploadErr } = await extractDelegation(uploadBytes);
             if (!uploadDelegation) {
                 return { text: `Invalid upload delegation: ${uploadErr}` };
             }
             // Validate name delegation
-            const nameBytes = Buffer.from(nameB64, "base64");
+            const nameBytes = decodeDelegation(nameB64);
             const { ok: nameDelegation, error: nameErr } = await extractDelegation(nameBytes);
             if (!nameDelegation) {
                 return { text: `Invalid name delegation: ${nameErr}` };
             }
+            const config = await loadDeviceConfig(workspace);
+            if (!config?.agentKey) {
+                return { text: "Run `/storacha-init` first to generate an agent identity." };
+            }
+            if (config.setupComplete) {
+                return { text: "Setup already complete. Use `/storacha-status` to check sync state." };
+            }
             const { Agent } = await import("@storacha/ucn/pail");
-            const agent = await Agent.generate();
-            const agentKey = Agent.format(agent);
+            const agent = Agent.parse(config.agentKey);
             const spaceDID = uploadDelegation.capabilities[0]?.with;
-            const config = {
-                agentKey,
-                uploadDelegation: uploadB64,
-                nameDelegation: nameB64,
-                spaceDID: spaceDID ?? undefined,
-                setupComplete: true,
-            };
+            config.uploadDelegation = uploadB64;
+            config.nameDelegation = nameB64;
+            config.spaceDID = spaceDID ?? undefined;
+            config.setupComplete = true;
             await saveDeviceConfig(workspace, config);
             // Pull remote state immediately before watcher starts
             let pullCount = 0;
@@ -314,7 +367,7 @@ export default function plugin(api) {
             const config = await loadDeviceConfig(workspace);
             if (!config) {
                 return {
-                    text: "Not initialized. Run `/storacha-init` or `/storacha-join` first.",
+                    text: "Not initialized. Run `/storacha-init` first.",
                 };
             }
             const results = [];
@@ -331,7 +384,7 @@ export default function plugin(api) {
                     ]);
                     const { ok: archiveBytes } = await uploadDelegation.archive();
                     if (archiveBytes) {
-                        const b64 = Buffer.from(archiveBytes).toString("base64");
+                        const b64 = encodeDelegation(archiveBytes);
                         results.push("**Upload delegation:**\n```\n" + b64 + "\n```");
                     }
                 }
@@ -349,11 +402,11 @@ export default function plugin(api) {
                     const agent = Agent.parse(config.agentKey);
                     let name;
                     if (config.nameArchive) {
-                        const archiveBytes = Buffer.from(config.nameArchive, "base64");
+                        const archiveBytes = decodeDelegation(config.nameArchive);
                         name = await Name.extract(agent, archiveBytes);
                     }
                     else {
-                        const nameBytes = Buffer.from(config.nameDelegation, "base64");
+                        const nameBytes = decodeDelegation(config.nameDelegation);
                         const { ok: nameDel } = await extractDelegation(nameBytes);
                         if (!nameDel) {
                             results.push("\u274c Failed to extract name delegation.");
@@ -366,7 +419,7 @@ export default function plugin(api) {
                         const nameDel = await name.grant(targetDID);
                         const { ok: archiveBytes } = await nameDel.archive();
                         if (archiveBytes) {
-                            const b64 = Buffer.from(archiveBytes).toString("base64");
+                            const b64 = encodeDelegation(archiveBytes);
                             results.push("**Name delegation:**\n```\n" + b64 + "\n```");
                         }
                     }
@@ -403,7 +456,7 @@ export default function plugin(api) {
             const config = await loadDeviceConfig(workspace);
             if (!config)
                 return {
-                    text: "Not initialized. Run /storacha-init or /storacha-join first.",
+                    text: "Not initialized. Run `/storacha-init` first.",
                 };
             const lines = [
                 "\u{1f525} Storacha Sync Status",

package/dist/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EAEV,YAAY,EACb,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,cAAc,CAAS;gBAEnB,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAMrD;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/C;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD3B;;OAEG;YACW,iBAAiB;IAc/B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAc5C;;OAEG;YACW,kBAAkB;IAWhC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IA0B7B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAW5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;YAM5B,WAAW;CAK1B"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EAEV,YAAY,EACb,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,qBAAa,UAAU;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,cAAc,CAAS;gBAEnB,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAMrD;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/C;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAe1D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD3B;;OAEG;YACW,iBAAiB;IAc/B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAc5C;;OAEG;YACW,kBAAkB;IAWhC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IA0B7B,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAW5B,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;YAM5B,WAAW;CAK1B"}

package/dist/sync.js

@@ -16,6 +16,7 @@ import { applyRemoteChanges } from "./handlers/remote.js";
 import { processChanges } from "./handlers/process.js";
 import { diffRemoteChanges } from "./utils/differ.js";
 import { makeTempCar } from "./utils/tempcar.js";
+import { decodeDelegation, encodeDelegation } from "./utils/delegation.js";
 export class SyncEngine {
     workspace;
     blocks;
@@ -38,13 +39,13 @@ export class SyncEngine {
         const agent = Agent.parse(config.agentKey);
         if (config.nameArchive) {
             // Restore from previously saved archive (has full state)
-            const archiveBytes = Buffer.from(config.nameArchive, "base64");
+            const archiveBytes = decodeDelegation(config.nameArchive);
             this.name = await Name.extract(agent, archiveBytes);
         }
         else if (config.nameDelegation) {
             // Reconstruct from delegation (granted by another device)
             const { extract } = await import("@storacha/client/delegation");
-            const nameBytes = Buffer.from(config.nameDelegation, "base64");
+            const nameBytes = decodeDelegation(config.nameDelegation);
             const { ok: delegation } = await extract(nameBytes);
             if (!delegation)
                 throw new Error("Failed to extract name delegation");
@@ -205,7 +206,7 @@ export class SyncEngine {
         if (!this.name)
             throw new Error("Sync engine not initialized");
         const bytes = await this.name.archive();
-        return Buffer.from(bytes).toString("base64");
+        return encodeDelegation(bytes);
     }
     async storeBlocks(blocks) {
         for (const block of blocks) {

package/dist/utils/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/utils/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,CA8BjB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/utils/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,CA8BjB"}

package/dist/utils/client.js

@@ -8,6 +8,7 @@ import { Agent as PailAgent } from "@storacha/ucn/pail";
 import { create as createClient } from "@storacha/client";
 import { StoreMemory } from "@storacha/client/stores/memory";
 import { extract } from "@storacha/client/delegation";
+import { decodeDelegation } from "./delegation.js";
 /**
  * Build a Storacha Client from device config.
  * Requires agentKey and uploadDelegation to be present.
@@ -22,7 +23,7 @@ export async function createStorachaClient(config) {
         store: new StoreMemory(),
     });
     // Import the upload delegation (space → agent)
-    const uploadBytes = Buffer.from(config.uploadDelegation, "base64");
+    const uploadBytes = decodeDelegation(config.uploadDelegation);
     const { ok: uploadDelegation, error: uploadErr } = await extract(uploadBytes);
     if (!uploadDelegation) {
         throw new Error(`Failed to extract upload delegation: ${uploadErr}`);

package/dist/utils/delegation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Delegation encoding/decoding utilities.
+ *
+ * Delegations are serialized as CIDv1 with the CAR codec (0x0202)
+ * and identity multihash, encoded as base64. This matches the format
+ * used by the Storacha CLI (`storacha delegation create --base64`).
+ */
+/**
+ * Encode delegation archive bytes as a CID string (base64).
+ * archive bytes → CIDv1(CAR, identity) → base64 string
+ */
+export declare function encodeDelegation(archiveBytes: Uint8Array): string;
+/**
+ * Decode a delegation CID string back to archive bytes.
+ * base64 string → CID → identity multihash digest → bytes
+ */
+export declare function decodeDelegation(encoded: string): Uint8Array;
+//# sourceMappingURL=delegation.d.ts.map

package/dist/utils/delegation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../../src/utils/delegation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,UAAU,GAAG,MAAM,CAGjE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAQ5D"}

package/dist/utils/delegation.js

@@ -0,0 +1,31 @@
+/**
+ * Delegation encoding/decoding utilities.
+ *
+ * Delegations are serialized as CIDv1 with the CAR codec (0x0202)
+ * and identity multihash, encoded as base64. This matches the format
+ * used by the Storacha CLI (`storacha delegation create --base64`).
+ */
+import { CID } from "multiformats/cid";
+import { base64 } from "multiformats/bases/base64";
+import { identity } from "multiformats/hashes/identity";
+/** CAR codec code (multicodec 0x0202) */
+const CAR_CODE = 0x0202;
+/**
+ * Encode delegation archive bytes as a CID string (base64).
+ * archive bytes → CIDv1(CAR, identity) → base64 string
+ */
+export function encodeDelegation(archiveBytes) {
+    const cid = CID.createV1(CAR_CODE, identity.digest(archiveBytes));
+    return cid.toString(base64);
+}
+/**
+ * Decode a delegation CID string back to archive bytes.
+ * base64 string → CID → identity multihash digest → bytes
+ */
+export function decodeDelegation(encoded) {
+    const cid = CID.parse(encoded, base64);
+    if (cid.multihash.code !== identity.code) {
+        throw new Error("Invalid delegation encoding: expected identity multihash");
+    }
+    return cid.multihash.digest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
   "files": [