@storacha/clawracha 0.0.11-rc.0 → 0.1.0

package/README.md

@@ -21,12 +21,14 @@ openclaw plugins install @storacha/clawracha
 
 ## Setup
 
-Setup is done via slash commands in your chat session with the agent (not CLI commands).
+Setup is done via CLI commands on the host (not slash commands in chat).
+
+All commands require `--agent <id>` to specify which agent workspace to configure.
 
 ### Step 1: Initialize the agent
 
-```
-/storacha-init
+```bash
+openclaw clawracha init --agent <id>
 ```
 
 Generates an agent identity and displays the Agent DID. You'll need this DID to create delegations.
@@ -35,32 +37,32 @@ Generates an agent identity and displays the Agent DID. You'll need this DID to
 
 **New workspace (first device):**
 
-```
-/storacha-setup <upload-delegation-b64>
+```bash
+openclaw clawracha setup <delegation> --agent <id>
 ```
 
-Have the space owner create an upload delegation for your Agent DID, then import it. Creates a fresh UCN Name and starts syncing.
+`<delegation>` can be a file path (raw CAR) or a base64 CID string. Have the space owner create an upload delegation for your Agent DID, then import it.
 
 **Join an existing workspace (additional devices):**
 
-```
-/storacha-join <upload-delegation-b64> <name-delegation-b64>
+```bash
+openclaw clawracha join <upload-delegation> <name-delegation> --agent <id>
 ```
 
-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.
+Get both delegations by running `openclaw clawracha grant` on the existing device. Arguments can be file paths or base64 CID strings. The join command pulls all remote files before the watcher starts.
 
 ### Grant access to another device
 
-```
-/storacha-grant <target-agent-DID>
+```bash
+openclaw clawracha grant <target-agent-DID> --agent <id>
 ```
 
-Generates upload and name delegations for the target device. The target device uses these with `/storacha-join`.
+Generates upload and name delegations for the target device.
 
 ### Check status
 
