@xfxstudio/claworld 2026.7.9-testing.3 → 2026.7.13-testing.2

package/src/openclaw/plugin/register.js

@@ -27,9 +27,7 @@ import {
 import { resolveOpenClawWorkspaceRoot } from '../runtime/workspace-resolver.js';
 import {
   augmentConversationPayloadWithLocalTranscriptIndex,
-  CLAWORLD_TRANSCRIPT_REPORT_STYLE,
-  CLAWORLD_TRANSCRIPT_REPORT_TOOL_NAME,
-  renderClaworldTranscriptReport,
+  renderTranscriptReport,
 } from '../runtime/transcript-report.js';
 import { setClaworldRuntime } from './runtime.js';
 import { PUBLIC_TOOL_ACTION_CATALOG } from '../../product-shell/contracts/search-item.js';
@@ -63,6 +61,159 @@ import {
   withToolErrorBoundary,
 } from './register-tooling.js';
 
+function resolveShareCardToolResult(result) {
+  if (!Array.isArray(result?.content)) return null;
+  for (let index = 0; index < result.content.length; index += 1) {
+    const entry = result.content[index];
+    if (entry?.type !== 'text' || typeof entry.text !== 'string') continue;
+    try {
+      const payload = JSON.parse(entry.text);
+      const shareCard = normalizeObject(payload?.shareCard, null);
+      if (normalizeText(shareCard?.status, null) !== 'ready') continue;
+      const mediaUrl = normalizeText(
+        shareCard?.imageUrl,
+        normalizeText(shareCard?.downloadUrl, null),
+      );
+      if (!mediaUrl) continue;
+      return { index, entry, payload, shareCard, mediaUrl };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+async function deliverShareCardToCurrentChannel(api, result, toolContext = {}) {
+  const resolved = resolveShareCardToolResult(result);
+  if (!resolved) return result;
+
+  const route = toolContext?.deliveryContext || {};
+  const channel = normalizeText(route.channel, normalizeText(toolContext?.messageChannel, null));
+  const to = normalizeText(route.to, null);
+  if (!channel || !to) {
+    throw new Error('share-card delivery requires an active channel route');
+  }
+
+  const loadAdapter = api?.runtime?.channel?.outbound?.loadAdapter;
+  if (typeof loadAdapter !== 'function') {
+    throw new Error('share-card delivery requires the OpenClaw channel outbound runtime');
+  }
+  const adapter = await loadAdapter(channel);
+  if (typeof adapter?.sendMedia !== 'function') {
+    throw new Error(`share-card delivery is unavailable for channel ${channel}`);
+  }
+
+  const deliveryResult = await adapter.sendMedia({
+    cfg: toolContext?.getRuntimeConfig?.() || toolContext?.runtimeConfig || api.config,
+    to,
+    text: '',
+    mediaUrl: resolved.mediaUrl,
+    ...(normalizeText(route.accountId, null) ? { accountId: normalizeText(route.accountId, null) } : {}),
+    ...(route.threadId != null ? { threadId: route.threadId } : {}),
+  });
+  if (deliveryResult?.success === false) {
+    throw new Error(`share-card delivery failed on channel ${channel}`);
+  }
+  const deliveryKind = normalizeText(deliveryResult?.receipt?.kind, null)?.toLowerCase();
+  if (deliveryKind && !['image', 'media'].includes(deliveryKind)) {
+    throw new Error(`share-card delivery did not produce native media on channel ${channel}`);
+  }
+
+  const content = [...result.content];
+  content[resolved.index] = {
+    ...resolved.entry,
+    text: JSON.stringify({
+      ...resolved.payload,
+      shareCard: {
+        ...resolved.shareCard,
+        description: '分享卡图片已通过当前聊天渠道发送给用户。请只用一句普通文本确认分享卡已生成；不要下载、再次发送或输出 MEDIA:。',
+      },
+    }, null, 2),
+  };
+  return { ...result, content };
+}
+
+async function deliverTranscriptPagesToCurrentChannel(api, report, toolContext = {}) {
+  const pngPages = Array.isArray(report?.artifacts?.pngPages)
+    ? report.artifacts.pngPages.filter((page) => normalizeText(page?.path, null))
+    : [];
+  if (pngPages.length === 0) return report;
+
+  const route = toolContext?.deliveryContext || {};
+  const channel = normalizeText(route.channel, normalizeText(toolContext?.messageChannel, null));
+  const to = normalizeText(route.to, null);
+  if (!channel || !to || channel === 'claworld') {
+    return {
+      ...report,
+      delivery: {
+        status: 'media_refs_ready',
+        pageCount: pngPages.length,
+        description: 'PNG pages are ready. In Management Session, copy deliveryHint.primaryMediaBatch into the sessions_send report handoff for Main Session.',
+      },
+    };
+  }
+
+  const loadAdapter = api?.runtime?.channel?.outbound?.loadAdapter;
+  if (typeof loadAdapter !== 'function') {
+    throw new Error('transcript delivery requires the OpenClaw channel outbound runtime');
+  }
+  const adapter = await loadAdapter(channel);
+  if (typeof adapter?.sendMedia !== 'function') {
+    throw new Error(`transcript delivery is unavailable for channel ${channel}`);
+  }
+
+  const receipts = [];
+  for (const page of pngPages) {
+    const deliveryResult = await adapter.sendMedia({
+      cfg: toolContext?.getRuntimeConfig?.() || toolContext?.runtimeConfig || api.config,
+      to,
+      text: '',
+      mediaUrl: page.path,
+      ...(normalizeText(route.accountId, null) ? { accountId: normalizeText(route.accountId, null) } : {}),
+      ...(route.threadId != null ? { threadId: route.threadId } : {}),
+    });
+    if (deliveryResult?.success === false) {
+      throw new Error(`transcript page ${page.page} delivery failed on channel ${channel}`);
+    }
+    const deliveryKind = normalizeText(deliveryResult?.receipt?.kind, null)?.toLowerCase();
+    if (deliveryKind && !['image', 'media'].includes(deliveryKind)) {
+      throw new Error(`transcript page ${page.page} delivery did not produce native media on channel ${channel}`);
+    }
+    receipts.push({
+      page: page.page,
+      messageId: normalizeText(deliveryResult?.messageId, null),
+      kind: deliveryKind || 'media',
+    });
+  }
+  return {
+    ...report,
+    delivery: {
+      status: 'sent',
+      channel,
+      pageCount: receipts.length,
+      receipts,
+      description: 'All PNG transcript pages were sent through the current user-facing channel. Confirm delivery in ordinary text; do not output local paths, SVG, BubbleSpec, or MEDIA refs.',
+    },
+  };
+}
+
+async function resolveTranscriptWorkspace(api, params = {}, toolContext = {}) {
+  const cfg = await loadCurrentConfig(api);
+  const agentId = normalizeText(
+    toolContext?.agentId,
+    normalizeText(toolContext?.context?.agentId, normalizeText(params.agentId, null)),
+  );
+  return {
+    cfg,
+    agentId,
+    workspaceRoot: resolveOpenClawWorkspaceRoot({
+      sources: [toolContext, toolContext?.context, params],
+      config: cfg,
+      agentId,
+    }),
+  };
+}
+
 function buildClaworldStatusRoute(plugin) {
   return {
     method: 'GET',
@@ -481,118 +632,6 @@ 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)) {
@@ -698,7 +737,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 renderTranscriptTool = 'claworld_render_transcript_report';
   const accountTool = 'claworld_manage_account';
   const publicProfileTool = 'claworld_get_public_profile';
 
@@ -1456,7 +1495,7 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
           }),
         },
       }),
