squad-openclaw 2026.2.2001 → 2026.2.2003

package/README.md

@@ -10,7 +10,7 @@ OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity regis
 | `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | Remote filesystem access for browser clients (subject to security restrictions below) |
 | `sql_query` | Restricted SQLite query tool — `sqlite3` only, scoped to `~/.openclaw/squad-ceo-data/` |
 | `squad.version.check`, `squad.version.update` | Plugin version management and self-update |
-| `tools.invoke` | RPC-based tool invocation for relay mode (WebSocket) |
+| `tools.invoke` | RPC-based tool invocation for relay mode — **only invokes this plugin's own tools**, each with its own security restrictions (see below) |
 | Cloud relay client | **Disabled by default (opt-in).** Connects outbound to `relay.squad.ceo` for remote browser access |
 
 ## Security Model
@@ -112,13 +112,31 @@ Browser ──[connect request]──> relay.squad.ceo ──[relay.forward]─
 
 The relay server only sees the outer `relay.forward` envelope. It **never** receives the modified request containing the token. The token injection happens entirely within the relay-client process, and the modified message is sent over a **local loopback** connection to the gateway. A compromised relay server cannot intercept the operator token because it never traverses the relay — it only exists on the `localhost:18789` path.
 
+## Remote Tool Invocation (`tools.invoke`)
+
+The `tools.invoke` gateway method allows the browser to call plugin tools over WebSocket (used in relay mode where there is no HTTP path). This is **not** a generic RPC gateway — it is scoped exclusively to the tools registered by **this plugin**:
+
+| Tool | What it can access | Restrictions |
+|---|---|---|
+| `fs_read`, `fs_write`, `fs_list`, `fs_delete`, `fs_rename`, `fs_mkdir` | `~/.openclaw/` only | All 4 security layers apply (blocked dirs, blocked files, redaction, allowed roots, write protection) |
+| `sql_query` | `~/.openclaw/squad-ceo-data/*.db` only | sqlite3 only, no shell, no command injection (see below) |
+| `entity_list`, `entity_search`, `entity_sync` | In-memory entity index | Read-only metadata (names, types, paths) |
+| `squad.version.check`, `squad.version.update` | npm registry | Read-only check + controlled `npm install` |
+
+It **cannot** invoke gateway core tools (`exec`, `bash`, `read`, `write`, `web_fetch`, etc.) — only the tools this plugin registers via `api.registerTool()`. Every invoked tool enforces its own security restrictions independently — `tools.invoke` is just a transport layer, not a privilege escalation.
+
+**Authentication chain for relay access:** Browser JWT → relay claim token → operator-approved device pairing → operator auth token (localhost only). All four must be valid for a `tools.invoke` call to reach the gateway.
+
 ## SQL Query Tool
 
+> **`sql_query` can only access the plugin's own application data** in `~/.openclaw/squad-ceo-data/`. It cannot read or modify any other files on the system — not system databases, not user documents, not gateway configuration.
+
 The `sql_query` tool provides restricted SQLite access:
 
-- **Path restriction:** Database files must be within `~/.openclaw/squad-ceo-data/`
+- **Path restriction:** Database files must be within `~/.openclaw/squad-ceo-data/` — the plugin's own data directory containing entity registries and application state. Paths outside this directory are rejected before any query is executed.
 - **No shell:** Uses `execFile` (not `exec`) — arguments are passed as an argv array, preventing command injection
-- **No arbitrary commands:** Only `sqlite3` is executed
+- **No arbitrary commands:** Only `sqlite3` is executed — no other binary can be invoked through this tool
+- **Data scope:** The databases in `squad-ceo-data/` contain only Squad application data (entity metadata, search indexes, user preferences). No credentials, tokens, or gateway configuration is stored in these databases.
 
 ## Build Transparency
 

package/dist/index.js

@@ -1,3 +1,107 @@
+// src/agents.ts
+import { execSync } from "child_process";
+function registerAgentMethods(api) {
+  api.registerGatewayMethod(
+    "squad.agents.add",
+    async ({ params, respond }) => {
+      const name = params?.name;
+      const model = params?.model;
+      if (!name || typeof name !== "string" || !name.trim()) {
+        respond(false, { error: "Missing or empty 'name' parameter" });
+        return;
+      }
+      const safeName = name.trim();
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9 _-]*$/.test(safeName)) {
+        respond(false, { error: "Agent name must start with a letter/number and contain only letters, numbers, spaces, hyphens, or underscores" });
+        return;
+      }
+      try {
+        let cmd = `openclaw agents add ${JSON.stringify(safeName)} --non-interactive`;
+        if (model) {
+          cmd += ` --model ${JSON.stringify(model)}`;
+        }
+        const output = execSync(cmd, {
+          timeout: 3e4,
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"]
+        });
+        respond(true, { ok: true, output: output.slice(0, 1e3) });
+      } catch (err2) {
+        const msg = err2 instanceof Error ? err2.message : String(err2);
+        const stderr = err2?.stderr;
+        respond(false, {
+          error: `Failed to add agent: ${stderr || msg}`.slice(0, 500)
+        });
+      }
+    }
+  );
+  api.registerGatewayMethod(
+    "squad.agents.delete",
+    async ({ params, respond }) => {
+      const agentId = params?.agentId;
+      if (!agentId || typeof agentId !== "string" || !agentId.trim()) {
+        respond(false, { error: "Missing or empty 'agentId' parameter" });
+        return;
+      }
+      if (agentId === "main") {
+        respond(false, { error: "Cannot delete the main agent" });
+        return;
+      }
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(agentId)) {
+        respond(false, { error: "Invalid agent ID format" });
+        return;
+      }
+      try {
+        const output = execSync(
+          `openclaw agents delete ${JSON.stringify(agentId)} --non-interactive 2>&1`,
+          { timeout: 3e4, encoding: "utf-8" }
+        );
+        respond(true, { ok: true, output: output.slice(0, 1e3) });
+      } catch (err2) {
+        const msg = err2 instanceof Error ? err2.message : String(err2);
+        const stderr = err2?.stderr;
+        respond(false, {
+          error: `Failed to delete agent: ${stderr || msg}`.slice(0, 500)
+        });
+      }
+    }
+  );
+  api.registerGatewayMethod(
+    "squad.agents.set-identity",
+    async ({ params, respond }) => {
+      const agentId = params?.agentId;
+      const name = params?.name;
+      const emoji = params?.emoji;
+      const theme = params?.theme;
+      if (!agentId || typeof agentId !== "string") {
+        respond(false, { error: "Missing 'agentId' parameter" });
+        return;
+      }
+      const args = [`--agent`, JSON.stringify(agentId)];
+      if (name) args.push(`--name`, JSON.stringify(name));
+      if (emoji) args.push(`--emoji`, JSON.stringify(emoji));
+      if (theme) args.push(`--theme`, JSON.stringify(theme));
+      if (args.length <= 2) {
+        respond(false, { error: "No identity fields provided (name, emoji, or theme)" });
+        return;
+      }
+      try {
+        const output = execSync(
+          `openclaw agents set-identity ${args.join(" ")} 2>&1`,
+          { timeout: 15e3, encoding: "utf-8" }
+        );
+        respond(true, { ok: true, output: output.slice(0, 1e3) });
+      } catch (err2) {
+        const msg = err2 instanceof Error ? err2.message : String(err2);
+        const stderr = err2?.stderr;
+        respond(false, {
+          error: `Failed to set identity: ${stderr || msg}`.slice(0, 500)
+        });
+      }
+    }
+  );
+}
+
 // src/entities.ts
 import { Type as T } from "@sinclair/typebox";
 import path3 from "path";
@@ -1111,7 +1215,7 @@ function registerSqlTools(api) {
 }
 
 // src/version.ts
-import { execSync } from "child_process";
+import { execSync as execSync2 } from "child_process";
 import fs5 from "fs";
 import path5 from "path";
 import { fileURLToPath } from "url";
@@ -1176,13 +1280,13 @@ function registerVersionMethods(api) {
         const before = getCurrentVersion();
         let updateOutput = "";
         try {
-          updateOutput = execSync(
+          updateOutput = execSync2(
             `openclaw plugins update ${PACKAGE_NAME} 2>&1`,
             { timeout: 12e4, encoding: "utf-8" }
           );
         } catch {
           try {
-            updateOutput = execSync(
+            updateOutput = execSync2(
               `npm install -g ${PACKAGE_NAME}@latest 2>&1`,
               { timeout: 12e4, encoding: "utf-8" }
             );
@@ -1208,7 +1312,7 @@ function registerVersionMethods(api) {
         );
         setTimeout(() => {
           try {
-            execSync("openclaw gateway restart 2>&1", {
+            execSync2("openclaw gateway restart 2>&1", {
               timeout: 3e4,
               encoding: "utf-8"
             });
@@ -1895,6 +1999,7 @@ function squadAppPlugin(api) {
   registerFilesystemTools(api);
   registerSqlTools(api);
   registerVersionMethods(api);
+  registerAgentMethods(api);
   api.registerGatewayMethod(
     "tools.invoke",
     async ({ params, respond }) => {
@@ -1918,6 +2023,49 @@ function squadAppPlugin(api) {
       }
     }
   );
+  api.registerGatewayMethod(
+    "tools.list",
+    async ({ respond }) => {
+      const coreTools = [
+        "exec",
+        "bash",
+        "process",
+        "read",
+        "write",
+        "edit",
+        "apply_patch",
+        "web_search",
+        "web_fetch",
+        "browser",
+        "canvas",
+        "nodes",
+        "image",
+        "message",
+        "cron",
+        "gateway",
+        "sessions_list",
+        "sessions_history",
+        "sessions_send",
+        "sessions_spawn",
+        "session_status",
+        "agents_list",
+        "memory_search"
+      ];
+      const groups = [
+        "group:fs",
+        "group:runtime",
+        "group:sessions",
+        "group:memory",
+        "group:web",
+        "group:ui",
+        "group:automation",
+        "group:messaging",
+        "group:nodes"
+      ];
+      const pluginTools = Array.from(toolExecutors.keys());
+      respond(true, { tools: [...coreTools, ...groups, ...pluginTools] });
+    }
+  );
   const relayEnabled = api.pluginConfig?.["relay.enabled"] ?? false;
   if (relayEnabled) {
     const relayUrl = api.pluginConfig?.["relay.url"] || "wss://relay.squad.ceo";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-openclaw",
-  "version": "2026.2.2001",
+  "version": "2026.2.2003",
   "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
   "type": "module",
   "main": "./dist/index.js",