@xfxstudio/claworld 0.1.1 → 0.1.3

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
@@ -48,7 +48,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.14"
+    "openclaw": ">=2026.3.22"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -76,7 +76,7 @@
     "install": {
       "npmSpec": "@xfxstudio/claworld",
       "defaultChoice": "npm",
-      "minHostVersion": ">=2026.3.14"
+      "minHostVersion": ">=2026.3.22"
     }
   }
 }

package/src/lib/runtime-guidance.js

@@ -91,12 +91,10 @@ function formatSessionOverview(detail = {}) {
     : {};
   const mode = normalizeText(detail.sessionMode || sessionOverview.mode, null);
   const maxTurns = normalizeInteger(sessionOverview.maxTurns, null);
-  const turnTimeoutMs = normalizeInteger(sessionOverview.turnTimeoutMs, null);
   const parts = [];
 
   if (mode) parts.push(`${mode} mode`);
   if (maxTurns != null) parts.push(`max ${maxTurns} turns`);
-  if (turnTimeoutMs != null) parts.push(`${turnTimeoutMs}ms turn timeout`);
 
   return parts.length > 0 ? parts.join(', ') : null;
 }
@@ -182,6 +180,7 @@ export function buildWorldSessionStartupEvent(detail = {}) {
     summary ? `Summary: ${summary}` : null,
     sessionSummary ? `Session overview: ${sessionSummary}` : null,
     raiseHandSummary ? `Completion rule: ${raiseHandSummary}` : null,
+    'Interruption handling: prefer reconnect/resume. Temporary silence or reconnect churn is not the normal way to close a round.',
     openingText ? `Opening focus: ${openingText}` : null,
     interactionRules ? `Interaction rules: ${interactionRules}` : null,
     prohibitedRules ? `Prohibited rules: ${prohibitedRules}` : null,

package/src/openclaw/installer/constants.js

@@ -3,4 +3,4 @@ export const CLAWORLD_INSTALLER_PACKAGE_NAME = '@xfxstudio/claworld';
 export const CLAWORLD_INSTALLER_COMMAND = 'npx -y @xfxstudio/claworld install';
 export const CLAWORLD_DOCTOR_COMMAND = 'npx -y @xfxstudio/claworld doctor';
 export const CLAWORLD_UPDATE_COMMAND = 'npx -y @xfxstudio/claworld update';
-export const CLAWORLD_OPENCLAW_MIN_HOST_VERSION = '>=2026.3.14';
+export const CLAWORLD_OPENCLAW_MIN_HOST_VERSION = '>=2026.3.22';

package/src/openclaw/installer/core.js

@@ -1,3 +1,4 @@
+import { accessSync, constants as FS_CONSTANTS } from 'fs';
 import fs from 'fs/promises';
 import os from 'os';
 import path from 'path';
@@ -80,8 +81,8 @@ export function isRelayBootstrapReady(account = {}) {
 }
 
 function parseCommandVersion(text) {
-  const match = String(text || '').match(/OpenClaw\s+([0-9]+(?:\.[0-9]+)+)/i)
-    || String(text || '').match(/([0-9]+(?:\.[0-9]+)+)/);
+  const match = String(text || '').match(/OpenClaw\s+([0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z.-]+)?)/i)
+    || String(text || '').match(/([0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z.-]+)?)/);
   return match ? match[1] : null;
 }
 
@@ -138,6 +139,90 @@ function cloneObject(value = {}) {
   return JSON.parse(JSON.stringify(ensureObject(value)));
 }
 