-      async execute(toolCallId, params = {}) {
+      async execute(toolCallId, params = {}, toolContext = {}) {
         const action = normalizeTerminalConversationAction(params.action, 'list_related', { throwOnInvalid: true });
         if (action === 'request') {
           const context = await resolveToolContext(api, plugin, params, {
@@ -1486,15 +1525,16 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
             action: 'list',
             ...(Object.keys(filters).length > 0 ? { filters } : {}),
           });
-          return augmentConversationToolResultWithTranscripts(
-            api,
-            plugin,
-            params,
+          const rewritten = rewriteToolResultName(result, manageConversationsTool, action);
+          const payload = parseToolResultPayload(rewritten);
+          if (!payload) return rewritten;
+          const { workspaceRoot } = await resolveTranscriptWorkspace(api, params, toolContext);
+          const augmented = await augmentConversationPayloadWithLocalTranscriptIndex({
+            workspaceRoot,
+            payload,
             filters,
-            result,
-            manageConversationsTool,
-            action,
-          );
+          });
+          return buildToolResult(augmented);
         }
         if (action === 'accept' || action === 'reject') {
           const result = await requireTerminalTool(internalTools, 'claworld_chat_inbox').execute(toolCallId, {
@@ -1526,30 +1566,97 @@ function createTerminalToolAdapters(api, plugin, internalTools) {
       },
     },
     {
-      name: transcriptReportTool,
+      name: renderTranscriptTool,
       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.',
+      description: 'Render one exact Claworld conversation episode or an agent-selected excerpt as the canonical Claworld comic-grid PNG transcript. Use mode=stored with stored.chatRequestId for a complete indexed episode. Stored reports recover public identities and world context from the indexed kickoff and accept optional human-readable header overrides. Use mode=manual for selected quotes, topic excerpts, highlights, or summaries. PNG is the normal user-visible deliverable; SVG and BubbleSpec are source/debug artifacts only.',
       metadata: buildToolMetadata({
-        category: 'transcript_report',
+        category: 'conversation',
         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.',
+          'Use stored.chatRequestId, never conversationKey or localSessionKey, to select a complete stored episode.',
+          'Keep request, conversation, session, and agent ids out of stored title/profile/speaker-label overrides.',
+          'For manual mode, provide only ordered visible peer/local messages and accurate createdAt timestamps.',
+          'Main Session calls send all PNG pages through the current user-facing channel when available.',
+          'Management Session calls return deliveryHint.primaryMediaBatch for inclusion in the sessions_send report handoff.',
         ],
       }),
-      parameters: buildTranscriptReportParameters(),
-      async execute(_toolCallId, params = {}) {
-        const { workspaceRoot, agentId } = await resolveLocalWorkspaceRootForTool(api, plugin, params);
-        const payload = await renderClaworldTranscriptReport({
+      parameters: objectParam({
+        description: 'Claworld transcript report render request.',
+        required: ['mode'],
+        properties: {
+          mode: stringParam({
+            description: 'stored renders one indexed local episode by chatRequestId; manual renders exactly manual.messages.',
+            enumValues: ['stored', 'manual'],
+          }),
+          stored: objectParam({
+            description: 'Stored episode selector. Provide only with mode=stored.',
+            required: ['chatRequestId'],
+            properties: {
+              chatRequestId: stringParam({
+                description: 'Canonical Claworld chat request / episode id.',
+                minLength: 1,
+              }),
+              title: stringParam({
+                description: 'Optional human-readable report title. Defaults to public peer/world context from the indexed kickoff.',
+                minLength: 1,
+              }),
+              peerProfile: stringParam({
+                description: 'Optional public subtitle/profile. Defaults to public peer identity and the applicable world/global profile.',
+                minLength: 1,
+              }),
+              localLabel: stringParam({
+                description: 'Optional public speaker label for local/right messages.',
+                minLength: 1,
+              }),
+              peerLabel: stringParam({
+                description: 'Optional public speaker label for peer/left messages.',
+                minLength: 1,
+              }),
+            },
+          }),
+          manual: objectParam({
+            description: 'Exact visible transcript rows and header context. Provide only with mode=manual.',
+            required: ['messages', 'title', 'peerProfile', 'localLabel', 'peerLabel'],
+            properties: {
+              messages: arrayParam({
+                description: 'Ordered visible transcript rows.',
+                items: objectParam({
+                  required: ['from', 'text', 'createdAt'],
+                  properties: {
+                    from: stringParam({ description: 'peer=left; local=right.', enumValues: ['peer', 'local'] }),
+                    text: stringParam({ description: 'Visible message text.', minLength: 1 }),
+                    createdAt: stringParam({ description: 'Message timestamp, preferably ISO 8601.', minLength: 1 }),
+                  },
+                }),
+              }),
+              title: stringParam({ description: 'Report header title.', minLength: 1 }),
+              peerProfile: stringParam({ description: 'Peer profile/header subtitle appropriate to direct or world scope.', minLength: 1 }),
+              localLabel: stringParam({ description: 'Speaker label for local/right messages.', minLength: 1 }),
+              peerLabel: stringParam({ description: 'Speaker label for peer/left messages.', minLength: 1 }),
+            },
+          }),
+          style: stringParam({
+            description: 'Optional visual style. Defaults to the Hermes-compatible Claworld comic grid.',
+            enumValues: ['claworld-comic-grid'],
+          }),
+          maxPageHeight: integerParam({
+            description: 'Maximum page height in pixels. Long transcripts paginate without truncation.',
+            minimum: 900,
+            maximum: 8000,
+          }),
+        },
+      }),
+      async execute(_toolCallId, params = {}, toolContext = {}) {
+        const { workspaceRoot, agentId } = await resolveTranscriptWorkspace(api, params, toolContext);
+        if (!workspaceRoot) {
+          throw new Error('unable to resolve the active OpenClaw workspace for transcript rendering');
+        }
+        const report = await renderTranscriptReport({
           workspaceRoot,
-          agentId,
-          args: stripTranscriptReportToolContextParams(params),
-        });
-        return buildToolResult({
-          ...payload,
-          tool: transcriptReportTool,
+          localAgentId: agentId,
+          args: params,
         });
+        const delivered = await deliverTranscriptPagesToCurrentChannel(api, report, toolContext);
+        return buildToolResult({ ...delivered, tool: renderTranscriptTool });
       },
     },
   ];
@@ -2595,11 +2702,40 @@ export function registerClaworldPluginFull(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);
+    for (const terminalTool of createTerminalToolAdapters(api, plugin, internalTools)) {
+      if (terminalTool.name === 'claworld_manage_account') {
+        api.registerTool(
+          (toolContext) => ({
+            ...terminalTool,
+            execute: withToolErrorBoundary(terminalTool.name, async (...args) => {
+              const result = await terminalTool.execute(...args);
+              return await deliverShareCardToCurrentChannel(api, result, toolContext);
+            }),
+          }),
+          { name: terminalTool.name },
+        );
+        continue;
+      }
+      if (
+        terminalTool.name === 'claworld_manage_conversations'
+        || terminalTool.name === 'claworld_render_transcript_report'
+      ) {
+        api.registerTool(
+          (toolContext) => ({
+            ...terminalTool,
+            execute: withToolErrorBoundary(
+              terminalTool.name,
+              async (...args) => await terminalTool.execute(...args, toolContext),
+            ),
+          }),
+          { name: terminalTool.name },
+        );
+        continue;
+      }
+      api.registerTool({
+        ...terminalTool,
+        execute: withToolErrorBoundary(terminalTool.name, terminalTool.execute),
+      });
     }
   }
   return plugin;

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

@@ -97,6 +97,8 @@ export function buildInboundEnvelope(message = {}) {
       'notification',
       'conversationKey',
       'worldId',
+      'chatRequestId',
+      'requestId',
     ]) {
       if (payload[key] == null && data[key] != null) payload[key] = data[key];
     }
@@ -134,6 +136,17 @@ export function buildInboundEnvelope(message = {}) {
     data.eventName,
     normalizeEnvelopeText(payload.eventName, isDeliveryEvent ? null : normalizeEnvelopeText(message.event, null)),
   );
+  const chatRequestId = [
+    data.chatRequestId,
+    data.requestId,
+    payload.chatRequestId,
+    payload.requestId,
+    metadata.kickoffRequestId,
+    metadata.chatRequestId,
+    metadata.requestId,
+    notification.chatRequestId,
+    notification.relatedObjects?.chatRequestId,
+  ].map((candidate) => normalizeEnvelopeText(candidate, null)).find(Boolean) || null;
   return {
     eventType: eventType || 'delivery',
     eventName,
@@ -141,6 +154,7 @@ export function buildInboundEnvelope(message = {}) {
     deliveryId,
     sessionKey,
     targetAgentId,
+    chatRequestId,
     conversationKey: normalizeEnvelopeText(
       data.conversationKey,
       normalizeEnvelopeText(payload.conversationKey, normalizeEnvelopeText(notification.relatedObjects?.conversationKey, null)),

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

@@ -15,18 +15,15 @@ export const CLAWORLD_WORLD_TOOL_NAMES = Object.freeze([
 
 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([