@xfxstudio/claworld 2026.7.7-testing.1 → 2026.7.9-testing.1

package/src/openclaw/runtime/transcript-report.js

@@ -0,0 +1,1309 @@
+import { execFile } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { deflateSync } from 'node:zlib';
+import { createRuntimeBoundaryError } from '../../lib/runtime-errors.js';
+import {
+  appendClaworldJournalEvent,
+  CLAWORLD_REPORTS_DIR,
+  CLAWORLD_WORKING_MEMORY_DIR,
+  ensureClaworldWorkingMemory,
+  readClaworldSessionDirectory,
+} from './working-memory.js';
+
+const execFileAsync = promisify(execFile);
+
+export const CLAWORLD_TRANSCRIPT_REPORT_TOOL_NAME = 'claworld_render_transcript_report';
+export const CLAWORLD_TRANSCRIPT_REPORT_STYLE = 'claworld-comic-grid';
+export const CLAWORLD_TRANSCRIPT_REPORT_STYLES = Object.freeze([
+  CLAWORLD_TRANSCRIPT_REPORT_STYLE,
+]);
+
+const DEFAULT_WIDTH = 720;
+const DEFAULT_MAX_PAGE_HEIGHT = 2600;
+const MIN_PAGE_HEIGHT = 900;
+const MAX_PAGE_HEIGHT = 8000;
+const TOP_LEVEL_RENDER_FIELDS = new Set(['mode', 'stored', 'manual', 'style', 'maxPageHeight']);
+const MANUAL_RENDER_FIELDS = new Set(['messages', 'title', 'peerProfile', 'localLabel', 'peerLabel']);
+const MANUAL_MESSAGE_FIELDS = new Set(['from', 'text', 'createdAt']);
+const TIME_SPLIT_SECONDS = 5 * 60;
+const SEGMENT_GAP_SECONDS = 4 * 60 * 60;
+const ARTIFACT_SCHEMA = 'claworld.transcript_report.v1';
+
+function isObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function inputError(field, message) {
+  throw createRuntimeBoundaryError({
+    code: 'tool_input_invalid',
+    category: 'input',
+    status: 400,
+    message,
+    publicMessage: message,
+    recoverable: true,
+    context: { field },
+  });
+}
+
+function assertObject(value, field) {
+  if (!isObject(value)) inputError(field, `${field} must be an object`);
+  return value;
+}
+
+function assertNoUnknownFields(value, allowedFields, field) {
+  const source = assertObject(value, field);
+  for (const key of Object.keys(source)) {
+    if (!allowedFields.has(key)) inputError(`${field}.${key}`, `${field}.${key} is not supported`);
+  }
+}
+
+function validateRenderArgs(args = {}) {
+  const params = assertObject(args, 'parameters');
+  assertNoUnknownFields(params, TOP_LEVEL_RENDER_FIELDS, 'parameters');
+  const mode = normalizeText(params.mode, null);
+  if (!mode) inputError('mode', 'mode is required');
+  if (!['stored', 'manual'].includes(mode)) inputError('mode', 'mode must be stored or manual');
+  const style = normalizeText(params.style, CLAWORLD_TRANSCRIPT_REPORT_STYLE);
+  if (!CLAWORLD_TRANSCRIPT_REPORT_STYLES.includes(style)) {
+    inputError('style', `style must be ${CLAWORLD_TRANSCRIPT_REPORT_STYLE}`);
+  }
+  const maxPageHeight = Number.isInteger(params.maxPageHeight)
+    ? params.maxPageHeight
+    : DEFAULT_MAX_PAGE_HEIGHT;
+  if (maxPageHeight < MIN_PAGE_HEIGHT || maxPageHeight > MAX_PAGE_HEIGHT) {
+    inputError('maxPageHeight', `maxPageHeight must be between ${MIN_PAGE_HEIGHT} and ${MAX_PAGE_HEIGHT}`);
+  }
+
+  if (mode === 'stored') {
+    const stored = assertObject(params.stored, 'stored');
+    assertNoUnknownFields(stored, new Set(['chatRequestId']), 'stored');
+    const chatRequestId = normalizeText(stored.chatRequestId, null);
+    if (!chatRequestId) inputError('stored.chatRequestId', 'stored.chatRequestId is required');
+    return { mode, style, maxPageHeight, stored: { chatRequestId } };
+  }
+
+  const manual = assertObject(params.manual, 'manual');
+  assertNoUnknownFields(manual, MANUAL_RENDER_FIELDS, 'manual');
+  for (const field of MANUAL_RENDER_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(manual, field)) {
+      inputError(`manual.${field}`, `manual.${field} is required`);
+    }
+  }
+  if (!Array.isArray(manual.messages) || manual.messages.length === 0) {
+    inputError('manual.messages', 'manual.messages must contain at least one message');
+  }
+  const messages = manual.messages.map((message, index) => {
+    if (!isObject(message)) inputError(`manual.messages.${index}`, 'manual message must be an object');
+    assertNoUnknownFields(message, MANUAL_MESSAGE_FIELDS, `manual.messages.${index}`);
+    const from = normalizeText(message.from, null);
+    if (!['peer', 'local'].includes(from)) {
+      inputError(`manual.messages.${index}.from`, 'manual message from must be peer or local');
+    }
+    const text = normalizeText(message.text, null);
+    if (!text) inputError(`manual.messages.${index}.text`, 'manual message text is required');
+    const createdAt = normalizeText(message.createdAt, null);
+    if (!createdAt) inputError(`manual.messages.${index}.createdAt`, 'manual message createdAt is required');
+    if (!parseTimestampMs(createdAt)) {
+      inputError(`manual.messages.${index}.createdAt`, 'manual message createdAt must be a parseable timestamp');
+    }
+    return { from, text, createdAt };
+  });
+  return {
+    mode,
+    style,
+    maxPageHeight,
+    manual: {
+      messages,
+      title: normalizeText(manual.title, null) || inputError('manual.title', 'manual.title is required'),
+      peerProfile: normalizeText(manual.peerProfile, null) || inputError('manual.peerProfile', 'manual.peerProfile is required'),
+      localLabel: normalizeText(manual.localLabel, null) || inputError('manual.localLabel', 'manual.localLabel is required'),
+      peerLabel: normalizeText(manual.peerLabel, null) || inputError('manual.peerLabel', 'manual.peerLabel is required'),
+    },
+  };
+}
+
+function resolveWorkspaceRoot(workspaceRoot = null) {
+  return path.resolve(normalizeText(workspaceRoot, null) || process.cwd());
+}
+
+function stableJson(value) {
+  return JSON.stringify(value, Object.keys(value || {}).sort());
+}
+
+function sha256Buffer(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+async function hashFile(filePath) {
+  return sha256Buffer(await fs.readFile(filePath));
+}
+
+function safeFileStem(value) {
+  const text = normalizeText(value, 'report') || 'report';
+  return text.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'report';
+}
+
+async function atomicWriteText(filePath, text) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await fs.writeFile(tempPath, text, 'utf8');
+  await fs.rename(tempPath, filePath);
+}
+
+async function atomicWriteBuffer(filePath, buffer) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await fs.writeFile(tempPath, buffer);
+  await fs.rename(tempPath, filePath);
+}
+
+function resolveArtifactDirs(workspaceRoot) {
+  const baseDir = path.join(
+    workspaceRoot,
+    CLAWORLD_WORKING_MEMORY_DIR,
+    CLAWORLD_REPORTS_DIR,
+    'transcripts',
+  );
+  return {
+    baseDir,
+    imageDir: path.join(baseDir, 'images'),
+    documentDir: path.join(baseDir, 'documents'),
+  };
+}
+
+function parseTimestampMs(value) {
+  if (value == null || value === '') return null;
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value > 1_000_000_000_000 ? Math.trunc(value) : Math.trunc(value * 1000);
+  }
+  const text = String(value).trim();
+  if (!text) return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return parseTimestampMs(Number(text));
+  const parsed = Date.parse(text);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function toIsoTimestamp(value) {
+  const ms = parseTimestampMs(value);
+  if (!ms) return null;
+  return new Date(ms).toISOString();
+}
+
+function formatTimestampLabel(value) {
+  const ms = parseTimestampMs(value);
+  if (!ms) return '';
+  const date = new Date(ms);
+  const pad = (part) => String(part).padStart(2, '0');
+  return [
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`,
+    `${pad(date.getHours())}:${pad(date.getMinutes())}`,
+  ].join(' ');
+}
+
+function flattenContent(value) {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    return value.map(flattenContent).filter(Boolean).join('\n');
+  }
+  if (isObject(value)) {
+    for (const key of ['text', 'input_text', 'output_text', 'content', 'body', 'message']) {
+      if (value[key] != null) {
+        const text = flattenContent(value[key]);
+        if (text) return text;
+      }
+    }
+    return '';
+  }
+  return String(value);
+}
+
+function extractFencedBlockAfter(text, marker) {
+  const source = String(text || '');
+  const index = source.indexOf(marker);
+  if (index < 0) return null;
+  const afterMarker = source.slice(index + marker.length).trimStart();
+  const fenceMatch = afterMarker.match(/^```[^\n]*\n([\s\S]*?)\n```/);
+  if (fenceMatch) return fenceMatch[1].trim();
+  const nextSection = afterMarker.search(/\n(?:Routing metadata|Backend-authored Claworld|Relay untrusted context|Claworld live conversation rules):/);
+  return (nextSection >= 0 ? afterMarker.slice(0, nextSection) : afterMarker).trim();
+}
+
+function stripInternalEnvelopeSections(text) {
+  let output = String(text || '');
+  const markers = [
+    'Routing metadata:',
+    'Backend-authored Claworld context:',
+    'Backend-authored Claworld command:',
+    'Relay untrusted context:',
+    'Claworld live conversation rules:',
+  ];
+  for (const marker of markers) {
+    const index = output.indexOf(marker);
+    if (index >= 0) output = output.slice(0, index);
+  }
+  output = output.replace(/```[a-zA-Z0-9_-]*\n([\s\S]*?)\n```/g, '$1');
+  return output.trim();
+}
+
+function stripOpenClawSpeakerPrefix(text) {
+  const source = String(text || '').trim();
+  const match = source.match(/^([^\n:]{1,80}):\s+([\s\S]+)$/);
+  if (!match) return { text: source, speaker: null };
+  const label = match[1].trim();
+  if (/^(https?|file|data)$/i.test(label)) return { text: source, speaker: null };
+  return { text: match[2].trim(), speaker: label };
+}
+
+function redactSensitiveText(text) {
+  let output = String(text || '');
+  output = output.replace(
+    /\bauthorization\b\s*[:=]\s*(?:bearer\s+)?`?[^`\s,;]+`?/gi,
+    'authorization=[REDACTED]',
+  );
+  output = output.replace(
+    /\b(api[_-]?key|app[_-]?token|access[_-]?token|refresh[_-]?token|secret|password)\b\s*[:=]\s*`?[^`\s,;]+`?/gi,
+    '$1=[REDACTED]',
+  );
+  output = output.replace(/\bbearer\s+[a-zA-Z0-9._~+/=-]{12,}/gi, 'bearer [REDACTED]');
+  output = output.replace(/\bsk-[a-zA-Z0-9_-]{12,}\b/g, '[REDACTED_TOKEN]');
+  output = output.replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '[REDACTED_EMAIL]');
+  output = output.replace(/\+?\d[\d ()-]{8,}\d/g, '[REDACTED_PHONE]');
+  return output.trim();
+}
+
+function normalizeTagLabel(value) {
+  const tag = normalizeText(value, null);
+  if (!tag) return null;
+  const compact = tag.toLowerCase().replace(/\s+/g, '_');
+  if (compact === 'request_conversation_end' || compact === 'request_end' || compact === 'end') {
+    return 'request end';
+  }
+  if (compact === 'like') return 'like';
+  if (compact === 'dislike') return 'dislike';
+  return tag.replace(/_/g, ' ').trim().toLowerCase();
+}
+
+function extractControlTags(text) {
+  const tags = [];
+  const cleaned = String(text || '').replace(/\[\[([a-zA-Z0-9_\-\s]+)\]\]|\[([a-zA-Z0-9_\-\s]+)\]/g, (match, doubleTag, singleTag) => {
+    const label = normalizeTagLabel(doubleTag || singleTag);
+    if (label) tags.push(label);
+    return '';
+  });
+  return {
+    text: cleaned.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim(),
+    tags: [...new Set(tags)],
+  };
+}
+
+function extractEpisodeIds(...values) {
+  const ids = new Set();
+  const source = values.map((value) => String(value || '')).join('\n');
+  const patterns = [
+    /(?:Chat Request ID|chatRequestId|requestId|Intent ID|intentId)\s*[:=]\s*`?([a-zA-Z0-9._:-]+)/gi,
+    /\b(?:chatRequestId|requestId|intentId)\b["']?\s*[:=]\s*["']?([a-zA-Z0-9._:-]+)/gi,
+  ];
+  for (const pattern of patterns) {
+    for (const match of source.matchAll(pattern)) {
+      const id = normalizeText(match[1], null);
+      if (id) ids.add(id.replace(/[`,.;)\]}]+$/g, ''));
+    }
+  }
+  return [...ids];
+}
+
+function getMessageText(record) {
+  if (record?.text != null) return flattenContent(record.text);
+  if (record?.body != null) return flattenContent(record.body);
+  if (record?.content != null) return flattenContent(record.content);
+  if (record?.message?.content != null) return flattenContent(record.message.content);
+  if (record?.payload?.content != null) return flattenContent(record.payload.content);
+  return '';
+}
+
+function getMessageRole(record) {
+  return normalizeText(
+    record?.role
+      ?? record?.from
+      ?? record?.message?.role
+      ?? record?.payload?.role,
+    null,
+  );
+}
+
+function getMessageTimestamp(record) {
+  return record?.createdAt
+    ?? record?.created_at
+    ?? record?.timestamp
+    ?? record?.message?.createdAt
+    ?? record?.message?.timestamp
+    ?? record?.payload?.createdAt
+    ?? record?.payload?.timestamp
+    ?? record?.__openclaw?.recordTimestampMs
+    ?? record?.__openclaw?.recordTimestamp
+    ?? null;
+}
+
+function normalizeManualMessage(raw, index) {
+  const tagsResult = extractControlTags(raw.text);
+  return {
+    id: `manual-${index + 1}`,
+    side: raw.from === 'peer' ? 'peer' : 'local',
+    speaker: null,
+    text: redactSensitiveText(tagsResult.text),
+    tags: tagsResult.tags,
+    createdAt: toIsoTimestamp(raw.createdAt),
+    createdAtLabel: formatTimestampLabel(raw.createdAt),
+    timestampMs: parseTimestampMs(raw.createdAt),
+    episodeIds: [],
+    sourceRole: raw.from,
+  };
+}
+
+function normalizeStoredMessage(record, index) {
+  const role = getMessageRole(record);
+  if (['system', 'developer', 'tool', 'tool_call'].includes(role)) return null;
+
+  const side = role === 'assistant' || role === 'local' || role === 'me' || role === 'right'
+    ? 'local'
+    : 'peer';
+  let text = getMessageText(record);
+  const rawText = text;
+  const episodeIds = extractEpisodeIds(
+    rawText,
+    record?.id,
+    record?.message?.id,
+    record?.__openclaw?.id,
+  );
+
+  if (side === 'peer') {
+    const peerVisible = extractFencedBlockAfter(text, 'Peer-visible Claworld message:');
+    const hasBackendCommand = text.includes('Backend-authored Claworld command:');
+    if (peerVisible != null) {
+      text = peerVisible;
+    } else if (hasBackendCommand) {
+      return null;
+    } else {
+      text = stripInternalEnvelopeSections(text);
+    }
+  } else {
+    text = stripInternalEnvelopeSections(text);
+    if (/^NO_REPLY$/i.test(text.trim())) return null;
+  }
+
+  const speakerResult = side === 'peer' ? stripOpenClawSpeakerPrefix(text) : { text: text.trim(), speaker: null };
+  const tagsResult = extractControlTags(speakerResult.text);
+  const redactedText = redactSensitiveText(tagsResult.text);
+  if (!redactedText && tagsResult.tags.length === 0) return null;
+  const timestamp = getMessageTimestamp(record) || new Date(0).toISOString();
+  return {
+    id: normalizeText(record?.id ?? record?.message?.id ?? record?.__openclaw?.id, `message-${index + 1}`),
+    side,
+    speaker: speakerResult.speaker,
+    text: redactedText,
+    tags: tagsResult.tags,
+    createdAt: toIsoTimestamp(timestamp),
+    createdAtLabel: formatTimestampLabel(timestamp),
+    timestampMs: parseTimestampMs(timestamp) || 0,
+    episodeIds,
+    sourceRole: role,
+  };
+}
+
+function normalizeTranscriptMessages(records, { mode } = {}) {
+  const messages = records
+    .map((record, index) => (
+      mode === 'manual'
+        ? normalizeManualMessage(record, index)
+        : normalizeStoredMessage(record, index)
+    ))
+    .filter(Boolean)
+    .filter((message) => message.text || message.tags.length > 0)
+    .sort((left, right) => (left.timestampMs || 0) - (right.timestampMs || 0));
+  return messages;
+}
+
+function episodeSetsIntersect(left = [], right = []) {
+  if (!left.length || !right.length) return true;
+  const rightSet = new Set(right);
+  return left.some((id) => rightSet.has(id));
+}
+
+function segmentTranscriptMessages(messages = []) {
+  const segments = [];
+  let current = null;
+  for (const message of messages) {
+    const previous = current?.messages?.[current.messages.length - 1] || null;
+    const gapSeconds = previous && message.timestampMs && previous.timestampMs
+      ? Math.abs(message.timestampMs - previous.timestampMs) / 1000
+      : 0;
+    const currentEpisodeIds = current ? [...current.episodeIds] : [];
+    const startsNewEpisode = current
+      && message.episodeIds.length > 0
+      && currentEpisodeIds.length > 0
+      && !episodeSetsIntersect(message.episodeIds, currentEpisodeIds);
+    const startsAfterCompletion = previous
+      && current?.endedSides?.size >= 2
+      && message.side === 'peer';
+    if (!current || gapSeconds > SEGMENT_GAP_SECONDS || startsNewEpisode || startsAfterCompletion) {
+      current = {
+        messages: [],
+        episodeIds: new Set(),
+        endedSides: new Set(),
+      };
+      segments.push(current);
+    }
+    current.messages.push(message);
+    for (const id of message.episodeIds) current.episodeIds.add(id);
+    if (message.tags.includes('request end')) current.endedSides.add(message.side);
+  }
+  return segments;
+}
+
+function selectStoredMessages(messages, chatRequestId) {
+  const targetId = normalizeText(chatRequestId, null);
+  if (!targetId) return messages;
+  const segments = segmentTranscriptMessages(messages);
+  const segment = segments.find((candidate) => candidate.episodeIds.has(targetId));
+  if (segment) return segment.messages;
+  const tagged = messages.filter((message) => message.episodeIds.includes(targetId));
+  return tagged.length > 0 ? tagged : messages;
+}
+
+function parseJsonLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    return isObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractTranscriptRecordsFromJson(value, fallbackId = 'json') {
+  if (Array.isArray(value)) return value;
+  if (!isObject(value)) return [];
+  for (const key of ['entries', 'records', 'messages', 'items', 'transcript']) {
+    if (Array.isArray(value[key])) return value[key];
+  }
+  if (Array.isArray(value.conversation?.messages)) return value.conversation.messages;
+  if (Array.isArray(value.session?.messages)) return value.session.messages;
+  if (isObject(value.message) || value.role || value.content || value.text) {
+    return [{ ...value, id: value.id ?? fallbackId }];
+  }
+  return [];
+}
+
+async function loadTranscriptRecords(transcriptPath) {
+  const content = await fs.readFile(transcriptPath, 'utf8');
+  const trimmed = content.trim();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      return extractTranscriptRecordsFromJson(JSON.parse(trimmed), path.basename(transcriptPath));
+    } catch {
+      // Fall back to line-oriented parsing below.
+    }
+  }
+  const records = [];
+  let index = 0;
+  for (const line of content.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    index += 1;
+    const parsed = parseJsonLine(line);
+    if (!parsed) continue;
+    if (isObject(parsed.message)) {
+      records.push({
+        ...parsed.message,
+        id: parsed.message.id ?? parsed.id ?? `line-${index}`,
+        timestamp: parsed.message.timestamp ?? parsed.timestamp ?? parsed.createdAt ?? null,
+        __openclaw: {
+          id: parsed.id ?? null,
+          recordTimestamp: parsed.timestamp ?? null,
+          seq: index,
+        },
+      });
+      continue;
+    }
+    if (parsed.type === 'response_item' && isObject(parsed.payload) && parsed.payload.type === 'message') {
+      records.push({
+        ...parsed.payload,
+        id: parsed.payload.id ?? parsed.id ?? `line-${index}`,
+        timestamp: parsed.payload.timestamp ?? parsed.timestamp ?? null,
+        __openclaw: {
+          id: parsed.id ?? null,
+          recordTimestamp: parsed.timestamp ?? null,
+          seq: index,
+        },
+      });
+      continue;
+    }
+    if (parsed.type === 'message' || parsed.role || parsed.content || parsed.text) {
+      records.push({
+        ...parsed,
+        id: parsed.id ?? `line-${index}`,
+        timestamp: parsed.timestamp ?? parsed.createdAt ?? null,
+        __openclaw: {
+          id: parsed.id ?? null,
+          recordTimestamp: parsed.timestamp ?? null,
+          seq: index,
+        },
+      });
+    }
+  }
+  return records;
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function artifactPathCandidates(artifact = {}) {
+  return [
+    normalizeText(artifact.transcriptPath, null),
+    normalizeText(artifact.sessionFile, null),
+  ].filter(Boolean);
+}
+
+async function chooseReadableArtifact(artifacts = []) {
+  const ordered = [...artifacts].reverse();
+  for (const artifact of ordered) {
+    for (const candidatePath of artifactPathCandidates(artifact)) {
+      if (await pathExists(candidatePath)) {
+        return {
+          artifact,
+          transcriptPath: candidatePath,
+        };
+      }
+    }
+  }
+  const fallback = ordered.find((artifact) => artifactPathCandidates(artifact).length > 0);
+  if (!fallback) return null;
+  return {
+    artifact: fallback,
+    transcriptPath: artifactPathCandidates(fallback)[0],
+  };
+}
+
+function summarizeDirectoryRequest({
+  chatRequestId,
+  localSessionKey,
+  session = {},
+  request = {},
+  artifact = {},
+  transcriptPath = null,
+} = {}) {
+  return {
+    chatRequestId,
+    localSessionKey,
+    relaySessionKey: normalizeText(session.relaySessionKey, null),
+    conversationKey: normalizeText(session.conversationKey, null),
+    worldId: normalizeText(session.worldId, null),
+    localAgentId: normalizeText(session.localAgentId, null),
+    firstSeenAt: normalizeText(request.firstSeenAt, null),
+    lastSeenAt: normalizeText(request.lastSeenAt, null),
+    artifactCount: Array.isArray(request.artifacts) ? request.artifacts.length : 0,
+    sessionId: normalizeText(artifact.sessionId, null),
+    sessionFile: normalizeText(artifact.sessionFile, null),
+    transcriptPath: normalizeText(transcriptPath || artifact.transcriptPath, null),
+    deliveryId: normalizeText(artifact.deliveryId, null),
+    sourceEventId: normalizeText(artifact.sourceEventId, null),
+  };
+}
+
+async function resolveStoredTranscriptSource(workspaceRoot, chatRequestId) {
+  const sessionDirectory = await readClaworldSessionDirectory(workspaceRoot);
+  const conversationSessions = sessionDirectory.directory?.conversationSessions || {};
+  for (const [localSessionKey, session] of Object.entries(conversationSessions)) {
+    const request = session?.chatRequests?.[chatRequestId];
+    if (!request) continue;
+    const artifacts = Array.isArray(request.artifacts) ? request.artifacts : [];
+    const readable = await chooseReadableArtifact(artifacts);
+    if (!readable?.transcriptPath) {
+      inputError('stored.chatRequestId', `No local transcript artifact is indexed for chatRequestId=${chatRequestId}`);
+    }
+    return {
+      mode: 'stored',
+      chatRequestId,
+      transcriptPath: readable.transcriptPath,
+      sessionDirectoryPath: sessionDirectory.sessionDirectoryPath,
+      summary: summarizeDirectoryRequest({
+        chatRequestId,
+        localSessionKey,
+        session,
+        request,
+        artifact: readable.artifact,
+        transcriptPath: readable.transcriptPath,
+      }),
+    };
+  }
+  inputError('stored.chatRequestId', `chatRequestId=${chatRequestId} was not found in .claworld/sessions/index.json`);
+}
+
+function normalizeHeaderContext({ mode, manual = null, source = null, messages = [] } = {}) {
+  if (mode === 'manual') {
+    return {
+      title: manual.title,
+      subtitle: manual.peerProfile,
+      peerLabel: manual.peerLabel,
+      localLabel: manual.localLabel,
+    };
+  }
+  const firstPeer = messages.find((message) => message.side === 'peer');
+  const peerLabel = firstPeer?.speaker
+    || normalizeText(source?.summary?.counterpartyAgentId, null)
+    || normalizeText(source?.summary?.relaySessionKey, null)
+    || 'Peer';
+  const title = normalizeText(firstPeer?.speaker, null)
+    || normalizeText(source?.summary?.conversationKey, null)
+    || normalizeText(source?.chatRequestId, null)
+    || 'Claworld conversation';
+  const subtitleParts = [
+    normalizeText(source?.summary?.worldId, null) ? `world ${source.summary.worldId}` : null,
+    normalizeText(source?.chatRequestId, null) ? `chat request ${source.chatRequestId}` : null,
+  ].filter(Boolean);
+  return {
+    title,
+    subtitle: subtitleParts.join(' · ') || 'Claworld transcript',
+    peerLabel,
+    localLabel: 'You',
+  };
+}
+
+function displayColumns(text) {
+  let columns = 0;
+  for (const char of String(text || '')) {
+    const code = char.codePointAt(0);
+    columns += code > 0x2e80 ? 2 : 1;
+  }
+  return columns;
+}
+
+function wrapText(text, maxColumns) {
+  const source = String(text || '').replace(/\r/g, '').split('\n');
+  const lines = [];
+  for (const paragraph of source) {
+    let current = '';
+    let columns = 0;
+    const words = paragraph.includes(' ') ? paragraph.split(/(\s+)/) : [...paragraph];
+    for (const word of words) {
+      const wordColumns = displayColumns(word);
+      if (current && columns + wordColumns > maxColumns) {
+        lines.push(current.trimEnd());
+        current = '';
+        columns = 0;
+      }
+      current += word;
+      columns += wordColumns;
+    }
+    if (current) lines.push(current.trimEnd());
+    if (!paragraph) lines.push('');
+  }
+  return lines.length > 0 ? lines : [''];
+}
+
+function timeLabelForMessage(message) {
+  return message.createdAtLabel || formatTimestampLabel(message.createdAt);
+}
+
+function buildRenderItems(messages = []) {
+  const items = [];
+  let previousMessage = null;
+  for (const message of messages) {
+    const gapSeconds = previousMessage && message.timestampMs && previousMessage.timestampMs
+      ? Math.abs(message.timestampMs - previousMessage.timestampMs) / 1000
+      : Number.POSITIVE_INFINITY;
+    if (!previousMessage || gapSeconds > TIME_SPLIT_SECONDS) {
+      items.push({
+        kind: 'time',
+        label: timeLabelForMessage(message),
+      });
+    }
+    items.push({
+      kind: 'message',
+      message,
+    });
+    previousMessage = message;
+  }
+  return items;
+}
+
+function estimateMessageLayout(message) {
+  const maxColumns = message.side === 'local' ? 42 : 40;
+  const lines = wrapText(message.text, maxColumns);
+  const tagRows = message.tags.length > 0 ? 1 : 0;
+  const textWidth = Math.min(
+    440,
+    Math.max(160, Math.max(...lines.map(displayColumns), 10) * 8 + 34),
+  );
+  const height = 24 + lines.length * 20 + tagRows * 25;
+  return {
+    lines,
+    width: textWidth,
+    height,
+  };
+}
+
+function layoutPages({ messages, header, maxPageHeight }) {
+  const width = DEFAULT_WIDTH;
+  const maxHeight = maxPageHeight || DEFAULT_MAX_PAGE_HEIGHT;
+  const margin = 32;
+  const headerHeight = 102;
+  const bottomMargin = 32;
+  const pages = [];
+  let page = {
+    page: 1,
+    width,
+    height: Math.min(maxHeight, Math.max(MIN_PAGE_HEIGHT, headerHeight + bottomMargin)),
+    elements: [],
+  };
+  let y = headerHeight;
+
+  const pushPage = () => {
+    page.height = Math.min(maxHeight, Math.max(MIN_PAGE_HEIGHT, Math.ceil(y + bottomMargin)));
+    pages.push(page);
+    page = {
+      page: pages.length + 1,
+      width,
+      height: MIN_PAGE_HEIGHT,
+      elements: [],
+    };
+    y = 82;
+  };
+
+  for (const item of buildRenderItems(messages)) {
+    if (item.kind === 'time') {
+      const height = 28;
+      if (y + height + bottomMargin > maxHeight && page.elements.length > 0) pushPage();
+      page.elements.push({ ...item, x: margin, y, width: width - margin * 2, height });
+      y += height;
+      continue;
+    }
+    const messageLayout = estimateMessageLayout(item.message);
+    const height = messageLayout.height + 10;
+    if (y + height + bottomMargin > maxHeight && page.elements.length > 0) pushPage();
+    const x = item.message.side === 'local'
+      ? width - margin - messageLayout.width
+      : margin;
+    page.elements.push({
+      kind: 'message',
+      message: item.message,
+      layout: messageLayout,
+      x,
+      y,
+      width: messageLayout.width,
+      height: messageLayout.height,
+    });
+    y += height;
+  }
+  page.height = Math.min(maxHeight, Math.max(MIN_PAGE_HEIGHT, Math.ceil(y + bottomMargin)));
+  pages.push(page);
+  return {
+    width,
+    header,
+    pages,
+  };
+}
+
+function escapeXml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function renderSvgPage({ page, header, pageCount }) {
+  const pageTitle = page.page === 1 ? header.title : `${header.title} (continued)`;
+  const subtitle = page.page === 1 ? header.subtitle : `Page ${page.page} of ${pageCount}`;
+  const parts = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${page.width}" height="${page.height}" viewBox="0 0 ${page.width} ${page.height}" role="img" aria-label="${escapeXml(pageTitle)}">`,
+    '<style>',
+    '.bg{fill:#fbf7ef}.panel{fill:#fffdf8;stroke:#222;stroke-width:2}.title{font:700 26px Arial,sans-serif;fill:#161616}.subtitle{font:14px Arial,sans-serif;fill:#5f5b52}.label{font:700 12px Arial,sans-serif;fill:#666}.bubblePeer{fill:#ffffff;stroke:#222;stroke-width:2}.bubbleLocal{fill:#dff3e5;stroke:#1d3b29;stroke-width:2}.msg{font:15px Arial,sans-serif;fill:#171717}.time{font:12px Arial,sans-serif;fill:#736d63}.tag{font:700 11px Arial,sans-serif;fill:#161616}.tagBox{fill:#f6cf4f;stroke:#222;stroke-width:1}.tagEnd{fill:#f0b4a8}.tagLike{fill:#b9e3ff}.tagDislike{fill:#ddd}.shadow{fill:#222;opacity:.16}',
+    '</style>',
+    `<rect class="bg" x="0" y="0" width="${page.width}" height="${page.height}"/>`,
+    `<rect class="panel" x="22" y="18" width="${page.width - 44}" height="${page.height - 36}" rx="18"/>`,
+    `<text class="title" x="42" y="56">${escapeXml(pageTitle)}</text>`,
+    `<text class="subtitle" x="42" y="80">${escapeXml(subtitle || 'Claworld transcript')}</text>`,
+  ];
+
+  for (const element of page.elements) {
+    if (element.kind === 'time') {
+      parts.push(`<text class="time" x="${page.width / 2}" y="${element.y + 18}" text-anchor="middle">${escapeXml(element.label)}</text>`);
+      continue;
+    }
+    const { message, layout, x, y, width, height } = element;
+    const bubbleClass = message.side === 'local' ? 'bubbleLocal' : 'bubblePeer';
+    const label = message.side === 'local' ? header.localLabel : (message.speaker || header.peerLabel);
+    parts.push(`<text class="label" x="${x}" y="${y + 10}">${escapeXml(label)}</text>`);
+    parts.push(`<rect class="shadow" x="${x + 4}" y="${y + 18}" width="${width}" height="${height}" rx="16"/>`);
+    parts.push(`<rect class="${bubbleClass}" x="${x}" y="${y + 14}" width="${width}" height="${height}" rx="16"/>`);
+    const textX = x + 17;
+    let textY = y + 40;
+    parts.push(`<text class="msg" x="${textX}" y="${textY}">`);
+    for (const [index, line] of layout.lines.entries()) {
+      parts.push(`<tspan x="${textX}" dy="${index === 0 ? 0 : 20}">${escapeXml(line)}</tspan>`);
+    }
+    parts.push('</text>');
+    textY += layout.lines.length * 20 + 4;
+    let tagX = textX;
+    for (const tag of message.tags) {
+      const tagWidth = Math.max(48, displayColumns(tag) * 7 + 24);
+      const className = tag === 'request end'
+        ? 'tagEnd'
+        : tag === 'like'
+          ? 'tagLike'
+          : tag === 'dislike'
+            ? 'tagDislike'
+            : 'tagBox';
+      parts.push(`<rect class="${className}" x="${tagX}" y="${textY}" width="${tagWidth}" height="18" rx="9"/>`);
+      parts.push(`<text class="tag" x="${tagX + 12}" y="${textY + 13}">${escapeXml(tag)}</text>`);
+      tagX += tagWidth + 6;
+    }
+  }
+  parts.push('</svg>');
+  return parts.join('\n');
+}
+
+function buildBubbleSpec({ mode, source, header, messages, layout, style }) {
+  return {
+    schema: ARTIFACT_SCHEMA,
+    format: 'bubblespec',
+    style,
+    width: layout.width,
+    mode,
+    chatRequestId: source?.chatRequestId || null,
+    source: {
+      mode,
+      transcriptPath: source?.transcriptPath || null,
+      sessionDirectoryPath: source?.sessionDirectoryPath || null,
+      summary: source?.summary || null,
+    },
+    header,
+    messages: messages.map((message) => ({
+      id: message.id,
+      side: message.side,
+      speaker: message.speaker,
+      text: message.text,
+      tags: message.tags,
+      createdAt: message.createdAt,
+      episodeIds: message.episodeIds,
+    })),
+    pages: layout.pages.map((page) => ({
+      page: page.page,
+      width: page.width,
+      height: page.height,
+      elementCount: page.elements.length,
+    })),
+  };
+}
+
+function makeCrcTable() {
+  const table = [];
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) {
+      c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    table[n] = c >>> 0;
+  }
+  return table;
+}
+
+const CRC_TABLE = makeCrcTable();
+
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (const byte of buffer) {
+    crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data = Buffer.alloc(0)) {
+  const typeBuffer = Buffer.from(type, 'ascii');
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const crcBuffer = Buffer.alloc(4);
+  crcBuffer.writeUInt32BE(crc32(Buffer.concat([typeBuffer, data])), 0);
+  return Buffer.concat([length, typeBuffer, data, crcBuffer]);
+}
+
+function writeRect(rgba, width, x, y, rectWidth, rectHeight, color) {
+  const [r, g, b, a] = color;
+  const left = Math.max(0, Math.floor(x));
+  const top = Math.max(0, Math.floor(y));
+  const right = Math.min(width, Math.ceil(x + rectWidth));
+  const bottom = Math.min(Math.floor(rgba.length / (width * 4)), Math.ceil(y + rectHeight));
+  for (let row = top; row < bottom; row += 1) {
+    for (let col = left; col < right; col += 1) {
+      const offset = (row * width + col) * 4;
+      rgba[offset] = r;
+      rgba[offset + 1] = g;
+      rgba[offset + 2] = b;
+      rgba[offset + 3] = a;
+    }
+  }
+}
+
+function buildFallbackPngBuffer(page) {
+  const width = page.width;
+  const height = page.height;
+  const rgba = Buffer.alloc(width * height * 4, 255);
+  writeRect(rgba, width, 0, 0, width, height, [251, 247, 239, 255]);
+  writeRect(rgba, width, 22, 18, width - 44, height - 36, [255, 253, 248, 255]);
+  writeRect(rgba, width, 40, 38, width - 80, 18, [22, 22, 22, 255]);
+  writeRect(rgba, width, 40, 68, width - 180, 10, [120, 112, 100, 255]);
+  for (const element of page.elements) {
+    if (element.kind !== 'message') continue;
+    const color = element.message.side === 'local' ? [223, 243, 229, 255] : [255, 255, 255, 255];
+    writeRect(rgba, width, element.x, element.y + 14, element.width, element.height, color);
+    writeRect(rgba, width, element.x + 16, element.y + 36, element.width - 32, 5, [45, 45, 45, 255]);
+    writeRect(rgba, width, element.x + 16, element.y + 54, Math.max(60, element.width - 90), 5, [80, 80, 80, 255]);
+  }
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  for (let row = 0; row < height; row += 1) {
+    const rawOffset = row * (width * 4 + 1);
+    raw[rawOffset] = 0;
+    rgba.copy(raw, rawOffset + 1, row * width * 4, (row + 1) * width * 4);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('IDAT', deflateSync(raw)),
+    pngChunk('IEND'),
+  ]);
+}
+
+async function tryConvertSvgToPng(svgPath, pngPath, page) {
+  const attempts = [
+    { renderer: 'rsvg-convert', cmd: 'rsvg-convert', args: ['--format', 'png', '--output', pngPath, svgPath] },
+    { renderer: 'resvg', cmd: 'resvg', args: [svgPath, pngPath] },
+    { renderer: 'magick', cmd: 'magick', args: [svgPath, pngPath] },
+    { renderer: 'convert', cmd: 'convert', args: [svgPath, pngPath] },
+    { renderer: 'sips', cmd: 'sips', args: ['-s', 'format', 'png', svgPath, '--out', pngPath] },
+  ];
+  for (const attempt of attempts) {
+    try {
+      await execFileAsync(attempt.cmd, attempt.args, { timeout: 15000, maxBuffer: 2 * 1024 * 1024 });
+      const stat = await fs.stat(pngPath);
+      if (stat.size > 64) return attempt.renderer;
+    } catch {
+      // Continue to the next local renderer.
+    }
+  }
+  await atomicWriteBuffer(pngPath, buildFallbackPngBuffer(page));
+  return 'fallback-png';
+}
+
+async function writeArtifacts({ workspaceRoot, artifactId, spec, layout }) {
+  const dirs = resolveArtifactDirs(workspaceRoot);
+  await fs.mkdir(dirs.imageDir, { recursive: true });
+  await fs.mkdir(dirs.documentDir, { recursive: true });
+  const bubbleSpecPath = path.join(dirs.documentDir, `${artifactId}.bubblespec.json`);
+  await atomicWriteText(bubbleSpecPath, `${JSON.stringify(spec, null, 2)}\n`);
+  const svgPages = [];
+  const pngPages = [];
+  for (const page of layout.pages) {
+    const pageStem = `${artifactId}-page-${String(page.page).padStart(2, '0')}`;
+    const svgPath = path.join(dirs.documentDir, `${pageStem}.svg`);
+    const pngPath = path.join(dirs.imageDir, `${pageStem}.png`);
+    await atomicWriteText(svgPath, renderSvgPage({ page, header: layout.header, pageCount: layout.pages.length }));
+    const renderer = await tryConvertSvgToPng(svgPath, pngPath, page);
+    svgPages.push({
+      page: page.page,
+      format: 'svg',
+      path: svgPath,
+      width: page.width,
+      height: page.height,
+      sha256: await hashFile(svgPath),
+    });
+    pngPages.push({
+      page: page.page,
+      format: 'png',
+      path: pngPath,
+      width: page.width,
+      height: page.height,
+      renderer,
+      sha256: await hashFile(pngPath),
+      mediaRef: `MEDIA:${pngPath}`,
+    });
+  }
+  return {
+    bubbleSpec: {
+      format: 'bubblespec',
+      path: bubbleSpecPath,
+      sha256: await hashFile(bubbleSpecPath),
+    },
+    svgPages,
+    pngPages,
+  };
+}
+
+function buildDiagnostics({ sourceRecords, normalizedMessages, renderedMessages, source }) {
+  return {
+    source: {
+      mode: source.mode,
+      transcriptPath: source.transcriptPath || null,
+      sessionDirectoryPath: source.sessionDirectoryPath || null,
+    },
+    stats: {
+      sourceMessages: sourceRecords.length,
+      normalizedMessages: normalizedMessages.length,
+      renderedMessages: renderedMessages.length,
+      droppedMessages: Math.max(0, sourceRecords.length - normalizedMessages.length),
+    },
+  };
+}
+
+async function appendRenderJournalEvent(workspaceRoot, result) {
+  try {
+    await appendClaworldJournalEvent(workspaceRoot, {
+      source: 'claworld_runtime',
+      kind: 'transcript_report',
+      scope: 'conversation',
+      summary: `Rendered Claworld transcript report ${result.artifactId}.`,
+      refs: {
+        chatRequestId: result.chatRequestId || null,
+        artifactId: result.artifactId,
+      },
+      artifacts: {
+        bubbleSpec: result.artifacts?.bubbleSpec?.path || null,
+        pngPages: (result.artifacts?.pngPages || []).map((page) => page.path),
+        svgPages: (result.artifacts?.svgPages || []).map((page) => page.path),
+      },
+    }, { updateSessionDirectory: false });
+  } catch {
+    // Rendering should not fail because the journal is unavailable.
+  }
+}
+
+export async function renderClaworldTranscriptReport({
+  workspaceRoot = null,
+  agentId = null,
+  args = {},
+} = {}) {
+  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
+  await ensureClaworldWorkingMemory(resolvedWorkspaceRoot);
+  const params = validateRenderArgs(args);
+  let source = { mode: params.mode };
+  let sourceRecords = [];
+  let normalizedMessages = [];
+  let renderedMessages = [];
+  if (params.mode === 'manual') {
+    sourceRecords = params.manual.messages;
+    normalizedMessages = normalizeTranscriptMessages(sourceRecords, { mode: 'manual' });
+    renderedMessages = normalizedMessages;
+    source = {
+      mode: 'manual',
+      summary: {
+        suppliedMessageCount: sourceRecords.length,
+      },
+    };
+  } else {
+    source = await resolveStoredTranscriptSource(resolvedWorkspaceRoot, params.stored.chatRequestId);
+    sourceRecords = await loadTranscriptRecords(source.transcriptPath);
+    normalizedMessages = normalizeTranscriptMessages(sourceRecords, { mode: 'stored' });
+    renderedMessages = selectStoredMessages(normalizedMessages, params.stored.chatRequestId);
+  }
+  if (renderedMessages.length === 0) {
+    inputError('messages', 'No renderable peer-visible transcript messages were found');
+  }
+
+  const header = normalizeHeaderContext({
+    mode: params.mode,
+    manual: params.manual || null,
+    source,
+    messages: renderedMessages,
+  });
+  const layout = layoutPages({
+    messages: renderedMessages,
+    header,
+    maxPageHeight: params.maxPageHeight,
+  });
+  const spec = buildBubbleSpec({
+    mode: params.mode,
+    source,
+    header,
+    messages: renderedMessages,
+    layout,
+    style: params.style,
+  });
+  const seed = `${params.mode}:${source?.chatRequestId || header.title}:${renderedMessages.length}:${Date.now()}:${stableJson({ agentId })}`;
+  const artifactId = `claworld-transcript-${safeFileStem(source?.chatRequestId || header.title)}-${sha256Buffer(Buffer.from(seed)).slice(0, 10)}`;
+  const artifacts = await writeArtifacts({
+    workspaceRoot: resolvedWorkspaceRoot,
+    artifactId,
+    spec,
+    layout,
+  });
+  const result = {
+    status: 'ok',
+    mode: params.mode,
+    chatRequestId: source.chatRequestId || null,
+    artifactId,
+    messageCount: renderedMessages.length,
+    pageCount: layout.pages.length,
+    style: params.style,
+    artifacts,
+    deliveryHint: {
+      primaryMedia: artifacts.pngPages[0]?.mediaRef || null,
+      primaryMediaBatch: artifacts.pngPages.map((page) => page.mediaRef).join('\n'),
+      sourceSvgDocument: artifacts.svgPages[0] ? `[[as_document]]\nMEDIA:${artifacts.svgPages[0].path}` : null,
+      openClawMediaPaths: artifacts.pngPages.map((page) => page.path),
+    },
+    diagnostics: buildDiagnostics({
+      sourceRecords,
+      normalizedMessages,
+      renderedMessages,
+      source,
+    }),
+  };
+  await appendRenderJournalEvent(resolvedWorkspaceRoot, result);
+  return result;
+}
+
+function buildEpisodeFilters(input = {}) {
+  const source = isObject(input.filters) ? input.filters : input;
+  return {
+    chatRequestId: normalizeText(source.chatRequestId, null),
+    conversationKey: normalizeText(source.conversationKey, null),
+    localSessionKey: normalizeText(source.localSessionKey, null),
+    worldId: normalizeText(source.worldId, null),
+    counterpartyAgentId: normalizeText(source.counterpartyAgentId, null),
+  };
+}
+
+function episodeMatchesFilters(summary, filters) {
+  if (filters.chatRequestId && summary.chatRequestId !== filters.chatRequestId) return false;
+  if (filters.localSessionKey && summary.localSessionKey !== filters.localSessionKey) return false;
+  if (filters.conversationKey && summary.conversationKey !== filters.conversationKey) return false;
+  if (filters.worldId && summary.worldId !== filters.worldId) return false;
+  if (
+    filters.counterpartyAgentId
+    && summary.relaySessionKey !== filters.counterpartyAgentId
+    && summary.conversationKey?.includes(filters.counterpartyAgentId) !== true
+  ) {
+    return false;
+  }
+  return true;
+}
+
+export async function listClaworldLocalTranscriptEpisodes({
+  workspaceRoot = null,
+  filters = {},
+} = {}) {
+  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
+  const normalizedFilters = buildEpisodeFilters(filters);
+  const sessionDirectory = await readClaworldSessionDirectory(resolvedWorkspaceRoot);
+  const summaries = [];
+  const conversationSessions = sessionDirectory.directory?.conversationSessions || {};
+  for (const [localSessionKey, session] of Object.entries(conversationSessions)) {
+    const chatRequests = session?.chatRequests || {};
+    for (const [chatRequestId, request] of Object.entries(chatRequests)) {
+      const artifacts = Array.isArray(request?.artifacts) ? request.artifacts : [];
+      const latestArtifact = [...artifacts].reverse().find((artifact) => artifactPathCandidates(artifact).length > 0) || {};
+      const summary = summarizeDirectoryRequest({
+        chatRequestId,
+        localSessionKey,
+        session,
+        request,
+        artifact: latestArtifact,
+        transcriptPath: latestArtifact.transcriptPath || latestArtifact.sessionFile || null,
+      });
+      if (episodeMatchesFilters(summary, normalizedFilters)) summaries.push(summary);
+    }
+  }
+  return summaries.sort((left, right) => String(right.lastSeenAt || '').localeCompare(String(left.lastSeenAt || '')));
+}
+
+export async function summarizeClaworldChatRequestTranscript({
+  workspaceRoot = null,
+  chatRequestId,
+} = {}) {
+  const resolvedWorkspaceRoot = resolveWorkspaceRoot(workspaceRoot);
+  const id = normalizeText(chatRequestId, null);
+  if (!id) inputError('chatRequestId', 'chatRequestId is required');
+  const source = await resolveStoredTranscriptSource(resolvedWorkspaceRoot, id);
+  const sourceRecords = await loadTranscriptRecords(source.transcriptPath);
+  const normalizedMessages = normalizeTranscriptMessages(sourceRecords, { mode: 'stored' });
+  const renderedMessages = selectStoredMessages(normalizedMessages, id);
+  return {
+    chatRequestId: id,
+    transcriptPath: source.transcriptPath,
+    sourceMessageCount: sourceRecords.length,
+    renderableMessageCount: renderedMessages.length,
+    peerMessageCount: renderedMessages.filter((message) => message.side === 'peer').length,
+    localMessageCount: renderedMessages.filter((message) => message.side === 'local').length,
+    firstMessageAt: renderedMessages[0]?.createdAt || null,
+    lastMessageAt: renderedMessages[renderedMessages.length - 1]?.createdAt || null,
+  };
+}
+
+function buildLocalTranscriptSummary(episodes = []) {
+  return {
+    count: episodes.length,
+    chatRequestIds: episodes.map((episode) => episode.chatRequestId).filter(Boolean),
+    latestChatRequestId: episodes[0]?.chatRequestId || null,
+  };
+}
+
+export async function augmentConversationPayloadWithLocalTranscriptIndex(payload, {
+  workspaceRoot = null,
+  filters = {},
+} = {}) {
+  if (!isObject(payload)) return payload;
+  const episodes = await listClaworldLocalTranscriptEpisodes({ workspaceRoot, filters });
+  const addition = {
+    localTranscriptEpisodes: episodes,
+    localTranscriptSummary: buildLocalTranscriptSummary(episodes),
+  };
+  if (Array.isArray(payload.items)) {
+    return {
+      ...payload,
+      ...addition,
+      items: payload.items.map((item) => {
+        if (!isObject(item)) return item;
+        const itemFilters = buildEpisodeFilters({
+          chatRequestId: item.chatRequestId,
+          conversationKey: item.conversationKey,
+          localSessionKey: item.localSessionKey,
+          worldId: item.worldId,
+          counterpartyAgentId: item.counterpartyAgentId || item.targetAgentId || item.peerAgentId,
+        });
+        const itemEpisodes = episodes.filter((episode) => episodeMatchesFilters(episode, itemFilters));
+        if (itemEpisodes.length === 0) return item;
+        return {
+          ...item,
+          localTranscriptEpisodes: itemEpisodes,
+          localTranscriptSummary: buildLocalTranscriptSummary(itemEpisodes),
+        };
+      }),
+    };
+  }
+  return {
+    ...payload,
+    ...addition,
+  };
+}