@xfxstudio/claworld 2026.4.22-testing.6 → 2026.4.27-testing

package/src/openclaw/plugin/register.js

@@ -1,7 +1,6 @@
 import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
   projectToolChatRequestMutationResponse,
-  projectToolCandidateFeedResponse,
   projectToolCreateWorldResponse,
   projectToolFeedbackSubmissionResponse,
   projectToolJoinWorldResponse,
@@ -11,6 +10,16 @@ import {
   projectToolWorldSearchResponse,
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
+import {
+  CLAWORLD_BOOTSTRAP_TARGETS,
+  appendClaworldJournalEvent,
+  buildClaworldBootstrapPromptContext,
+  buildClaworldContextPointer,
+  buildClaworldToolMaintenanceEvent,
+  ensureClaworldWorkingMemory,
+  resolveClaworldBootstrapTarget,
+} from '../runtime/working-memory.js';
+import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
 import { setClaworldRuntime } from './runtime.js';
 import {
   CHAT_REQUEST_APPROVAL_POLICY_MODES,
@@ -72,6 +81,48 @@ function buildClaworldStatusRoute(plugin) {
   };
 }
 
+async function resolveHookWorkspaceRoot(api, event = {}, ctx = {}) {
+  const directWorkspaceRoot = resolveOpenClawWorkspaceRoot({ sources: [event, ctx] });
+  if (directWorkspaceRoot) return directWorkspaceRoot;
+  const cfg = await loadCurrentConfig(api);
+  return resolveOpenClawWorkspaceRoot({
+    sources: [event, ctx],
+    config: cfg,
+    agentId: ctx?.agentId ?? event?.agentId,
+  });
+}
+
+function getHookLogger(api) {
+  return api?.logger || api?.runtime?.logger || console;
+}
+
+function parseHookToolPayload(result) {
+  if (!result || typeof result !== 'object') return null;
+  const text = Array.isArray(result.content)
+    ? result.content.find((entry) => entry?.type === 'text' && typeof entry.text === 'string')?.text
+    : null;
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function isSuccessfulHookToolCall(event = {}) {
+  if (event?.error || event?.isError === true) return false;
+  const result = event?.result ?? event?.output ?? event?.response ?? null;
+  if (result?.isError === true) return false;
+  const payload = parseHookToolPayload(result);
+  if (normalizeText(payload?.status, null) === 'error') return false;
+  return true;
+}
+
+function hookToolResult(event = {}) {
+  return event?.result ?? event?.output ?? event?.response ?? null;
+}
+
 const CHAT_INBOX_FILTER_DIRECTIONS = Object.freeze([
   'inbound',
   'outbound',
@@ -92,6 +143,134 @@ const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
   'ended',
 ]);
 
+const TERMINAL_ACCOUNT_ACTIONS = Object.freeze([
+  'view_account',
+  'activate_account',
+  'update_display_name',
+  'update_human_profile',
+  'update_agent_profile',
+  'set_discoverability',
+  'set_contactability',
+  'set_chat_policy',
+  'set_proactivity',
+  'subscribe_person',
+  'unsubscribe_person',
+]);
+
+const TERMINAL_WORLD_ACTIONS = Object.freeze([
+  'list_owned_worlds',
+  'list_joined_worlds',
+  'get_world',
+  'create_world',
+  'update_world',
+  'join_world',
+  'update_world_profile',
+  'leave_world',
+  'subscribe_world',
+  'unsubscribe_world',
+  'set_world_broadcast_preference',
+  'publish_broadcast',
+  'list_world_activity',
+  'list_broadcast_history',
+  'manage_members',
+]);
+
+const TERMINAL_CONVERSATION_ACTIONS = Object.freeze([
+  'request',
+  'accept',
+  'reject',
+  'end',
+  'get_state',
+  'list_related',
+]);
+
+const ACCOUNT_IMPLEMENTATION_ACTIONS = Object.freeze({
+  view_account: 'view',
+  activate_account: 'update_identity',
+});
+
+const WORLD_IMPLEMENTATION_ACTIONS = Object.freeze({
+  list_owned_worlds: 'list',
+  list_joined_worlds: 'list_memberships',
+  update_world: 'update_context',
+  update_world_profile: 'update_profile',
+  publish_broadcast: 'broadcast',
+  leave_world: 'leave',
+});
+
+function normalizeTerminalAction(action, allowedActions, fallback = null) {
+  const normalized = normalizeText(action, fallback);
+  return allowedActions.includes(normalized) ? normalized : fallback;
+}
+
+function hasExplicitAction(params = {}) {
+  return Object.prototype.hasOwnProperty.call(params, 'action') && normalizeText(params.action, null) != null;
+}
+
+function normalizeTerminalAccountAction(params = {}) {
+  if (hasExplicitAction(params)) {
+    const explicitAction = normalizeText(params.action, null);
+    const terminalAction = normalizeTerminalAction(explicitAction, TERMINAL_ACCOUNT_ACTIONS, null);
+    if (terminalAction) return terminalAction;
+    requireManageWorldField('action', `action must be one of ${TERMINAL_ACCOUNT_ACTIONS.join(', ')}`);
+  }
+  if (normalizeText(params.displayName, null)) return 'update_display_name';
+  if (Object.prototype.hasOwnProperty.call(params, 'humanProfile')) return 'update_human_profile';
+  if (
+    Object.prototype.hasOwnProperty.call(params, 'agentProfile')
+    || Object.prototype.hasOwnProperty.call(params, 'profile')
+  ) return 'update_agent_profile';
+  if (Object.prototype.hasOwnProperty.call(params, 'discoverable')) return 'set_discoverability';
+  if (Object.prototype.hasOwnProperty.call(params, 'contactable')) return 'set_contactability';
+  if (normalizeObject(params.chatRequestApprovalPolicy, null)) return 'set_chat_policy';
+  if (Object.prototype.hasOwnProperty.call(params, 'proactivitySettings')) return 'set_proactivity';
+  return 'view_account';
+}
+
+function normalizeTerminalWorldAction(params = {}) {
+  if (hasExplicitAction(params)) {
+    const explicitAction = normalizeText(params.action, null);
+    const terminalAction = normalizeTerminalAction(explicitAction, TERMINAL_WORLD_ACTIONS, null);
+    if (terminalAction) return terminalAction;
+    requireManageWorldField('action', `action must be one of ${TERMINAL_WORLD_ACTIONS.join(', ')}`);
+  }
+  if (!normalizeText(params.worldId, null)) return 'list_owned_worlds';
+  if (normalizeText(params.announcementText, null)) return 'publish_broadcast';
+  if (normalizeText(params.participantContextText, null)) return 'update_world_profile';
+  if (
+    normalizeText(params.worldContextText, null)
+    || normalizeText(params.displayName, null)
+    || normalizeObject(params.broadcast, null)
+    || typeof params.enabled === 'boolean'
+  ) {
+    return 'update_world';
+  }
+  return 'get_world';
+}
+
+function normalizeTerminalConversationAction(action, fallback = 'list_related', { throwOnInvalid = false } = {}) {
+  const normalized = normalizeText(action, null);
+  if (!normalized) return fallback;
+  if (TERMINAL_CONVERSATION_ACTIONS.includes(normalized)) return normalized;
+  if (throwOnInvalid) {
+    requireManageWorldField('action', `action must be one of ${TERMINAL_CONVERSATION_ACTIONS.join(', ')}`);
+  }
+  return null;
+}
+
+function buildTerminalActionResult({ tool, action, payload = {}, status = null } = {}) {
+  const normalizedPayload = payload && typeof payload === 'object' && !Array.isArray(payload)
+    ? payload
+    : { value: payload };
+  const normalizedStatus = status || normalizeText(normalizedPayload.status, 'ok');
+  return buildToolResult({
+    ...normalizedPayload,
+    tool,
+    action,
+    status: normalizedStatus,
+  });
+}
+
 function normalizeChatInboxListFiltersInput(params = {}) {
   const source = normalizeObject(params.filters, {}) || {};
   const normalized = {
@@ -109,6 +288,577 @@ function normalizeChatInboxListFiltersInput(params = {}) {
   );
 }
 
+function parseToolResultPayload(result = null) {
+  const text = result?.content?.[0]?.text;
+  if (typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function rewriteToolResultName(result, toolName, action = null) {
+  const payload = parseToolResultPayload(result);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return result;
+  return buildToolResult({
+    ...payload,
+    tool: toolName,
+    ...(action ? { action } : {}),
+  });
+}
+
+function requireTerminalTool(internalTools, toolName) {
+  const tool = internalTools.get(toolName);
+  if (!tool || typeof tool.execute !== 'function') {
+    throw new Error(`terminal public tool adapter requires ${toolName}`);
+  }
+  return tool;
+}
+
+function createTerminalToolAdapters(api, plugin, internalTools) {
+  const accountIdProperty = stringParam({
+    description: 'Claworld account id to execute the tool against.',
+    minLength: 1,
+    examples: ['claworld'],
+  });
+  const worldIdProperty = stringParam({
+    description: 'Canonical world id.',
+    minLength: 1,
+    examples: ['dating-demo-world'],
+  });
+  const searchTool = 'claworld_search';
+  const manageWorldsTool = 'claworld_manage_worlds';
+  const manageConversationsTool = 'claworld_manage_conversations';
+  const accountTool = 'claworld_manage_account';
+  const publicProfileTool = 'claworld_get_public_profile';
+
+  return [
+    {
+      name: accountTool,
+      label: 'Claworld Manage Account',
+      description: 'Terminal account surface for readiness, public identity, global profile, share-card generation, and account-level chat policy.',
+      metadata: buildToolMetadata({
+        category: 'account',
+        usageNotes: [
+          'Use this owner-facing account surface for activation, profile, policy, and subscription decisions.',
+          'Use action=view_account for readiness; update_display_name, update_agent_profile, or set_chat_policy for common account mutations.',
+          'Use subscribe_person or unsubscribe_person when a search/profile result exposes a person subscription target.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Terminal account management payload.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Account action.',
+            enumValues: TERMINAL_ACCOUNT_ACTIONS,
+            examples: ['view_account', 'update_display_name', 'set_chat_policy'],
+          }),
+          displayName: stringParam({
+            description: 'Public-facing display name for activate_account or update_display_name.',
+            minLength: 1,
+            examples: ['Moza', '小发发'],
+          }),
+          profile: stringParam({
+            description: 'Optional global profile text used when updating the agent profile.',
+            examples: ['喜欢慢节奏介绍，也愿意先让 agent 做初步认识。🙂'],
+          }),
+          humanProfile: stringParam({
+            description: 'Owner-facing human profile text for update_human_profile.',
+            examples: ['周末在上海，喜欢网球和安静咖啡馆。'],
+          }),
+          agentProfile: stringParam({
+            description: 'Agent-facing profile/personality text for update_agent_profile.',
+            examples: ['偏主动但会先确认边界，擅长总结和约局。'],
+          }),
+          discoverable: booleanParam({ description: 'Whether this account can appear in global people search.' }),
+          contactable: booleanParam({ description: 'Whether this account can receive direct public-profile chat requests.' }),
+          chatRequestApprovalPolicy: objectParam({
+            description: 'Backend-managed inbound chat-request policy for this account.',
+            additionalProperties: true,
+          }),
+          proactivitySettings: objectParam({
+            description: 'Account-level proactive-management settings.',
+            additionalProperties: true,
+          }),
+          communicationPreference: objectParam({
+            description: 'Optional account-level communication preference settings.',
+            additionalProperties: true,
+          }),
+          targetAgentId: stringParam({
+            description: 'Target agent id for subscribe_person or unsubscribe_person.',
+            minLength: 1,
+            examples: ['agt_alice'],
+          }),
+          targetId: stringParam({
+            description: 'Generic target id for subscription actions.',
+            minLength: 1,
+          }),
+          subscriptionId: stringParam({
+            description: 'Existing subscription id for unsubscribe_person.',
+            minLength: 1,
+            examples: ['sub_123'],
+          }),
+          generateShareCard: booleanParam({
+            description: 'When true, include a temporary public identity card when supported.',
+          }),
+          expiresInSeconds: integerParam({
+            description: 'Optional temporary share-card TTL in seconds.',
+            minimum: 1,
+            examples: [7200],
+          }),
+        },
+      }),
+      async execute(toolCallId, params = {}) {
+        const action = normalizeTerminalAccountAction(params);
+        const subscriptionTargetId = normalizeText(params.targetAgentId, normalizeText(params.targetId, null));
+        if (action === 'subscribe_person') {
+          if (!subscriptionTargetId) requireManageWorldField('targetAgentId', 'targetAgentId is required for action=subscribe_person');
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'subscribe person',
+          });
+          const payload = await plugin.runtime.productShell.subscriptions.createSubscription({
+            ...context,
+            targetType: 'person',
+            targetId: subscriptionTargetId,
+          });
+          return buildTerminalActionResult({ tool: accountTool, action, payload });
+        }
+        if (action === 'unsubscribe_person') {
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'unsubscribe person',
+          });
+          const payload = await plugin.runtime.productShell.subscriptions.deleteSubscription({
+            ...context,
+            subscriptionId: params.subscriptionId || null,
+            targetType: subscriptionTargetId ? 'person' : null,
+            targetId: subscriptionTargetId,
+          });
+          return buildTerminalActionResult({ tool: accountTool, action, payload });
+        }
+
+        const implementationAction = ACCOUNT_IMPLEMENTATION_ACTIONS[action] || null;
+        if (implementationAction) {
+          const implementationParams = {
+            ...params,
+            action: implementationAction,
+            ...(action === 'update_agent_profile' && params.agentProfile !== undefined
+              ? { profile: params.agentProfile }
+              : {}),
+          };
+          const result = await requireTerminalTool(internalTools, 'claworld_account').execute(toolCallId, implementationParams);
+          return rewriteToolResultName(
+            result,
+            accountTool,
+            action,
+          );
+        }
+
+        if (typeof plugin.runtime.productShell.profile.executeAccountAction !== 'function') {
+          requireManageWorldField('action', `action=${action} requires the account management runtime adapter`);
+        }
+        const context = await resolveToolContext(api, plugin, params, {
+          requiredPublicIdentityCapability: action === 'activate_account' ? null : 'manage account',
+        });
+        const generateShareCard = typeof params.generateShareCard === 'boolean'
+          ? params.generateShareCard
+          : action === 'update_display_name';
+        const payload = await plugin.runtime.productShell.profile.executeAccountAction({
+          ...context,
+          action,
+          displayName: params.displayName || null,
+          profile: params.profile,
+          humanProfile: params.humanProfile,
+          agentProfile: params.agentProfile,
+          discoverable: params.discoverable,
+          contactable: params.contactable,
+          chatRequestApprovalPolicy: params.chatRequestApprovalPolicy || null,
+          proactivitySettings: params.proactivitySettings,
+          communicationPreference: params.communicationPreference,
+          generateShareCard,
+          expiresInSeconds: params.expiresInSeconds ?? null,
+        });
+        return buildTerminalActionResult({ tool: accountTool, action, payload });
+      },
+    },
+    {
+      name: searchTool,
+      label: 'Claworld Search',
+      description: 'Terminal search surface for worlds, world members, and people. Use scope=worlds for world discovery and scope=world_members for in-world member search.',
+      metadata: buildToolMetadata({
+        category: 'search',
+        usageNotes: [
+          'scope=worlds searches or browses visible worlds.',
+          'scope=world_members searches members in an authorized world.',
+          'scope=people searches globally discoverable/contactable public identities.',
+          'scope=mixed combines world, optional world-member, and global people search results in one SearchItemEnvelope list.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Terminal Claworld search payload.',
+        properties: {
+          accountId: accountIdProperty,
+          scope: stringParam({
+            description: 'Search scope.',
+            enumValues: ['worlds', 'world_members', 'people', 'mixed'],
+            examples: ['mixed'],
+          }),
+          worldId: worldIdProperty,
+          query: stringParam({
+            description: 'Optional search text.',
+            minLength: 1,
+            examples: ['网球 搭子 周末约球'],
+          }),
+          sort: stringParam({
+            description: 'Sort mode for the selected scope.',
+            enumValues: ['match', 'hot', 'latest', 'likes'],
+            examples: ['match'],
+          }),
+          limit: integerParam({
+            description: 'Maximum result count.',
+            minimum: 1,
+            maximum: 50,
+            examples: [10],
+          }),
+          page: integerParam({
+            description: '1-based page for world search.',
+            minimum: 1,
+            examples: [1],
+          }),
+        },
+        examples: [
+          { accountId: 'claworld', scope: 'worlds', query: '网球', sort: 'match', limit: 5 },
+          { accountId: 'claworld', scope: 'world_members', worldId: 'dating-demo-world', query: '上海 周末', limit: 5 },
+          { accountId: 'claworld', scope: 'people', query: 'Moza', limit: 5 },
+          { accountId: 'claworld', scope: 'mixed', query: '网球 Moza', limit: 5 },
+        ],
+      }),
+      async execute(toolCallId, params = {}) {
+        const context = await resolveToolContext(api, plugin, params);
+        const scope = normalizeText(params.scope, params.worldId ? 'world_members' : 'mixed');
+        if (scope === 'world_members' && !normalizeText(params.worldId, null)) {
+          requireManageWorldField('worldId', 'worldId is required for scope=world_members');
+        }
+        if (!['worlds', 'world_members', 'people', 'mixed'].includes(scope)) {
+          requireManageWorldField('scope', 'scope must be one of worlds, world_members, people, or mixed');
+        }
+        const payload = await plugin.runtime.productShell.search({
+          ...context,
+          scope,
+          worldId: params.worldId || null,
+          query: params.query || null,
+          sort: params.sort || null,
+          limit: params.limit ?? null,
+          page: params.page ?? null,
+        });
+        return buildToolResult({ tool: searchTool, ...payload });
+      },
+    },
+    {
+      name: publicProfileTool,
+      label: 'Claworld Get Public Profile',
+      description: 'Read the current account public profile/readiness projection. Target public-profile lookup is exposed as a terminal tool name and remains backend-fact based.',
+      metadata: buildToolMetadata({
+        category: 'public_profile',
+        usageNotes: [
+          'Use this for public identity readiness and share-card fetches.',
+          'It intentionally does not expose notification or runtime-inbox internals.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Public profile lookup payload.',
+        properties: {
+          accountId: accountIdProperty,
+          agentCode: stringParam({
+            description: 'Optional public code for a future target lookup route.',
+            minLength: 1,
+            examples: ['ZX82QP'],
+          }),
+          displayName: stringParam({
+            description: 'Optional display name paired with agentCode for a future target lookup route.',
+            minLength: 1,
+            examples: ['Runtime Peer'],
+          }),
+          generateShareCard: booleanParam({
+            description: 'When true, include the current account share-card when available.',
+          }),
+          expiresInSeconds: integerParam({
+            description: 'Optional temporary share-card TTL in seconds.',
+            minimum: 1,
+            examples: [7200],
+          }),
+        },
+      }),
+      async execute(toolCallId, params = {}) {
+        const result = await requireTerminalTool(internalTools, 'claworld_account').execute(toolCallId, {
+          ...params,
+          action: 'view',
+        });
+        return rewriteToolResultName(result, publicProfileTool);
+      },
+    },
+    {
+      name: manageWorldsTool,
+      label: 'Claworld Manage Worlds',
+      description: 'Terminal world surface for browsing selected world details, joining, creation, owner governance, broadcast, and membership self-service.',
+      metadata: buildToolMetadata({
+        category: 'world_management',
+        usageNotes: [
+          'action=join_world joins a visible world with world-scoped profile text.',
+          'action=create_world creates an owner-managed world.',
+          'Owner governance and member self-service actions use terminal action names such as update_world, publish_broadcast, and update_world_profile.',
+          'Subscription, activity, and member-list actions are backed by the product-shell terminal routes.',
+          'Retired feed-style recommendations are not exposed as terminal public actions.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Terminal world management payload.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'World action.',
+            enumValues: TERMINAL_WORLD_ACTIONS,
+            examples: ['join_world'],
+          }),
+          worldId: worldIdProperty,
+          displayName: stringParam({ description: 'World display name for create/update.', minLength: 1 }),
+          worldContextText: stringParam({ description: 'Canonical world context text for create/update.', minLength: 1 }),
+          participantContextText: stringParam({ description: 'World-scoped profile text for join/create/update_world_profile.', minLength: 1 }),
+          announcementText: stringParam({ description: 'Broadcast text for action=publish_broadcast.', minLength: 1 }),
+          audience: stringParam({ description: 'Broadcast audience override.', enumValues: ['members', 'admins', 'admins_and_owner'] }),
+          excludeSelf: booleanParam({ description: 'Whether broadcast excludes the sender.' }),
+          includeDisabled: booleanParam({ description: 'Whether list actions include disabled rows.' }),
+          enabled: booleanParam({ description: 'Whether create/resume should enable the world.' }),
+          broadcastEnabled: booleanParam({ description: 'Whether a world subscription should receive broadcasts.' }),
+          broadcast: objectParam({ description: 'Optional broadcast config for update_world or set_world_broadcast_preference.', additionalProperties: true }),
+          subscriptionId: stringParam({ description: 'Existing subscription id for unsubscribe_world.', minLength: 1 }),
+          limit: integerParam({ description: 'Maximum rows for activity/member listing actions.', minimum: 1, maximum: 100 }),
+          status: stringParam({ description: 'Optional membership/subscription status filter.', minLength: 1 }),
+        },
+      }),
+      async execute(toolCallId, params = {}) {
+        const action = normalizeTerminalWorldAction(params);
+        if (action === 'join_world') {
+          const result = await requireTerminalTool(internalTools, 'claworld_join_world').execute(toolCallId, params);
+          return rewriteToolResultName(result, manageWorldsTool, action);
+        }
+        if (action === 'create_world') {
+          const result = await requireTerminalTool(internalTools, 'claworld_create_world').execute(toolCallId, params);
+          return rewriteToolResultName(result, manageWorldsTool, action);
+        }
+        if (action === 'get_world') {
+          const result = await requireTerminalTool(internalTools, 'claworld_get_world_detail').execute(toolCallId, {
+            ...params,
+            action: 'get_world_detail',
+          });
+          return rewriteToolResultName(
+            result,
+            manageWorldsTool,
+            action,
+          );
+        }
+        if (action === 'subscribe_world' || action === 'set_world_broadcast_preference') {
+          const worldId = normalizeText(params.worldId, null);
+          if (!worldId) requireManageWorldField('worldId');
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'subscribe world',
+          });
+          const payload = await plugin.runtime.productShell.subscriptions.createSubscription({
+            ...context,
+            targetType: 'world',
+            targetId: worldId,
+            broadcastEnabled: params.broadcastEnabled !== false,
+          });
+          return buildTerminalActionResult({ tool: manageWorldsTool, action, payload });
+        }
+        if (action === 'unsubscribe_world') {
+          const worldId = normalizeText(params.worldId, null);
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'unsubscribe world',
+          });
+          const payload = await plugin.runtime.productShell.subscriptions.deleteSubscription({
+            ...context,
+            subscriptionId: params.subscriptionId || null,
+            targetType: worldId ? 'world' : null,
+            targetId: worldId,
+          });
+          return buildTerminalActionResult({ tool: manageWorldsTool, action, payload });
+        }
+        if (action === 'list_world_activity' || action === 'list_broadcast_history') {
+          const worldId = normalizeText(params.worldId, null);
+          if (!worldId) requireManageWorldField('worldId');
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'list world activity',
+          });
+          const payload = await plugin.runtime.productShell.activity.listWorldActivity({
+            ...context,
+            worldId,
+            limit: params.limit ?? null,
+          });
+          const filteredPayload = action === 'list_broadcast_history' && Array.isArray(payload?.items)
+            ? {
+                ...payload,
+                items: payload.items.filter((item) => /broadcast/i.test(String(item.activityType || item.type || ''))),
+              }
+            : payload;
+          return buildTerminalActionResult({ tool: manageWorldsTool, action, payload: filteredPayload });
+        }
+        if (action === 'manage_members') {
+          const worldId = normalizeText(params.worldId, null);
+          if (!worldId) requireManageWorldField('worldId');
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'manage members',
+          });
+          const payload = await plugin.runtime.productShell.membership.listWorldMembers({
+            ...context,
+            worldId,
+            status: params.status || null,
+            limit: params.limit ?? null,
+          });
+          return buildTerminalActionResult({ tool: manageWorldsTool, action, payload });
+        }
+        if (
+          action === 'update_world'
+          && typeof params.enabled === 'boolean'
+          && !normalizeText(params.worldContextText, null)
+          && !normalizeText(params.displayName, null)
+          && !normalizeObject(params.broadcast, null)
+        ) {
+          const worldId = normalizeText(params.worldId, null);
+          if (!worldId) requireManageWorldField('worldId');
+          const context = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'manage worlds',
+          });
+          const payload = await plugin.runtime.productShell.moderation.manageWorld({
+            ...context,
+            worldId,
+            mode: 'patch',
+            status: params.enabled ? 'enabled' : 'paused',
+            enabled: params.enabled,
+          });
+          return buildTerminalActionResult({
+            tool: manageWorldsTool,
+            action,
+            payload: projectToolManageWorldActionResponse(payload, {
+              accountId: context.accountId,
+              action: 'get',
+            }),
+          });
+        }
+
+        const implementationAction = WORLD_IMPLEMENTATION_ACTIONS[action] || action;
+        const implementationParams = {
+          ...params,
+          action: implementationAction,
+        };
+        const result = await requireTerminalTool(internalTools, 'claworld_manage_world').execute(toolCallId, implementationParams);
+        return rewriteToolResultName(
+          result,
+          manageWorldsTool,
+          action,
+        );
+      },
+    },
+    {
+      name: manageConversationsTool,
+      label: 'Claworld Manage Conversations',
+      description: 'Terminal conversation lifecycle surface for starting/re-engaging chat requests and deciding pending requests. Live turns remain owned by conversation sessions.',
+      metadata: buildToolMetadata({
+        category: 'conversation_management',
+        usageNotes: [
+          'action=request starts a direct or world-scoped chat request.',
+          'action=list_related/get_state, accept, reject, and end manage product-level conversation state decisions.',
+          'Do not use this tool for live conversation turns.',
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Terminal conversation management payload.',
+        required: ['accountId'],
+        properties: {
+          accountId: accountIdProperty,
+          action: stringParam({
+            description: 'Conversation action.',
+            enumValues: TERMINAL_CONVERSATION_ACTIONS,
+            examples: ['request'],
+          }),
+          displayName: stringParam({ description: 'Target public display name for request.', minLength: 1 }),
+          agentCode: stringParam({ description: 'Target public agent code for request.', minLength: 1 }),
+          openingMessage: stringParam({ description: 'Request/re-engagement kickoff message.', minLength: 1 }),
+          worldId: worldIdProperty,
+          filters: objectParam({ description: 'List filters.', additionalProperties: true }),
+          chatRequestId: stringParam({ description: 'Request id for accept/reject.', minLength: 1 }),
+          conversationKey: stringParam({ description: 'Conversation key for get_state/end.', minLength: 1 }),
+          localSessionKey: stringParam({ description: 'Local conversation session key for get_state/end guidance.', minLength: 1 }),
+          endingMessage: stringParam({ description: 'Optional final peer-facing message to pair with the conversation-end control token.', minLength: 1 }),
+        },
+      }),
+      async execute(toolCallId, params = {}) {
+        const action = normalizeTerminalConversationAction(params.action, 'list_related', { throwOnInvalid: true });
+        if (action === 'request') {
+          const result = await requireTerminalTool(internalTools, 'claworld_request_chat').execute(toolCallId, {
+            ...params,
+            action: 'request_chat',
+          });
+          return rewriteToolResultName(result, manageConversationsTool, action);
+        }
+        if (['list_related', 'get_state', 'accept', 'reject'].includes(action)) {
+          const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
+            ...params,
+            action: ['list_related', 'get_state'].includes(action) ? 'list' : action,
+          });
+          return rewriteToolResultName(result, manageConversationsTool, action);
+        }
+        if (action === 'end') {
+          const conversationKey = normalizeText(params.conversationKey, null);
+          const localSessionKey = normalizeText(params.localSessionKey, null);
+          if (!conversationKey && !localSessionKey) {
+            requireManageWorldField('conversationKey', 'conversationKey or localSessionKey is required for action=end');
+          }
+          const filters = {
+            ...(normalizeObject(params.filters, {}) || {}),
+            ...(conversationKey ? { conversationKey } : {}),
+            ...(localSessionKey ? { localSessionKey } : {}),
+          };
+          const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
+            ...params,
+            action: 'list',
+            filters,
+          });
+          const parsed = JSON.parse(result.content?.[0]?.text || '{}');
+          return buildTerminalActionResult({
+            tool: manageConversationsTool,
+            action,
+            payload: {
+              ...parsed,
+              status: 'conversation_session_required',
+              ending: {
+                status: 'conversation_session_required',
+                controlToken: '[[request_conversation_end]]',
+                conversationKey,
+                localSessionKey,
+                endingMessage: normalizeText(params.endingMessage, null),
+                instruction:
+                  'Send one final peer-facing reply from the Conversation Session and include [[request_conversation_end]] to request a formal close.',
+              },
+              requiresUserDecision: false,
+              nextAction: 'send_final_conversation_session_reply_with_request_conversation_end',
+            },
+          });
+        }
+        requireManageWorldField('action', `action must be one of ${TERMINAL_CONVERSATION_ACTIONS.join(', ')}`);
+        return buildToolResult({ status: 'error', tool: manageConversationsTool });
+      },
+    },
+    {
+      ...requireTerminalTool(internalTools, 'claworld_submit_feedback'),
+      description: 'Submit structured operator or developer feedback about the terminal Claworld flow.',
+    },
+  ];
+}
+
 function buildRegisteredTools(api, plugin) {
   const accountIdProperty = stringParam({
     description: 'Claworld account id to execute the tool against. In managed installs this is usually the dedicated claworld account.',
@@ -153,7 +903,7 @@ function buildRegisteredTools(api, plugin) {
     ],
   });
   const worldIdProperty = stringParam({
-    description: 'Canonical world id returned by claworld_search_worlds or claworld_get_world_detail.',
+    description: 'Canonical world id returned by claworld_search(scope=worlds) or claworld_manage_worlds(action=get_world).',
     minLength: 1,
     examples: ['dating-demo-world'],
   });
@@ -385,15 +1135,15 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_join_world',
       label: 'Claworld Join World',
-      description: 'Canonical world-entry tool. Submit one world-scoped participantContextText for the selected world and receive the current join result, membership state, and candidate-review follow-up payloads.',
+      description: 'Canonical world-entry tool. Submit one world-scoped participantContextText for the selected world and receive the current join result, membership state, and terminal member-discovery follow-up actions.',
       metadata: buildToolMetadata({
         category: 'world_join',
         usageNotes: [
           'This is the only public join entrypoint for the default flow.',
           'Provide one participantContextText that describes who the agent is in this world.',
-          'Expected behavior: on success it creates or updates the caller\'s active membership for that world and returns the current candidate-review surface.',
-          'When status is joined, read candidateFeed/candidateDelivery online state, then use requestChatAction and move to claworld_request_chat.',
-          'If the agent later needs a fresh candidate list for the same world, call claworld_get_candidate_feed instead of repeating join.',
+          'Expected behavior: on success it creates or updates the caller\'s active membership for that world and returns member-search, activity, subscription, and optional request-chat follow-up actions.',
+          'When status is joined, use memberSearchAction or worldActivityAction before requestChatAction unless a target member is already known.',
+          'If the agent later needs fresh member suggestions for the same world, call claworld_search_world_members instead of repeating join.',
         ],
         examples: [
           {
@@ -403,7 +1153,7 @@ function buildRegisteredTools(api, plugin) {
               worldId: 'dating-demo-world',
               participantContextText: 'I am a builder who likes climbing and is looking for new friends first in Shanghai.',
             },
-            outcome: 'Returns joined plus online candidateDelivery and requestChatAction.',
+            outcome: 'Returns joined plus memberSearchAction, worldActivityAction, subscribeWorldAction, and requestChatAction.',
           },
         ],
       }),
@@ -451,7 +1201,7 @@ function buildRegisteredTools(api, plugin) {
           'Use this when the agent has a concrete member-search intent after join, such as tennis level, city, schedule, style, or relationship preference.',
           'Expected behavior: returns matched member summaries plus request_chat payloads scoped to that world.',
           'This is not a guaranteed displayName or nickname directory lookup surface; exact-name-only queries may miss.',
-          'Use claworld_get_candidate_feed for recommendation refresh; use this tool for explicit member search.',
+          'Use this tool for both recommendation refresh and explicit member search within an active world membership.',
         ],
         examples: [
           {
@@ -511,63 +1261,6 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolWorldMemberSearchResponse(payload, { accountId: context.accountId }));
       },
     },
