draft plugin system

Author: webdeb

AGENTS.md

@@ -0,0 +1,115 @@
+# Clawset Integration Guide
+
+You are running inside a **clawset-managed instance**. Clawset is an orchestrator that manages your lifecycle, provides credentials, and connects you with peer agents.
+
+## Directory: `$HOME/clawset/.clawset/`
+
+This is the shared communication directory between you and the clawset host.
+
+### Files You Can READ
+
+| File | Purpose |
+|------|---------|
+| `context.json` | Info about this instance, peer instances, and available auth |
+| `auth/{provider}.json` | Credentials for AI providers (e.g., `auth/openai-codex.json`) |
+| `CLAWSET.md` | This file |
+
+### Files You Can WRITE
+
+| File | Purpose |
+|------|---------|
+| `views.json` | Register web UIs that clawset should display as tabs |
+
+---
+
+## Registering Views
+
+To make a web UI visible in the clawset desktop app, write to `views.json`:
+
+```json
+{
+  "views": [
+    {
+      "id": "my-dashboard",
+      "name": "My Dashboard",
+      "port": 8080,
+      "path": "/"
+    }
+  ]
+}
+```
+
+Each entry becomes a tab in clawset. You can add/remove entries at any time — clawset polls this file periodically.
+
+**Fields:**
+- `id` — unique identifier (lowercase, kebab-case)
+- `name` — display name shown in the tab
+- `port` — port your web service listens on (bound to `0.0.0.0`)
+- `path` — URL path (default: `/`)
+
+---
+
+## Reading Context
+
+`context.json` is written by clawset and tells you about your environment:
+
+```json
+{
+  "orchestrator": "clawset",
+  "instance": {
+    "id": "clawset-1",
+    "ip": "192.168.64.2",
+    "provider": "multipass"
+  },
+  "peers": [
+    {
+      "id": "clawset-2",
+      "ip": "192.168.64.3",
+      "apps": ["zeroclaw"],
+      "provider": "multipass"
+    }
+  ],
+  "auth": {
+    "available": ["openai-codex"],
+    "missing": ["anthropic"]
+  }
+}
+```
+
+Use `peers` to discover and communicate with other agent instances.
+
+---
+
+## Using Auth Credentials
+
+Credentials are stored in `auth/{provider-id}.json`. Format depends on the provider type:
+
+**OAuth2 (e.g., openai-codex):**
+```json
+{
+  "type": "oauth2",
+  "access": "eyJ...",
+  "refresh": "eyJ...",
+  "expires": 1709235600,
+  "accountId": "user_..."
+}
+```
+
+**API Key (e.g., anthropic):**
+```json
+{
+  "type": "api_key",
+  "key": "sk-ant-..."
+}
+```
+
+Map these to your own config format as needed.
+
+---
+
+## Important Notes
+
+- **Do not delete** `context.json` or `auth/` files — clawset manages these.
+- **Do** update `views.json` whenever you start or stop a web service.
+- Bind web services to `0.0.0.0`, not `localhost`, so they're accessible from the host.
+- This directory is on a shared mount — changes are visible immediately.

CLAWSET.md

@@ -0,0 +1,26 @@
+type: instance-provider
+id: multipass
+name: Multipass
+version: "1.0.0"
+description: "Ubuntu VMs via Canonical Multipass"
+homepage: https://github.com/webdeb/clawset-multipass
+
+requirements:
+  binaries: [multipass]
+
+capabilities:
+  mount: true
+  transfer: true
+  shell: true
+
+scripts:
+  is_available: scripts/is_available.js
+  create: scripts/create.js
+  destroy: scripts/destroy.js
+  start: scripts/start.js
+  stop: scripts/stop.js
+  list: scripts/list.js
+  get: scripts/get.js
+  exec: scripts/exec.js
+  transfer: scripts/transfer.js
+  mount: scripts/mount.js

plugins/clawset-multipass/manifest.yaml

@@ -0,0 +1,29 @@
+// Create a new Multipass instance
+var name = clawset.env("NAME");
+var cpus = clawset.env("CPUS") || "2";
+var memory = clawset.env("MEMORY") || "4G";
+var disk = clawset.env("DISK") || "20G";
+var image = clawset.env("IMAGE") || "lts";
+
+clawset.log("Launching Ubuntu " + image + " instance '" + name + "' (cpus=" + cpus + ", memory=" + memory + ", disk=" + disk + ")...");
+
+var result = clawset.shell("multipass", [
+    "launch", "-v", image,
+    "--name", name,
+    "--cpus", cpus,
+    "--memory", memory,
+    "--disk", disk
+]);
+
+if (result.exitCode !== 0) {
+    throw new Error("Failed to launch instance: " + result.stderr);
+}
+
+clawset.log("Instance '" + name + "' created successfully!");
+
+return {
+    id: name,
+    name: name,
+    status: "Running",
+    provider: "multipass"
+};

