|
| 1 | +/** |
| 2 | + * Pure trace → Markdown serializer for /export-with-traces. |
| 3 | + * |
| 4 | + * Consumes the trace store's per-run event log (trace/recorder.js) — an |
| 5 | + * append-only, compaction-immune record whose tool results are the RAW structured |
| 6 | + * values (pre-truncated by the recorder, never `_wrapUntrusted`-wrapped). That is |
| 7 | + * the right source for a tool chain; `this.conversations` is not (it is compacted, |
| 8 | + * enriched, and wrapped — see the closed PR #348 review). |
| 9 | + * |
| 10 | + * This renders the TOOL CHAIN: user/assistant/planner prose, tool calls (name, |
| 11 | + * args, result), and errors — in order. Screenshot / note / vision_sub_call events |
| 12 | + * are recorded but deliberately not rendered; the file says so in its footer, so it |
| 13 | + * never claims to be a complete record. The complete record is the Traces-page JSON. |
| 14 | + * |
| 15 | + * Pure and browser-neutral → unit-tested in test/run.js without a DOM or IndexedDB. |
| 16 | + * |
| 17 | + * @param {Array<{run: object, events: Array}>} runsWithEvents chronological runs, |
| 18 | + * each with its ordered event list. |
| 19 | + */ |
| 20 | + |
| 21 | +const ARGS_LIMIT = 300; |
| 22 | +const RESULT_LIMIT = 600; |
| 23 | +const FOOTER = '_Screenshots, notes and vision sub-calls are recorded but not rendered here — see the Traces page for the complete record._'; |
| 24 | + |
| 25 | +function oneLine(t) { return String(t ?? '').replace(/\s+/g, ' ').trim(); } |
| 26 | +function humanSize(n) { return n >= 1024 ? `${(n / 1024).toFixed(1)}kb` : `${n}b`; } |
| 27 | + |
| 28 | +function truncate(text, limit) { |
| 29 | + const s = String(text ?? ''); |
| 30 | + if (s.length <= limit) return s; |
| 31 | + return `${s.slice(0, limit)}… +${humanSize(s.length - limit)} truncated`; |
| 32 | +} |
| 33 | + |
| 34 | +// Wrap text in a fenced code block that survives content which is ITSELF fenced. |
| 35 | +// Planner responses usually arrive already wrapped in ```json … ```; naively |
| 36 | +// re-fencing them produces ```\n```json\n…, which no Markdown renderer parses. |
| 37 | +// So: unwrap a single enclosing fence (keeping its language hint), then choose a |
| 38 | +// fence longer than any backtick run left inside, per CommonMark, so nothing can |
| 39 | +// close the block early. |
| 40 | +function fencedBlock(content) { |
| 41 | + let body = String(content ?? '').trim(); |
| 42 | + let info = ''; |
| 43 | + const wrapped = body.match(/^```([^\n]*)\n([\s\S]*?)\n```$/); |
| 44 | + if (wrapped) { info = wrapped[1].trim(); body = wrapped[2].trim(); } |
| 45 | + const longestRun = (body.match(/`+/g) || []).reduce((n, s) => Math.max(n, s.length), 0); |
| 46 | + const fence = '`'.repeat(Math.max(3, longestRun + 1)); |
| 47 | + return `${fence}${info}\n${body}\n${fence}`; |
| 48 | +} |
| 49 | + |
| 50 | +// IndexedDB can retain values that JSON.stringify rejects (circular / bigint / |
| 51 | +// sparse). Never throw mid-export — fall back to a readable marker. |
| 52 | +function safeJsonStringify(value) { |
| 53 | + try { |
| 54 | + return JSON.stringify(value); |
| 55 | + } catch { |
| 56 | + try { |
| 57 | + return String(value); |
| 58 | + } catch { |
| 59 | + return '(unserializable)'; |
| 60 | + } |
| 61 | + } |
| 62 | +} |
| 63 | + |
| 64 | +function stringifyArgs(args) { |
| 65 | + if (args == null) return ''; |
| 66 | + const s = typeof args === 'string' ? args : safeJsonStringify(args); |
| 67 | + return truncate(oneLine(s), ARGS_LIMIT); |
| 68 | +} |
| 69 | + |
| 70 | +// A trace tool result is a RAW value: a structured object ({success,error,...}), |
| 71 | +// a string, or the recorder's large-result marker { _truncated, length, head }. |
| 72 | +function renderResult(result) { |
| 73 | + if (result == null) return { text: '(no result recorded)', failed: false }; |
| 74 | + if (typeof result === 'object' && result._truncated) { |
| 75 | + return { |
| 76 | + text: `${truncate(oneLine(String(result.head ?? '')), RESULT_LIMIT)} [recorder-truncated, ${humanSize(result.length || 0)} total]`, |
| 77 | + failed: false, |
| 78 | + }; |
| 79 | + } |
| 80 | + const failed = typeof result === 'object' ? (result.success === false || !!result.error) : false; |
| 81 | + const s = typeof result === 'string' ? result : safeJsonStringify(result); |
| 82 | + return { text: truncate(oneLine(s), RESULT_LIMIT), failed }; |
| 83 | +} |
| 84 | + |
| 85 | +export function tracesToMarkdown(runsWithEvents, { |
| 86 | + title = 'WebBrain Conversation — tool chain', |
| 87 | + notes = [], |
| 88 | +} = {}) { |
| 89 | + const runs = Array.isArray(runsWithEvents) ? runsWithEvents : []; |
| 90 | + let md = `# ${title}\n\n`; |
| 91 | + let turnCount = 0; |
| 92 | + let toolCount = 0; |
| 93 | + |
| 94 | + for (const entry of runs) { |
| 95 | + if (!entry || !entry.run) continue; |
| 96 | + turnCount += 1; |
| 97 | + const run = entry.run; |
| 98 | + const user = oneLine(run.userMessage || ''); |
| 99 | + const meta = [run.model, run.status].filter(Boolean).join(' · '); |
| 100 | + md += `## Turn ${turnCount}${user ? ` — ${user}` : ''}\n`; |
| 101 | + if (meta) md += `_${meta}_\n`; |
| 102 | + md += '\n'; |
| 103 | + |
| 104 | + const events = Array.isArray(entry.events) ? [...entry.events].sort((a, b) => (a?.seq || 0) - (b?.seq || 0)) : []; |
| 105 | + for (const ev of events) { |
| 106 | + const d = (ev && ev.data) || {}; |
| 107 | + if (ev.kind === 'llm_response') { |
| 108 | + const content = String(d.content || '').trim(); |
| 109 | + if (!content) continue; |
| 110 | + // Plan-before-Act runs record the planner call with phase:'planner'; keep |
| 111 | + // it (derails often start in the plan) but label it and preserve its shape. |
| 112 | + if (d.phase === 'planner') { |
| 113 | + md += `**Planner:**\n${fencedBlock(content)}\n`; |
| 114 | + } else { |
| 115 | + md += `**WebBrain:** ${oneLine(content)}\n`; |
| 116 | + } |
| 117 | + } else if (ev.kind === 'tool') { |
| 118 | + toolCount += 1; |
| 119 | + const { text, failed } = renderResult(d.result); |
| 120 | + md += `- 🔧 \`${d.name || 'tool'}\`(${stringifyArgs(d.args)}) → ${failed ? '✗ ' : ''}${text}\n`; |
| 121 | + } else if (ev.kind === 'error') { |
| 122 | + md += `- ⚠️ error${d.phase ? ` (${d.phase})` : ''}: ${oneLine(d.message || '')}\n`; |
| 123 | + } |
| 124 | + // screenshot / note / vision_sub_call intentionally omitted — see FOOTER. |
| 125 | + } |
| 126 | + md += '\n'; |
| 127 | + } |
| 128 | + |
| 129 | + for (const note of Array.isArray(notes) ? notes : []) { |
| 130 | + const line = oneLine(note); |
| 131 | + if (line) md += `_Note: ${line}_\n`; |
| 132 | + } |
| 133 | + md += `${FOOTER}\n`; |
| 134 | + return { markdown: md, turnCount, toolCount }; |
| 135 | +} |
0 commit comments