-```
-/storacha-status
+```bash
+openclaw clawracha status --agent <id>
 ```
 
 After setup, restart the gateway to start syncing:

package/dist/plugin.d.ts

@@ -2,13 +2,10 @@
  * OpenClaw Plugin Entry Point
  *
  * Registers:
- * - Background service for file watching and sync
+ * - Background service that syncs ALL agent workspaces with .storacha configs
+ * - CLI commands for setup and management (openclaw clawracha ...)
  * - Agent tools for manual sync control
- * - Slash commands for setup
  */
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-/**
- * Plugin entry — called by OpenClaw when the plugin is loaded.
- */
 export default function plugin(api: OpenClawPluginApi): void;
 //# sourceMappingURL=plugin.d.ts.map

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;AAyC7B;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QA4hBpD"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAiG7B,MAAM,CAAC,OAAO,UAAU,MAAM,CAAC,GAAG,EAAE,iBAAiB,QAoepD"}

package/dist/plugin.js

@@ -2,24 +2,19 @@
  * OpenClaw Plugin Entry Point
  *
  * Registers:
- * - Background service for file watching and sync
+ * - Background service that syncs ALL agent workspaces with .storacha configs
+ * - CLI commands for setup and management (openclaw clawracha ...)
  * - Agent tools for manual sync control
- * - Slash commands for setup
  */
 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
-let syncEngine = null;
-let fileWatcher = null;
-let workspaceDir;
-/**
- * Load device config from .storacha/config.json
- */
+import { decodeDelegation, encodeDelegation, readDelegationArg, } from "./utils/delegation.js";
+import { resolveAgentWorkspace, getAgentIds, } from "./utils/workspace.js";
+const activeSyncers = new Map();
+// --- Config helpers ---
 async function loadDeviceConfig(workspace) {
     const configPath = path.join(workspace, ".storacha", "config.json");
     try {
@@ -32,22 +27,49 @@ async function loadDeviceConfig(workspace) {
         throw err;
     }
 }
-/**
- * Save device config
- */
 async function saveDeviceConfig(workspace, config) {
     const configDir = path.join(workspace, ".storacha");
     await fs.mkdir(configDir, { recursive: true });
     const configPath = path.join(configDir, "config.json");
     await fs.writeFile(configPath, JSON.stringify(config, null, 2));
 }
-/**
- * Plugin entry — called by OpenClaw when the plugin is loaded.
- */
+// --- Service helpers ---
+async function startWorkspaceSync(workspace, agentId, pluginConfig, logger) {
+    const deviceConfig = await loadDeviceConfig(workspace);
+    if (!deviceConfig || !deviceConfig.setupComplete) {
+        return null;
+    }
+    const storachaClient = await createStorachaClient(deviceConfig);
+    const engine = new SyncEngine(storachaClient, workspace);
+    await engine.init(deviceConfig);
+    const watcher = new FileWatcher({
+        workspace,
+        config: {
+            enabled: true,
+            watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
+            ignorePatterns: pluginConfig.ignorePatterns ?? [
+                ".storacha/**",
+                "node_modules/**",
+                ".git/**",
+                "dist/**",
+            ],
+        },
+        onChanges: async (changes) => {
+            await engine.processChanges(changes);
+            await engine.sync();
+            const nameArchive = await engine.exportNameArchive();
+            const updatedConfig = { ...deviceConfig, nameArchive };
+            await saveDeviceConfig(workspace, updatedConfig);
+        },
+    });
+    await watcher.start();
+    logger.info(`[${agentId}] Started syncing workspace: ${workspace}`);
+    return { engine, watcher, workspace, agentId };
+}
+// --- Plugin entry ---
 export default function plugin(api) {
-    // Capture plugin-specific config at registration time
     const pluginConfig = (api.pluginConfig ?? {});
-    // Register background service
+    // --- Background service: one syncer per agent workspace ---
     api.registerService({
         id: "storacha-sync",
         async start(ctx) {
@@ -55,73 +77,55 @@ export default function plugin(api) {
                 ctx.logger.info("Storacha sync disabled via config.");
                 return;
             }
-            workspaceDir = ctx.workspaceDir;
-            const workspace = workspaceDir;
-            if (!workspace) {
-                ctx.logger.warn("No workspace directory configured");
-                return;
+            const agentIds = getAgentIds(ctx.config);
+            for (const agentId of agentIds) {
+                const workspace = resolveAgentWorkspace(ctx.config, agentId);
+                try {
+                    const sync = await startWorkspaceSync(workspace, agentId, pluginConfig, ctx.logger);
+                    if (sync) {
+                        activeSyncers.set(workspace, sync);
+                    }
+                }
+                catch (err) {
+                    ctx.logger.warn(`[${agentId}] Failed to start sync: ${err.message}`);
+                }
             }
-            const deviceConfig = await loadDeviceConfig(workspace);
-            if (!deviceConfig || !deviceConfig.setupComplete) {
-                ctx.logger.info("Setup not complete. Run /storacha-init first, then /storacha-setup or /storacha-join.");
-                return;
+            if (activeSyncers.size === 0) {
+                ctx.logger.info("No agent workspaces configured for Storacha sync. Use `openclaw clawracha init --agent <id>` to set up.");
+            }
+            else {
+                ctx.logger.info(`Storacha sync active for ${activeSyncers.size} workspace(s).`);
             }
-            const storachaClient = await createStorachaClient(deviceConfig);
-            syncEngine = new SyncEngine(storachaClient, workspace);
-            await syncEngine.init(deviceConfig);
-            fileWatcher = new FileWatcher({
-                workspace,
-                config: {
-                    enabled: true,
-                    watchPatterns: pluginConfig.watchPatterns ?? ["**/*"],
-                    ignorePatterns: pluginConfig.ignorePatterns ?? [
-                        ".storacha/**",
-                        "node_modules/**",
-                        ".git/**",
-                        "dist/**",
-                    ],
-                },
-                onChanges: async (changes) => {
-                    if (!syncEngine)
-                        return;
-                    await syncEngine.processChanges(changes);
-                    await syncEngine.sync();
-                    const nameArchive = await syncEngine.exportNameArchive();
-                    const updatedConfig = { ...deviceConfig, nameArchive };
-                    await saveDeviceConfig(workspace, updatedConfig);
-                },
-            });
-            await fileWatcher.start();
-            ctx.logger.info("Started watching workspace");
         },
         async stop(ctx) {
-            if (fileWatcher) {
-                await fileWatcher.stop();
-                fileWatcher = null;
+            for (const [workspace, sync] of activeSyncers) {
+                await sync.watcher.stop();
+                ctx.logger.info(`[${sync.agentId}] Stopped syncing: ${workspace}`);
             }
-            syncEngine = null;
-            ctx.logger.info("Stopped");
+            activeSyncers.clear();
         },
     });
-    // Register agent tools
+    // --- Agent tools (keyed by workspace dir) ---
     api.registerTool({
         name: "storacha_sync_status",
         label: "Storacha Sync Status",
         description: "Get the current Storacha workspace sync status",
         parameters: { type: "object", properties: {} },
-        execute: async () => {
-            if (!syncEngine) {
+        execute: async (_params, ctx) => {
+            const workspace = ctx?.workspaceDir;
+            const sync = workspace ? activeSyncers.get(workspace) : undefined;
+            if (!sync) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "Sync not initialized. Run /storacha-init first, then /storacha-setup or /storacha-join.",
+                            text: "Sync not active for this workspace. Set up with `openclaw clawracha init --agent <id>`.",
                         },
                     ],
                     details: null,
                 };
             }
-            const status = await syncEngine.status();
+            const status = await sync.engine.status();
             return {
                 content: [
                     { type: "text", text: JSON.stringify(status, null, 2) },
@@ -135,20 +139,22 @@ export default function plugin(api) {
         label: "Storacha Sync Now",
         description: "Trigger an immediate workspace sync to Storacha",
         parameters: { type: "object", properties: {} },
-        execute: async () => {
-            if (!syncEngine) {
+        execute: async (_params, ctx) => {
+            const workspace = ctx?.workspaceDir;
+            const sync = workspace ? activeSyncers.get(workspace) : undefined;
+            if (!sync) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "Sync not initialized. Run /storacha-init first, then /storacha-setup or /storacha-join.",
+                            text: "Sync not active for this workspace. Set up with `openclaw clawracha init --agent <id>`.",
                         },
                     ],
                     details: null,
                 };
             }
-            await syncEngine.sync();
-            const status = await syncEngine.status();
+            await sync.engine.sync();
+            const status = await sync.engine.status();
             return {
                 content: [
                     {
@@ -160,375 +166,272 @@ export default function plugin(api) {
             };
         },
     });
-    // --- Slash Commands ---
-    api.registerCommand({
-        name: "storacha-init",
-        description: "Generate an agent identity for Storacha sync",
-        handler: async (_ctx) => {
+    // --- CLI commands: openclaw clawracha <subcommand> ---
+    api.registerCli(({ program, config }) => {
+        const clawracha = program
+            .command("clawracha")
+            .description("Storacha workspace sync commands");
+        // Helper to resolve workspace from --agent
+        function requireAgent(agentId) {
+            if (!agentId) {
+                console.error("Error: --agent <id> is required. Specify which agent workspace to configure.");
+                process.exit(1);
+            }
+            return {
+                agentId,
+                workspace: resolveAgentWorkspace(config, agentId),
+            };
+        }
+        // --- init ---
+        clawracha
+            .command("init")
+            .description("Generate an agent identity for Storacha sync")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (opts) => {
             try {
-                const workspace = workspaceDir;
-                if (!workspace)
-                    return { text: "No workspace configured." };
-                // Check if already initialized
+                const { agentId, workspace } = requireAgent(opts.agent);
                 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"),
-                    };
+                    console.log(`Agent already initialized for ${agentId}.`);
+                    console.log(`Agent DID: ${agent.did()}`);
+                    if (existing.setupComplete) {
+                        console.log(`\nSetup is complete. Use \`openclaw clawracha status --agent ${agentId}\` to check sync state.`);
+                    }
+                    else {
+                        console.log("\nNext step — choose one:");
+                        console.log(`  New workspace:  openclaw clawracha setup <delegation> --agent ${agentId}`);
+                        console.log(`  Join existing:  openclaw clawracha join <upload> <name> --agent ${agentId}`);
+                    }
+                    return;
                 }
                 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"),
