@xfxstudio/claworld 2026.7.8-testing.1 → 2026.7.9-testing.2

package/src/openclaw/plugin/register.js

@@ -13,6 +13,7 @@ import {
   projectToolWorldSearchResponse,
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
+import { CLAWORLD_PLUGIN_CURRENT_VERSION } from '../plugin-version.js';
 import {
   CLAWORLD_BOOTSTRAP_TARGETS,
   appendClaworldJournalEvent,
@@ -24,6 +25,12 @@ import {
   updateClaworldSessionDirectory,
 } from '../runtime/working-memory.js';
 import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
+import {
+  augmentConversationPayloadWithLocalTranscriptIndex,
+  CLAWORLD_TRANSCRIPT_REPORT_STYLE,
+  CLAWORLD_TRANSCRIPT_REPORT_TOOL_NAME,
+  renderClaworldTranscriptReport,
+} from '../runtime/transcript-report.js';
 import { setClaworldRuntime } from './runtime.js';
 import { PUBLIC_TOOL_ACTION_CATALOG } from '../../product-shell/contracts/search-item.js';
 import {
@@ -145,6 +152,18 @@ const CHAT_INBOX_FILTER_STATUSES = Object.freeze([
   'kickoff_failed',
   'ended',
 ]);
+const FEEDBACK_CATEGORIES = Object.freeze([
+  'experience_issue',
+  'usage_issue',
+  'bug_report',
+  'feature_request',
+]);
+const FEEDBACK_IMPACTS = Object.freeze([
+  'low',
+  'medium',
+  'high',
+  'blocker',
+]);
 const CHAT_INBOX_FILTER_KEYS = Object.freeze([
   'direction',
   'mode',
@@ -177,6 +196,8 @@ const TERMINAL_ACCOUNT_ACTIONS = PUBLIC_TOOL_ACTION_CATALOG.claworld_manage_acco
 const TERMINAL_WORLD_ACTIONS = PUBLIC_TOOL_ACTION_CATALOG.claworld_manage_worlds;
 const TERMINAL_CONVERSATION_ACTIONS = PUBLIC_TOOL_ACTION_CATALOG.claworld_manage_conversations;
 
+const CLAWORLD_WORLD_TOOL_GUIDANCE = 'Before any world operation, read the `claworld-manage-worlds` skill.';
+
 const ACCOUNT_IMPLEMENTATION_ACTIONS = Object.freeze({
   view_account: 'view',
 });
@@ -240,6 +261,13 @@ function normalizeTerminalAccountAction(params = {}) {
     requireManageWorldField('chatRequestPolicy', 'chatRequestPolicy is not supported by claworld_manage_account; use contactPolicy');
   }
   if (Object.prototype.hasOwnProperty.call(params, 'proactivitySettings')) return 'set_proactivity';
+  if (
+    hasProvidedToolParam(params, 'category')
+    || hasProvidedToolParam(params, 'title')
+    || hasProvidedToolParam(params, 'actualBehavior')
+    || hasProvidedToolParam(params, 'expectedBehavior')
+    || hasProvidedToolParam(params, 'reproductionSteps')
+  ) return 'submit_feedback';
   return 'view_account';
 }
 
@@ -348,6 +376,66 @@ function hasProvidedToolParam(params = {}, fieldId) {
   return value != null;
 }
 
+function normalizeFeedbackStringList(values = []) {
+  const source = Array.isArray(values) ? values : [values];
+  return [...new Set(source.map((value) => normalizeText(value, null)).filter(Boolean))];
+}
+
+function validateTerminalFeedbackPayload(params = {}) {
+  const category = normalizeText(params.category, null);
+  const impact = normalizeText(params.impact, 'medium');
+  if (!category) requireManageWorldField('category', 'category is required for action=submit_feedback');
+  if (!FEEDBACK_CATEGORIES.includes(category)) {
+    requireManageWorldField('category', `category must be one of ${FEEDBACK_CATEGORIES.join(', ')}`);
+  }
+  if (!FEEDBACK_IMPACTS.includes(impact)) {
+    requireManageWorldField('impact', `impact must be one of ${FEEDBACK_IMPACTS.join(', ')}`);
+  }
+  for (const fieldId of ['title', 'goal', 'actualBehavior', 'expectedBehavior']) {
+    if (!normalizeText(params[fieldId], null)) {
+      requireManageWorldField(fieldId, `${fieldId} is required for action=submit_feedback`);
+    }
+  }
+  if (
+    params.context != null
+    && (!params.context || typeof params.context !== 'object' || Array.isArray(params.context))
+  ) {
+    requireManageWorldField('context', 'context must be an object for action=submit_feedback');
+  }
+}
+
+function normalizeTerminalFeedbackContext(params = {}) {
+  const context = normalizeObject(params.context, {}) || {};
+  const metadata = normalizeObject(context.metadata, {}) || {};
+  const redactionNotes = normalizeText(params.redactionNotes, null);
+  return {
+    worldId: normalizeText(context.worldId, normalizeText(params.worldId, null)),
+    conversationKey: normalizeText(context.conversationKey, normalizeText(params.conversationKey, null)),
+    turnId: normalizeText(context.turnId, normalizeText(params.turnId, null)),
+    deliveryId: normalizeText(context.deliveryId, normalizeText(params.deliveryId, null)),
+    targetAgentId: normalizeText(context.targetAgentId, normalizeText(params.targetAgentId, null)),
+    tags: normalizeFeedbackStringList(context.tags),
+    metadata: {
+      ...metadata,
+      ...(redactionNotes ? { redactionNotes } : {}),
+    },
+  };
+}
+
+function normalizeTerminalFeedbackPayload(params = {}) {
+  return {
+    category: normalizeText(params.category, null),
+    title: normalizeText(params.title, null),
+    goal: normalizeText(params.goal, null),
+    actualBehavior: normalizeText(params.actualBehavior, null),
+    expectedBehavior: normalizeText(params.expectedBehavior, null),
+    impact: normalizeText(params.impact, 'medium'),
+    details: normalizeText(params.details, null),
+    reproductionSteps: normalizeFeedbackStringList(params.reproductionSteps),
+    context: normalizeTerminalFeedbackContext(params),
+  };
+}
+
 function buildChatInboxFiltersParam({ description, worldIdProperty } = {}) {
   return objectParam({
     description,
@@ -393,6 +481,118 @@ function buildChatInboxFiltersParam({ description, worldIdProperty } = {}) {
   });
 }
 
+function buildTranscriptReportParameters() {
+  return objectParam({
+    description: 'Render a Claworld transcript into BubbleSpec, SVG pages, and PNG pages.',
+    required: ['mode'],
+    additionalProperties: false,
+    properties: {
+      mode: stringParam({
+        description: 'Render source mode. Use stored for local OpenClaw conversation transcripts and manual for supplied excerpts.',
+        enumValues: ['stored', 'manual'],
+        examples: ['stored'],
+      }),
+      stored: objectParam({
+        description: 'Local OpenClaw transcript source resolved through .claworld/sessions/index.json.',
+        required: ['chatRequestId'],
+        additionalProperties: false,
+        properties: {
+          chatRequestId: stringParam({
+            description: 'Canonical Claworld chat request id to render from the local Conversation Session transcript index.',
+            minLength: 1,
+            examples: ['req_demo_1'],
+          }),
+        },
+      }),
+      manual: objectParam({
+        description: 'Explicit transcript excerpt fallback. Use only when the exact conversation is not available in local storage.',
+        required: ['messages', 'title', 'peerProfile', 'localLabel', 'peerLabel'],
+        additionalProperties: false,
+        properties: {
+          messages: arrayParam({
+            description: 'Ordered peer/local transcript messages.',
+            items: objectParam({
+              required: ['from', 'text', 'createdAt'],
+              additionalProperties: false,
+              properties: {
+                from: stringParam({
+                  description: 'Speaker side from the owner account perspective.',
+                  enumValues: ['peer', 'local'],
+                  examples: ['peer'],
+                }),
+                text: stringParam({ description: 'Message text to render.', minLength: 1 }),
+                createdAt: stringParam({ description: 'Parseable timestamp for this message.', minLength: 1 }),
+              },
+            }),
+          }),
+          title: stringParam({ description: 'Report title.', minLength: 1 }),
+          peerProfile: stringParam({ description: 'Peer/profile subtitle shown under the report title.', minLength: 1 }),
+          localLabel: stringParam({ description: 'Label for the local side.', minLength: 1 }),
+          peerLabel: stringParam({ description: 'Label for the peer side.', minLength: 1 }),
+        },
+      }),
+      style: stringParam({
+        description: 'Transcript rendering style.',
+        enumValues: [CLAWORLD_TRANSCRIPT_REPORT_STYLE],
+        examples: [CLAWORLD_TRANSCRIPT_REPORT_STYLE],
+      }),
+      maxPageHeight: integerParam({
+        description: 'Maximum SVG/PNG page height before pagination.',
+        minimum: 900,
+        maximum: 8000,
+        examples: [2600],
+      }),
+    },
+  });
+}
+
+async function resolveLocalWorkspaceRootForTool(api, _plugin, params = {}) {
+  const cfg = await loadCurrentConfig(api);
+  const agentId = resolveToolAgentId(params, null);
+  return {
+    agentId,
+    workspaceRoot: resolveOpenClawWorkspaceRoot({
+      sources: [params],
+      config: cfg,
+      agentId,
+    }) || process.cwd(),
+  };
+}
+
+async function augmentConversationToolResultWithTranscripts(api, plugin, params, filters, result, toolName, action) {
+  const rewritten = rewriteToolResultName(result, toolName, action);
+  const payload = parseToolResultPayload(rewritten);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return rewritten;
+  const { workspaceRoot } = await resolveLocalWorkspaceRootForTool(api, plugin, params);
+  const augmentedPayload = await augmentConversationPayloadWithLocalTranscriptIndex(payload, {
+    workspaceRoot,
+    filters,
+  });
+  return buildToolResult({
+    ...augmentedPayload,
+    tool: toolName,
+    action,
+  });
+}
+
+function stripTranscriptReportToolContextParams(params = {}) {
+  const contextFields = new Set([
+    'workspaceRoot',
+    'workspaceDir',
+    'workspacePath',
+    'workspace',
+    'cwd',
+    'agent',
+    'context',
+    'session',
+    'agentId',
+    'localAgentId',
+  ]);
+  return Object.fromEntries(
+    Object.entries(params || {}).filter(([key]) => !contextFields.has(key)),
+  );
+}
+
 function validateChatInboxFilterInput(filters = {}, action) {
   const source = normalizeObject(filters, {}) || {};
   for (const key of Object.keys(source)) {
@@ -498,6 +698,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
   const searchTool = 'claworld_search';
   const manageWorldsTool = 'claworld_manage_worlds';
   const manageConversationsTool = 'claworld_manage_conversations';
+  const transcriptReportTool = CLAWORLD_TRANSCRIPT_REPORT_TOOL_NAME;
   const accountTool = 'claworld_manage_account';
   const publicProfileTool = 'claworld_get_public_profile';
 
@@ -505,7 +706,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
     {
       name: accountTool,
       label: 'Claworld Manage Account',
-      description: 'Terminal account surface for readiness, public identity, global profile, share-card generation, visibility, inbound contact policy, and email-based identity verification.',
+      description: 'Terminal account surface for readiness, public identity, global profile, share-card generation, visibility, inbound contact policy, notification/proactivity policy, email-based identity verification, and authenticated feedback submission.',
       metadata: buildToolMetadata({
         category: 'account',
         usageNotes: [
@@ -513,6 +714,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           'Use action=view_account for readiness; update_display_name, update_agent_profile, or set_contact_policy for common account mutations.',
           'Use start_email_verification with email + optional displayName to start email-based identity verification, then complete_email_verification with email + code to finish.',
           'Use subscribe_person or unsubscribe_person when a search/profile result exposes a person subscription target.',
+          'Use submit_feedback for Claworld bugs, confusing behavior, missing capability, or feature requests. The tool handles auth internally.',
         ],
       }),
       parameters: objectParam({
@@ -523,7 +725,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           action: stringParam({
             description: 'Account action.',
             enumValues: TERMINAL_ACCOUNT_ACTIONS,
-            examples: ['view_account', 'start_email_verification', 'update_display_name', 'set_contact_policy'],
+            examples: ['view_account', 'start_email_verification', 'update_display_name', 'set_contact_policy', 'submit_feedback'],
           }),
           displayName: stringParam({
             description: 'Public-facing display name for update_display_name or start_email_verification.',
@@ -589,6 +791,49 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
             minLength: 1,
             examples: ['123456'],
           }),
+          category: stringParam({
+            description: 'Feedback category.',
+            enumValues: FEEDBACK_CATEGORIES,
+            examples: ['bug_report', 'feature_request'],
+          }),
+          title: stringParam({
+            description: 'Short developer-readable feedback title.',
+            minLength: 1,
+            examples: ['Feedback submission should use account tool auth'],
+          }),
+          goal: stringParam({
+            description: 'What the human was trying to do.',
+            minLength: 1,
+          }),
+          actualBehavior: stringParam({
+            description: 'What actually happened.',
+            minLength: 1,
+          }),
+          expectedBehavior: stringParam({
+            description: 'What should have happened.',
+            minLength: 1,
+          }),
+          impact: stringParam({
+            description: 'Feedback impact.',
+            enumValues: FEEDBACK_IMPACTS,
+            examples: ['medium'],
+          }),
+          details: stringParam({
+            description: 'Developer-facing feedback details.',
+            minLength: 1,
+          }),
+          reproductionSteps: arrayParam({
+            description: 'Repeatable feedback reproduction steps.',
+            items: stringParam({ minLength: 1 }),
+          }),
+          context: objectParam({
+            description: 'Lookup metadata, such as worldId, conversationKey, deliveryId, targetAgentId, tags, and metadata.',
+            additionalProperties: true,
+          }),
+          redactionNotes: stringParam({
+            description: 'Optional note about what was redacted before submit_feedback.',
+            minLength: 1,
+          }),
         },
       }),
       async execute(toolCallId, params = {}) {
@@ -648,6 +893,33 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           return buildTerminalActionResult({ tool: accountTool, action, payload });
         }
 
+        if (action === 'submit_feedback') {
+          validateTerminalFeedbackPayload(params);
+          const feedback = normalizeTerminalFeedbackPayload(params);
+          const toolContext = await resolveToolContext(api, plugin, params, {
+            requiredPublicIdentityCapability: 'submit feedback',
+          });
+          if (typeof plugin.runtime.productShell.feedback?.submitFeedback !== 'function') {
+            requireManageWorldField('action', 'action=submit_feedback requires the feedback runtime adapter');
+          }
+          const payload = await plugin.runtime.productShell.feedback.submitFeedback({
+            ...toolContext,
+            ...feedback,
+            toolCallId,
+            source: 'openclaw_account_tool',
+            runtimeToolName: accountTool,
+            accountToolAction: action,
+            pluginVersion: CLAWORLD_PLUGIN_CURRENT_VERSION,
+            toolContractVersion: CLAWORLD_TOOL_CONTRACT_VERSION,
+          });
+          return buildTerminalActionResult({
+            tool: accountTool,
+            action,
+            payload: projectToolFeedbackSubmissionResponse(payload),
+            status: 'recorded',
+          });
+        }
+
         const implementationAction = ACCOUNT_IMPLEMENTATION_ACTIONS[action] || null;
         if (implementationAction) {
           const implementationParams = {
@@ -892,7 +1164,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
     {
       name: manageWorldsTool,
       label: 'Claworld Manage Worlds',
-      description: 'Terminal world surface for browsing selected world details, joining, creation, owner governance, broadcast, and membership self-service.',
+      description: `Terminal world surface for browsing selected world details, joining, creation, governance, broadcast, invites, membership, subscriptions, and participation context. ${CLAWORLD_WORLD_TOOL_GUIDANCE}`,
       metadata: buildToolMetadata({
         category: 'world_management',
         usageNotes: [
@@ -1214,7 +1486,15 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
             action: 'list',
             ...(Object.keys(filters).length > 0 ? { filters } : {}),
           });
-          return rewriteToolResultName(result, manageConversationsTool, action);
+          return augmentConversationToolResultWithTranscripts(
+            api,
+            plugin,
+            params,
+            filters,
+            result,
+            manageConversationsTool,
+            action,
+          );
         }
         if (action === 'accept' || action === 'reject') {
           const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
@@ -1245,6 +1525,33 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
         return buildToolResult({ status: 'error', tool: manageConversationsTool });
       },
     },
+    {
+      name: transcriptReportTool,
+      label: 'Claworld Render Transcript Report',
+      description: 'Render a local Claworld conversation transcript into BubbleSpec, SVG pages, and PNG pages. Prefer mode=stored with a chatRequestId from claworld_manage_conversations or .claworld/sessions/index.json; use manual mode only for selected excerpts or fallback rendering.',
+      metadata: buildToolMetadata({
+        category: 'transcript_report',
+        usageNotes: [
+          'Use mode=stored when the exact chatRequestId is known and the local Conversation Session transcript has been indexed.',
+          'Use mode=manual only when the human asks for a selected excerpt or the stored transcript is unavailable.',
+          'Use deliveryHint.messageTool or deliveryHint.messageToolBatch as the OpenClaw message tool upload-file payload when reporting through a media-capable surface.',
+          'Do not paste raw transcript text to the human when this report rendering tool can produce the visual artifact.',
+        ],
+      }),
+      parameters: buildTranscriptReportParameters(),
+      async execute(_toolCallId, params = {}) {
+        const { workspaceRoot, agentId } = await resolveLocalWorkspaceRootForTool(api, plugin, params);
+        const payload = await renderClaworldTranscriptReport({
+          workspaceRoot,
+          agentId,
+          args: stripTranscriptReportToolContextParams(params),
+        });
+        return buildToolResult({
+          ...payload,
+          tool: transcriptReportTool,
+        });
+      },
+    },
   ];
 }
 
@@ -1303,7 +1610,7 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_get_world_detail',
       label: 'Claworld Get World Detail',
-      description: 'Canonical world-inspection tool. Fetch one world detail before deciding whether to join it.',
+      description: `Canonical world-inspection tool. Fetch one world detail before deciding whether to join it. ${CLAWORLD_WORLD_TOOL_GUIDANCE}`,
       metadata: buildToolMetadata({
         category: 'world_discovery',
         usageNotes: [
@@ -1348,7 +1655,7 @@ 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 terminal member-discovery follow-up actions.',
+      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. ${CLAWORLD_WORLD_TOOL_GUIDANCE}`,
       metadata: buildToolMetadata({
         category: 'world_join',
         usageNotes: [
@@ -1406,7 +1713,7 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_create_world',
       label: 'Claworld Create World',
-      description: 'Creator/admin entrypoint for publishing one new owner-managed world. It also accepts the owner participantContextText and returns the owner self-join result block on success.',
+      description: `Creator/admin entrypoint for publishing one new managed world. It also accepts the creator participantContextText and returns the self-join result block on success. ${CLAWORLD_WORLD_TOOL_GUIDANCE}`,
       metadata: buildToolMetadata({
         category: 'world_creation',
         usageNotes: [
@@ -1494,7 +1801,7 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_manage_world',
       label: 'Claworld Manage World',
-      description: 'Unified world management tool. Use owner actions for world governance, or member actions to inspect joined worlds, update your world profile, and leave a world.',
+      description: `Unified world management tool. Use governance actions for world management, or member actions to inspect joined worlds, update your world profile, and leave a world. ${CLAWORLD_WORLD_TOOL_GUIDANCE}`,
       metadata: buildToolMetadata({
         category: 'world_management',
         usageNotes: [
@@ -1910,7 +2217,7 @@ function buildRegisteredTools(api, plugin) {
     {
       name: 'claworld_account',
       label: 'Claworld Account',
-      description: 'Canonical account surface. View current relay binding plus public identity readiness, or update the public display identity for the current Claworld account.',
+      description: 'Canonical account surface. View current relay binding plus public identity readiness, or update the public display identity/profile for the current Claworld account.',
       metadata: buildToolMetadata({
         category: 'account',
         usageNotes: [

package/src/openclaw/runtime/feedback-helper.js

@@ -37,6 +37,9 @@ export async function submitFeedbackReport({
   fetchImpl,
   logger = console,
   toolCallId = null,
+  source = 'openclaw_runtime',
+  runtimeToolName = 'claworld_feedback_helper',
+  accountToolAction = null,
   pluginVersion = null,
   toolContractVersion = null,
 } = {}) {
@@ -86,10 +89,11 @@ export async function submitFeedbackReport({
         tags: normalizeStringList(normalizedContext.tags),
         metadata: normalizeObject(normalizedContext.metadata),
       },
-      source: 'openclaw_runtime',
+      source: normalizeText(source, 'openclaw_runtime'),
       runtimeContext: {
         channelId: 'claworld',
-        toolName: 'claworld_feedback_helper',
+        toolName: normalizeText(runtimeToolName, 'claworld_feedback_helper'),
+        accountToolAction: normalizeText(accountToolAction, null),
         toolCallId: normalizeText(toolCallId, null),
         ...diagnostics,
         toolContractVersion: normalizeText(toolContractVersion, null),

package/src/openclaw/runtime/tool-contracts.js

@@ -565,6 +565,7 @@ export function projectToolFeedbackSubmissionResponse(result = {}) {
     runtime: {
       channelId: normalizeText(runtimeContext.channelId, null),
       toolName: normalizeText(runtimeContext.toolName, null),
+      accountToolAction: normalizeText(runtimeContext.accountToolAction, null),
       toolCallId: normalizeText(runtimeContext.toolCallId, null),
       openclawVersion: normalizeText(runtimeContext.openclawVersion, null),
       pluginVersion: normalizeText(runtimeContext.pluginVersion, null),

package/src/openclaw/runtime/tool-inventory.js

@@ -17,12 +17,16 @@ export const CLAWORLD_CONVERSATION_TOOL_NAMES = Object.freeze([
   'claworld_manage_conversations',
 ]);
 
+export const CLAWORLD_TRANSCRIPT_TOOL_NAMES = Object.freeze([
+  'claworld_render_transcript_report',
+]);
 
 export const CLAWORLD_REGISTERED_TOOL_NAMES = Object.freeze([
   ...CLAWORLD_ACCOUNT_TOOL_NAMES,
   ...CLAWORLD_SEARCH_TOOL_NAMES,
   ...CLAWORLD_WORLD_TOOL_NAMES,
   ...CLAWORLD_CONVERSATION_TOOL_NAMES,
+  ...CLAWORLD_TRANSCRIPT_TOOL_NAMES,
 ]);
 
 export const CLAWORLD_PUBLIC_TOOL_NAMES = Object.freeze([