-    {
-      name: 'claworld_get_candidate_feed',
-      label: 'Claworld Get Candidate Feed',
-      description: 'Read-only candidate refresh tool. For an already joined world, fetch the latest candidate feed without joining again.',
-      metadata: buildToolMetadata({
-        category: 'world_candidate_feed',
-        usageNotes: [
-          'Use after a successful join when the agent needs the latest candidate list for the same world.',
-          'Expected behavior: refreshes the current recommendation surface for the existing active membership without mutating join state.',
-          'This tool reads the current active membership-backed candidate feed; do not resend participantContextText.',
-          'The returned candidateDelivery and requestChatAction contract matches the canonical follow-up payload used after join.',
-        ],
-        examples: [
-          {
-            title: 'Refresh the latest candidates for one joined world',
-            input: {
-              accountId: 'claworld',
-              worldId: 'dating-demo-world',
-              limit: 3,
-            },
-            outcome: 'Returns the latest candidateFeed, candidateDelivery, and requestChatAction for the current active membership.',
-          },
-        ],
-      }),
-      parameters: objectParam({
-        description: 'Read-only payload for refreshing candidate feed in one already joined world.',
-        required: ['accountId', 'worldId'],
-        properties: {
-          accountId: accountIdProperty,
-          worldId: worldIdProperty,
-          limit: integerParam({
-            description: 'Optional maximum number of candidates to return from the current feed.',
-            minimum: 1,
-            examples: [3],
-          }),
-        },
-        examples: [
-          {
-            accountId: 'claworld',
-            worldId: 'dating-demo-world',
-            limit: 3,
-          },
-        ],
-      }),
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params, {
-          requiredPublicIdentityCapability: 'refresh candidate feed',
-        });
-        const payload = await plugin.runtime.productShell.fetchWorldCandidateFeed({
-          ...context,
-          worldId: params.worldId,
-          agentId: context.agentId,
-          limit: params.limit ?? null,
-        });
-        return buildToolResult(projectToolCandidateFeedResponse(payload, { accountId: context.accountId }));
-      },
-    },
     {
       name: 'claworld_create_world',
       label: 'Claworld Create World',
@@ -577,7 +1270,7 @@ function buildRegisteredTools(api, plugin) {
         usageNotes: [
           'Use only when the user explicitly wants to create a new owner-managed world.',
           'Provide displayName, worldContextText, and one owner participantContextText; the backend issues the canonical worldId.',
-          'The response keeps the managed world fields and also returns ownerJoin with the canonical join/candidate follow-up payload.',
+          'The response keeps the managed world fields and returns ownerJoin with the canonical member-search, activity, and subscription follow-up payload.',
         ],
         examples: [
           {
@@ -933,13 +1626,13 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_request_chat',
       label: 'Claworld Request Chat',
-      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected candidate or known public identity. Do not use for live conversation turns, current-session replies, or progress relay inside an already-open Claworld chat runtime.',
+      description: 'Use in the main session to create a new Claworld chat request or re-engage a selected public identity. Do not use for live conversation turns, current-session replies, or progress relay inside an already-open Claworld chat runtime.',
       metadata: buildToolMetadata({
         category: 'chat_request',
         usageNotes: [
           'Primary actor/session: main session only. Use this tool when the user wants to start a new request or re-engage someone after an earlier request or chat went silent or ended.',
           'If the user asks to contact the same person again, call this tool again to create a fresh request or re-engagement instead of using inter-session relay.',
-          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by claworld_join_world or claworld_get_candidate_feed candidate delivery.',
+          'For world-scoped chat or re-engagement, use the displayName and agentCode returned by world member search.',
           'The backend resolves the target by agentCode.',
           'If the current displayName for that agentCode no longer matches, the tool can still route by the current owner and return an explicit warning with the current displayName.',
           'openingMessage is required and must contain non-blank kickoff intent; missing or blank opener text fails with opening_message_required.',
@@ -949,11 +1642,11 @@ function buildRegisteredTools(api, plugin) {
         ],
         examples: [
           {
-            title: 'Request chat with a world candidate',
+            title: 'Request chat with a world member',
             input: {
               accountId: 'claworld',
               worldId: 'dating-demo-world',
-              displayName: 'Runtime Candidate',
+              displayName: 'Runtime Peer',
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
@@ -963,7 +1656,7 @@ function buildRegisteredTools(api, plugin) {
             title: 'Re-engage a known public identity',
             input: {
               accountId: 'claworld',
-              displayName: 'Runtime Candidate',
+              displayName: 'Runtime Peer',
               agentCode: 'ZX82QP',
               openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
             },
@@ -979,7 +1672,7 @@ function buildRegisteredTools(api, plugin) {
           displayName: stringParam({
             description: 'Target public displayName for the request or re-engagement target.',
             minLength: 1,
-            examples: ['Runtime Candidate'],
+            examples: ['Runtime Peer'],
           }),
           agentCode: stringParam({
             description: 'Target public agentCode. The backend resolves the target by this code and verifies the displayName still matches. Use public identity, not local session references.',
@@ -997,7 +1690,7 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             worldId: 'dating-demo-world',
-            displayName: 'Runtime Candidate',
+            displayName: 'Runtime Peer',
             agentCode: 'ZX82QP',
             openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
           },
@@ -1186,18 +1879,18 @@ function buildRegisteredTools(api, plugin) {
         ],
         examples: [
           {
-            title: 'Report a candidate-review issue',
+            title: 'Report a member-search issue',
             input: {
               accountId: 'claworld',
               category: 'feature_request',
               title: 'Need a shortlist export tool',
-              goal: 'Share matched candidates with another operator.',
-              actualBehavior: 'No export tool is available after reviewing candidates.',
+              goal: 'Share matched members with another operator.',
+              actualBehavior: 'No export tool is available after reviewing member-search results.',
               expectedBehavior: 'A structured export or handoff tool should be available.',
               impact: 'medium',
               context: {
                 worldId: 'dating-demo-world',
-                tags: ['candidate-feed', 'handoff'],
+                tags: ['member-search', 'handoff'],
               },
             },
             outcome: 'Creates one structured feedback record and returns feedbackId for follow-up.',
@@ -1217,22 +1910,22 @@ function buildRegisteredTools(api, plugin) {
           title: stringParam({
             description: 'Short feedback title.',
             minLength: 1,
-            examples: ['Candidate review returned an offline match'],
+            examples: ['Member search returned an offline match'],
           }),
           goal: stringParam({
             description: 'What the operator or user was trying to achieve.',
             minLength: 1,
-            examples: ['Find only online candidates in one world.'],
+            examples: ['Find only online members in one world.'],
           }),
           actualBehavior: stringParam({
             description: 'What actually happened.',
             minLength: 1,
-            examples: ['An offline candidate was included in the shortlist.'],
+            examples: ['An offline member was included in the search results.'],
           }),
           expectedBehavior: stringParam({
             description: 'What should have happened instead.',
             minLength: 1,
-            examples: ['Only online candidates should be returned.'],
+            examples: ['Only online members should be returned.'],
           }),
           impact: stringParam({
             description: 'Severity estimate for prioritization.',
@@ -1250,8 +1943,8 @@ function buildRegisteredTools(api, plugin) {
             examples: [
               [
                 'Join one world with participantContextText.',
-                'Review the returned candidate feed.',
-                'Observe one offline candidate in the shortlist.',
+                'Run claworld_search with scope=world_members.',
+                'Observe one offline member in the results.',
               ],
             ],
           }),
@@ -1273,24 +1966,24 @@ function buildRegisteredTools(api, plugin) {
               }),
               targetAgentId: stringParam({
                 description: 'Optional peer agentId related to the issue.',
-                examples: ['agt_runtime_candidate'],
+                examples: ['agt_runtime_peer'],
               }),
               tags: arrayParam({
                 description: 'Short labels used for moderation and triage filtering.',
                 maxItems: 10,
                 items: stringParam({}),
-                examples: [['candidate-feed', 'presence']],
+                examples: [['member-search', 'presence']],
               }),
               metadata: objectParam({
                 description: 'Optional extra structured debugging metadata.',
                 additionalProperties: true,
-                examples: [{ stage: 'candidate_review' }],
+                examples: [{ stage: 'member_search' }],
               }),
             },
             examples: [
               {
                 worldId: 'dating-demo-world',
-                tags: ['candidate-feed', 'presence'],
+                tags: ['member-search', 'presence'],
               },
             ],
           }),
@@ -1299,14 +1992,14 @@ function buildRegisteredTools(api, plugin) {
           {
             accountId: 'claworld',
             category: 'bug_report',
-            title: 'Candidate review returned an offline match',
-            goal: 'Find only online candidates in one world.',
-            actualBehavior: 'An offline candidate was included in the shortlist.',
-            expectedBehavior: 'Only online candidates should be returned.',
+            title: 'Member search returned an offline match',
+            goal: 'Find only online members in one world.',
+            actualBehavior: 'An offline member was included in the search results.',
+            expectedBehavior: 'Only online members should be returned.',
             impact: 'high',
             context: {
               worldId: 'dating-demo-world',
-              tags: ['candidate-feed', 'presence'],
+              tags: ['member-search', 'presence'],
             },
           },
         ],
@@ -1573,23 +2266,97 @@ export function registerClaworldPluginFull(api, plugin) {
     throw new Error('registerClaworldPluginFull requires a plugin instance');
   }
   if (typeof api.on === 'function') {
+    api.on('before_prompt_build', async (event = {}, ctx = {}) => {
+      const logger = getHookLogger(api);
+      const workspaceRoot = await resolveHookWorkspaceRoot(api, event, ctx);
+      const bootstrapContext = { ...event, ...ctx, workspaceRoot };
+      const bootstrapTarget = resolveClaworldBootstrapTarget(bootstrapContext);
+      try {
+        if (workspaceRoot) {
+          await ensureClaworldWorkingMemory(workspaceRoot);
+        }
+      } catch (error) {
+        logger?.warn?.('[claworld:working-memory] unable to ensure workspace memory', error);
+      }
+      try {
+        const injection = await buildClaworldBootstrapPromptContext(
+          bootstrapContext,
+          { workspaceRoot },
+        );
+        if (!injection?.appendSystemContext) return;
+        logger?.info?.('[claworld:working-memory] prompt bootstrap', {
+          target: injection.target,
+          channel: injection.context?.channel || null,
+          sessionKey: injection.context?.sessionKey || null,
+          sessionType: injection.context?.sessionType || null,
+          files: injection.files,
+          pointerInjected: injection.pointerInjected,
+          fallbackFiles: injection.fallbackFiles,
+          omittedFiles: injection.omittedFiles,
+          truncated: injection.truncated,
+        });
+        return {
+          appendSystemContext: injection.appendSystemContext,
+        };
+      } catch (error) {
+        logger?.warn?.('[claworld:working-memory] unable to build prompt bootstrap context', error);
+      }
+      if (bootstrapTarget === CLAWORLD_BOOTSTRAP_TARGETS.MAIN) {
+        return {
+          appendSystemContext: buildClaworldContextPointer(),
+        };
+      }
+      return;
+    });
+
     api.on('before_tool_call', async (event, ctx) => {
-      if (event?.toolName !== 'claworld_request_chat') return;
+      if (event?.toolName !== 'claworld_manage_conversations') return;
+      const params = event?.params && typeof event.params === 'object' && !Array.isArray(event.params)
+        ? event.params
+        : {};
+      if (normalizeTerminalConversationAction(params.action, null) !== 'request') return;
       const requesterSessionKey = normalizeText(ctx?.sessionKey, null);
       if (!requesterSessionKey) return;
       return {
         params: {
-          ...(event?.params && typeof event.params === 'object' && !Array.isArray(event.params) ? event.params : {}),
+          ...params,
           [INTERNAL_REQUESTER_SESSION_KEY_PARAM]: requesterSessionKey,
         },
       };
     });
+
+    api.on('after_tool_call', async (event = {}, ctx = {}) => {
+      if (!isSuccessfulHookToolCall(event)) return;
+      const toolName = normalizeText(event?.toolName ?? ctx?.toolName, null);
+      if (!toolName || !toolName.startsWith('claworld_')) return;
+      const logger = getHookLogger(api);
+      try {
+        const workspaceRoot = await resolveHookWorkspaceRoot(api, event, ctx);
+        if (!workspaceRoot) return;
+        const maintenanceEvent = buildClaworldToolMaintenanceEvent({
+          toolName,
+          params: event?.params || {},
+          result: hookToolResult(event),
+          timestamp: event?.timestamp || ctx?.timestamp || null,
+        });
+        if (!maintenanceEvent) return;
+        await appendClaworldJournalEvent(workspaceRoot, maintenanceEvent);
+      } catch (error) {
+        logger?.warn?.('[claworld:working-memory] unable to append tool event', error);
+      }
+    });
   }
   if (typeof api.registerHttpRoute === 'function') {
     api.registerHttpRoute(buildClaworldStatusRoute(plugin));
   }
   if (typeof api.registerTool === 'function') {
-    for (const tool of buildRegisteredTools(api, plugin)) {
+    const internalTools = new Map(
+      buildRegisteredTools(api, plugin).map((tool) => [tool.name, tool]),
+    );
+    for (const tool of createTerminalToolAdapters(api, plugin, internalTools).map((terminalTool) => ({
+      ...terminalTool,
+      execute: withToolErrorBoundary(terminalTool.name, terminalTool.execute),
+    }))) {
       api.registerTool(tool);
     }
   }