squad-openclaw 2026.2.2021 → 2026.2.2024

package/dist/index.js

@@ -440,9 +440,28 @@ var RelayClient = class {
       }
     }
     if (msg.type === "req" && msg.method === "connect") {
+      const connectRequestId = typeof msg.id === "string" ? msg.id : null;
       if (conn.connectHandshakeComplete) {
+        if (connectRequestId && conn.lastSuccessfulConnectRequestId === connectRequestId) {
+          console.log(`[relay-client] Duplicate connect id for ${userId} (${connectRequestId}) \u2014 reusing existing session`);
+          this.sendToRelay({
+            type: "relay.forward",
+            userId,
+            inner: {
+              type: "res",
+              id: connectRequestId,
+              ok: true,
+              payload: { protocol: 3 }
+            }
+          });
+          return;
+        }
         console.log(`[relay-client] New connect from ${userId} \u2014 creating fresh local WS for handshake`);
-        this.createUserConnection(userId);
+        this.createUserConnection(userId, {
+          pendingConnect: null,
+          pendingMessages: conn.pendingMessages,
+          e2e: conn.e2e
+        });
         conn = this.userConnections.get(userId);
         if (!conn) return;
       }
@@ -523,7 +542,8 @@ var RelayClient = class {
       connectHandshakeComplete: false,
       challengeNonce: null,
       pendingConnect: carry?.pendingConnect ?? null,
-      pendingMessages: carry?.pendingMessages ?? []
+      pendingMessages: carry?.pendingMessages ?? [],
+      lastSuccessfulConnectRequestId: null
     };
     this.userConnections.set(userId, conn);
     localWs.on("open", () => {
@@ -609,8 +629,9 @@ Device ID: ${this.deviceKeys.deviceId}`
         }
       }
     }
-    if (parsed.type === "res" && parsed.id === "connect-1" && parsed.ok) {
+    if (parsed.type === "res" && typeof parsed.id === "string" && parsed.id.startsWith("connect-") && parsed.ok) {
       conn.connectHandshakeComplete = true;
+      conn.lastSuccessfulConnectRequestId = parsed.id;
       if (conn.pendingMessages.length > 0) {
         console.log(`[relay-client] Flushing ${conn.pendingMessages.length} buffered messages for ${userId}`);
         for (const queued of conn.pendingMessages) {
@@ -731,6 +752,11 @@ function broadcastToUsers(event, payload) {
 
 // src/agents.ts
 import { execSync } from "child_process";
+import path4 from "path";
+function deriveAgentIdFromName(name) {
+  const normalized = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized || "agent";
+}
 function registerAgentMethods(api) {
   const callGateway = async (ctx, method, params = {}) => {
     const ctxRequest = ctx.request;
@@ -745,6 +771,8 @@ function registerAgentMethods(api) {
     "squad.agents.add",
     async ({ params, respond }) => {
       const name = params?.name;
+      const agentId = params?.agentId;
+      const workspace = params?.workspace;
       const model = params?.model;
       if (!name || typeof name !== "string" || !name.trim()) {
         respond(false, { error: "Missing or empty 'name' parameter" });
@@ -755,8 +783,19 @@ function registerAgentMethods(api) {
         respond(false, { error: "Agent name must start with a letter/number and contain only letters, numbers, spaces, hyphens, or underscores" });
         return;
       }
+      const providedAgentId = typeof agentId === "string" ? agentId.trim() : "";
+      if (providedAgentId && !/^[a-z0-9][a-z0-9-]*$/.test(providedAgentId)) {
+        respond(false, { error: "Invalid agentId format" });
+        return;
+      }
+      const effectiveAgentId = providedAgentId || deriveAgentIdFromName(safeName);
+      const defaultWorkspace = path4.join(
+        getOpenclawStateDir(),
+        effectiveAgentId === "main" ? "workspace" : `workspace-${effectiveAgentId}`
+      );
+      const workspacePath = typeof workspace === "string" && workspace.trim() ? workspace.trim() : defaultWorkspace;
       try {
-        let cmd = `openclaw agents add ${JSON.stringify(safeName)} --non-interactive`;
+        let cmd = `openclaw agents add ${JSON.stringify(safeName)} --non-interactive --workspace ${JSON.stringify(workspacePath)}`;
         if (model) {
           cmd += ` --model ${JSON.stringify(model)}`;
         }
@@ -910,11 +949,11 @@ function registerAgentMethods(api) {
 
 // src/entities.ts
 import { Type as T } from "@sinclair/typebox";
-import path7 from "path";
+import path8 from "path";
 import fs7 from "fs";
 
 // src/watcher.ts
-import path4 from "path";
+import path5 from "path";
 import fs4 from "fs";
 import chokidar from "chokidar";
 var debounceTimers = /* @__PURE__ */ new Map();
@@ -945,29 +984,29 @@ function debouncedFs(relPath, action, fn) {
   );
 }
 function isWorkspaceIdentity(filePath, configDir) {
-  const rel = path4.relative(configDir, filePath);
+  const rel = path5.relative(configDir, filePath);
   const match = rel.match(/^(workspace(?:-([^/]+))?)\/IDENTITY\.md$/);
   if (!match) return null;
   const dirName = match[1];
   const agentId = match[2] ?? "main";
-  return { agentId, workspacePath: path4.join(configDir, dirName) };
+  return { agentId, workspacePath: path5.join(configDir, dirName) };
 }
 function isWorkspaceAgentJson(filePath, configDir) {
-  const rel = path4.relative(configDir, filePath);
+  const rel = path5.relative(configDir, filePath);
   const match = rel.match(/^(workspace(?:-([^/]+))?)\/agent\.json$/);
   if (!match) return null;
   const dirName = match[1];
   const agentId = match[2] ?? "main";
-  return { agentId, workspacePath: path4.join(configDir, dirName) };
+  return { agentId, workspacePath: path5.join(configDir, dirName) };
 }
 function isGlobalSkillDir(filePath, configDir) {
-  const rel = path4.relative(configDir, filePath);
+  const rel = path5.relative(configDir, filePath);
   const match = rel.match(/^skills\/([^/]+)\/?$/);
   if (!match) return null;
   return { skillKey: match[1] };
 }
 function isWorkspaceSkillDir(filePath, configDir) {
-  const rel = path4.relative(configDir, filePath);
+  const rel = path5.relative(configDir, filePath);
   const match = rel.match(
     /^workspace(?:-([^/]+))?\/skills\/([^/]+)\/?$/
   );
@@ -975,13 +1014,13 @@ function isWorkspaceSkillDir(filePath, configDir) {
   return { agentId: match[1] ?? "main", skillKey: match[2] };
 }
 function isPluginManifest(filePath, configDir) {
-  const rel = path4.relative(configDir, filePath);
+  const rel = path5.relative(configDir, filePath);
   const match = rel.match(/^extensions\/([^/]+)\/openclaw\.plugin\.json$/);
   if (!match) return null;
   return { pluginDirName: match[1] };
 }
 function isOpenClawConfig(filePath, configDir) {
-  return path4.relative(configDir, filePath) === "openclaw.json";
+  return path5.relative(configDir, filePath) === "openclaw.json";
 }
 function updateAgent(agentId, workspacePath) {
   const now = Date.now();
@@ -989,7 +1028,7 @@ function updateAgent(agentId, workspacePath) {
   const metadata = { workspacePath };
   try {
     const content = fs4.readFileSync(
-      path4.join(workspacePath, "IDENTITY.md"),
+      path5.join(workspacePath, "IDENTITY.md"),
       "utf-8"
     );
     const parsed = parseIdentityName(content);
@@ -999,7 +1038,7 @@ function updateAgent(agentId, workspacePath) {
   if (name === agentId) {
     try {
       const raw = fs4.readFileSync(
-        path4.join(workspacePath, "agent.json"),
+        path5.join(workspacePath, "agent.json"),
         "utf-8"
       );
       const config = JSON.parse(raw);
@@ -1023,7 +1062,7 @@ function updateAgent(agentId, workspacePath) {
 }
 function updatePlugin(pluginDirName, configDir) {
   const now = Date.now();
-  const manifestPath = path4.join(
+  const manifestPath = path5.join(
     configDir,
     "extensions",
     pluginDirName,
@@ -1040,7 +1079,7 @@ function updatePlugin(pluginDirName, configDir) {
       name,
       title: name,
       description: manifest.description || null,
-      metadata: { pluginId, pluginDir: path4.dirname(manifestPath) },
+      metadata: { pluginId, pluginDir: path5.dirname(manifestPath) },
       source: "filesystem",
       source_key: manifestPath,
       created_at: now,
@@ -1067,7 +1106,7 @@ function startWatcher(configDir, onFsChange) {
   });
   const emitFsChange = (action, filePath) => {
     if (!onFsChange) return;
-    const rel = path4.relative(configDir, filePath);
+    const rel = path5.relative(configDir, filePath);
     debouncedFs(rel, action, () => {
       onFsChange({ action, path: rel });
     });
@@ -1121,7 +1160,7 @@ function startWatcher(configDir, onFsChange) {
       );
       return;
     }
-    const rel = path4.relative(configDir, dirPath);
+    const rel = path5.relative(configDir, dirPath);
     if (/^workspace(-[^/]+)?$/.test(rel)) {
       debounced("agents", () => scanAgents(configDir));
       return;
@@ -1129,7 +1168,7 @@ function startWatcher(configDir, onFsChange) {
   };
   const handleUnlinkDir = (dirPath) => {
     emitFsChange("unlinkDir", dirPath);
-    const rel = path4.relative(configDir, dirPath);
+    const rel = path5.relative(configDir, dirPath);
     const wsMatch = rel.match(/^workspace(?:-([^/]+))?$/);
     if (wsMatch) {
       const agentId = wsMatch[1] ?? "main";
@@ -1167,14 +1206,14 @@ function startWatcher(configDir, onFsChange) {
 
 // src/filesystem.ts
 import fs6 from "fs";
-import path6 from "path";
+import path7 from "path";
 
 // src/layout.ts
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 function resolveMaybeRelativePath(stateDir, p) {
-  if (path5.isAbsolute(p)) return path5.resolve(p);
-  return path5.resolve(stateDir, p);
+  if (path6.isAbsolute(p)) return path6.resolve(p);
+  return path6.resolve(stateDir, p);
 }
 function listWorkspaceFallbacks(stateDir) {
   let entries;
@@ -1185,7 +1224,7 @@ function listWorkspaceFallbacks(stateDir) {
   }
   return entries.filter((entry) => entry.isDirectory() && (entry.name === "workspace" || entry.name.startsWith("workspace-"))).map((entry) => {
     const agentId = entry.name === "workspace" ? "main" : entry.name.replace("workspace-", "");
-    const workspacePath = path5.join(stateDir, entry.name);
+    const workspacePath = path6.join(stateDir, entry.name);
     return {
       agentId,
       path: workspacePath,
@@ -1204,7 +1243,7 @@ function readOpenclawConfig(configPath) {
 }
 function resolveGatewayLayout() {
   const stateDir = getOpenclawStateDir();
-  const configPath = path5.join(stateDir, "openclaw.json");
+  const configPath = path6.join(stateDir, "openclaw.json");
   const config = readOpenclawConfig(configPath);
   const workspaces = [];
   if (config?.agents?.main?.workspace || config?.agents?.main?.workspacePath) {
@@ -1238,14 +1277,13 @@ function resolveGatewayLayout() {
     }
   }
   const resolvedWorkspaces = Array.from(deduped.values());
-  const mainWorkspace = resolvedWorkspaces.find((ws) => ws.agentId === "main");
-  const defaultFileBrowserRoot = mainWorkspace?.path ?? stateDir;
+  const defaultFileBrowserRoot = stateDir;
   return {
     stateDir,
     configPath,
-    mediaDir: path5.join(stateDir, "media"),
-    skillsDir: path5.join(stateDir, "skills"),
-    extensionsDir: path5.join(stateDir, "extensions"),
+    mediaDir: path6.join(stateDir, "media"),
+    skillsDir: path6.join(stateDir, "skills"),
+    extensionsDir: path6.join(stateDir, "extensions"),
     defaultFileBrowserRoot,
     workspaces: resolvedWorkspaces
   };
@@ -1255,16 +1293,16 @@ function resolveGatewayLayout() {
 var HOME_DIR = process.env.HOME ?? "/root";
 var OPENCLAW_DIR = getOpenclawStateDir();
 var SENSITIVE_BLOCKED_DIRS = [
-  path6.join(OPENCLAW_DIR, "credentials"),
-  path6.join(OPENCLAW_DIR, "devices"),
-  path6.join(OPENCLAW_DIR, "identity")
+  path7.join(OPENCLAW_DIR, "credentials"),
+  path7.join(OPENCLAW_DIR, "devices"),
+  path7.join(OPENCLAW_DIR, "identity")
 ];
 var SENSITIVE_BLOCKED_FILES = [
-  path6.join(OPENCLAW_DIR, "squad-ceo-data", "relay", "squad-relay.json")
+  path7.join(OPENCLAW_DIR, "squad-ceo-data", "relay", "squad-relay.json")
 ];
 function isSensitivePath(resolvedPath) {
   for (const blocked of SENSITIVE_BLOCKED_DIRS) {
-    if (resolvedPath === blocked || resolvedPath.startsWith(blocked + path6.sep)) {
+    if (resolvedPath === blocked || resolvedPath.startsWith(blocked + path7.sep)) {
       return true;
     }
   }
@@ -1273,7 +1311,7 @@ function isSensitivePath(resolvedPath) {
       return true;
     }
   }
-  if (path6.dirname(resolvedPath) === OPENCLAW_DIR && resolvedPath.endsWith(".bak")) {
+  if (path7.dirname(resolvedPath) === OPENCLAW_DIR && resolvedPath.endsWith(".bak")) {
     return true;
   }
   return false;
@@ -1322,20 +1360,20 @@ function redactOpenclawJson(rawContent) {
   return JSON.stringify(config, null, 2);
 }
 function isOpenclawJson(resolvedPath) {
-  return path6.basename(resolvedPath) === OPENCLAW_JSON_FILENAME && resolvedPath.startsWith(OPENCLAW_DIR);
+  return path7.basename(resolvedPath) === OPENCLAW_JSON_FILENAME && resolvedPath.startsWith(OPENCLAW_DIR);
 }
 function expandHome(p) {
   if (p.startsWith("~/") || p === "~") {
-    return path6.join(HOME_DIR, p.slice(1));
+    return path7.join(HOME_DIR, p.slice(1));
   }
   return p;
 }
 function validatePath(p, allowedRoots) {
-  const resolved = path6.resolve(expandHome(p));
+  const resolved = path7.resolve(expandHome(p));
   if (!allowedRoots || allowedRoots.length === 0) return resolved;
   const allowed = allowedRoots.some((root) => {
-    const resolvedRoot = path6.resolve(expandHome(root));
-    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path6.sep);
+    const resolvedRoot = path7.resolve(expandHome(root));
+    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path7.sep);
   });
   if (!allowed) {
     throw new Error(`Path "${p}" is outside allowed roots`);
@@ -1376,7 +1414,7 @@ function listDir(dirPath, opts) {
   const results = [];
   for (const dirent of dirents) {
     if (!opts.includeHidden && dirent.name.startsWith(".")) continue;
-    const entryPath = path6.join(dirPath, dirent.name);
+    const entryPath = path7.join(dirPath, dirent.name);
     let type = "other";
     if (dirent.isFile()) type = "file";
     else if (dirent.isDirectory()) type = "directory";
@@ -1487,7 +1525,7 @@ function registerFilesystemTools(api) {
         const encoding = params.encoding ?? "utf-8";
         const mkdir = params.mkdir !== false;
         if (mkdir) {
-          fs6.mkdirSync(path6.dirname(filePath), { recursive: true });
+          fs6.mkdirSync(path7.dirname(filePath), { recursive: true });
         }
         fs6.writeFileSync(filePath, content, encoding);
         const stat = fs6.statSync(filePath);
@@ -1687,10 +1725,10 @@ function scanAgents(configDir) {
   );
   for (const dir of workspaceDirs) {
     const agentId = dir.name === "workspace" ? "main" : dir.name.replace("workspace-", "");
-    const workspacePath = path7.join(configDir, dir.name);
+    const workspacePath = path8.join(configDir, dir.name);
     let name = agentId;
     const metadata = { workspacePath };
-    const identityPath = path7.join(workspacePath, "IDENTITY.md");
+    const identityPath = path8.join(workspacePath, "IDENTITY.md");
     try {
       const content = fs7.readFileSync(identityPath, "utf-8");
       const parsed = parseIdentityName(content);
@@ -1698,7 +1736,7 @@ function scanAgents(configDir) {
     } catch {
     }
     if (name === agentId) {
-      const agentJsonPath = path7.join(workspacePath, "agent.json");
+      const agentJsonPath = path8.join(workspacePath, "agent.json");
       try {
         const raw = fs7.readFileSync(agentJsonPath, "utf-8");
         const config = JSON.parse(raw);
@@ -1725,7 +1763,7 @@ function scanAgents(configDir) {
 }
 function scanSkills(configDir) {
   const now = Date.now();
-  const globalSkillsDir = path7.join(configDir, "skills");
+  const globalSkillsDir = path8.join(configDir, "skills");
   scanSkillsDir(globalSkillsDir, "global", now);
   let entries;
   try {
@@ -1738,7 +1776,7 @@ function scanSkills(configDir) {
       continue;
     }
     const agentId = dir.name === "workspace" ? "main" : dir.name.replace("workspace-", "");
-    const agentSkillsDir = path7.join(configDir, dir.name, "skills");
+    const agentSkillsDir = path8.join(configDir, dir.name, "skills");
     scanSkillsDir(agentSkillsDir, agentId, now);
   }
 }
@@ -1752,12 +1790,12 @@ function scanSkillsDir(skillsDir, scope, now) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const skillKey = entry.name;
-    const skillPath = path7.join(skillsDir, skillKey);
+    const skillPath = path8.join(skillsDir, skillKey);
     let name = skillKey;
     for (const manifestName of ["manifest.json", "package.json"]) {
       try {
         const raw = fs7.readFileSync(
-          path7.join(skillPath, manifestName),
+          path8.join(skillPath, manifestName),
           "utf-8"
         );
         const manifest = JSON.parse(raw);
@@ -1784,7 +1822,7 @@ function scanSkillsDir(skillsDir, scope, now) {
 }
 function scanPlugins2(configDir) {
   const now = Date.now();
-  const extensionsDir = path7.join(configDir, "extensions");
+  const extensionsDir = path8.join(configDir, "extensions");
   let entries;
   try {
     entries = fs7.readdirSync(extensionsDir, { withFileTypes: true });
@@ -1793,8 +1831,8 @@ function scanPlugins2(configDir) {
   }
   for (const dir of entries) {
     if (!dir.isDirectory()) continue;
-    const pluginDir = path7.join(extensionsDir, dir.name);
-    const manifestPath = path7.join(pluginDir, "openclaw.plugin.json");
+    const pluginDir = path8.join(extensionsDir, dir.name);
+    const manifestPath = path8.join(pluginDir, "openclaw.plugin.json");
     try {
       const raw = fs7.readFileSync(manifestPath, "utf-8");
       const manifest = JSON.parse(raw);
@@ -1820,7 +1858,7 @@ function scanTools(configDir) {
   const now = Date.now();
   try {
     const raw = fs7.readFileSync(
-      path7.join(configDir, "openclaw.json"),
+      path8.join(configDir, "openclaw.json"),
       "utf-8"
     );
     const config = JSON.parse(raw);
@@ -1871,12 +1909,12 @@ var MIME_MAP = {
   ".gz": "application/gzip"
 };
 function getMimeType(filename) {
-  const ext = path7.extname(filename).toLowerCase();
+  const ext = path8.extname(filename).toLowerCase();
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 function scanMedia(configDir) {
   const now = Date.now();
-  const mediaDir = path7.join(configDir, "media");
+  const mediaDir = path8.join(configDir, "media");
   scanMediaDir(mediaDir, now);
 }
 function scanMediaDir(dirPath, now) {
@@ -1888,7 +1926,7 @@ function scanMediaDir(dirPath, now) {
   }
   for (const entry of entries) {
     if (entry.name.startsWith(".")) continue;
-    const entryPath = path7.join(dirPath, entry.name);
+    const entryPath = path8.join(dirPath, entry.name);
     if (isSensitivePath(entryPath)) continue;
     if (entry.isDirectory()) {
       registrySet({
@@ -2026,18 +2064,18 @@ function registerEntityTools(api, onFsChange) {
 
 // src/sql.ts
 import { execFile } from "child_process";
-import path8 from "path";
+import path9 from "path";
 import fs8 from "fs";
 import { Type as T2 } from "@sinclair/typebox";
 var HOME_DIR2 = process.env.HOME ?? "/root";
-var ALLOWED_DATA_DIR = path8.join(getOpenclawStateDir(), "squad-ceo-data");
+var ALLOWED_DATA_DIR = path9.join(getOpenclawStateDir(), "squad-ceo-data");
 function validateDbPath(dbPath) {
   let expanded = dbPath;
   if (expanded.startsWith("~/") || expanded === "~") {
-    expanded = path8.join(HOME_DIR2, expanded.slice(1));
+    expanded = path9.join(HOME_DIR2, expanded.slice(1));
   }
-  const resolved = path8.resolve(expanded);
-  if (resolved !== ALLOWED_DATA_DIR && !resolved.startsWith(ALLOWED_DATA_DIR + path8.sep)) {
+  const resolved = path9.resolve(expanded);
+  if (resolved !== ALLOWED_DATA_DIR && !resolved.startsWith(ALLOWED_DATA_DIR + path9.sep)) {
     throw new Error(
       `Access denied: database path must be within ~/.openclaw/squad-ceo-data/`
     );
@@ -2111,10 +2149,10 @@ function registerSqlTools(api) {
 // src/version.ts
 import { execSync as execSync2 } from "child_process";
 import fs9 from "fs";
-import path9 from "path";
+import path10 from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "squad-openclaw";
-var CONFIG_PATH = path9.join(getOpenclawStateDir(), "openclaw.json");
+var CONFIG_PATH = path10.join(getOpenclawStateDir(), "openclaw.json");
 var updateInProgress = false;
 var VERIFY_TIMEOUT_MS = 2e4;
 var VERIFY_INTERVAL_MS = 500;
@@ -2161,7 +2199,7 @@ function reconcileInstallMetadata(verification) {
 }
 function getCurrentVersion() {
   const thisFile = fileURLToPath(import.meta.url);
-  const pkgPath = path9.resolve(path9.dirname(thisFile), "..", "package.json");
+  const pkgPath = path10.resolve(path10.dirname(thisFile), "..", "package.json");
   try {
     const pkg = JSON.parse(fs9.readFileSync(pkgPath, "utf-8"));
     return pkg.version ?? "0.0.0";
@@ -2248,9 +2286,9 @@ function verifyInstalledPluginState() {
     };
   }
   const requiredFiles = [
-    path9.join(installPath, "package.json"),
-    path9.join(installPath, "openclaw.plugin.json"),
-    path9.join(installPath, "dist", "index.js")
+    path10.join(installPath, "package.json"),
+    path10.join(installPath, "openclaw.plugin.json"),
+    path10.join(installPath, "dist", "index.js")
   ];
   const requiredFilesMissing = requiredFiles.filter((p) => !fs9.existsSync(p));
   if (requiredFilesMissing.length > 0) {
@@ -2266,7 +2304,7 @@ function verifyInstalledPluginState() {
   let installedPackage;
   try {
     installedPackage = JSON.parse(
-      fs9.readFileSync(path9.join(installPath, "package.json"), "utf-8")
+      fs9.readFileSync(path10.join(installPath, "package.json"), "utf-8")
     );
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
@@ -2281,7 +2319,7 @@ function verifyInstalledPluginState() {
   }
   try {
     JSON.parse(
-      fs9.readFileSync(path9.join(installPath, "openclaw.plugin.json"), "utf-8")
+      fs9.readFileSync(path10.join(installPath, "openclaw.plugin.json"), "utf-8")
     );
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
@@ -2463,6 +2501,59 @@ function registerVersionMethods(api) {
   );
 }
 
+// src/questions.ts
+var MARKER = "[HUMAN_INPUT_REQUIRED]";
+function normalizeEnvelope(raw) {
+  if (raw.blocking !== true) return null;
+  if (typeof raw.qid !== "string" || !raw.qid.trim()) return null;
+  if (typeof raw.sessionKey !== "string" || !raw.sessionKey.trim()) return null;
+  if (typeof raw.title !== "string" || !raw.title.trim()) return null;
+  if (typeof raw.question !== "string" || !raw.question.trim()) return null;
+  const agentId = typeof raw.agentId === "string" && raw.agentId.trim() ? raw.agentId.trim() : void 0;
+  return {
+    qid: raw.qid.trim(),
+    sessionKey: raw.sessionKey.trim(),
+    agentId,
+    title: raw.title.trim(),
+    question: raw.question.trim(),
+    blocking: true
+  };
+}
+function validateHumanQuestionEnvelope(text) {
+  const markerIndex = text.indexOf(MARKER);
+  if (markerIndex < 0) return { valid: false, markerFound: false };
+  const tail = text.slice(markerIndex + MARKER.length).trimStart();
+  const firstLine = tail.split("\n")[0]?.trim() ?? "";
+  if (!firstLine.startsWith("{")) {
+    return { valid: false, markerFound: true, errorCode: "missing_json_line" };
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(firstLine);
+  } catch {
+    return { valid: false, markerFound: true, errorCode: "invalid_json" };
+  }
+  const normalized = normalizeEnvelope(parsed);
+  if (!normalized) {
+    return { valid: false, markerFound: true, errorCode: "schema_invalid" };
+  }
+  return { valid: true, markerFound: true, normalizedEnvelope: normalized };
+}
+function registerQuestionMethods(api) {
+  api.registerGatewayMethod(
+    "squad.questions.validate-envelope",
+    async ({ params, respond }) => {
+      const text = typeof params?.text === "string" ? params.text : "";
+      if (!text) {
+        respond(false, { error: "Missing 'text' parameter" });
+        return;
+      }
+      const result = validateHumanQuestionEnvelope(text);
+      respond(true, result);
+    }
+  );
+}
+
 // src/shared-api.ts
 var CORE_TOOLS = [
   "exec",
@@ -2514,6 +2605,7 @@ function registerSquadSharedApi(api, onFsChange) {
   registerSqlTools(api);
   registerVersionMethods(api);
   registerAgentMethods(api);
+  registerQuestionMethods(api);
   const invokeTool = async (tool, args) => {
     const executeFn = toolExecutors.get(tool);
     if (!executeFn) {

package/package.json

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