-                };
+                await saveDeviceConfig(workspace, { agentKey });
+                console.log(`🔥 Agent initialized for ${agentId}!`);
+                console.log(`Agent DID: ${agent.did()}`);
+                console.log("\nNext step — choose one:");
+                console.log(`  New workspace:  openclaw clawracha setup <delegation> --agent ${agentId}`);
+                console.log(`  Join existing:  openclaw clawracha join <upload> <name> --agent ${agentId}`);
             }
             catch (err) {
-                return {
-                    text: `\u274c Command failed: ${err.message}\n\`\`\`\n${err.stack ?? err}\n\`\`\``,
-                };
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-        },
-    });
-    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) => {
+        });
+        // --- setup ---
+        clawracha
+            .command("setup <delegation>")
+            .description("Set up a NEW workspace (first device). <delegation> is a file path or base64 CID string.")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (delegationArg, opts) => {
             try {
-                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.",
-                    };
+                const { agentId, workspace } = requireAgent(opts.agent);
+                const deviceConfig = await loadDeviceConfig(workspace);
+                if (!deviceConfig?.agentKey) {
+                    console.error(`Run \`openclaw clawracha init --agent ${agentId}\` first.`);
+                    process.exit(1);
                 }
-                if (config.setupComplete) {
-                    return {
-                        text: "Setup already complete. Use `/storacha-status` to check sync state.",
-                    };
+                if (deviceConfig.setupComplete) {
+                    console.log("Setup already complete.");
+                    return;
                 }
-                const b64 = _ctx.args?.trim();
-                if (!b64) {
-                    return {
-                        text: [
-                            "Usage: `/storacha-setup <upload-delegation-b64>`",
-                            "",
-                            "This creates a **new** workspace. If you're joining an existing workspace, use `/storacha-join` instead.",
-                        ].join("\n"),
-                    };
-                }
-                return {
-                    text: [
-                        "You ran '/storacha-setup' without the following command argument:",
-                        "",
-                        b64,
-                    ].join("\n"),
-                };
-                /*
-                // Validate delegation
-                const bytes = decodeDelegation(b64);
-                const { ok: delegation, error } = await extractDelegation(bytes);
-                if (!delegation) {
-                  return { text: `Invalid delegation: ${error}` };
-                }
-        
+                const delegation = await readDelegationArg(delegationArg);
                 const spaceDID = delegation.capabilities[0]?.with;
-        
-                config.uploadDelegation = b64;
-                config.spaceDID = spaceDID ?? undefined;
-                config.setupComplete = true;
-                await saveDeviceConfig(workspace, config);
-        
+                const { ok: archiveBytes } = await delegation.archive();
+                if (!archiveBytes) {
+                    throw new Error("Failed to archive delegation");
+                }
+                deviceConfig.uploadDelegation = encodeDelegation(archiveBytes);
+                deviceConfig.spaceDID = spaceDID ?? undefined;
+                deviceConfig.setupComplete = true;
+                await saveDeviceConfig(workspace, deviceConfig);
                 const { Agent } = await import("@storacha/ucn/pail");
-                const agent = Agent.parse(config.agentKey);
-        
-                return {
-                  text: [
-                    "\u{1f525} Storacha workspace ready!",
-                    `Agent DID: \`${agent.did()}\``,
-                    `Space: \`${spaceDID ?? "unknown"}\``,
-                    "",
-                    "Restart the gateway to start syncing.",
-                    "",
-                    "To add another device, run `/storacha-grant <their-agent-DID>` here,",
-                    "then `/storacha-join <upload-b64> <name-b64>` on the other device.",
-                  ].join("\n"),
-                };*/
+                const agent = Agent.parse(deviceConfig.agentKey);
+                console.log(`🔥 Storacha workspace ready for ${agentId}!`);
+                console.log(`Agent DID: ${agent.did()}`);
+                console.log(`Space: ${spaceDID ?? "unknown"}`);
+                console.log("\nRestart the gateway to start syncing: `openclaw gateway restart`");
+                console.log(`\nTo add another device, run \`openclaw clawracha grant <their-DID> --agent ${agentId}\` here,`);
+                console.log(`then \`openclaw clawracha join <upload> <name> --agent <id>\` on the other device.`);
             }
             catch (err) {
-                return {
-                    text: `\u274c Command failed: ${err.message}\n\`\`\`\n${err.stack ?? err}\n\`\`\``,
-                };
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-        },
-    });
-    api.registerCommand({
-        name: "storacha-join",
-        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) => {
+        });
+        // --- join ---
+        clawracha
+            .command("join <upload-delegation> <name-delegation>")
+            .description("Join an existing workspace from another device. Arguments are file paths or base64 CID strings.")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (uploadArg, nameArg, opts) => {
             try {
-                const workspace = workspaceDir;
-                if (!workspace)
-                    return { text: "No workspace configured." };
-                const args = _ctx.args?.trim();
-                if (!args) {
-                    return {
-                        text: [
-                            "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-setup` instead.",
-                        ].join("\n"),
-                    };
+                const { agentId, workspace } = requireAgent(opts.agent);
+                const deviceConfig = await loadDeviceConfig(workspace);
+                if (!deviceConfig?.agentKey) {
+                    console.error(`Run \`openclaw clawracha init --agent ${agentId}\` first.`);
+                    process.exit(1);
                 }
-                const spaceIdx = args.indexOf(" ");
-                if (spaceIdx === -1) {
-                    return {
-                        text: "Two arguments required: `/storacha-join <upload-b64> <name-b64>`",
-                    };
-                }
-                const uploadB64 = args.slice(0, spaceIdx).trim();
-                const nameB64 = args.slice(spaceIdx + 1).trim();
-                if (!uploadB64 || !nameB64) {
-                    return {
-                        text: "Two arguments required: `/storacha-join <upload-b64> <name-b64>`",
-                    };
-                }
-                // Validate upload delegation
-                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 = 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.",
-                    };
+                if (deviceConfig.setupComplete) {
+                    console.log("Setup already complete.");
+                    return;
                 }
-                const { Agent } = await import("@storacha/ucn/pail");
-                const agent = Agent.parse(config.agentKey);
+                const uploadDelegation = await readDelegationArg(uploadArg);
+                const nameDelegation = await readDelegationArg(nameArg);
                 const spaceDID = uploadDelegation.capabilities[0]?.with;
-                config.uploadDelegation = uploadB64;
-                config.nameDelegation = nameB64;
-                config.spaceDID = spaceDID ?? undefined;
-                config.setupComplete = true;
-                await saveDeviceConfig(workspace, config);
-                // Pull remote state immediately before watcher starts
+                const { ok: uploadArchive } = await uploadDelegation.archive();
+                if (!uploadArchive)
+                    throw new Error("Failed to archive upload delegation");
+                const { ok: nameArchiveBytes } = await nameDelegation.archive();
+                if (!nameArchiveBytes)
+                    throw new Error("Failed to archive name delegation");
+                deviceConfig.uploadDelegation = encodeDelegation(uploadArchive);
+                deviceConfig.nameDelegation = encodeDelegation(nameArchiveBytes);
+                deviceConfig.spaceDID = spaceDID ?? undefined;
+                deviceConfig.setupComplete = true;
+                await saveDeviceConfig(workspace, deviceConfig);
+                // Pull remote state before watcher starts
                 let pullCount = 0;
-                try {
-                    const storachaClient = await createStorachaClient(config);
-                    const engine = new SyncEngine(storachaClient, workspace);
-                    await engine.init(config);
-                    pullCount = await engine.pullRemote();
-                    // Save name archive after pull
-                    const nameArchive = await engine.exportNameArchive();
-                    config.nameArchive = nameArchive;
-                    await saveDeviceConfig(workspace, config);
-                }
-                catch (err) {
-                    return {
-                        text: [
-                            "\u26a0\ufe0f Delegations saved but initial pull failed:",
-                            `\`${err.message}\``,
-                            "",
-                            "Restart the gateway to retry.",
-                        ].join("\n"),
-                    };
-                }
-                return {
-                    text: [
-                        "\u{1f525} Joined existing Storacha workspace!",
-                        `Agent DID: \`${agent.did()}\``,
-                        `Space: \`${spaceDID ?? "unknown"}\``,
-                        `Pulled ${pullCount} files from remote.`,
-                        "",
-                        "Restart the gateway to start syncing.",
-                    ].join("\n"),
-                };
+                const storachaClient = await createStorachaClient(deviceConfig);
+                const engine = new SyncEngine(storachaClient, workspace);
+                await engine.init(deviceConfig);
+                pullCount = await engine.pullRemote();
+                // Save name archive after pull
+                const exportedArchive = await engine.exportNameArchive();
+                deviceConfig.nameArchive = exportedArchive;
+                await saveDeviceConfig(workspace, deviceConfig);
+                const { Agent } = await import("@storacha/ucn/pail");
+                const agent = Agent.parse(deviceConfig.agentKey);
+                console.log(`🔥 Joined existing Storacha workspace for ${agentId}!`);
+                console.log(`Agent DID: ${agent.did()}`);
+                console.log(`Space: ${spaceDID ?? "unknown"}`);
+                console.log(`Pulled ${pullCount} files from remote.`);
+                console.log("\nRestart the gateway to start syncing: `openclaw gateway restart`");
             }
             catch (err) {
-                return {
-                    text: `\u274c Command failed: ${err.message}\n\`\`\`\n${err.stack ?? err}\n\`\`\``,
-                };
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-        },
-    });
-    api.registerCommand({
-        name: "storacha-grant",
-        description: "Grant another device access. Usage: /storacha-grant <target-DID>",
-        acceptsArgs: true,
-        handler: async (_ctx) => {
+        });
+        // --- grant ---
+        clawracha
+            .command("grant <target-DID>")
+            .description("Grant another device access to this workspace")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (targetDID, opts) => {
             try {
-                const workspace = workspaceDir;
-                if (!workspace)
-                    return { text: "No workspace configured." };
-                const targetDID = _ctx.args?.trim();
-                if (!targetDID || !targetDID.startsWith("did:")) {
-                    return { text: "Usage: `/storacha-grant <did:key:z...>`" };
+                const { agentId, workspace } = requireAgent(opts.agent);
+                if (!targetDID.startsWith("did:")) {
+                    console.error("Error: target must be a DID (did:key:z...)");
+                    process.exit(1);
                 }
-                const config = await loadDeviceConfig(workspace);
-                if (!config) {
-                    return {
-                        text: "Not initialized. Run `/storacha-init` first.",
-                    };
+                const deviceConfig = await loadDeviceConfig(workspace);
+                if (!deviceConfig) {
+                    console.error(`Not initialized. Run \`openclaw clawracha init --agent ${agentId}\` first.`);
+                    process.exit(1);
                 }
                 const results = [];
                 // Re-delegate upload capability
-                if (config.uploadDelegation) {
-                    try {
-                        const storachaClient = await createStorachaClient(config);
-                        const audience = { did: () => targetDID };
-                        const uploadDelegation = await storachaClient.createDelegation(audience, [
-                            "space/blob/add",
-                            "space/index/add",
-                            "upload/add",
-                            "filecoin/offer",
-                        ]);
-                        const { ok: archiveBytes } = await uploadDelegation.archive();
-                        if (archiveBytes) {
-                            const b64 = encodeDelegation(archiveBytes);
-                            results.push("**Upload delegation:**\n```\n" + b64 + "\n```");
-                        }
-                    }
-                    catch (err) {
-                        results.push(`\u274c Failed to create upload delegation: ${err.message}`);
+                if (deviceConfig.uploadDelegation) {
+                    const storachaClient = await createStorachaClient(deviceConfig);
+                    const audience = {
+                        did: () => targetDID,
+                    };
+                    const uploadDel = await storachaClient.createDelegation(audience, [
+                        "space/blob/add",
+                        "space/index/add",
+                        "upload/add",
+                        "filecoin/offer",
+                    ]);
+                    const { ok: archiveBytes } = await uploadDel.archive();
+                    if (archiveBytes) {
+                        results.push(`Upload delegation:\n${encodeDelegation(archiveBytes)}`);
                     }
                 }
                 else {
-                    results.push("\u26a0\ufe0f No upload delegation to re-delegate.");
+                    results.push("⚠️ No upload delegation to re-delegate.");
                 }
-                // Re-delegate name (pail sync) capability
-                if (config.nameDelegation) {
-                    try {
-                        const { Agent, Name } = await import("@storacha/ucn/pail");
-                        const agent = Agent.parse(config.agentKey);
-                        let name;
-                        if (config.nameArchive) {
-                            const archiveBytes = decodeDelegation(config.nameArchive);
-                            name = await Name.extract(agent, archiveBytes);
-                        }
-                        else {
-                            const nameBytes = decodeDelegation(config.nameDelegation);
-                            const { ok: nameDel } = await extractDelegation(nameBytes);
-                            if (!nameDel) {
-                                results.push("\u274c Failed to extract name delegation.");
-                            }
-                            else {
-                                name = Name.from(agent, [nameDel]);
-                            }
-                        }
-                        if (name) {
-                            const nameDel = await name.grant(targetDID);
-                            const { ok: archiveBytes } = await nameDel.archive();
-                            if (archiveBytes) {
-                                const b64 = encodeDelegation(archiveBytes);
-                                results.push("**Name delegation:**\n```\n" + b64 + "\n```");
-                            }
+                // Re-delegate name capability
+                if (deviceConfig.nameDelegation) {
+                    const { Agent, Name } = await import("@storacha/ucn/pail");
+                    const { extract } = await import("@storacha/client/delegation");
+                    const agent = Agent.parse(deviceConfig.agentKey);
+                    let name;
+                    if (deviceConfig.nameArchive) {
+                        const archiveBytes = decodeDelegation(deviceConfig.nameArchive);
+                        name = await Name.extract(agent, archiveBytes);
+                    }
+                    else {
+                        const nameBytes = decodeDelegation(deviceConfig.nameDelegation);
+                        const { ok: nameDel } = await extract(nameBytes);
+                        if (nameDel) {
+                            name = Name.from(agent, [nameDel]);
                         }
                     }
-                    catch (err) {
-                        results.push(`\u274c Failed to create name delegation: ${err.message}`);
+                    if (name) {
+                        const nameDel = await name.grant(targetDID);
+                        const { ok: archiveBytes } = await nameDel.archive();
+                        if (archiveBytes) {
+                            results.push(`Name delegation:\n${encodeDelegation(archiveBytes)}`);
+                        }
                     }
                 }
                 else {
-                    results.push("\u26a0\ufe0f No name delegation to re-delegate.");
+                    results.push("⚠️ No name delegation to re-delegate.");
                 }
-                if (results.length === 0) {
-                    return { text: "Nothing to grant. Set up this device first." };
+                console.log(`🔥 Delegations for ${targetDID}:\n`);
+                for (const r of results) {
+                    console.log(r);
+                    console.log();
                 }
-                return {
-                    text: [
-                        `\u{1f525} Delegations for \`${targetDID}\`:`,
-                        "",
-                        ...results,
-                        "",
-                        "The target device should run:",
-                        "`/storacha-join <upload-b64> <name-b64>`",
-                    ].join("\n"),
-                };
+                console.log("The target device should run:");
+                console.log(`  openclaw clawracha join <upload-delegation> <name-delegation> --agent <id>`);
+                console.log("\nThen restart the gateway: `openclaw gateway restart`");
             }
             catch (err) {
-                return {
-                    text: `\u274c Command failed: ${err.message}\n\`\`\`\n${err.stack ?? err}\n\`\`\``,
-                };
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-        },
-    });
-    api.registerCommand({
-        name: "storacha-status",
-        description: "Show Storacha sync status",
-        handler: async (_ctx) => {
+        });
+        // --- status ---
+        clawracha
+            .command("status")
+            .description("Show Storacha sync status for an agent workspace")
+            .requiredOption("--agent <id>", "Agent ID")
+            .action(async (opts) => {
             try {
-                const workspace = workspaceDir;
-                if (!workspace)
-                    return { text: "No workspace configured." };
-                const config = await loadDeviceConfig(workspace);
-                if (!config)
-                    return {
-                        text: "Not initialized. Run `/storacha-init` first.",
-                    };
-                const lines = [
-                    "\u{1f525} Storacha Sync Status",
-                    `Agent: configured`,
-                    `Upload delegation: ${config.uploadDelegation ? "\u2705" : "\u274c not set"}`,
-                    `Name delegation: ${config.nameDelegation ? "\u2705" : "\u274c not set"}`,
-                    `Space DID: ${config.spaceDID ?? "unknown"}`,
-                    `Name Archive: ${config.nameArchive ? "saved" : "not created"}`,
-                    `Setup complete: ${config.setupComplete ? "\u2705" : "\u274c"}`,
-                ];
-                if (syncEngine) {
-                    const status = await syncEngine.status();
-                    lines.push(`Running: ${status.running}`, `Last Sync: ${status.lastSync
-                        ? new Date(status.lastSync).toISOString()
-                        : "never"}`, `Entries: ${status.entryCount}`, `Pending: ${status.pendingChanges}`);
+                const { agentId, workspace } = requireAgent(opts.agent);
+                const deviceConfig = await loadDeviceConfig(workspace);
+                if (!deviceConfig) {
+                    console.log(`Not initialized. Run \`openclaw clawracha init --agent ${agentId}\` first.`);
+                    return;
+                }
+                console.log(`🔥 Storacha Sync Status [${agentId}]`);
+                console.log(`Workspace: ${workspace}`);
+                console.log(`Upload delegation: ${deviceConfig.uploadDelegation ? "✅" : "❌ not set"}`);
+                console.log(`Name delegation: ${deviceConfig.nameDelegation ? "✅" : "❌ not set"}`);
+                console.log(`Space DID: ${deviceConfig.spaceDID ?? "unknown"}`);
+                console.log(`Name Archive: ${deviceConfig.nameArchive ? "saved" : "not created"}`);
+                console.log(`Setup complete: ${deviceConfig.setupComplete ? "✅" : "❌"}`);
+                const sync = activeSyncers.get(workspace);
+                if (sync) {
+                    const status = await sync.engine.status();
+                    console.log(`Running: true`);
+                    console.log(`Last Sync: ${status.lastSync ? new Date(status.lastSync).toISOString() : "never"}`);
+                    console.log(`Entries: ${status.entryCount}`);
+                    console.log(`Pending: ${status.pendingChanges}`);
+                }
+                else {
+                    console.log(`Running: false`);
                 }
-                return { text: lines.join("\n") };
             }
             catch (err) {
-                return {
-                    text: `\u274c Command failed: ${err.message}\n\`\`\`\n${err.stack ?? err}\n\`\`\``,
-                };
+                console.error(`Error: ${err.message}`);
+                process.exit(1);
             }
-        },
-    });
+        });
+    }, { commands: ["clawracha"] });
 }

package/dist/utils/delegation.d.ts

@@ -15,4 +15,9 @@ export declare function encodeDelegation(archiveBytes: Uint8Array): string;
  * base64 string → CID → identity multihash digest → bytes
  */
 export declare function decodeDelegation(encoded: string): Uint8Array;
+/**
+ * Read a delegation from either a file path (raw CAR) or a CID string (base64).
+ * Returns the extracted delegation.
+ */
+export declare function readDelegationArg(input: string): Promise<import("@ucanto/interface").Delegation<import("@ipld/dag-ucan").Capabilities>>;
 //# sourceMappingURL=delegation.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../../src/utils/delegation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,UAAU,GAAG,MAAM,CAGjE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAQ5D;AAGD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,0FAcpD"}

package/dist/utils/delegation.js

@@ -5,7 +5,9 @@
  * and identity multihash, encoded as base64. This matches the format
  * used by the Storacha CLI (`storacha delegation create --base64`).
  */
+import * as fs from "node:fs/promises";
 import { CID } from "multiformats/cid";
+import { extract } from "@storacha/client/delegation";
 import { base64 } from "multiformats/bases/base64";
 import { identity } from "multiformats/hashes/identity";
 /** CAR codec code (multicodec 0x0202) */
@@ -29,3 +31,23 @@ export function decodeDelegation(encoded) {
     }
     return cid.multihash.digest;
 }
+/**
+ * Read a delegation from either a file path (raw CAR) or a CID string (base64).
+ * Returns the extracted delegation.
+ */
+export async function readDelegationArg(input) {
+    let bytes;
+    try {
+        // Try reading as file first
+        bytes = await fs.readFile(input);
+    }
+    catch {
+        // Not a file — treat as CID string
+        bytes = decodeDelegation(input);
+    }
+    const { ok: delegation, error } = await extract(bytes);
+    if (!delegation) {
+        throw new Error(`Invalid delegation: ${error}`);
+    }
+    return delegation;
+}

package/dist/utils/workspace.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent workspace resolution.
+ *
+ * Mirrors OpenClaw's resolveAgentWorkspaceDir logic from
+ * src/agents/agent-scope.ts — resolves workspace dir for a given agent ID.
+ */
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+/**
+ * Resolve the workspace directory for an agent by ID.
+ * Matches OpenClaw's resolution order:
+ * 1. Agent-specific workspace from config
+ * 2. For default agent: agents.defaults.workspace or ~/.openclaw/workspace
+ * 3. For other agents: ~/.openclaw/workspace-{agentId}
+ */
+export declare function resolveAgentWorkspace(config: OpenClawConfig, agentId: string): string;
+/**
+ * Get all agent IDs from config.
+ */
+export declare function getAgentIds(config: OpenClawConfig): string[];
+//# sourceMappingURL=workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/utils/workspace.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,GACd,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAQ5D"}

package/dist/utils/workspace.js

@@ -0,0 +1,72 @@
+/**
+ * Agent workspace resolution.
+ *
+ * Mirrors OpenClaw's resolveAgentWorkspaceDir logic from
+ * src/agents/agent-scope.ts — resolves workspace dir for a given agent ID.
+ */
+import * as path from "node:path";
+import * as os from "node:os";
+/**
+ * Resolve the workspace directory for an agent by ID.
+ * Matches OpenClaw's resolution order:
+ * 1. Agent-specific workspace from config
+ * 2. For default agent: agents.defaults.workspace or ~/.openclaw/workspace
+ * 3. For other agents: ~/.openclaw/workspace-{agentId}
+ */
+export function resolveAgentWorkspace(config, agentId) {
+    const agent = config.agents?.list?.find((a) => a.id.toLowerCase() === agentId.toLowerCase());
+    // Agent-specific workspace
+    if (agent?.workspace?.trim()) {
+        return resolveUserPath(agent.workspace.trim());
+    }
+    // Default agent gets the default workspace
+    const defaultId = resolveDefaultAgentId(config);
+    if (agentId.toLowerCase() === defaultId.toLowerCase()) {
+        const fallback = config.agents?.defaults?.workspace?.trim();
+        if (fallback) {
+            return resolveUserPath(fallback);
+        }
+        return path.join(resolveStateDir(), "workspace");
+    }
+    // Other agents: workspace-{id}
+    return path.join(resolveStateDir(), `workspace-${agentId}`);
+}
+/**
+ * Get all agent IDs from config.
+ */
+export function getAgentIds(config) {
+    const list = config.agents?.list;
+    if (!Array.isArray(list) || list.length === 0) {
+        return ["default"];
+    }
+    return list
+        .filter((a) => a && typeof a === "object" && a.id)
+        .map((a) => a.id);
+}
+/**
+ * Resolve the default agent ID from config.
+ */
+function resolveDefaultAgentId(config) {
+    const list = config.agents?.list;
+    if (!Array.isArray(list) || list.length === 0) {
+        return "default";
+    }
+    const defaultAgent = list.find((a) => a.default);
+    return (defaultAgent ?? list[0])?.id?.trim() || "default";
+}
+/**
+ * Resolve OpenClaw state directory.
+ */
+function resolveStateDir() {
+    return (process.env.OPENCLAW_STATE_DIR ||
+        path.join(os.homedir(), ".openclaw"));
+}
+/**
+ * Expand ~ in paths.
+ */
+function resolveUserPath(p) {
+    if (p.startsWith("~/")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/clawracha",
-  "version": "0.0.11-rc.0",
+  "version": "0.1.0",
   "description": "OpenClaw plugin for Storacha workspace sync via UCN Pail",
   "type": "module",
   "files": [
@@ -36,7 +36,7 @@
     "@web3-storage/pail": "0.6.3-rc.3",
     "carstream": "^2.3.0",
     "chokidar": "^3.6.0",
-    "multiformats": "^13.3.6"
+    "multiformats": "^13.0.0"
   },
   "devDependencies": {
     "@ipld/unixfs": "^3.0.0",