plugins/clawset-multipass/scripts/create.js

@@ -0,0 +1,7 @@
+// Destroy a Multipass instance
+var instanceId = clawset.env("INSTANCE_ID");
+var result = clawset.shell("multipass", ["delete", instanceId, "--purge"]);
+if (result.exitCode !== 0) {
+    throw new Error("Failed to destroy instance: " + result.stderr);
+}
+return { success: true };

plugins/clawset-multipass/scripts/destroy.js

@@ -0,0 +1,13 @@
+// Execute a command inside a Multipass instance
+var instanceId = clawset.env("INSTANCE_ID");
+var cmd = clawset.env("CMD");
+
+var result = clawset.shell("multipass", [
+    "exec", instanceId, "--", "bash", "-ic", cmd
+]);
+
+return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode
+};

plugins/clawset-multipass/scripts/exec.js

@@ -0,0 +1,99 @@
+// Get detailed info for a single Multipass instance
+var instanceId = clawset.env("INSTANCE_ID");
+var result = clawset.shell("multipass", ["info", instanceId, "--format", "json"]);
+
+if (result.exitCode !== 0) {
+    clawset.log("multipass info failed: " + result.stderr);
+    return null;
+}
+
+var data = JSON.parse(result.stdout);
+var info = data.info && data.info[instanceId];
+
+if (!info) {
+    return null;
+}
+
+// Parse resources
+var memory = null;
+if (info.memory) {
+    var memTotal = info.memory.total || 0;
+    var memUsed = info.memory.used || 0;
+    memory = Math.round(memUsed / 1024 / 1024) + " MB / " + Math.round(memTotal / 1024 / 1024) + " MB";
+}
+
+var cpus = null;
+if (info.cpu_count) {
+    cpus = String(info.cpu_count);
+}
+
+var storage = null;
+if (info.disks && info.disks.sda1) {
+    var diskTotal = parseInt(info.disks.sda1.total || "0");
+    var diskUsed = parseInt(info.disks.sda1.used || "0");
+    storage = Math.round(diskUsed / 1024 / 1024 / 1024) + " GB / " + Math.round(diskTotal / 1024 / 1024 / 1024) + " GB";
+}
+
+// Parse mounts
+var mounts = {};
+if (info.mounts) {
+    for (var mountPoint in info.mounts) {
+        mounts[mountPoint] = info.mounts[mountPoint].source_path || "";
+    }
+}
+
+var ip = "";
+if (info.ipv4 && info.ipv4.length > 0) {
+    ip = info.ipv4[0];
+}
+
+// Check node/openclaw/provisioning status inside the VM
+var innerResult = clawset.shell("multipass", [
+    "exec", instanceId, "--", "bash", "-ic",
+    "source ~/.bashrc; echo '===NODE==='; node -v || echo 'NOT_FOUND'; echo '===OPENCLAW_VER==='; openclaw --version || echo 'NOT_FOUND'; echo '===PROVISIONING==='; if [ -f /tmp/provisioning ]; then echo 'YES'; else echo 'NO'; fi"
+]);
+
+var nodeInstalled = null;
+var openclawInstalled = false;
+var isProvisioning = false;
+
+if (innerResult.exitCode === 0) {
+    var lines = innerResult.stdout.split("\n");
+    var section = "";
+    for (var i = 0; i < lines.length; i++) {
+        var line = lines[i].trim();
+        if (line === "===NODE===") { section = "node"; continue; }
+        if (line === "===OPENCLAW_VER===") { section = "openclaw"; continue; }
+        if (line === "===PROVISIONING===") { section = "provisioning"; continue; }
+
+        if (section === "node" && line !== "NOT_FOUND" && line !== "") {
+            nodeInstalled = line;
+        }
+        if (section === "openclaw" && line !== "NOT_FOUND" && line !== "") {
+            openclawInstalled = true;
+        }
+        if (section === "provisioning") {
+            isProvisioning = (line === "YES");
+        }
+    }
+}
+
+return {
+    id: instanceId,
+    name: instanceId,
+    status: info.state || "Unknown",
+    ip: ip,
+    provider: "multipass",
+    meta: {
+        os: info.image_release || "Ubuntu"
+    },
+    resources: {
+        cpus: cpus,
+        memory: memory,
+        storage: storage
+    },
+    mounts: mounts,
+    node_installed: nodeInstalled,
+    openclaw_installed: openclawInstalled,
+    is_provisioning: isProvisioning
+};

plugins/clawset-multipass/scripts/get.js

@@ -0,0 +1,3 @@
+// Check if Multipass is available on this host
+var result = clawset.shell("multipass", ["version"]);
+return result.exitCode === 0;