squad-openclaw 2026.2.2201 → 2026.2.2205

package/README.md

@@ -135,6 +135,13 @@ echo '{"claimToken":"<token>"}' > ~/.openclaw/squad-ceo-data/relay/squad-relay.j
 
 The claim token is a short-lived, single-use code generated by the relay server for the authenticated user. It links this gateway to the user's Squad account. Once consumed, the relay returns a `roomId` for future reconnections, and the claim token is no longer needed.
 
+For local testing, the relay endpoint can be overridden with environment variables:
+
+- `OPENCLAW_SQUAD_RELAY_URL` (preferred)
+- `SQUAD_RELAY_URL` (fallback)
+
+If neither is set, the plugin uses the production default `wss://relay.squad.ceo`.
+
 ### How the Relay Connection Works
 
 ```

package/dist/index.js

@@ -2183,7 +2183,7 @@ function registerSqlTools(api) {
 }
 
 // src/version.ts
-import { execSync as execSync2 } from "child_process";
+import { spawn } from "child_process";
 import fs9 from "fs";
 import path10 from "path";
 import { fileURLToPath } from "url";
@@ -2193,6 +2193,9 @@ var updateInProgress = false;
 var VERIFY_TIMEOUT_MS = 2e4;
 var VERIFY_INTERVAL_MS = 500;
 var RESTART_BUFFER_MS = 5e3;
+var REGISTRY_TIMEOUT_MS = 2500;
+var COMMAND_OUTPUT_LIMIT = 8e3;
+var COMMAND_KILL_GRACE_MS = 2e3;
 function readInstalledVersionFromConfig() {
   try {
     const raw = fs9.readFileSync(CONFIG_PATH, "utf-8");
@@ -2243,9 +2246,9 @@ function getCurrentVersion() {
     return "0.0.0";
   }
 }
-async function fetchLatestVersion() {
+async function fetchLatestVersion(timeoutMs = REGISTRY_TIMEOUT_MS) {
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 1e4);
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}`, {
       signal: controller.signal
@@ -2257,14 +2260,64 @@ async function fetchLatestVersion() {
     clearTimeout(timeout);
   }
 }