+function isExplicitCommandPath(command = '') {
+  const normalized = String(command || '').trim();
+  if (!normalized) return false;
+  return normalized.includes('/') || normalized.includes('\\') || path.isAbsolute(normalized);
+}
+
+function splitPathEnvEntries(pathValue = '') {
+  return String(pathValue || '')
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function isNodeModulesBinEntry(entry = '') {
+  const normalized = path.resolve(String(entry || ''));
+  return path.basename(normalized) === '.bin'
+    && path.basename(path.dirname(normalized)) === 'node_modules';
+}
+
+function resolveCommandNameCandidates(command = '', env = process.env) {
+  const normalized = String(command || '').trim();
+  if (!normalized) return [];
+  if (process.platform !== 'win32' || path.extname(normalized)) {
+    return [normalized];
+  }
+
+  const pathExt = splitPathEnvEntries(env?.PATHEXT || process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .map((ext) => ext.toLowerCase());
+  return [...new Set([normalized, ...pathExt.map((ext) => `${normalized}${ext}`)])];
+}
+
+function hasExecutableAccess(filePath = '') {
+  try {
+    accessSync(filePath, FS_CONSTANTS.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveOpenclawCliBinary({
+  openclawBin = DEFAULT_OPENCLAW_BIN,
+  env = process.env,
+} = {}) {
+  const requestedBin = normalizeText(openclawBin, DEFAULT_OPENCLAW_BIN);
+  if (
+    requestedBin !== DEFAULT_OPENCLAW_BIN
+    || isExplicitCommandPath(requestedBin)
+  ) {
+    return {
+      requestedBin,
+      binaryPath: requestedBin,
+      binarySource: isExplicitCommandPath(requestedBin) ? 'explicit_path' : 'explicit_command',
+      skippedLocalBinaryPaths: [],
+    };
+  }
+
+  const candidates = [];
+  for (const entry of splitPathEnvEntries(env?.PATH || process.env.PATH || '')) {
+    for (const name of resolveCommandNameCandidates(requestedBin, env)) {
+      const candidatePath = path.join(entry, name);
+      if (hasExecutableAccess(candidatePath)) {
+        candidates.push(candidatePath);
+      }
+    }
+  }
+
+  const uniqueCandidates = [...new Set(candidates)];
+  const hostCandidates = uniqueCandidates.filter((candidate) => !isNodeModulesBinEntry(path.dirname(candidate)));
+  const localCandidates = uniqueCandidates.filter((candidate) => isNodeModulesBinEntry(path.dirname(candidate)));
+  const binaryPath = hostCandidates[0] || uniqueCandidates[0] || requestedBin;
+
+  return {
+    requestedBin,
+    binaryPath,
+    binarySource: hostCandidates[0]
+      ? 'host_path'
+      : uniqueCandidates[0]
+        ? 'package_local_path'
+        : 'default_command',
+    skippedLocalBinaryPaths: localCandidates.filter((candidate) => candidate !== binaryPath),
+  };
+}
+
 function parseJson(text, fallback = null) {
   try {
     return JSON.parse(String(text || '').trim());
@@ -369,7 +454,12 @@ function defaultCommandRunner({
   dryRun = false,
   capture = true,
 } = {}) {
-  const rendered = [bin, ...args].join(' ');
+  const resolvedBin = resolveOpenclawCliBinary({
+    openclawBin: bin,
+    env,
+  });
+  const effectiveBin = resolvedBin.binaryPath;
+  const rendered = [effectiveBin, ...args].join(' ');
   if (dryRun) {
     return {
       status: 0,
@@ -377,10 +467,14 @@ function defaultCommandRunner({
       stderr: '',
       rendered,
       dryRun: true,
+      requestedBin: bin,
+      resolvedBin: effectiveBin,
+      binSource: resolvedBin.binarySource,
+      skippedBinCandidates: resolvedBin.skippedLocalBinaryPaths,
     };
   }
 
-  const result = spawnSync(bin, args, {
+  const result = spawnSync(effectiveBin, args, {
     cwd,
     env,
     stdio: capture ? 'pipe' : 'inherit',
@@ -397,12 +491,16 @@ function defaultCommandRunner({
     throw error;
   }
 
-  return {
-    status: result.status ?? 0,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    rendered,
-  };
+    return {
+      status: result.status ?? 0,
+      stdout: result.stdout || '',
+      stderr: result.stderr || '',
+      rendered,
+      requestedBin: bin,
+      resolvedBin: effectiveBin,
+      binSource: resolvedBin.binarySource,
+      skippedBinCandidates: resolvedBin.skippedLocalBinaryPaths,
+    };
 }
 
 async function executeCommand({
@@ -597,6 +695,12 @@ export async function detectOpenclawHost({
   return {
     version,
     raw: (result.stdout || result.stderr || '').trim(),
+    requestedBin: result.requestedBin || openclawBin,
+    binaryPath: result.resolvedBin || openclawBin,
+    binarySource: result.binSource || 'default_command',
+    skippedLocalBinaryPaths: Array.isArray(result.skippedBinCandidates)
+      ? result.skippedBinCandidates
+      : [],
   };
 }
 

package/src/openclaw/installer/doctor.js

@@ -103,6 +103,42 @@ function normalizeGatewayBaseUrl(gatewayStatus) {
   return `http://${host}:${port}`;
 }
 
+function normalizeConfiguredGatewayBaseUrl(config = {}) {
+  const configuredPort = Number(config?.gateway?.port);
+  if (!Number.isFinite(configuredPort) || configuredPort <= 0) {
+    return null;
+  }
+
+  const configuredBind = normalizeText(config?.gateway?.bind, '127.0.0.1');
+  const configuredHost = (
+    configuredBind === 'loopback'
+    || configuredBind === 'localhost'
+    || configuredBind === '0.0.0.0'
+    || configuredBind === '::'
+  )
+    ? '127.0.0.1'
+    : configuredBind;
+  return `http://${configuredHost}:${configuredPort}`;
+}
+
+function describePluginStatusRouteTarget({
+  config = {},
+  gatewayStatus = {},
+} = {}) {
+  const configuredBaseUrl = normalizeConfiguredGatewayBaseUrl(config);
+  const runtimeBaseUrl = normalizeGatewayBaseUrl(gatewayStatus);
+  return {
+    configuredBaseUrl,
+    runtimeBaseUrl,
+    baseUrlMismatch: Boolean(
+      configuredBaseUrl
+      && runtimeBaseUrl
+      && configuredBaseUrl !== runtimeBaseUrl
+    ),
+    runtimePortSource: normalizeText(gatewayStatus?.gateway?.portSource, null),
+  };
+}
+
 async function fetchPluginStatusRoute({
   gatewayBaseUrl,
   fetchImpl = globalThis.fetch?.bind(globalThis),
@@ -224,7 +260,13 @@ export async function runClaworldDoctor({
         status: 'fail',
         summary: `OpenClaw ${host.version} is below the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
         action: `Upgrade OpenClaw, then rerun \`${CLAWORLD_DOCTOR_COMMAND}\`.`,
-        details: { version: host.version, minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
+        details: {
+          version: host.version,
+          minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+          requestedBin: host.requestedBin || null,
+          binaryPath: host.binaryPath || null,
+          binarySource: host.binarySource || null,
+        },
       }));
     } else {
       checks.push(createCheck({
@@ -233,7 +275,14 @@ export async function runClaworldDoctor({
         label: 'OpenClaw host version',
         status: 'pass',
         summary: `OpenClaw ${host.version} satisfies the required minimum ${CLAWORLD_OPENCLAW_MIN_HOST_VERSION}.`,
-        details: { version: host.version, minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION },
+        details: {
+          version: host.version,
+          minimum: CLAWORLD_OPENCLAW_MIN_HOST_VERSION,
+          requestedBin: host.requestedBin || null,
+          binaryPath: host.binaryPath || null,
+          binarySource: host.binarySource || null,
+          skippedLocalBinaryPaths: host.skippedLocalBinaryPaths || [],
+        },
       }));
     }
   } catch (error) {
@@ -573,7 +622,11 @@ export async function runClaworldDoctor({
   }
 
   if (facts.gatewayStatus?.service?.runtime?.status === 'running') {
-    const gatewayBaseUrl = normalizeGatewayBaseUrl(facts.gatewayStatus);
+    const routeTarget = describePluginStatusRouteTarget({
+      config,
+      gatewayStatus: facts.gatewayStatus,
+    });
+    const gatewayBaseUrl = routeTarget.runtimeBaseUrl;
     facts.pluginStatusRoute = await fetchPluginStatusRoute({
       gatewayBaseUrl,
       fetchImpl,
@@ -583,7 +636,19 @@ export async function runClaworldDoctor({
     let status = 'pass';
     let summary = `Reached ${facts.pluginStatusRoute.routeUrl}.`;
     let action = null;
-    if (!routeReachable) {
+    if (routeTarget.baseUrlMismatch) {
+      status = 'warn';
+      const runtimeTarget = routeTarget.runtimeBaseUrl || 'the running gateway target';
+      const configuredTarget = routeTarget.configuredBaseUrl || 'the inspected config target';
+      const responseSummary = routeStatus == null
+        ? facts.pluginStatusRoute.error || 'no response'
+        : `HTTP ${routeStatus}`;
+      summary = [
+        `OpenClaw gateway status resolved ${runtimeTarget}, but the inspected config declares ${configuredTarget}.`,
+        `Treating \`${facts.pluginStatusRoute.routeUrl || '/plugins/claworld/status'}\` as advisory because the host service is targeting a different HTTP endpoint (${responseSummary}).`,
+      ].join(' ');
+      action = 'Align the host gateway service target with the inspected config if you need live plugin-route proof for this config.';
+    } else if (!routeReachable) {
       status = 'fail';
       summary = `Unable to reach ${facts.pluginStatusRoute.routeUrl || 'the plugin status route'}.`;
       action = 'Confirm the local OpenClaw gateway HTTP surface is reachable, then rerun doctor.';
@@ -599,7 +664,13 @@ export async function runClaworldDoctor({
       status,
       summary,
       action,
-      details: facts.pluginStatusRoute,
+      details: {
+        ...facts.pluginStatusRoute,
+        configuredBaseUrl: routeTarget.configuredBaseUrl,
+        runtimeBaseUrl: routeTarget.runtimeBaseUrl,
+        baseUrlMismatch: routeTarget.baseUrlMismatch,
+        runtimePortSource: routeTarget.runtimePortSource,
+      },
     }));
   } else {
     checks.push(createCheck({

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -222,26 +222,6 @@ function shouldAuthorizeBridgedCommand({ runtimeConfig = {}, relayEvent, incomin
   return typeof incomingText === 'string' && incomingText.trim().startsWith('/');
 }
 
-const CLAWORLD_RAISE_HAND_DIRECTIVE = '[[CLAWORLD_RAISE_HAND]]';
-const CLAWORLD_RAISE_HAND_DIRECTIVE_PATTERN = /\[\[\s*CLAWORLD_RAISE_HAND\s*\]\]/gi;
-
-function extractControlledReply(text) {
-  let raiseHand = false;
-  const sanitized = String(text || '')
-    .replace(CLAWORLD_RAISE_HAND_DIRECTIVE_PATTERN, () => {
-      raiseHand = true;
-      return ' ';
-    })
-    .replace(/[ \t]+\n/g, '\n')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
-
-  return {
-    text: sanitized || (raiseHand ? 'I am ready to conclude this round.' : ''),
-    control: raiseHand ? { type: 'raise_hand', raiseHand: true } : null,
-  };
-}
-
 const CLAWORLD_RELAY_OPERATIONAL_NOTICE_PATTERNS = [
   /^🧭\s*New session:\s+\S+/i,
   /^🧹\s*Auto-compaction complete(?:\s*\(count \d+\))?\.$/i,
@@ -1602,9 +1582,8 @@ function createRelayReplyDispatcher({
   };
 
   const flushReply = async (text) => {
-    const controlledReply = extractControlledReply(text);
-    const normalized = String(controlledReply.text || '').trim();
-    if ((!normalized && !controlledReply.control) || replied || suppressed) return false;
+    const normalized = String(text || '').trim();
+    if (!normalized || replied || suppressed) return false;
     if (allowRelayContinuation === false) {
       suppressed = true;
       return false;
@@ -1619,7 +1598,6 @@ function createRelayReplyDispatcher({
         payload: {
           text: normalized,
           source: 'openclaw-autochain',
-          ...(controlledReply.control ? { control: controlledReply.control } : {}),
         },
       });
       if (result.status !== 201) {
@@ -1631,7 +1609,6 @@ function createRelayReplyDispatcher({
         messageId: turnId,
         replyText: normalized,
         source: 'openclaw-autochain',
-        ...(controlledReply.control ? { control: controlledReply.control } : {}),
       });
     }
     replied = true;
@@ -2732,6 +2709,7 @@ export function createClaworldChannelPlugin({
             agentId: resolvedContext.agentId || null,
             profile: context.profile || {},
             profileSnapshot: context.profileSnapshot ?? null,
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
             limit: context.limit ?? context.candidateLimit ?? null,
             fetchImpl,
             logger,
@@ -2969,6 +2947,7 @@ export function createClaworldChannelPlugin({
             agentId: resolvedContext.agentId || null,
             profile: context.profile || {},
             profileSnapshot: context.profileSnapshot ?? null,
+            profileUpdate: context.profileUpdate ?? context.profilePatch ?? null,
             limit: context.limit ?? context.candidateLimit ?? null,
             fetchImpl,
             logger,

package/src/openclaw/plugin/register.js

@@ -328,7 +328,7 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_prepare_world_join',
-      description: 'Inspect or update the current profile draft for a Claworld world join. This remains available for draft-first flows, but direct join can also collect missing fields now.',
+      description: 'Compatibility helper for inspect-first world joins. The canonical agent-facing path is direct claworld_join_world with structured retry fields when profile data is incomplete.',
       parameters: {
         type: 'object',
         additionalProperties: false,
@@ -362,7 +362,7 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_join_world',
-      description: 'Create or activate a Claworld world membership for the current relay agent, and if required fields are still missing return the next profile fields before retrying the same tool.',
+      description: 'Create or confirm a Claworld world membership for the current relay agent. When profile data is incomplete it returns structured missing-field guidance for retrying the same tool; on success it returns the canonical candidate-review payload so the next world step is review candidate feed -> claworld_request_chat.',
       parameters: {
         type: 'object',
         additionalProperties: false,
@@ -383,7 +383,7 @@ function buildRegisteredTools(api, plugin) {
         const profileDraftParams = resolveProfileDraftParams(params, {
           includeProfileSnapshot: true,
         });
-        const payload = await plugin.runtime.productShell.submitWorldJoin({
+        const payload = await plugin.runtime.productShell.resolveWorldJoinFlow({
           ...context,
           worldId: params.worldId,
           agentId: context.agentId,
@@ -401,7 +401,7 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_search_world',
-      description: 'Search the selected Claworld world for active online agents. Results return canonical agentId plus a compatibility playerId alias.',
+      description: 'Optional compatibility/debug search inside a joined Claworld world. This is not the canonical post-join path; default world discovery should use candidate feed and then claworld_request_chat.',
       parameters: {
         type: 'object',
         additionalProperties: false,
@@ -556,7 +556,7 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_request_chat',
-      description: 'Create a direct or world-scoped chat request for another relay peer using its canonical targetAgentId. `openingMessage` is treated as a kickoff brief/opener intent; if the peer accepts, the backend constructs the kickoff bundle, wakes the sender runtime first, and delivers the sender-composed opener to the recipient runtime.',
+      description: 'Create a direct or world-scoped chat request for another relay peer using its canonical targetAgentId. For world-scoped discovery, use the targetAgentId returned from candidate-feed review after join_world; this remains the canonical world-scoped contact-establishment step. `openingMessage` is treated as a kickoff brief/opener intent; if the peer accepts, the backend constructs the kickoff bundle, wakes the sender runtime first, and delivers the sender-composed opener to the recipient runtime.',
       parameters: {
         type: 'object',
         additionalProperties: false,

package/src/openclaw/plugin/relay-client.js

@@ -517,7 +517,7 @@ export class ClaworldRelayClient extends EventEmitter {
     config,
     agentId,
     credential = null,
-    clientVersion = 'claworld-plugin/0.1.1',
+    clientVersion = 'claworld-plugin/0.1.3',
     sessionTarget,
     fallbackTarget,
   } = {}) {