-function runDoctorFixSilently() {
-  try {
-    execSync2("openclaw doctor --fix 2>/dev/null || true", {
-      timeout: 3e4,
-      encoding: "utf-8"
+async function runCommand(args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn("openclaw", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true
     });
-  } catch {
-  }
+    let output = "";
+    let timedOut = false;
+    let resolved = false;
+    let killGraceTimer = null;
+    const append = (chunk) => {
+      output += chunk.toString();
+      if (output.length > COMMAND_OUTPUT_LIMIT) {
+        output = output.slice(output.length - COMMAND_OUTPUT_LIMIT);
+      }
+    };
+    const finalize = (result) => {
+      if (resolved) return;
+      resolved = true;
+      if (killGraceTimer) clearTimeout(killGraceTimer);
+      clearTimeout(timeout);
+      resolve(result);
+    };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", (err2) => {
+      append(String(err2));
+      finalize({
+        ok: false,
+        timedOut,
+        exitCode: null,
+        signal: null,
+        output
+      });
+    });
+    child.on("close", (code, signal) => {
+      finalize({
+        ok: !timedOut && code === 0,
+        timedOut,
+        exitCode: code,
+        signal,
+        output
+      });
+    });
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+      }
+      killGraceTimer = setTimeout(() => {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+        }
+      }, COMMAND_KILL_GRACE_MS);
+    }, timeoutMs);
+  });
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -2399,13 +2452,25 @@ async function waitForVerifiedInstall() {
 function registerVersionMethods(api) {
   api.registerGatewayMethod(
     "squad.version.check",
-    async ({ respond }) => {
+    async ({ respond, params }) => {
       try {
+        const checkParams = params ?? {};
         const current = getCurrentVersion();
+        if (checkParams.skipRegistry) {
+          console.log("[version_check_local] returning local version only");
+          respond(true, {
+            current,
+            latest: null,
+            updateAvailable: false,
+            registrySkipped: true
+          });
+          return;
+        }
         let latest;
         try {
           latest = await fetchLatestVersion();
         } catch {
+          console.log("[version_check_registry_timeout] npm registry unavailable");
           respond(true, {
             current,
             latest: null,
@@ -2433,6 +2498,7 @@ function registerVersionMethods(api) {
         return;
       }
       updateInProgress = true;
+      const updateAttemptId = `${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
       try {
         const before = getCurrentVersion();
         const beforeInstalledVersion = readInstalledVersionFromConfig();
@@ -2448,19 +2514,25 @@ function registerVersionMethods(api) {
           configBackup = fs9.readFileSync(CONFIG_PATH, "utf-8");
         } catch {
         }
-        runDoctorFixSilently();
+        await runCommand(["doctor", "--fix"], 3e4);
         try {
-          updateOutput = execSync2(
-            `openclaw plugins update ${PACKAGE_NAME} 2>&1`,
-            { timeout: 12e4, encoding: "utf-8" }
-          );
+          const first = await runCommand(["plugins", "update", PACKAGE_NAME], 12e4);
+          updateOutput = first.output;
+          if (!first.ok) {
+            throw new Error(
+              first.timedOut ? "UPDATE_TIMEOUT: plugins update timed out" : `UPDATE_FAILED: plugins update exited with code ${String(first.exitCode)}`
+            );
+          }
         } catch (firstErr) {
-          runDoctorFixSilently();
+          await runCommand(["doctor", "--fix"], 3e4);
           try {
-            updateOutput = execSync2(
-              `openclaw plugins update ${PACKAGE_NAME} 2>&1`,
-              { timeout: 12e4, encoding: "utf-8" }
-            );
+            const retry = await runCommand(["plugins", "update", PACKAGE_NAME], 12e4);
+            updateOutput = retry.output;
+            if (!retry.ok) {
+              throw new Error(
+                retry.timedOut ? "UPDATE_TIMEOUT: plugins update timed out after retry" : `UPDATE_FAILED: plugins update retry exited with code ${String(retry.exitCode)}`
+              );
+            }
           } catch (installErr) {
             if (configBackup) {
               try {
@@ -2471,9 +2543,11 @@ function registerVersionMethods(api) {
             const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
             const retryMsg = installErr instanceof Error ? installErr.message : String(installErr);
             respond(false, {
+              code: /UPDATE_TIMEOUT/.test(retryMsg) ? "UPDATE_TIMEOUT" : "UPDATE_FAILED",
               error: `Update failed after doctor fix retry: ${retryMsg}`,
               output: updateOutput,
-              firstError: firstMsg
+              firstError: firstMsg,
+              updateAttemptId
             });
             return;
           }
@@ -2487,9 +2561,11 @@ function registerVersionMethods(api) {
             }
           }
           respond(false, {
+            code: "VERIFY_FAILED",
             error: `Update verification failed: ${verification.reason ?? "unknown error"}`,
             output: updateOutput.slice(0, 500),
-            verification
+            verification,
+            updateAttemptId
           });
           return;
         }
@@ -2498,10 +2574,12 @@ function registerVersionMethods(api) {
         if (beforeInstalledVersion && verificationAfterReconcile.packageVersion && beforeInstalledVersion === verificationAfterReconcile.packageVersion) {
           const alreadyLatest = !!latestVersion && compareVersions(verificationAfterReconcile.packageVersion, latestVersion) >= 0;
           respond(false, {
+            code: "UPDATE_FAILED",
             error: alreadyLatest ? `Already at latest version (${verificationAfterReconcile.packageVersion}).` : `Update command completed but installed version did not change (${verificationAfterReconcile.packageVersion}).`,
             output: updateOutput.slice(0, 500),
             verification: verificationAfterReconcile,
-            latestVersion
+            latestVersion,
+            updateAttemptId
           });
           return;
         }
@@ -2514,22 +2592,27 @@ function registerVersionMethods(api) {
           restartInMs: RESTART_BUFFER_MS,
           verification: verificationAfterReconcile,
           latestVersion,
-          output: updateOutput.slice(0, 500)
+          output: updateOutput.slice(0, 500),
+          updateAttemptId
         });
         await sleep(RESTART_BUFFER_MS);
         console.log(
           `[version] Plugin update verified (was ${before}), restarting gateway...`
         );
-        try {
-          execSync2("openclaw gateway restart 2>&1", {
-            timeout: 3e4,
-            encoding: "utf-8"
+        const restartResult = await runCommand(["gateway", "restart"], 3e4);
+        if (!restartResult.ok && !restartResult.timedOut) {
+          console.log("[update_cmd_timeout] restart command failed unexpectedly", {
+            updateAttemptId,
+            exitCode: restartResult.exitCode,
+            signal: restartResult.signal
           });
-        } catch {
         }
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        respond(false, { error: msg });
+        respond(false, {
+          code: /VERIFY_FAILED/.test(msg) ? "VERIFY_FAILED" : /UPDATE_TIMEOUT/.test(msg) ? "UPDATE_TIMEOUT" : "UPDATE_FAILED",
+          error: msg
+        });
       } finally {
         updateInProgress = false;
       }
@@ -2555,7 +2638,7 @@ function normalizeEnvelope(raw) {
     blocking: true
   };
 }
-function validateHumanQuestionEnvelope(text) {
+function validateHumanQuestionEnvelope(text, options) {
   const markerIndex = text.indexOf(MARKER);
   if (markerIndex < 0) return { valid: false, markerFound: false };
   const tail = text.slice(markerIndex + MARKER.length).trimStart();
@@ -2573,23 +2656,111 @@ function validateHumanQuestionEnvelope(text) {
   if (!normalized) {
     return { valid: false, markerFound: true, errorCode: "schema_invalid" };
   }
-  return { valid: true, markerFound: true, normalizedEnvelope: normalized };
+  const expectedSessionKey = options?.expectedSessionKey?.trim();
+  const sessionKeyMismatch = !!(expectedSessionKey && normalized.sessionKey !== expectedSessionKey);
+  return {
+    valid: true,
+    markerFound: true,
+    normalizedEnvelope: normalized,
+    sessionKeyMismatch
+  };
 }
 function registerQuestionMethods(api) {
   api.registerGatewayMethod(
     "squad.questions.validate-envelope",
     async ({ params, respond }) => {
       const text = typeof params?.text === "string" ? params.text : "";
+      const expectedSessionKey = typeof params?.expectedSessionKey === "string" ? params.expectedSessionKey : void 0;
       if (!text) {
         respond(false, { error: "Missing 'text' parameter" });
         return;
       }
-      const result = validateHumanQuestionEnvelope(text);
+      const result = validateHumanQuestionEnvelope(text, { expectedSessionKey });
       respond(true, result);
     }
   );
 }
 
+// src/sessions.ts
+function asRecord(value) {
+  return value && typeof value === "object" ? value : null;
+}
+function extractSessionKey(value) {
+  const record = asRecord(value);
+  if (!record) return null;
+  if (typeof record.key === "string" && record.key.trim()) {
+    return record.key.trim();
+  }
+  const nestedKey = asRecord(record.key);
+  if (nestedKey && typeof nestedKey.key === "string" && nestedKey.key.trim()) {
+    return nestedKey.key.trim();
+  }
+  if (typeof record.sessionKey === "string" && record.sessionKey.trim()) {
+    return record.sessionKey.trim();
+  }
+  const nestedSession = asRecord(record.session);
+  if (nestedSession && typeof nestedSession.key === "string" && nestedSession.key.trim()) {
+    return nestedSession.key.trim();
+  }
+  return null;
+}
+function registerSessionMethods(api) {
+  const callGateway = async (ctx, method, params = {}) => {
+    const ctxRequest = ctx.request;
+    if (typeof ctxRequest === "function") return ctxRequest(method, params);
+    const apiRequest = api?.request;
+    if (typeof apiRequest === "function") return apiRequest(method, params);
+    const apiCallGatewayMethod = api?.callGatewayMethod;
+    if (typeof apiCallGatewayMethod === "function") return apiCallGatewayMethod(method, params);
+    throw new Error("Gateway method invocation API unavailable in plugin context");
+  };
+  api.registerGatewayMethod(
+    "squad.sessions.create",
+    async (ctx) => {
+      const { params, respond } = ctx;
+      const sessionKey = params?.sessionKey;
+      const agentId = params?.agentId;
+      if (sessionKey !== void 0) {
+        if (typeof sessionKey !== "string" || !sessionKey.trim()) {
+          respond(false, { error: "Invalid 'sessionKey' parameter (must be a non-empty string when provided)" });
+          return;
+        }
+      }
+      if (agentId !== void 0) {
+        if (typeof agentId !== "string" || !agentId.trim()) {
+          respond(false, { error: "Invalid 'agentId' parameter (must be a non-empty string when provided)" });
+          return;
+        }
+      }
+      const createParams = {
+        ...typeof sessionKey === "string" ? { sessionKey: sessionKey.trim() } : {},
+        ...typeof agentId === "string" ? { agentId: agentId.trim() } : {}
+      };
+      try {
+        const nativeResult = await callGateway(ctx, "sessions.create", createParams);
+        const normalizedKey = extractSessionKey(nativeResult) ?? (typeof sessionKey === "string" ? sessionKey.trim() : null);
+        if (!normalizedKey) {
+          respond(false, {
+            error: "Session creation succeeded but no session key was returned",
+            nativeResult
+          });
+          return;
+        }
+        const nativeRecord = asRecord(nativeResult);
+        respond(true, {
+          ...nativeRecord ?? {},
+          key: normalizedKey
+        });
+      } catch (err2) {
+        const msg = err2 instanceof Error ? err2.message : String(err2);
+        respond(false, {
+          error: `Failed to create session: ${msg}`.slice(0, 500)
+        });
+      }
+    }
+  );
+}
+
 // src/shared-api.ts
 var CORE_TOOLS = [
   "exec",
@@ -2642,6 +2813,7 @@ function registerSquadSharedApi(api, onFsChange) {
   registerVersionMethods(api);
   registerAgentMethods(api);
   registerQuestionMethods(api);
+  registerSessionMethods(api);
   const invokeTool = async (tool, args) => {
     const executeFn = toolExecutors.get(tool);
     if (!executeFn) {
@@ -2703,7 +2875,7 @@ function squadAppPlugin(api) {
   const relayState = readRelayState();
   const relayEnabled = !!(relayState.claimToken || relayState.roomId);
   if (relayEnabled) {
-    const relayUrl = "wss://relay.squad.ceo";
+    const relayUrl = process.env.OPENCLAW_SQUAD_RELAY_URL || process.env.SQUAD_RELAY_URL || "wss://relay.squad.ceo";
     startRelayClient(api, relayUrl);
   }
 }

package/package.json

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