Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(mcp-host): add the shared input, output and image modules of the artifact generators

marcoteb6171e514f2fa
diff --git a/mcp-host/src/workflow/__tests__/embeddedImages.test.ts b/mcp-host/src/workflow/__tests__/embeddedImages.test.ts
new file mode 100644
index 000000000..44344d271
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/embeddedImages.test.ts
@@ -0,0 +1,273 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createCanvas, loadImage } from '@napi-rs/canvas'
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import { fitImageSize, loadEmbeddableImage, predecodeImages } from '../embeddedImages'
+
+let outputDir: string
+
+beforeEach(() => {
+ outputDir = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-embed-'))
+})
+
+afterEach(() => {
+ fs.rmSync(outputDir, { recursive: true, force: true })
+})
+
+async function writeImage(name: string, format: 'png' | 'jpeg' | 'webp', w = 40, h = 20) {
+ const canvas = createCanvas(w, h)
+ canvas.getContext('2d').fillRect(0, 0, w, h)
+ const data = format === 'png' ? canvas.toBuffer('image/png') : await canvas.encode(format)
+ fs.writeFileSync(path.join(outputDir, name), data)
+}
+
+/** A JPEG with an APP1 Exif segment carrying only the orientation tag. */
+function withExifOrientation(jpeg: Buffer, orientation: number): Buffer {
+ const tiff = Buffer.from([
+ 0x4d,
+ 0x4d,
+ 0x00,
+ 0x2a,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x08,
+ 0x00,
+ 0x01,
+ 0x01,
+ 0x12,
+ 0x00,
+ 0x03,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x01,
+ 0x00,
+ orientation,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ 0x00,
+ ])
+ const body = Buffer.concat([Buffer.from('Exif\0\0', 'latin1'), tiff])
+ const header = Buffer.from([0xff, 0xe1, (body.length + 2) >> 8, (body.length + 2) & 0xff])
+ return Buffer.concat([jpeg.subarray(0, 2), header, body, jpeg.subarray(2)])
+}
+
+async function opaquePixels(png: Buffer): Promise<number> {
+ const image = await loadImage(png)
+ const canvas = createCanvas(image.width, image.height)
+ const ctx = canvas.getContext('2d')
+ ctx.drawImage(image, 0, 0)
+ const data = ctx.getImageData(0, 0, image.width, image.height).data
+ let count = 0
+ for (let i = 3; i < data.length; i += 4) if (data[i] > 0) count++
+ return count
+}
+
+describe('fitImageSize', () => {
+ const box = { width: 500, height: 300 }
+
+ it('keeps proportions and never exceeds the box, even for an explicit size', () => {
+ expect(fitImageSize({ width: 1000, height: 500 }, box)).toEqual({ width: 500, height: 250 })
+ expect(fitImageSize({ width: 1000, height: 500 }, box, { width: 2000 })).toEqual({
+ width: 500,
+ height: 250,
+ })
+ expect(fitImageSize({ width: 100, height: 100 }, box, { height: 900 })).toEqual({
+ width: 300,
+ height: 300,
+ })
+ })
+
+ it('reads a width and height given together as a box to fit in', () => {
+ expect(fitImageSize({ width: 100, height: 100 }, box, { width: 200, height: 100 })).toEqual({
+ width: 100,
+ height: 100,
+ })
+ expect(fitImageSize({ width: 200, height: 100 }, box, { width: 400, height: 400 })).toEqual({
+ width: 400,
+ height: 200,
+ })
+ expect(fitImageSize({ width: 100, height: 100 }, box, { width: 1000, height: 1000 })).toEqual({
+ width: 300,
+ height: 300,
+ })
+ })
+})
+
+describe('loadEmbeddableImage', () => {
+ it('accepts a bare filename or an object with path', async () => {
+ await writeImage('a.png', 'png')
+ const warnings: string[] = []
+ expect(loadEmbeddableImage('a.png', outputDir, warnings)).toMatchObject({
+ format: 'png',
+ width: 40,
+ height: 20,
+ })
+ expect(loadEmbeddableImage({ path: 'a.png' }, outputDir, warnings)?.format).toBe('png')
+ expect(warnings).toEqual([])
+ })
+
+ it('reads the format from the bytes and converts decoded images to opaque PNG', async () => {
+ await writeImage('photo.png', 'jpeg')
+ await writeImage('anim.webp', 'webp')
+ fs.writeFileSync(
+ path.join(outputDir, 'logo.svg'),
+ '<svg xmlns="http://www.w3.org/2000/svg" width="30" height="10"><rect width="30" height="10"/></svg>'
+ )
+ await predecodeImages({ images: ['anim.webp', { path: 'logo.svg' }] }, outputDir)
+ const warnings: string[] = []
+ expect(loadEmbeddableImage('photo.png', outputDir, warnings)?.format).toBe('jpeg')
+ const webp = loadEmbeddableImage('anim.webp', outputDir, warnings)
+ expect(webp?.format).toBe('png')
+ expect(await opaquePixels(webp!.data)).toBe(40 * 20)
+ const svg = loadEmbeddableImage('logo.svg', outputDir, warnings)
+ expect(svg).toMatchObject({ format: 'png', width: 30, height: 10 })
+ expect(await opaquePixels(svg!.data)).toBe(30 * 10)
+ expect(warnings).toEqual([])
+ })
+
+ it('finds images named inside markdown bodies', async () => {
+ await writeImage('inline.webp', 'webp')
+ await predecodeImages({ body: 'Intro\n\n![sales](inline.webp)\n' }, outputDir)
+ const image = loadEmbeddableImage('inline.webp', outputDir, [])
+ expect(await opaquePixels(image!.data)).toBe(40 * 20)
+ })
+
+ it('finds a body image whose name holds spaces, in each form markdown writes it', async () => {
+ await writeImage('my chart.webp', 'webp')
+ await writeImage('image (1).webp', 'webp')
+ await predecodeImages(
+ { body: '![a](<my chart.webp>)\n\n![b](image (1).webp "Title")' },
+ outputDir
+ )
+ expect(loadEmbeddableImage('my chart.webp', outputDir, [])).toBeDefined()
+ expect(loadEmbeddableImage('image (1).webp', outputDir, [])).toBeDefined()
+ })
+
+ it('scans a body of unclosed image openings in linear time', async () => {
+ const started = performance.now()
+ await predecodeImages({ body: '!['.repeat(100000) }, outputDir)
+ expect(performance.now() - started).toBeLessThan(5000)
+ })
+
+ it('reports an image it was not able to decode instead of drawing it blank', async () => {
+ await writeImage('late.webp', 'webp')
+ const warnings: string[] = []
+ expect(loadEmbeddableImage('late.webp', outputDir, warnings)).toBeUndefined()
+ expect(warnings).toEqual(["'late.webp' is not an image this tool can read and was left out."])
+ })
+
+ it('rasterizes a huge SVG at a bounded size instead of its declared one', async () => {
+ // The canvas library aborts the process when it cannot allocate the bitmap.
+ fs.writeFileSync(
+ path.join(outputDir, 'huge.svg'),
+ '<svg xmlns="http://www.w3.org/2000/svg" width="32000" height="16000"><rect width="32000" height="16000"/></svg>'
+ )
+ fs.writeFileSync(
+ path.join(outputDir, 'inches.svg'),
+ '<svg xmlns="http://www.w3.org/2000/svg" width="1000in" height="1000in" viewBox="0 0 10 10"><rect width="10" height="10"/></svg>'
+ )
+ await predecodeImages(['huge.svg', 'inches.svg'], outputDir)
+ expect(loadEmbeddableImage('huge.svg', outputDir, [])).toMatchObject({
+ width: 2048,
+ height: 1024,
+ })
+ expect(loadEmbeddableImage('inches.svg', outputDir, [])).toMatchObject({
+ width: 2048,
+ height: 2048,
+ })
+ })
+
+ it('does not decode an image whose header declares an enormous size', async () => {
+ const gif = Buffer.from(
+ 'R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==',
+ 'base64'
+ )
+ gif.writeUInt16LE(60000, 6)
+ gif.writeUInt16LE(60000, 8)
+ fs.writeFileSync(path.join(outputDir, 'huge.gif'), gif)
+ await predecodeImages(['huge.gif'], outputDir)
+ expect(loadEmbeddableImage('huge.gif', outputDir, [])).toBeUndefined()
+ })
+
+ it('leaves out, with a warning, what is missing or not an image', () => {
+ fs.writeFileSync(path.join(outputDir, 'notes.png'), 'plain text')
+ const warnings: string[] = []
+ expect(loadEmbeddableImage('missing.png', outputDir, warnings)).toBeUndefined()
+ expect(loadEmbeddableImage('notes.png', outputDir, warnings)).toBeUndefined()
+ expect(loadEmbeddableImage({ width: 100 }, outputDir, warnings, 'images[2]')).toBeUndefined()
+ expect(warnings).toEqual([
+ "Image 'missing.png' was not found in the output folder and was left out.",
+ "'notes.png' is not an image this tool can read and was left out.",
+ 'images[2] needs a file name, such as the one clerum__generate_chart returns; it was left out.',
+ ])
+ })
+
+ it('uses the file of the same name when given an absolute path from elsewhere', async () => {
+ await writeImage('chart.png', 'png')
+ const warnings: string[] = []
+ const image = loadEmbeddableImage('/output/chart.png', outputDir, warnings)
+ expect(image?.path).toBe(path.join(path.resolve(outputDir), 'chart.png'))
+ expect(warnings[0]).toContain("'/output/chart.png' is outside the output folder")
+ })
+
+ it('refuses a link inside the output folder that points outside it', async () => {
+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-outside-'))
+ try {
+ const canvas = createCanvas(4, 4)
+ canvas.getContext('2d').fillRect(0, 0, 4, 4)
+ fs.writeFileSync(path.join(outside, 'secret.png'), canvas.toBuffer('image/png'))
+ fs.symlinkSync(path.join(outside, 'secret.png'), path.join(outputDir, 'innocent.png'))
+ expect(() => loadEmbeddableImage('innocent.png', outputDir, [])).toThrow(
+ /path traversal blocked/
+ )
+ } finally {
+ fs.rmSync(outside, { recursive: true, force: true })
+ }
+ })
+
+ it('says a web address is not downloaded', () => {
+ const warnings: string[] = []
+ expect(
+ loadEmbeddableImage('https://example.com/chart.png', outputDir, warnings, 'images[0]')
+ ).toBeUndefined()
+ expect(warnings[0]).toContain('is a web address or inline data, and images are not downloaded')
+ })
+
+ it('turns a photo tagged with an EXIF rotation upright for every format', async () => {
+ // 40x20 with the left quarter blue, tagged "rotate 90° clockwise".
+ const canvas = createCanvas(40, 20)
+ const ctx = canvas.getContext('2d')
+ ctx.fillStyle = '#ff0000'
+ ctx.fillRect(0, 0, 40, 20)
+ ctx.fillStyle = '#0000ff'
+ ctx.fillRect(0, 0, 10, 20)
+ fs.writeFileSync(
+ path.join(outputDir, 'photo.jpg'),
+ withExifOrientation(canvas.toBuffer('image/jpeg'), 6)
+ )
+ await predecodeImages(['photo.jpg'], outputDir)
+ const image = loadEmbeddableImage('photo.jpg', outputDir, [])!
+ expect(image).toMatchObject({ format: 'jpeg', width: 20, height: 40 })
+ const decoded = await loadImage(image.data)
+ const probe = createCanvas(decoded.width, decoded.height)
+ probe.getContext('2d').drawImage(decoded, 0, 0)
+ const [r, , b] = probe.getContext('2d').getImageData(10, 2, 1, 1).data
+ expect(b).toBeGreaterThan(200)
+ expect(r).toBeLessThan(60)
+ })
+
+ it('still refuses to leave the output folder', () => {
+ expect(() => loadEmbeddableImage('../../etc/passwd', outputDir, [])).toThrow(
+ /path traversal blocked/
+ )
+ expect(() => loadEmbeddableImage('/etc/passwd', outputDir, [])).toThrow(
+ /path traversal blocked/
+ )
+ })
+})
diff --git a/mcp-host/src/workflow/__tests__/inlineMarkup.test.ts b/mcp-host/src/workflow/__tests__/inlineMarkup.test.ts
new file mode 100644
index 000000000..49dff7cd0
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/inlineMarkup.test.ts
@@ -0,0 +1,209 @@
+import { describe, expect, it } from 'vitest'
+import {
+ decodeEntities,
+ htmlToMarkdownInline,
+ htmlToPlainText,
+ imageTarget,
+ inlineSpans,
+ quoteParagraphs,
+ withoutClosingHashes,
+} from '../inlineMarkup'
+
+describe('inline HTML', () => {
+ it('maps emphasis tags onto markdown and <br> onto a line break', () => {
+ expect(
+ htmlToMarkdownInline('<b>a</b> <strong>b</strong> <i>c</i> <em>d</em> <del>e</del>')
+ ).toBe('**a** **b** *c* *d* ~~e~~')
+ expect(htmlToMarkdownInline('one<br>two<BR/>three')).toBe('one\ntwo\nthree')
+ })
+
+ it('keeps links, turns img into an image reference and drops scripts and comments', () => {
+ expect(htmlToMarkdownInline('<a href="https://x.test/a">site</a>')).toBe(
+ '[site](https://x.test/a)'
+ )
+ expect(htmlToMarkdownInline('<img src="chart.png" alt="c">')).toBe('![](chart.png)')
+ expect(htmlToMarkdownInline('a<script>alert(1)</script>b<!-- note -->')).toBe('ab')
+ })
+
+ it('leaves text that only looks like a tag, and HTML quoted in code', () => {
+ expect(htmlToMarkdownInline('Vec<String> and a < b')).toBe('Vec<String> and a < b')
+ expect(htmlToMarkdownInline('use `<br>` here')).toBe('use `<br>` here')
+ expect(htmlToPlainText('if a<b and c>d or x<i then y>z')).toBe('if a<b and c>d or x<i then y>z')
+ })
+
+ it('reads a tag whose attributes have values, or are HTML boolean attributes', () => {
+ expect(htmlToMarkdownInline('<b class="x">a</b> <span data-n=1 title=\'t\'>b</span>')).toBe(
+ '**a** b'
+ )
+ expect(htmlToMarkdownInline('<table><tr><td nowrap>1</td><td>2</td></tr></table>')).toBe('1 2')
+ expect(htmlToMarkdownInline('<b >a</b >')).toBe('**a**')
+ })
+
+ it('breaks the line at block elements and drops their tags', () => {
+ expect(htmlToMarkdownInline('<h2>Sales</h2><p>One</p><div>Two</div>')).toBe('Sales\nOne\nTwo')
+ expect(
+ htmlToMarkdownInline('<table><tr><th>A</th><th>B</th></tr><tr><td>1</td></tr></table>')
+ ).toBe('A B\n1')
+ expect(htmlToMarkdownInline('<details><summary>S</summary>D</details>')).toBe('S\nD')
+ })
+
+ it('keeps list items apart, numbered as their list is', () => {
+ expect(htmlToMarkdownInline('<ul><li>a</li><li>b</li></ul><ol><li>c</li><li>d</li></ol>')).toBe(
+ '\u2022 a\n\u2022 b\n1. c\n2. d'
+ )
+ })
+
+ it('reduces a title to its text', () => {
+ expect(htmlToPlainText('HTML <b>mixed</b> &amp; <i>title</i>')).toBe('HTML mixed & title')
+ expect(htmlToPlainText('<h1>A</h1><p>B</p> <img src="x.png">')).toBe('A B')
+ })
+})
+
+describe('entities', () => {
+ it('decodes named and numeric references', () => {
+ expect(decodeEntities('a &amp; b &lt;c&gt; &#65;&#x42; &nbsp;')).toBe('a & b <c> AB \u00A0')
+ })
+
+ it('leaves unknown and unrepresentable references as written', () => {
+ expect(decodeEntities('&bogus; &#0; &#xD800;')).toBe('&bogus; &#0; &#xD800;')
+ })
+
+ it('prints an encoded marker instead of reading it as markup', () => {
+ expect(inlineSpans('&#42;&#42;not bold&#42;&#42; &lt;b&gt;')).toEqual([
+ { text: '**not bold** <b>' },
+ ])
+ })
+})
+
+describe('inline markdown', () => {
+ it('reads ***text*** as bold italic, and nests emphasis', () => {
+ expect(inlineSpans('A ***both*** B')).toEqual([
+ { text: 'A ' },
+ { text: 'both', bold: true, italics: true },
+ { text: ' B' },
+ ])
+ expect(inlineSpans('~~old **bold**~~')).toEqual([
+ { text: 'old ', strike: true },
+ { text: 'bold', strike: true, bold: true },
+ ])
+ })
+
+ it('prints an escaped marker as itself', () => {
+ expect(
+ inlineSpans('\\*not italic\\*')
+ .map(s => s.text)
+ .join('')
+ ).toBe('*not italic*')
+ expect(inlineSpans('\\*not italic\\*').some(s => s.italics)).toBe(false)
+ })
+
+ it('keeps multiplication signs that have spaces around them', () => {
+ expect(inlineSpans('Math 5 * 3 * 2 = 30')).toEqual([{ text: 'Math 5 * 3 * 2 = 30' }])
+ })
+
+ it('keeps balanced parentheses in a link target', () => {
+ expect(inlineSpans('[wiki](https://en.wikipedia.org/wiki/Foo_(bar)) end')).toEqual([
+ { text: 'wiki', link: 'https://en.wikipedia.org/wiki/Foo_(bar)' },
+ { text: ' end' },
+ ])
+ })
+
+ it('names an image written in the text, with its alt text', () => {
+ expect(inlineSpans('see ![Revenue](sales.png "t") now')).toEqual([
+ { text: 'see ' },
+ { text: 'Revenue', image: 'sales.png' },
+ { text: ' now' },
+ ])
+ expect(inlineSpans('`![x](y.png)`')).toEqual([{ text: '![x](y.png)', code: true }])
+ })
+})
+
+describe('ATX headings', () => {
+ it('drops a closing run of hashes only when a space precedes it', () => {
+ expect(withoutClosingHashes('Section title ##')).toBe('Section title')
+ expect(withoutClosingHashes('C#')).toBe('C#')
+ expect(withoutClosingHashes('Issue #42')).toBe('Issue #42')
+ expect(withoutClosingHashes('##')).toBe('')
+ })
+})
+
+describe('image targets', () => {
+ it('reads the file an image names, in each form Markdown allows', () => {
+ expect(imageTarget('chart.png')).toBe('chart.png')
+ expect(imageTarget(' <my chart.png> ')).toBe('my chart.png')
+ expect(imageTarget('<my chart.png> "Sales"')).toBe('my chart.png')
+ expect(imageTarget('chart.png "Quarterly sales"')).toBe('chart.png')
+ expect(imageTarget("chart.png 'Sales'")).toBe('chart.png')
+ expect(imageTarget('chart.png (Sales)')).toBe('chart.png')
+ expect(imageTarget('my\\_chart.png')).toBe('my_chart.png')
+ expect(imageTarget('a&amp;b.png')).toBe('a&b.png')
+ })
+
+ it('reads a name with spaces written without angle brackets whole', () => {
+ expect(imageTarget('my chart.png')).toBe('my chart.png')
+ expect(imageTarget('image (1).png')).toBe('image (1).png')
+ expect(imageTarget('image (1).png "Costs"')).toBe('image (1).png')
+ expect(imageTarget('my chart.png (Sales)')).toBe('my chart.png')
+ })
+
+ it('finds an image whose name holds a parenthesized part', () => {
+ const [span] = inlineSpans('![Sales](image (1).png)')
+ expect(span).toEqual({ text: 'Sales', image: 'image (1).png' })
+ })
+})
+
+describe('block quotes', () => {
+ it('ends a paragraph at an empty quoted line and runs the others on', () => {
+ expect(quoteParagraphs(['One', 'runs on.', '', ' ', 'Two.', ''])).toEqual([
+ 'One runs on.',
+ 'Two.',
+ ])
+ expect(quoteParagraphs(['', ''])).toEqual([''])
+ })
+})
+
+describe('hostile input', () => {
+ // Each input is about 200 KB on one line: an unclosed construct repeated, so
+ // a pattern that rescans the rest of the line from every opening is quadratic.
+ const inputs: Record<string, string> = {
+ img: "<img src='x".repeat(20000),
+ tag: '<b'.repeat(100000),
+ tagSpaced: '<b '.repeat(66667),
+ tagAttributes: '<b a=1'.repeat(30000),
+ tagAttributesOpen: `<b ${'a=1 '.repeat(50000)}`,
+ tagBoolean: `<td ${'nowrap '.repeat(28000)}`,
+ comment: '<!--'.repeat(50000),
+ script: '<script>'.repeat(25000),
+ anchor: '<a href="https://x.test">'.repeat(8000),
+ list: '<ol><li>'.repeat(25000),
+ image: '!['.repeat(100000),
+ imageSpaced: '![ '.repeat(66667),
+ imageOpen: '![a]('.repeat(40000),
+ imageGroups: `![a](${'(x)'.repeat(60000)}`,
+ imageGroupsRepeated: `![a](${'(x)'.repeat(5)}`.repeat(10000),
+ link: '[a](http://x'.repeat(16000),
+ bracket: '['.repeat(200000),
+ bold: '**a '.repeat(50000),
+ boldItalic: '***a '.repeat(40000),
+ italic: '*a '.repeat(66667),
+ strike: '~~a '.repeat(50000),
+ code: '`a '.repeat(66667),
+ escape: '\\*'.repeat(100000),
+ entity: '&#x1'.repeat(50000),
+ }
+ const parsers: Record<string, (text: string) => unknown> = {
+ htmlToMarkdownInline,
+ htmlToPlainText,
+ inlineSpans,
+ }
+
+ for (const [name, input] of Object.entries(inputs)) {
+ it(`reads ${name} in linear time`, () => {
+ for (const [parser, parse] of Object.entries(parsers)) {
+ const started = performance.now()
+ parse(input)
+ expect(performance.now() - started, `${parser} on ${name}`).toBeLessThan(2000)
+ }
+ })
+ }
+})
diff --git a/mcp-host/src/workflow/__tests__/tableRows.test.ts b/mcp-host/src/workflow/__tests__/tableRows.test.ts
new file mode 100644
index 000000000..422231039
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/tableRows.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { headerText, normalizeTableRows } from '../tableRows'
+
+describe('normalizeTableRows', () => {
+ it('passes array rows through untouched', () => {
+ const warnings: string[] = []
+ expect(normalizeTableRows([['a', 1, null]], ['A', 'B', 'C'], 'tables[0]', warnings)).toEqual([
+ ['a', 1, null],
+ ])
+ expect(warnings).toEqual([])
+ })
+
+ it('reads record rows by header name, ignoring case and spaces', () => {
+ const warnings: string[] = []
+ const rows = normalizeTableRows(
+ [
+ { Name: 'Ana', Amount: 1200 },
+ { ' name ': 'Luis', amount: 900, extra: 'x' },
+ ],
+ ['Name', 'Amount'],
+ 'tables[0]',
+ warnings
+ )
+ expect(rows).toEqual([
+ ['Ana', 1200],
+ ['Luis', 900],
+ ])
+ expect(warnings).toEqual([
+ 'tables[0]: 2 row(s) were objects and were read by header name; send each row as an array of cells in header order.',
+ "tables[0]: the key(s) 'extra' match no header, so those values were left out.",
+ ])
+ })
+
+ it('takes record values in order when there are no headers', () => {
+ expect(normalizeTableRows([{ a: 1, b: 2 }], undefined, 's', [])).toEqual([[1, 2]])
+ })
+
+ it('drops what is not a row and says so', () => {
+ const warnings: string[] = []
+ expect(normalizeTableRows([['ok'], 'text', null, 3], ['A'], 'sheets[1]', warnings)).toEqual([
+ ['ok'],
+ ])
+ expect(warnings).toEqual([
+ 'sheets[1]: 3 row(s) were neither an array nor an object and were left out.',
+ ])
+ const more: string[] = []
+ expect(normalizeTableRows('a,b', ['A'], 'tables[2]', more)).toEqual([])
+ expect(more).toEqual(['tables[2]: rows must be an array of rows; they were left out.'])
+ })
+})
+
+describe('headerText', () => {
+ it('shows numeric headers and blanks null', () => {
+ expect(headerText(2026)).toBe('2026')
+ expect(headerText(null)).toBe('')
+ expect(headerText('Q1')).toBe('Q1')
+ })
+})
diff --git a/mcp-host/src/workflow/artifactOutput.ts b/mcp-host/src/workflow/artifactOutput.ts
new file mode 100644
index 000000000..77b5315e4
--- /dev/null
+++ b/mcp-host/src/workflow/artifactOutput.ts
@@ -0,0 +1,162 @@
+/**
+ * Naming, placing and reporting the files the document generators write.
+ */
+import { createHash } from 'crypto'
+import * as fs from 'fs'
+import * as path from 'path'
+import type { ArtifactMetadata, InternalToolResult } from './types'
+
+const MAX_STEM_LENGTH = 120
+
+/**
+ * Extensions a requested name may already carry. Anything else after a dot is
+ * part of the name, so "report.v2" keeps its "v2".
+ */
+const KNOWN_EXTENSIONS = new Set([
+ 'md',
+ 'markdown',
+ 'txt',
+ 'pdf',
+ 'doc',
+ 'docx',
+ 'xls',
+ 'xlsx',
+ 'csv',
+ 'ppt',
+ 'pptx',
+ 'png',
+ 'jpg',
+ 'jpeg',
+ 'gif',
+ 'webp',
+ 'svg',
+ 'htm',
+ 'html',
+ 'json',
+])
+
+/**
+ * A safe filename for a generated artifact.
+ *
+ * Only ASCII letters, digits, '.', '_' and '-' are kept, because the download
+ * paths do not all encode other characters. Dropping characters must not make
+ * two requested names equal ("報告.md" and "資料.md" would both be "__.md"), so
+ * when anything other than a space is replaced or dropped a short hash of the
+ * requested name is appended. The stem is shortened before the extension is
+ * added, so a long name keeps its extension.
+ */
+export function outputFilename(requested: unknown, ext: string, fallbackStem: string): string {
+ const extension = ext.replace(/^\./, '').toLowerCase()
+ const base = path.basename(String(requested ?? '').normalize('NFC')).trim()
+ const dot = base.lastIndexOf('.')
+ const stem =
+ dot > 0 && KNOWN_EXTENSIONS.has(base.slice(dot + 1).toLowerCase()) ? base.slice(0, dot) : base
+
+ if (!stem) return `${fallbackStem}.${extension}`
+ const safe = stem
+ .replace(/[^A-Za-z0-9._-]+/g, '_')
+ .replace(/\.{2,}/g, '.')
+ .replace(/^[._-]+|[._-]+$/g, '')
+ if (safe === stem.replace(/\s+/g, '_') && safe && safe.length <= MAX_STEM_LENGTH) {
+ return `${safe}.${extension}`
+ }
+ const hash = createHash('sha256').update(stem).digest('hex').slice(0, 8)
+ return `${(safe || fallbackStem).slice(0, MAX_STEM_LENGTH - hash.length - 1)}-${hash}.${extension}`
+}
+
+export interface OutputTarget {
+ filename: string
+ filePath: string
+ /** A file already at `filePath` will be overwritten. */
+ replacesExisting: boolean
+}
+
+/** Where to write `filename`; a file already there is replaced. */
+export function claimOutputFile(outputDir: string, filename: string): OutputTarget {
+ const filePath = path.join(outputDir, filename)
+ const entry = lstat(filePath)
+ // A write follows a symbolic link, so a link in the name's place is removed
+ // and a regular file is written there instead of wherever it points.
+ if (entry?.isSymbolicLink()) fs.unlinkSync(filePath)
+ return { filename, filePath, replacesExisting: !!entry && !entry.isSymbolicLink() }
+}
+
+function lstat(file: string): fs.Stats | undefined {
+ try {
+ return fs.lstatSync(file)
+ } catch {
+ return undefined
+ }
+}
+
+/** Size of the file a write is about to replace, so a quota check does not count it twice. */
+export function replacedBytes(target: OutputTarget): number {
+ if (!target.replacesExisting) return 0
+ try {
+ return fs.statSync(target.filePath).size
+ } catch {
+ return 0
+ }
+}
+
+/** Lines of notes a result carries; the rest are counted. */
+const MAX_NOTES = 12
+
+/** Notes of one kind shown before the rest of the kind is counted. */
+const NOTES_PER_KIND = 3
+
+/** A note about content the file does not hold, which comes first. */
+const LOSS_NOTE =
+ /\b(dropped|left out|could not|cannot|missing|not drawn|was cut|were cut|skipped)\b/i
+
+/**
+ * `warnings` in a length the agent can relay: past a few, notes that differ
+ * only in their numbers (a row, a cell, a count) are counted, and notes about
+ * lost content come first.
+ */
+export function capNotes(warnings: string[]): string[] {
+ const groups = new Map<string, { notes: string[]; loss: boolean }>()
+ for (const warning of new Set(warnings)) {
+ const key = warning.replace(/\d+(?:\.\d+)?/g, '#')
+ const group = groups.get(key)
+ if (group) group.notes.push(warning)
+ else groups.set(key, { notes: [warning], loss: LOSS_NOTE.test(warning) })
+ }
+ const lines = [...groups.values()]
+ .sort((a, b) => Number(b.loss) - Number(a.loss))
+ .flatMap(({ notes }) => {
+ const shown = notes.slice(0, NOTES_PER_KIND)
+ const more = notes.length - shown.length
+ if (more > 0) shown[shown.length - 1] += ` (${more} more like it.)`
+ return shown
+ })
+ if (lines.length <= MAX_NOTES) return lines
+ return [...lines.slice(0, MAX_NOTES), `(${lines.length - MAX_NOTES} more notes of other kinds.)`]
+}
+
+/**
+ * The result of a generator that wrote `target`. The message leads with the
+ * name the file was actually saved under, which is what another generator must
+ * be given to embed it, and carries any warnings so the agent can relay them.
+ */
+export function artifactResult(
+ target: OutputTarget,
+ format: ArtifactMetadata['format'],
+ opts: { summary?: string; warnings?: string[] } = {}
+): InternalToolResult {
+ const stats = fs.statSync(target.filePath)
+ const parts = [opts.summary ?? `File generated: ${target.filename} (${format}).`]
+ const warnings = capNotes(opts.warnings ?? [])
+ if (warnings.length > 0) parts.push(`Notes: ${warnings.join(' ')}`)
+ return {
+ success: true,
+ artifact: {
+ name: target.filename,
+ format,
+ path: target.filePath,
+ sizeBytes: stats.size,
+ createdAt: new Date().toISOString(),
+ },
+ content: parts.join('\n'),
+ }
+}
diff --git a/mcp-host/src/workflow/embeddedImages.ts b/mcp-host/src/workflow/embeddedImages.ts
new file mode 100644
index 000000000..2b4f616d0
--- /dev/null
+++ b/mcp-host/src/workflow/embeddedImages.ts
@@ -0,0 +1,490 @@
+/**
+ * Reading, sizing and preparing the images the document generators embed.
+ */
+import { createCanvas, loadImage } from '@napi-rs/canvas'
+import * as fs from 'fs'
+import * as path from 'path'
+import { imageTarget } from './inlineMarkup'
+
+export interface ImageSize {
+ width: number
+ height: number
+}
+
+/** Pixels per metre at 96 dpi, the density a PNG carries when it is not oversampled. */
+export const PNG_BASE_PPM = 3780
+
+function isPng(buf: Buffer): boolean {
+ return buf.length > 24 && buf.readUInt32BE(0) === 0x89504e47
+}
+
+function isJpeg(buf: Buffer): boolean {
+ return buf.length > 4 && buf[0] === 0xff && buf[1] === 0xd8
+}
+
+/** The EXIF orientation of a JPEG (1 = upright), from its APP1 segment. */
+function jpegOrientation(buf: Buffer): number {
+ if (!isJpeg(buf)) return 1
+ let i = 2
+ while (i + 4 < buf.length && buf[i] === 0xff) {
+ const marker = buf[i + 1]
+ const length = buf.readUInt16BE(i + 2)
+ if (marker === 0xda) break
+ if (marker === 0xe1 && buf.toString('latin1', i + 4, i + 10) === 'Exif\0\0') {
+ const tiff = i + 10
+ const le = buf.toString('latin1', tiff, tiff + 2) === 'II'
+ const u16 = (at: number) => (le ? buf.readUInt16LE(at) : buf.readUInt16BE(at))
+ const u32 = (at: number) => (le ? buf.readUInt32LE(at) : buf.readUInt32BE(at))
+ if (tiff + 8 > buf.length) return 1
+ const ifd = tiff + u32(tiff + 4)
+ if (ifd + 2 > buf.length) return 1
+ for (let n = 0, count = u16(ifd); n < count; n++) {
+ const entry = ifd + 2 + n * 12
+ if (entry + 10 > buf.length) return 1
+ if (u16(entry) === 0x0112) return u16(entry + 8)
+ }
+ return 1
+ }
+ i += 2 + length
+ }
+ return 1
+}
+
+/** Pixel dimensions of a PNG or JPEG, read from its header. */
+function headerSize(buf: Buffer): ImageSize | undefined {
+ // PNG: IHDR is the first chunk, width and height at byte 16.
+ if (isPng(buf)) {
+ const width = buf.readUInt32BE(16)
+ const height = buf.readUInt32BE(20)
+ return width > 0 && height > 0 ? { width, height } : undefined
+ }
+ // JPEG: walk the segment chain to the frame header, which carries the size.
+ if (isJpeg(buf)) {
+ let i = 2
+ while (i + 9 < buf.length) {
+ if (buf[i] !== 0xff) {
+ i++
+ continue
+ }
+ const marker = buf[i + 1]
+ // SOF0..SOF15, skipping the non-frame markers in that range.
+ if (
+ marker >= 0xc0 &&
+ marker <= 0xcf &&
+ marker !== 0xc4 &&
+ marker !== 0xc8 &&
+ marker !== 0xcc
+ ) {
+ return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) }
+ }
+ i += 2 + buf.readUInt16BE(i + 2)
+ }
+ }
+ return undefined
+}
+
+/** 1200 dpi. A density past it is not one to show a picture at: it would shrink it to a speck. */
+const MAX_DENSITY_RATIO = 12.5
+
+/** Oversampling factor recorded in a PNG's pHYs chunk; 1 when absent or implausible. */
+function pngDensityRatio(buf: Buffer): number {
+ if (!isPng(buf)) return 1
+ let at = 8
+ while (at + 8 <= buf.length) {
+ const length = buf.readUInt32BE(at)
+ const type = buf.toString('latin1', at + 4, at + 8)
+ if (type === 'pHYs' && at + 8 + 9 <= buf.length) {
+ const ppm = buf.readUInt32BE(at + 8)
+ const unit = buf.readUInt8(at + 16)
+ if (unit === 1 && ppm > 0) {
+ const ratio = ppm / PNG_BASE_PPM
+ return Number.isFinite(ratio) && ratio >= 1 && ratio <= MAX_DENSITY_RATIO ? ratio : 1
+ }
+ return 1
+ }
+ if (type === 'IDAT' || type === 'IEND') return 1
+ at += 12 + length
+ }
+ return 1
+}
+
+/**
+ * Size an image should be shown at, in CSS pixels at 96 dpi. An oversampled
+ * image reports fewer display pixels than it stores, which is what keeps its
+ * type at the size it was laid out for.
+ */
+function displaySize(buf: Buffer): ImageSize | undefined {
+ const intrinsic = headerSize(buf)
+ if (!intrinsic) return undefined
+ const ratio = pngDensityRatio(buf)
+ if (ratio <= 1) return intrinsic
+ return {
+ width: Math.max(1, Math.round(intrinsic.width / ratio)),
+ height: Math.max(1, Math.round(intrinsic.height / ratio)),
+ }
+}
+
+function readFile(file: string): Buffer | undefined {
+ try {
+ return fs.readFileSync(file)
+ } catch {
+ return undefined
+ }
+}
+
+/**
+ * Pixel dimensions of a PNG or JPEG file. Embedding an image into a fixed box
+ * distorts it — a 2:1 chart placed in a 16:9 slot is visibly stretched — so
+ * every embedder sizes against the real aspect ratio.
+ */
+export function imageIntrinsicSize(file: string): ImageSize | undefined {
+ const buf = readFile(file)
+ return buf ? headerSize(buf) : undefined
+}
+
+export function imageDisplaySize(file: string): ImageSize | undefined {
+ const buf = readFile(file)
+ return buf ? displaySize(buf) : undefined
+}
+
+/**
+ * Box for an image of `size` that fits `max`, always in the image's own
+ * proportions. An explicit width or height is honoured and the other side
+ * derived; both together are read as a box to fit in, because a model that
+ * sends both almost never means to distort the image. Whatever was asked for
+ * is then scaled down until it fits the page.
+ */
+export function fitImageSize(
+ size: ImageSize | undefined,
+ max: ImageSize,
+ requested: { width?: number; height?: number } = {}
+): ImageSize {
+ const reqW = requested.width && requested.width > 0 ? requested.width : undefined
+ const reqH = requested.height && requested.height > 0 ? requested.height : undefined
+ let width: number
+ let height: number
+ if (!size) {
+ if (!reqW && !reqH) return { width: max.width, height: max.height }
+ width = reqW ?? max.width
+ height = reqH ?? max.height
+ } else {
+ const ratio = size.width / size.height
+ if (reqW && reqH) {
+ const scale = Math.min(reqW / size.width, reqH / size.height)
+ width = size.width * scale
+ height = size.height * scale
+ } else if (reqW) {
+ width = reqW
+ height = reqW / ratio
+ } else if (reqH) {
+ width = reqH * ratio
+ height = reqH
+ } else {
+ width = size.width
+ height = size.height
+ }
+ }
+ const scale = Math.min(max.width / width, max.height / height, 1)
+ return { width: Math.round(width * scale), height: Math.round(height * scale) }
+}
+
+/** fitImageSize for an image on disk. */
+export function fitImageBox(
+ file: string,
+ max: ImageSize,
+ requested: { width?: number; height?: number } = {}
+): ImageSize {
+ return fitImageSize(imageDisplaySize(file), max, requested)
+}
+
+/** The path an image argument names: a filename, or an object carrying `path`. */
+export function imageRefPath(ref: unknown): string | undefined {
+ if (typeof ref === 'string') return ref.trim() || undefined
+ if (ref && typeof ref === 'object') {
+ const p = (ref as { path?: unknown }).path
+ if (typeof p === 'string' && p.trim()) return p.trim()
+ }
+ return undefined
+}
+
+/**
+ * Resolve an image path inside `outputDir`.
+ *
+ * A path that escapes the folder is an error. The one exception is
+ * an absolute path whose file name exists in the folder: models copy the path
+ * a generator reported in another mode (`/output/chart.png`) or invent one, and
+ * failing the whole document for it helped nobody. Returns undefined, with a
+ * warning, when the file is missing.
+ */
+export function resolveImagePath(
+ requested: string,
+ outputDir: string,
+ warnings: string[]
+): string | undefined {
+ const root = path.resolve(outputDir)
+ const resolved = path.resolve(root, requested)
+ const inside = resolved.startsWith(root + path.sep)
+ let file = resolved
+ if (!inside) {
+ const sibling = path.join(root, path.basename(requested))
+ if (!path.isAbsolute(requested) || !fs.existsSync(sibling)) {
+ throw new Error(`path traversal blocked: ${requested}`)
+ }
+ warnings.push(
+ `'${requested}' is outside the output folder, so '${path.basename(requested)}' from the output folder was used.`
+ )
+ file = sibling
+ }
+ if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+ warnings.push(`Image '${requested}' was not found in the output folder and was left out.`)
+ return undefined
+ }
+ if (!insideRealFolder(file, root)) throw new Error(`path traversal blocked: ${requested}`)
+ return file
+}
+
+/** Whether `file`, links resolved, is inside `root`, links resolved. */
+function insideRealFolder(file: string, root: string): boolean {
+ try {
+ return fs.realpathSync(file).startsWith(fs.realpathSync(root) + path.sep)
+ } catch {
+ return false
+ }
+}
+
+export interface EmbeddableImage {
+ /** Resolved file inside the output folder. */
+ path: string
+ /** PNG or JPEG bytes; other formats arrive converted to PNG. */
+ data: Buffer
+ format: 'png' | 'jpeg'
+ /** Display size in CSS pixels. */
+ width: number
+ height: number
+ /** Size of the stored bitmap, which is larger than the display size when oversampled. */
+ pixels: ImageSize
+}
+
+/**
+ * Largest image decoded for conversion, in pixels (64 MB of RGBA). The canvas
+ * library aborts the whole process, uncatchably, when it cannot allocate a
+ * bitmap, so every size is checked from the file header before decoding.
+ */
+const MAX_DECODE_PIXELS = 16_000_000
+const MAX_SVG_SIDE = 2048
+
+/** Width and height from a GIF, WebP or BMP header, read before the image is decoded. */
+function declaredSize(buf: Buffer): ImageSize | undefined {
+ if (buf.length >= 10 && buf.toString('latin1', 0, 4) === 'GIF8') {
+ return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) }
+ }
+ if (buf.length >= 26 && buf.toString('latin1', 0, 2) === 'BM') {
+ return { width: Math.abs(buf.readInt32LE(18)), height: Math.abs(buf.readInt32LE(22)) }
+ }
+ if (
+ buf.length >= 30 &&
+ buf.toString('latin1', 0, 4) === 'RIFF' &&
+ buf.toString('latin1', 8, 12) === 'WEBP'
+ ) {
+ const chunk = buf.toString('latin1', 12, 16)
+ if (chunk === 'VP8X') {
+ return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) }
+ }
+ if (chunk === 'VP8L') {
+ const bits = buf.readUInt32LE(21)
+ return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >> 14) & 0x3fff) }
+ }
+ if (chunk === 'VP8 ') {
+ return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff }
+ }
+ }
+ return undefined
+}
+
+const SVG_UNIT_PX: Record<string, number> = {
+ '': 1,
+ px: 1,
+ pt: 4 / 3,
+ pc: 16,
+ mm: 96 / 25.4,
+ cm: 96 / 2.54,
+ in: 96,
+ em: 16,
+ ex: 8,
+}
+
+function svgLength(tag: string, name: string): number | undefined {
+ const m = new RegExp(`\\s${name}\\s*=\\s*["']\\s*([0-9.]+)\\s*([a-z]*)\\s*["']`, 'i').exec(tag)
+ const factor = m ? SVG_UNIT_PX[m[2].toLowerCase()] : undefined
+ return m && factor ? Number(m[1]) * factor : undefined
+}
+
+/**
+ * An SVG whose root size fits the decode budget. The canvas library rasterizes
+ * an SVG at its declared size, so a huge width, height or viewBox is rewritten
+ * to a smaller one; the drawing is vector, so it scales without loss.
+ */
+function boundedSvg(buf: Buffer): Buffer | undefined {
+ const text = buf.toString('utf8')
+ const open = /<svg\b[^<>]*>/i.exec(text)
+ if (!open) return undefined
+ const tag = open[0]
+ const box =
+ /\sviewBox\s*=\s*["']\s*[-0-9.e]+[\s,]+[-0-9.e]+[\s,]+([0-9.e]+)[\s,]+([0-9.e]+)/i.exec(tag)
+ const width = svgLength(tag, 'width') ?? (box ? Number(box[1]) : undefined)
+ const height = svgLength(tag, 'height') ?? (box ? Number(box[2]) : undefined)
+ if (!width || !height || !Number.isFinite(width) || !Number.isFinite(height)) return buf
+ const scale = Math.min(
+ 1,
+ MAX_SVG_SIDE / Math.max(width, height),
+ Math.sqrt(MAX_DECODE_PIXELS / (width * height))
+ )
+ if (scale >= 1) return buf
+ const sized = tag
+ .replace(/\s(width|height)\s*=\s*(["'])[^"']*\2/gi, '')
+ .replace(
+ /^<svg\b/i,
+ `<svg width="${Math.max(1, Math.floor(width * scale))}" height="${Math.max(1, Math.floor(height * scale))}"` +
+ (box ? '' : ` viewBox="0 0 ${width} ${height}"`)
+ )
+ return Buffer.from(
+ text.slice(0, open.index) + sized + text.slice(open.index + tag.length),
+ 'utf8'
+ )
+}
+
+function isSvg(buf: Buffer): boolean {
+ const head = buf.toString('utf8', 0, Math.min(buf.length, 1024)).trimStart()
+ return /^(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg\b/i.test(head)
+}
+
+/** Bytes safe to hand to the decoder, or undefined for a format or size this tool does not convert. */
+function decodable(raw: Buffer): Buffer | undefined {
+ if (isSvg(raw)) return boundedSvg(raw)
+ const size = isJpeg(raw) ? headerSize(raw) : declaredSize(raw)
+ if (!size || !size.width || !size.height) return undefined
+ return size.width * size.height <= MAX_DECODE_PIXELS ? raw : undefined
+}
+
+/**
+ * PNG bytes of images decoded ahead of a render, by file and version. The
+ * canvas library decodes GIF, WebP and SVG asynchronously, and an image drawn
+ * before it finishes comes out fully transparent; the generators read images
+ * synchronously deep inside their layout code, so the decoding happens first.
+ */
+const decoded = new Map<string, Buffer>()
+const MAX_DECODED = 32
+
+function decodedKey(file: string): string | undefined {
+ try {
+ const stat = fs.statSync(file)
+ return `${file}\0${stat.size}\0${stat.mtimeMs}`
+ } catch {
+ return undefined
+ }
+}
+
+const IMAGE_NAME = /\.(?:png|jpe?g|gif|webp|svg|bmp|avif|ico|tiff?)$/i
+// As the markdown reader matches an image: the alt text stops at the next
+// bracket, so a line of unclosed "![" is scanned once, not from every opening.
+const MARKDOWN_IMAGE = /!\[[^[\]\n]*\]\(((?:[^()\n]|\([^()\n]*\))*)\)/g
+
+function collectImageNames(value: unknown, into: Set<string>, depth = 0): void {
+ if (depth > 64) return
+ if (typeof value === 'string') {
+ const text = value.trim()
+ if (IMAGE_NAME.test(text) && text.length < 1024) into.add(text)
+ if (text.includes('!['))
+ for (const m of text.matchAll(MARKDOWN_IMAGE)) into.add(imageTarget(m[1]))
+ } else if (Array.isArray(value)) {
+ for (const item of value) collectImageNames(item, into, depth + 1)
+ } else if (value && typeof value === 'object') {
+ for (const item of Object.values(value)) collectImageNames(item, into, depth + 1)
+ }
+}
+
+/**
+ * Decode every image an argument names that is neither PNG nor JPEG, so
+ * loadEmbeddableImage can convert it. Never throws: whatever cannot be decoded
+ * here is reported by loadEmbeddableImage when a generator asks for it.
+ */
+export async function predecodeImages(args: unknown, outputDir: string): Promise<void> {
+ const names = new Set<string>()
+ collectImageNames(args, names)
+ const root = path.resolve(outputDir)
+ for (const name of names) {
+ try {
+ const resolved = path.resolve(root, name)
+ const file = resolved.startsWith(root + path.sep)
+ ? resolved
+ : path.isAbsolute(name)
+ ? path.join(root, path.basename(name))
+ : undefined
+ const key = file && decodedKey(file)
+ if (!file || !key || decoded.has(key) || !insideRealFolder(file, root)) continue
+ const raw = fs.readFileSync(file)
+ if (isPng(raw) || (isJpeg(raw) && jpegOrientation(raw) <= 1)) continue
+ const input = decodable(raw)
+ if (!input) continue
+ const image = await loadImage(input)
+ if (!image.width || !image.height || image.width * image.height > MAX_DECODE_PIXELS) continue
+ const canvas = createCanvas(image.width, image.height)
+ canvas.getContext('2d').drawImage(image, 0, 0)
+ // The decoder applies the EXIF rotation; re-encoding drops it, so every
+ // format shows the photo the same way up.
+ decoded.set(
+ key,
+ isJpeg(raw) ? canvas.toBuffer('image/jpeg', 92) : canvas.toBuffer('image/png')
+ )
+ while (decoded.size > MAX_DECODED) decoded.delete(decoded.keys().next().value as string)
+ } catch {
+ // Left for loadEmbeddableImage to report against the argument that named it.
+ }
+ }
+}
+
+/**
+ * Load an image argument for embedding. The format is read from the bytes, not
+ * the extension, so a GIF named .png still embeds; formats other than PNG and
+ * JPEG need predecodeImages first. Anything missing or unreadable is left out
+ * with a warning naming it, so the agent learns why it is not in the document.
+ */
+export function loadEmbeddableImage(
+ ref: unknown,
+ outputDir: string,
+ warnings: string[],
+ label = 'image'
+): EmbeddableImage | undefined {
+ const requested = imageRefPath(ref)
+ if (requested && /^(?:https?|ftp|data):/i.test(requested)) {
+ const shown = requested.length > 60 ? `${requested.slice(0, 57)}...` : requested
+ warnings.push(
+ `${label} '${shown}' is a web address or inline data, and images are not downloaded; ` +
+ 'save the image to the output folder first and pass its file name. It was left out.'
+ )
+ return undefined
+ }
+ if (!requested) {
+ warnings.push(
+ `${label} needs a file name, such as the one clerum__generate_chart returns; it was left out.`
+ )
+ return undefined
+ }
+ const file = resolveImagePath(requested, outputDir, warnings)
+ if (!file) return undefined
+ const raw = readFile(file)
+ const key = decodedKey(file)
+ const upright = raw && (isPng(raw) || (isJpeg(raw) && jpegOrientation(raw) <= 1))
+ const data = upright ? raw : key ? decoded.get(key) : undefined
+ const size = data ? displaySize(data) : undefined
+ const pixels = data ? headerSize(data) : undefined
+ if (!data || !size || !pixels) {
+ warnings.push(`'${requested}' is not an image this tool can read and was left out.`)
+ return undefined
+ }
+ return { path: file, data, format: isPng(data) ? 'png' : 'jpeg', ...size, pixels }
+}
+
+export function imageDataUrl(image: EmbeddableImage): string {
+ return `data:image/${image.format};base64,${image.data.toString('base64')}`
+}
diff --git a/mcp-host/src/workflow/fonts.ts b/mcp-host/src/workflow/fonts.ts
new file mode 100644
index 000000000..8d942bb4d
--- /dev/null
+++ b/mcp-host/src/workflow/fonts.ts
@@ -0,0 +1,1118 @@
+/**
+ * Font provisioning for the artifact renderers.
+ *
+ * Both renderers start from the Roboto faces pdfmake vendors as base64,
+ * registered from memory, so text renders even on an image without system
+ * fonts (where @napi-rs/canvas would measure every string at zero width) and a
+ * PDF never falls back to the Latin-1-only standard-14 Helvetica.
+ *
+ * Roboto carries no arrows, check marks or CJK. Where the image ships fonts
+ * that do, the canvas fallback stack reaches them and a PDF run switches to a
+ * face that has the character; where it ships none, the text is rewritten or
+ * reported. Chart coverage is measured by rendering, PDF coverage read from
+ * each face's cmap, so neither is assumed.
+ */
+import { GlobalFonts, type SKRSContext2D, createCanvas } from '@napi-rs/canvas'
+import * as fs from 'fs'
+import * as path from 'path'
+
+/** Family the bundled Roboto is registered under. */
+export const CHART_FONT_FAMILY = 'Clerum Sans'
+
+/** Family name registered with pdfmake. */
+export const PDF_FONT_FAMILY = 'ClerumSans'
+
+/** Family pdfmake uses for code blocks and inline code. */
+export const PDF_MONO_FAMILY = 'ClerumMono'
+
+/**
+ * Family list handed to the canvas. Roboto first so output is identical across
+ * images; the rest are picked up only when the image ships them, which is what
+ * makes arrows, check marks and CJK render natively where they exist.
+ */
+export const CHART_FONT_STACK =
+ `"${CHART_FONT_FAMILY}", "DejaVu Sans", "Noto Sans", "Liberation Sans", ` +
+ '"Noto Sans CJK SC", "Noto Sans CJK JP", "Arial Unicode MS", sans-serif'
+
+interface RobotoFaces {
+ normal: Buffer
+ bold: Buffer
+ italics: Buffer
+ bolditalics: Buffer
+}
+
+/**
+ * Directories scanned for extra faces. Registering them is what puts the
+ * fallback families above within the canvas's reach. Absent dirs are skipped.
+ */
+const SYSTEM_FONT_DIRS = [
+ '/usr/share/fonts',
+ '/usr/local/share/fonts',
+ '/opt/fonts',
+ '/System/Library/Fonts',
+]
+
+/** Private Use codepoint — no real font claims it, so it renders as "missing". */
+const MISSING_PROBE = '\uE000'
+
+let faces: RobotoFaces | undefined
+let ready = false
+
+function loadRobotoFaces(): RobotoFaces {
+ if (faces) return faces
+ // pdfmake's vfs export shape differs across builds (`pdfMake.vfs`, `vfs`, or
+ // the table itself), so probe rather than pin to one of them.
+ const mod = require('pdfmake/build/vfs_fonts.js')
+ const table: Record<string, string> = mod?.pdfMake?.vfs ?? mod?.vfs ?? mod
+ const decode = (name: string): Buffer => {
+ const b64 = table[name]
+ if (typeof b64 !== 'string') throw new Error(`pdfmake vfs is missing ${name}`)
+ return Buffer.from(b64, 'base64')
+ }
+ faces = {
+ normal: decode('Roboto-Regular.ttf'),
+ bold: decode('Roboto-Medium.ttf'),
+ italics: decode('Roboto-Italic.ttf'),
+ bolditalics: decode('Roboto-MediumItalic.ttf'),
+ }
+ return faces
+}
+
+function walk(dir: string, depth: number): string[] {
+ if (depth > 3) return []
+ const out: string[] = []
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ const full = path.join(dir, entry.name)
+ if (entry.isDirectory()) out.push(...walk(full, depth + 1))
+ else if (/\.(ttf|otf|ttc)$/i.test(entry.name)) out.push(full)
+ }
+ return out
+}
+
+function registerSystemFonts(): void {
+ for (const dir of SYSTEM_FONT_DIRS) {
+ let files: string[]
+ try {
+ if (!fs.existsSync(dir)) continue
+ files = walk(dir, 0)
+ } catch {
+ continue
+ }
+ for (const file of files) {
+ try {
+ GlobalFonts.registerFromPath(file)
+ } catch {
+ // A face the renderer cannot parse is simply not available.
+ }
+ }
+ }
+}
+
+/**
+ * Register the bundled faces (and any system faces) exactly once. Safe to call
+ * from every render path; later calls are free.
+ */
+export function ensureFontsReady(): void {
+ if (ready) return
+ ready = true
+ const f = loadRobotoFaces()
+ GlobalFonts.register(f.normal, CHART_FONT_FAMILY)
+ GlobalFonts.register(f.bold, `${CHART_FONT_FAMILY} Bold`)
+ registerSystemFonts()
+}
+
+/**
+ * Families a PDF can be built from, widest coverage first.
+ *
+ * The body family is the widest one present, since every run starts in it:
+ * DejaVu and Noto carry arrows, check marks, Greek and Cyrillic that Roboto
+ * lacks; anything it still lacks falls back per run.
+ * Matching is by family prefix rather than exact filename because the same
+ * family is packaged under different names — `DejaVuSans.ttf` on one image,
+ * `NotoSans-Regular.ttf` on another — and a missed guess would silently drop
+ * back to the narrower face.
+ */
+const PDF_FAMILY_PREFIXES = [
+ 'NotoSans',
+ 'DejaVuSans',
+ 'LiberationSans',
+ 'NotoSansSC',
+ 'NotoSerifSC',
+]
+
+/** Fixed-width families, for code blocks. */
+const MONO_FAMILY_PREFIXES = ['DejaVuSansMono', 'NotoSansMono', 'LiberationMono', 'DejaVuSerifMono']
+
+/**
+ * One face for pdfmake: an embedded buffer, a path to a standalone file, or a
+ * `[path, postScriptName]` pair addressing a face inside a collection.
+ * pdfmake spreads an array descriptor into `pdfKitDoc.font(...)`, which is the
+ * only way to open one face of a `.ttc`.
+ */
+type PdfFace = Buffer | string | [string, string]
+
+interface PdfFaces {
+ normal: PdfFace
+ bold: PdfFace
+ italics: PdfFace
+ bolditalics: PdfFace
+}
+
+let pdfFaces: PdfFaces | undefined
+let monoFaces: PdfFaces | undefined
+let faceIndex: Map<string, string> | undefined
+
+/**
+ * Every embeddable face on this image, keyed by lowercased basename.
+ *
+ * TrueType Collections are left out on purpose: pdfkit subsets a single face
+ * and cannot open a `.ttc` without being told which face inside it to use, so
+ * handing it one fails the whole document with "createSubset is not a
+ * function". The canvas has no such limit and keeps using them.
+ */
+function embeddableFaces(): Map<string, string> {
+ if (faceIndex) return faceIndex
+ const index = new Map<string, string>()
+ for (const dir of SYSTEM_FONT_DIRS) {
+ try {
+ if (!fs.existsSync(dir)) continue
+ for (const file of walk(dir, 0)) {
+ if (!/\.(ttf|otf)$/i.test(file)) continue
+ const stem = path
+ .basename(file)
+ .replace(/\.(ttf|otf)$/i, '')
+ .toLowerCase()
+ if (!index.has(stem)) index.set(stem, file)
+ }
+ } catch {
+ continue
+ }
+ }
+ faceIndex = index
+ return index
+}
+
+/** First face matching any of `stems`, in order. */
+function pickFace(stems: string[]): string | undefined {
+ const index = embeddableFaces()
+ for (const stem of stems) {
+ const hit = index.get(stem.toLowerCase())
+ if (hit) return hit
+ }
+ return undefined
+}
+
+/**
+ * Resolve one family's four faces from a prefix, accepting both the bare and
+ * the `-Regular` spelling, and falling back to the regular face for styles the
+ * image does not ship.
+ */
+function facesForPrefix(prefix: string): PdfFaces | undefined {
+ const normal = pickFace([prefix, `${prefix}-Regular`, `${prefix}-Book`])
+ if (!normal) return undefined
+ const bold = pickFace([`${prefix}-Bold`, `${prefix}Bold`]) ?? normal
+ const italics = pickFace([`${prefix}-Italic`, `${prefix}-Oblique`, `${prefix}Oblique`]) ?? normal
+ const bolditalics =
+ pickFace([`${prefix}-BoldItalic`, `${prefix}-BoldOblique`, `${prefix}BoldOblique`]) ?? bold
+ return { normal, bold, italics, bolditalics }
+}
+
+/**
+ * Characters Roboto cannot draw. A face is only worth preferring over the
+ * bundled one if it covers some of these.
+ */
+const COVERAGE_PROBES = ['\u2192', '\u2713', '\u4E2D', '\u2265', '\u03B1', '\u044F']
+
+/**
+ * A usable body face has to draw ordinary letters and digits. Checked because
+ * an image can ship fonts whose name suggests broad coverage but which hold
+ * only symbols — macOS packages one called `CJKSymbolsFallback` — and taking
+ * one of those would leave a document with no readable text at all.
+ */
+const LATIN_PROBES = ['A', 'g', '0']
+
+/**
+ * How many probe characters `file` can draw, measured by rendering them.
+ * Returns -1 for a face that cannot set plain Latin, which disqualifies it.
+ */
+function coverageScore(file: string): number {
+ const alias = '__ClerumProbeFace'
+ try {
+ GlobalFonts.registerFromPath(file, alias)
+ } catch {
+ return -1
+ }
+ const font = `"${alias}"`
+ const missing = renderSignature(MISSING_PROBE, font)
+ const blank = renderSignature(' ', font)
+ for (const ch of LATIN_PROBES) {
+ const sig = renderSignature(ch, font)
+ if (sig === missing || sig === blank) return -1
+ }
+ let score = 0
+ for (const ch of COVERAGE_PROBES) {
+ if (renderSignature(ch, font) !== missing) score++
+ }
+ return score
+}
+
+/**
+ * Any regular-weight face from a family known to be broad. Used only when none
+ * of the named prefixes matched, so an image that packages those families
+ * under names this list does not predict still gets the wider font rather than
+ * silently falling back to the narrow bundled one.
+ */
+function discoverWideFace(): PdfFaces | undefined {
+ const candidates: string[] = []
+ for (const [stem, file] of embeddableFaces()) {
+ if (!/^(dejavusans|notosans|liberationsans)(-regular|-book)?$/.test(stem)) continue
+ candidates.push(file)
+ }
+ let best: { file: string; score: number } | undefined
+ for (const file of candidates) {
+ const score = coverageScore(file)
+ if (score > 0 && (!best || score > best.score)) best = { file, score }
+ }
+ if (!best) return undefined
+ const stem = path.basename(best.file).replace(/\.(ttf|otf)$/i, '')
+ return facesForPrefix(stem.replace(/-(Regular|Book)$/i, ''))
+}
+
+/**
+ * PostScript names of the faces inside a TrueType Collection.
+ *
+ * Debian packages Noto CJK only as collections, and a collection cannot be
+ * embedded in a PDF without naming which face to take — so without this, a
+ * Chinese, Japanese or Korean document loses its text entirely. Parsed here
+ * rather than through a font library because the only consumer of one is
+ * pdfkit, reached through pdfmake.
+ */
+function collectionFaceNames(file: string): string[] {
+ return (
+ withFileReader(file, read => {
+ const names: string[] = []
+ for (const dirOffset of (collectionOffsets(read) ?? []).slice(0, 64)) {
+ const name = postScriptName(read, tableDirectory(read, dirOffset))
+ if (name && !names.includes(name)) names.push(name)
+ }
+ return names
+ }) ?? []
+ )
+}
+
+// What a face can draw is read from its cmap, which is exactly what pdfkit
+// consults when it embeds text, instead of being inferred from a rendering.
+
+/** `length` bytes at `offset`, or undefined when that runs past the end. */
+type ByteReader = (offset: number, length: number) => Buffer | undefined
+
+function bufferReader(buf: Buffer): ByteReader {
+ return (offset, length) =>
+ offset >= 0 && length >= 0 && offset + length <= buf.length
+ ? buf.subarray(offset, offset + length)
+ : undefined
+}
+
+/** Run `use` over `file`, reading only the byte ranges it asks for. */
+function withFileReader<T>(file: string, use: (read: ByteReader) => T): T | undefined {
+ let fd: number
+ try {
+ fd = fs.openSync(file, 'r')
+ } catch {
+ return undefined
+ }
+ try {
+ const size = fs.fstatSync(fd).size
+ return use((offset, length) => {
+ if (offset < 0 || length < 0 || offset + length > size) return undefined
+ const out = Buffer.alloc(length)
+ fs.readSync(fd, out, 0, length, offset)
+ return out
+ })
+ } catch {
+ return undefined
+ } finally {
+ fs.closeSync(fd)
+ }
+}
+
+/** Table-directory offsets of the faces in a collection; undefined for a single face. */
+function collectionOffsets(read: ByteReader): number[] | undefined {
+ const head = read(0, 12)
+ if (!head || head.toString('latin1', 0, 4) !== 'ttcf') return undefined
+ const count = head.readUInt32BE(8)
+ const table = read(12, count * 4)
+ if (!table) return []
+ return Array.from({ length: count }, (_, i) => table.readUInt32BE(i * 4))
+}
+
+interface TableEntry {
+ offset: number
+ length: number
+}
+
+function tableDirectory(read: ByteReader, dirOffset: number): Map<string, TableEntry> {
+ const tables = new Map<string, TableEntry>()
+ const head = read(dirOffset, 12)
+ if (!head) return tables
+ const count = head.readUInt16BE(4)
+ const records = read(dirOffset + 12, count * 16)
+ if (!records) return tables
+ for (let t = 0; t < count; t++) {
+ const at = t * 16
+ tables.set(records.toString('latin1', at, at + 4), {
+ offset: records.readUInt32BE(at + 8),
+ length: records.readUInt32BE(at + 12),
+ })
+ }
+ return tables
+}
+
+function postScriptName(read: ByteReader, tables: Map<string, TableEntry>): string | undefined {
+ const entry = tables.get('name')
+ const table = entry && read(entry.offset, entry.length)
+ if (!table || table.length < 6) return undefined
+ const count = table.readUInt16BE(2)
+ const stringOffset = table.readUInt16BE(4)
+ for (let r = 0; r < count; r++) {
+ const rec = 6 + r * 12
+ if (rec + 12 > table.length) break
+ // nameID 6 is the PostScript name, which is what pdfkit looks up.
+ if (table.readUInt16BE(rec + 6) !== 6) continue
+ const platformId = table.readUInt16BE(rec)
+ const len = table.readUInt16BE(rec + 8)
+ const off = stringOffset + table.readUInt16BE(rec + 10)
+ if (off + len > table.length) continue
+ const raw = Buffer.from(table.subarray(off, off + len))
+ // Platform 3 (Windows) stores UTF-16BE; the others are single-byte.
+ const text = platformId === 3 ? raw.swap16().toString('utf16le') : raw.toString('latin1')
+ const clean = text.replace(/[^\x20-\x7E]/g, '').trim()
+ if (clean) return clean
+ }
+ return undefined
+}
+
+/** Appends `cp` to sorted `[first, last, ...]` ranges, extending the last one when adjacent. */
+function addCodePoint(ranges: number[], cp: number): void {
+ const n = ranges.length
+ if (n > 0 && ranges[n - 1] === cp - 1) ranges[n - 1] = cp
+ else if (n === 0 || ranges[n - 1] < cp) ranges.push(cp, cp)
+}
+
+function format4Ranges(t: Buffer, off: number): number[] {
+ const ranges: number[] = []
+ const segX2 = t.readUInt16BE(off + 6)
+ const ends = off + 14
+ const starts = ends + segX2 + 2
+ const deltas = starts + segX2
+ const rangeOffsets = deltas + segX2
+ if (rangeOffsets + segX2 > t.length) return ranges
+ for (let s = 0; s < segX2 / 2; s++) {
+ const end = t.readUInt16BE(ends + 2 * s)
+ const start = t.readUInt16BE(starts + 2 * s)
+ const delta = t.readUInt16BE(deltas + 2 * s)
+ const ro = t.readUInt16BE(rangeOffsets + 2 * s)
+ for (let c = start; c <= Math.min(end, 0xfffe); c++) {
+ let glyph: number
+ if (ro === 0) {
+ glyph = (c + delta) & 0xffff
+ } else {
+ const at = rangeOffsets + 2 * s + ro + 2 * (c - start)
+ glyph = at + 2 <= t.length ? t.readUInt16BE(at) : 0
+ if (glyph !== 0) glyph = (glyph + delta) & 0xffff
+ }
+ if (glyph !== 0) addCodePoint(ranges, c)
+ }
+ }
+ return ranges
+}
+
+function format12Ranges(t: Buffer, off: number): number[] {
+ const groups: Array<[number, number]> = []
+ const count = t.readUInt32BE(off + 12)
+ for (let g = 0; g < count; g++) {
+ const at = off + 16 + g * 12
+ if (at + 12 > t.length) break
+ const first = t.readUInt32BE(at)
+ const last = t.readUInt32BE(at + 4)
+ // A group starting at glyph 0 maps its first code point to .notdef.
+ const from = t.readUInt32BE(at + 8) === 0 ? first + 1 : first
+ if (from <= last) groups.push([from, last])
+ }
+ groups.sort((a, b) => a[0] - b[0])
+ const ranges: number[] = []
+ for (const [first, last] of groups) {
+ const n = ranges.length
+ if (n > 0 && first <= ranges[n - 1] + 1) ranges[n - 1] = Math.max(ranges[n - 1], last)
+ else ranges.push(first, last)
+ }
+ return ranges
+}
+
+/** Unicode ranges the face's cmap maps to a glyph, from its widest Unicode subtable. */
+function cmapRanges(read: ByteReader, tables: Map<string, TableEntry>): number[] {
+ const entry = tables.get('cmap')
+ const t = entry && read(entry.offset, entry.length)
+ if (!t || t.length < 4) return []
+ let best: { off: number; format: number } | undefined
+ for (let i = 0; i < t.readUInt16BE(2); i++) {
+ const rec = 4 + i * 8
+ if (rec + 8 > t.length) break
+ const platform = t.readUInt16BE(rec)
+ const encoding = t.readUInt16BE(rec + 2)
+ const off = t.readUInt32BE(rec + 4)
+ if (off + 16 > t.length) continue
+ const format = t.readUInt16BE(off)
+ const unicode = platform === 0 || (platform === 3 && (encoding === 1 || encoding === 10))
+ if (!unicode || (format !== 4 && format !== 12)) continue
+ if (!best || (format === 12 && best.format !== 12)) best = { off, format }
+ }
+ if (!best) return []
+ return best.format === 12 ? format12Ranges(t, best.off) : format4Ranges(t, best.off)
+}
+
+interface FaceInfo {
+ /** Sorted `[first, last, ...]` code point ranges the face has glyphs for. */
+ ranges: number[]
+ /** Vertical metrics as pdfkit reads them, or undefined when the face has none. */
+ metrics?: FaceMetrics
+ /** Carries OpenType or AAT layout tables, so fontkit shapes and orders a right-to-left run itself. */
+ shapes: boolean
+ /** Has outlines pdfkit can embed; colour-bitmap emoji faces have none. */
+ outlines: boolean
+}
+
+/** From `hhea` and `head`, the tables fontkit reads ascent and descent from. */
+function faceMetrics(read: ByteReader, tables: Map<string, TableEntry>): FaceMetrics | undefined {
+ const hhea = tables.get('hhea')
+ const head = tables.get('head')
+ const vertical = hhea && read(hhea.offset + 4, 4)
+ const units = head && read(head.offset + 18, 2)
+ const em = units?.readUInt16BE(0)
+ if (!vertical || !em) return undefined
+ const ascent = vertical.readInt16BE(0) / em
+ return { ascent, lineHeight: ascent - vertical.readInt16BE(2) / em }
+}
+
+function faceInfoAt(read: ByteReader, dirOffset: number): FaceInfo {
+ const tables = tableDirectory(read, dirOffset)
+ return {
+ ranges: cmapRanges(read, tables),
+ metrics: faceMetrics(read, tables),
+ shapes: tables.has('GSUB') || tables.has('GPOS') || tables.has('morx'),
+ outlines:
+ (tables.has('glyf') || tables.has('CFF ')) && !tables.has('CBDT') && !tables.has('sbix'),
+ }
+}
+
+function readFaceInfo(face: PdfFace): FaceInfo | undefined {
+ if (Buffer.isBuffer(face)) {
+ const read = bufferReader(face)
+ return faceInfoAt(read, collectionOffsets(read)?.[0] ?? 0)
+ }
+ const [file, wanted] = Array.isArray(face) ? face : [face, undefined]
+ return withFileReader(file, read => {
+ const offsets = collectionOffsets(read)
+ if (!offsets) return faceInfoAt(read, 0)
+ const at = wanted
+ ? offsets.find(o => postScriptName(read, tableDirectory(read, o)) === wanted)
+ : offsets[0]
+ return at === undefined ? undefined : faceInfoAt(read, at)
+ })
+}
+
+function coversCodePoint(ranges: number[], cp: number): boolean {
+ let lo = 0
+ let hi = ranges.length / 2 - 1
+ while (lo <= hi) {
+ const mid = (lo + hi) >> 1
+ if (cp < ranges[mid * 2]) hi = mid - 1
+ else if (cp > ranges[mid * 2 + 1]) lo = mid + 1
+ else return true
+ }
+ return false
+}
+
+/** Collections worth embedding, and the script variants to prefer within them. */
+const COLLECTION_PREFERENCE = [/CJKsc-/i, /CJKjp-/i, /CJKtc-/i, /CJKkr-/i, /CJKhk-/i]
+
+/**
+ * Faces from a collection on disk, preferring a proportional script variant
+ * over the monospaced ones. Returns undefined when the file names no usable
+ * face, so the caller can move on to the next candidate.
+ */
+function facesFromCollection(file: string, boldFile?: string): PdfFaces | undefined {
+ const names = collectionFaceNames(file).filter(n => !/Mono/i.test(n))
+ if (names.length === 0) return undefined
+ const pick =
+ COLLECTION_PREFERENCE.map(re => names.find(n => re.test(n))).find(Boolean) ?? names[0]
+ const boldNames = boldFile ? collectionFaceNames(boldFile).filter(n => !/Mono/i.test(n)) : []
+ const boldPick =
+ COLLECTION_PREFERENCE.map(re => boldNames.find(n => re.test(n))).find(Boolean) ?? boldNames[0]
+ const normal: PdfFace = [file, pick]
+ const bold: PdfFace = boldFile && boldPick ? [boldFile, boldPick] : normal
+ return { normal, bold, italics: normal, bolditalics: bold }
+}
+
+/** Collections on this image, keyed by lowercased basename. */
+function embeddableCollections(): Map<string, string> {
+ if (collectionIndex) return collectionIndex
+ const index = new Map<string, string>()
+ for (const dir of SYSTEM_FONT_DIRS) {
+ try {
+ if (!fs.existsSync(dir)) continue
+ for (const file of walk(dir, 0)) {
+ if (!/\.ttc$/i.test(file)) continue
+ const stem = path
+ .basename(file)
+ .replace(/\.ttc$/i, '')
+ .toLowerCase()
+ if (!index.has(stem)) index.set(stem, file)
+ }
+ } catch {
+ continue
+ }
+ }
+ collectionIndex = index
+ return index
+}
+
+let collectionIndex: Map<string, string> | undefined
+
+/**
+ * The best CJK-capable collection the image ships, chosen by what it can
+ * actually draw rather than by its filename.
+ */
+function cjkCollectionFaces(): PdfFaces | undefined {
+ const collections = embeddableCollections()
+ let best: { faces: PdfFaces; score: number } | undefined
+ for (const [stem, file] of collections) {
+ if (!/cjk/.test(stem) || /serif/.test(stem) || /bold/.test(stem)) continue
+ const score = coverageScore(file)
+ // Rejects a symbols-only fallback, which sets no Latin and would leave the
+ // document unreadable.
+ if (score <= 0) continue
+ const boldFile = collections.get(stem.replace(/-regular$/, '-bold'))
+ const faces = facesFromCollection(file, boldFile)
+ if (faces && (!best || score > best.score)) best = { faces, score }
+ }
+ return best?.faces
+}
+
+function resolvePdfFaces(): PdfFaces {
+ if (pdfFaces) return pdfFaces
+ ensureFontsReady()
+ // A family with a real italic face comes first, since *emphasis* is drawn
+ // upright in one without; CJK falls back per character to the collection.
+ // Only an image with no standalone family takes the collection as body.
+ const named = PDF_FAMILY_PREFIXES.map(prefix => () => facesForPrefix(prefix))
+ const withItalic = named.map(faces => () => {
+ const found = faces()
+ return found && found.italics !== found.normal ? found : undefined
+ })
+ const candidates: Array<() => PdfFaces | undefined> = [
+ ...withItalic,
+ ...named,
+ cjkCollectionFaces,
+ discoverWideFace,
+ ]
+ let chosen: PdfFaces | undefined
+ for (const candidate of candidates) {
+ const faces = candidate()
+ if (faces && embeds(faces, 'Ag0')) {
+ chosen = faces
+ break
+ }
+ }
+ if (chosen) {
+ // Registering the chosen family under the PDF alias is what lets glyph
+ // coverage be measured against the faces the PDF will actually embed.
+ const file = Array.isArray(chosen.normal) ? chosen.normal[0] : chosen.normal
+ try {
+ if (typeof file === 'string') GlobalFonts.registerFromPath(file, PDF_FONT_FAMILY)
+ pdfFaces = chosen
+ return pdfFaces
+ } catch {
+ // Unparseable face: fall through to the bundled one.
+ }
+ }
+ const roboto = loadRobotoFaces()
+ GlobalFonts.register(roboto.normal, PDF_FONT_FAMILY)
+ pdfFaces = roboto
+ return pdfFaces
+}
+
+function resolveMonoFaces(): PdfFaces {
+ if (monoFaces) return monoFaces
+ ensureFontsReady()
+ for (const prefix of MONO_FAMILY_PREFIXES) {
+ const faces = facesForPrefix(prefix)
+ if (faces && embeds(faces, 'Ag0')) {
+ monoFaces = faces
+ return monoFaces
+ }
+ }
+ // No fixed-width face on this image. The body face would render the block
+ // but lose its column alignment, so Western text goes to the PDF viewer's
+ // built-in Courier and everything else falls back per character to embedded faces.
+ monoFaces = COURIER_FACES
+ return monoFaces
+}
+
+/** The standard-14 Courier. pdfkit encodes it as WinAnsi, so it can draw only that set. */
+const COURIER_FACES: PdfFaces = {
+ normal: 'Courier',
+ bold: 'Courier-Bold',
+ italics: 'Courier-Oblique',
+ bolditalics: 'Courier-BoldOblique',
+}
+
+/** Courier's advance width, in ems, for every character it is given. */
+const COURIER_ADVANCE = 0.6
+
+/** What pdfkit knows of Courier: WinAnsi coverage, and the ascent (629) and descent (-157) of its AFM. */
+const COURIER_INFO: FaceInfo = (() => {
+ const ranges: number[] = []
+ const winAnsi = [
+ 0x152, 0x153, 0x160, 0x161, 0x178, 0x17d, 0x17e, 0x192, 0x2c6, 0x2dc, 0x2013, 0x2014, 0x2018,
+ 0x2019, 0x201a, 0x201c, 0x201d, 0x201e, 0x2020, 0x2021, 0x2022, 0x2026, 0x2030, 0x2039, 0x203a,
+ 0x20ac, 0x2122,
+ ]
+ for (let cp = 0x20; cp <= 0x7e; cp++) addCodePoint(ranges, cp)
+ for (let cp = 0xa0; cp <= 0xff; cp++) addCodePoint(ranges, cp)
+ for (const cp of winAnsi) addCodePoint(ranges, cp)
+ return { ranges, metrics: { ascent: 0.629, lineHeight: 0.786 }, shapes: false, outlines: true }
+})()
+
+/** Font descriptors for `new PdfPrinter(...)`, keyed by the families pdfmake uses. */
+export function pdfFontDescriptors(): Record<string, PdfFaces> {
+ return {
+ [PDF_FONT_FAMILY]: resolvePdfFaces(),
+ [PDF_MONO_FAMILY]: resolveMonoFaces(),
+ }
+}
+
+// pdfmake embeds whatever family a run names, so a character the body face
+// lacks is drawn by giving its run another family. No CJK or Latin face carries
+// Arabic or Hebrew, so those always come from here.
+
+/**
+ * Faces tried, in order, for a character the run's own face lacks. The script
+ * faces lead so Arabic and Hebrew are set in faces drawn for them rather than
+ * in a broad face that carries a few of their letters.
+ */
+const SCRIPT_FALLBACK_PREFIXES = [
+ // Alpine's Noto Sans Arabic draws letters as a dotless base shared by several
+ // letters plus dot marks, and pdfkit's ToUnicode map gives each glyph one
+ // letter, so the text layer reads wrong letters; its UI build does not.
+ 'NotoSansArabicUI',
+ 'NotoSansArabic',
+ 'NotoNaskhArabic',
+ 'NotoKufiArabic',
+ 'NotoSansHebrew',
+ 'NotoSerifHebrew',
+ 'NotoRashiHebrew',
+]
+
+/** Tried after the script faces and the CJK collection. */
+const FALLBACK_PREFIXES = [
+ 'DejaVuSans',
+ 'NotoSans',
+ 'LiberationSans',
+ 'NotoSansSymbols2',
+ 'NotoSansSymbols',
+ 'NotoSansMath',
+]
+
+/** Other regular-weight faces from the families the images install, tried after the list above. */
+const FALLBACK_STEM = /^(noto|dejavu|liberation)[a-z0-9]*(-regular)?$/
+
+interface FallbackFamily {
+ family: string
+ faces: PdfFaces
+}
+
+/** Vertical metrics of a face in ems, as pdfkit uses them to lay out a line. */
+export interface FaceMetrics {
+ /** Height above the baseline. */
+ ascent: number
+ /** Ascent less descent: the height of one line before pdfmake's lineHeight factor. */
+ lineHeight: number
+}
+
+/** Everything a PDF typesetter needs to know about the faces available to it. */
+export interface PdfGlyphSource {
+ /** Family that can draw `cp` in a run set in `base`, or undefined when no face can. */
+ familyFor(cp: number, base: string): string | undefined
+ /** Whether fontkit puts a right-to-left run set in `family` into display order itself. */
+ reversesRtl(family: string): boolean
+ /** Advance width of `text` set in `family` at `size` points. */
+ measure(text: string, family: string, size: number, bold: boolean): number
+ /** Vertical metrics of `family`, or undefined when unknown. */
+ metrics(family: string): FaceMetrics | undefined
+ /** pdfmake descriptors for `families`, always including the body and mono ones. */
+ descriptors(families: Iterable<string>): Record<string, PdfFaces>
+}
+
+function faceFile(face: PdfFace): string | undefined {
+ if (Buffer.isBuffer(face)) return undefined
+ return Array.isArray(face) ? face[0] : face
+}
+
+/**
+ * Whether pdfkit can lay out and embed `ch` in `faces`. Some faces an image
+ * ships parse for their cmap yet fail inside pdfkit ("Not a fixed size"), and
+ * one such face named by a single run fails the whole document.
+ */
+function embeds(faces: PdfFaces, ch: string): boolean {
+ try {
+ const PdfPrinter = require('pdfmake')
+ const doc = new PdfPrinter({ Probe: faces }).createPdfKitDocument({
+ content: [{ text: ch, font: 'Probe' }],
+ defaultStyle: { font: 'Probe' },
+ })
+ doc.on('data', () => undefined)
+ doc.end()
+ return true
+ } catch {
+ return false
+ }
+}
+
+function discoverFallbacks(exclude: Set<string>): FallbackFamily[] {
+ const out: FallbackFamily[] = []
+ const seen = new Set<string>()
+ const add = (prefix: string): void => {
+ const faces = facesForPrefix(prefix)
+ const file = faces && faceFile(faces.normal)
+ if (!faces || !file || seen.has(file) || exclude.has(file)) return
+ seen.add(file)
+ out.push({ family: `Fallback-${prefix}`, faces })
+ }
+ SCRIPT_FALLBACK_PREFIXES.forEach(add)
+ const cjk = cjkCollectionFaces()
+ const cjkFile = cjk && faceFile(cjk.normal)
+ if (cjk && cjkFile && !exclude.has(cjkFile)) {
+ seen.add(cjkFile)
+ out.push({ family: 'Fallback-CJK', faces: cjk })
+ }
+ FALLBACK_PREFIXES.forEach(add)
+ const rest = [...embeddableFaces().keys()]
+ .filter(stem => FALLBACK_STEM.test(stem) && !/mono|emoji/.test(stem))
+ .sort((a, b) => Number(/serif/.test(a)) - Number(/serif/.test(b)) || a.localeCompare(b))
+ for (const stem of rest)
+ add(path.basename(embeddableFaces().get(stem)!).replace(/(-Regular)?\.(ttf|otf)$/i, ''))
+ return out
+}
+
+class GlyphSource implements PdfGlyphSource {
+ private readonly info = new Map<string, FaceInfo | undefined>()
+ private readonly chosen = new Map<string, string | undefined>()
+ private readonly embeddable = new Map<string, boolean>()
+ // resolvePdfFaces registers the body family with the canvas itself.
+ private readonly registered = new Set<string>([PDF_FONT_FAMILY])
+ private fallbacks?: FallbackFamily[]
+ private ctx?: SKRSContext2D
+
+ private facesOf(family: string): PdfFaces | undefined {
+ if (family === PDF_FONT_FAMILY) return resolvePdfFaces()
+ if (family === PDF_MONO_FAMILY) return resolveMonoFaces()
+ return this.fallbackList().find(f => f.family === family)?.faces
+ }
+
+ private fallbackList(): FallbackFamily[] {
+ if (!this.fallbacks) {
+ const exclude = new Set<string>()
+ for (const faces of [resolvePdfFaces(), resolveMonoFaces()]) {
+ const file = faceFile(faces.normal)
+ if (file) exclude.add(file)
+ }
+ this.fallbacks = discoverFallbacks(exclude)
+ }
+ return this.fallbacks
+ }
+
+ private infoOf(family: string): FaceInfo | undefined {
+ if (!this.info.has(family)) {
+ const faces = this.facesOf(family)
+ let info: FaceInfo | undefined
+ if (faces === COURIER_FACES) info = COURIER_INFO
+ else if (faces) info = readFaceInfo(faces.normal)
+ this.info.set(family, info?.outlines ? info : undefined)
+ }
+ return this.info.get(family)
+ }
+
+ private covers(family: string, cp: number): boolean {
+ const info = this.infoOf(family)
+ return info !== undefined && coversCodePoint(info.ranges, cp)
+ }
+
+ /** A fallback face is tried in pdfkit once, with the first character it is chosen for. */
+ private usable(fallback: FallbackFamily, cp: number): boolean {
+ let ok = this.embeddable.get(fallback.family)
+ if (ok === undefined) {
+ ok = embeds(fallback.faces, String.fromCodePoint(cp))
+ this.embeddable.set(fallback.family, ok)
+ }
+ return ok
+ }
+
+ familyFor(cp: number, base: string): string | undefined {
+ const key = `${base}\u0000${cp}`
+ if (this.chosen.has(key)) return this.chosen.get(key)
+ let hit: string | undefined
+ if (this.covers(base, cp)) hit = base
+ else if (base !== PDF_FONT_FAMILY && this.covers(PDF_FONT_FAMILY, cp)) hit = PDF_FONT_FAMILY
+ else {
+ hit = this.fallbackList().find(f => this.covers(f.family, cp) && this.usable(f, cp))?.family
+ }
+ this.chosen.set(key, hit)
+ return hit
+ }
+
+ reversesRtl(family: string): boolean {
+ return this.infoOf(family)?.shapes ?? false
+ }
+
+ metrics(family: string): FaceMetrics | undefined {
+ return this.infoOf(family)?.metrics
+ }
+
+ measure(text: string, family: string, size: number, bold: boolean): number {
+ const faces = this.facesOf(family)
+ if (!faces || faces === COURIER_FACES) return [...text].length * size * COURIER_ADVANCE
+ // The bold face is registered on its own, because the canvas would
+ // otherwise embolden the regular one, which is narrower than the face
+ // pdfkit embeds.
+ const face = bold ? faces.bold : faces.normal
+ const alias = bold ? `${family} Bold` : family
+ if (!this.registered.has(alias)) {
+ this.registered.add(alias)
+ ensureFontsReady()
+ try {
+ if (Buffer.isBuffer(face)) GlobalFonts.register(face, alias)
+ else GlobalFonts.registerFromPath(faceFile(face)!, alias)
+ } catch {
+ // Measured with the canvas default instead; only line breaking is approximate.
+ }
+ }
+ this.ctx ??= createCanvas(8, 8).getContext('2d')
+ this.ctx.font = `${size}px "${alias}"`
+ return this.ctx.measureText(text).width
+ }
+
+ descriptors(families: Iterable<string>): Record<string, PdfFaces> {
+ const out = pdfFontDescriptors()
+ for (const family of families) {
+ const faces = this.facesOf(family)
+ if (faces) out[family] = faces
+ }
+ return out
+ }
+}
+
+let glyphSource: GlyphSource | undefined
+
+/** The faces this image offers the PDF renderer, with per-character fallback between them. */
+export function pdfGlyphSource(): PdfGlyphSource {
+ glyphSource ??= new GlyphSource()
+ return glyphSource
+}
+
+// ─── Glyph coverage ──────────────────────────────────────────────────
+//
+// Chart text is checked by rendering it through the canvas fallback stack.
+// PDFs do not use this: pdfGlyphSource reads each face's cmap and falls back
+// per character.
+
+let missingSignature: string | undefined
+const coverage = new Map<number, boolean>()
+
+/**
+ * Signature of the pixels a character leaves when drawn in `font`.
+ *
+ * A plain ink count is not enough to tell a real glyph from the missing-glyph
+ * box: the two collide whenever they happen to darken the same number of
+ * pixels, and the character is then rewritten even though the font could draw
+ * it. Hashing the bitmap makes a collision effectively impossible.
+ */
+function renderSignature(ch: string, font: string): string {
+ const canvas = createCanvas(64, 64)
+ const ctx = canvas.getContext('2d')
+ ctx.fillStyle = '#ffffff'
+ ctx.fillRect(0, 0, 64, 64)
+ ctx.fillStyle = '#000000'
+ ctx.font = `36px ${font}`
+ ctx.fillText(ch, 6, 46)
+ const data = ctx.getImageData(0, 0, 64, 64).data
+ // FNV-1a over the thresholded (ink / no ink) bitmap, plus the ink count so an
+ // all-blank render stands out when debugging.
+ let hash = 0x811c9dc5
+ let ink = 0
+ for (let i = 0; i < data.length; i += 4) {
+ const dark = data[i] < 128 ? 1 : 0
+ if (dark) ink++
+ hash ^= dark
+ hash = Math.imul(hash, 0x01000193) >>> 0
+ }
+ return `${ink}:${hash.toString(36)}`
+}
+
+/**
+ * Whether the chart fonts can actually draw `ch`. Determined by rendering,
+ * because a font reports a width for glyphs it substitutes.
+ */
+export function canRender(ch: string): boolean {
+ const cp = ch.codePointAt(0)
+ if (cp === undefined || cp < 0x80) return true
+ const cached = coverage.get(cp)
+ if (cached !== undefined) return cached
+ let ok: boolean
+ try {
+ ensureFontsReady()
+ missingSignature ??= renderSignature(MISSING_PROBE, CHART_FONT_STACK)
+ ok = renderSignature(ch, CHART_FONT_STACK) !== missingSignature
+ } catch {
+ ok = false
+ }
+ coverage.set(cp, ok)
+ return ok
+}
+
+/**
+ * ASCII stand-ins for symbols models reach for constantly. Applied only when
+ * the character cannot be drawn, so a renderer whose fonts carry the glyph
+ * keeps the original.
+ */
+const SUBSTITUTIONS: Record<string, string> = {
+ '\u2192': '->',
+ '\u27F6': '->',
+ '\u279C': '->',
+ '\u2794': '->',
+ '\u2190': '<-',
+ '\u2194': '<->',
+ '\u21D2': '=>',
+ '\u21D0': '<=',
+ '\u21D4': '<=>',
+ '\u2191': '^',
+ '\u2193': 'v',
+ '\u2713': 'OK',
+ '\u2714': 'OK',
+ '\u2611': '[x]',
+ '\u2717': 'X',
+ '\u2718': 'X',
+ '\u2612': '[x]',
+ '\u2248': '~',
+ '\u2265': '>=',
+ '\u2264': '<=',
+ '\u2260': '!=',
+ '\u2261': '==',
+ '\u221E': 'inf',
+ '\u2022': '*',
+ '\u2023': '-',
+ '\u25AA': '-',
+ '\u25AB': '-',
+ '\u25E6': '-',
+ '\u25CF': '*',
+ '\u25CB': 'o',
+ '\u2605': '*',
+ '\u2606': '*',
+ '\u26A0': '!',
+ '\u2122': '(TM)',
+ '\u2120': '(SM)',
+ '\u2014': '-',
+ '\u2013': '-',
+ '\u2026': '...',
+ '\u201C': '"',
+ '\u201D': '"',
+ '\u2018': "'",
+ '\u2019': "'",
+ '\u2010': '-',
+ '\u2011': '-',
+ '\u2212': '-',
+ // Space variants: locale-formatted numbers and times carry U+202F and U+00A0.
+ '\u00A0': ' ',
+ '\u2000': ' ',
+ '\u2001': ' ',
+ '\u2002': ' ',
+ '\u2003': ' ',
+ '\u2004': ' ',
+ '\u2005': ' ',
+ '\u2006': ' ',
+ '\u2007': ' ',
+ '\u2008': ' ',
+ '\u2009': ' ',
+ '\u200A': ' ',
+ '\u202F': ' ',
+ '\u205F': ' ',
+ '\u3000': ' ',
+ // Status emoji, which models often put alone in a table cell. No embedded
+ // face draws them in colour, and a coloured circle means only its colour,
+ // so they become words.
+ '\u2705': 'OK',
+ '\u2716': 'X',
+ '\u274c': 'X',
+ '\u274e': 'X',
+ '\u2757': '!',
+ '\u2755': '!',
+ '\u2753': '?',
+ '\u2754': '?',
+ '\u2b50': '*',
+ '\u2b06': '^',
+ '\u2b07': 'v',
+ '\u27a1': '->',
+ '\u2b05': '<-',
+ '\u{1F7E2}': '(green)',
+ '\u{1F7E1}': '(yellow)',
+ '\u{1F7E0}': '(orange)',
+ '\u{1F534}': '(red)',
+ '\u{1F535}': '(blue)',
+ '\u{1F7E3}': '(purple)',
+ '\u{1F7E4}': '(brown)',
+ '\u26ab': '(black)',
+ '\u26aa': '(white)',
+ '\u{1F7E9}': '(green)',
+ '\u{1F7E8}': '(yellow)',
+ '\u{1F7E7}': '(orange)',
+ '\u{1F7E5}': '(red)',
+ '\u{1F7E6}': '(blue)',
+ '\u{1F7EA}': '(purple)',
+ '\u{1F7EB}': '(brown)',
+ '\u2b1b': '(black)',
+ '\u2b1c': '(white)',
+ '\u{1F4C8}': '(up)',
+ '\u{1F4C9}': '(down)',
+}
+
+/** The ASCII stand-in for a symbol or status emoji, when one is defined. */
+export function asciiStandIn(ch: string): string | undefined {
+ return SUBSTITUTIONS[ch]
+}
+
+/** Zero-width joiners, variation selectors and byte-order marks — safe to drop. */
+const INVISIBLE = /[\u200B-\u200F\u2060\uFE00-\uFE0F\uFEFF]/g
+
+const NON_ASCII = /[^\x00-\x7F]/
+
+/**
+ * Rewrite chart text so every character survives rendering. Characters the
+ * chart fonts cover are untouched; the rest become their ASCII stand-in, and
+ * anything with no stand-in is dropped rather than drawn as a blank box.
+ */
+export function sanitizeForFont(text: string): string {
+ if (!text || !NON_ASCII.test(text)) return text
+
+ let out = ''
+ for (const ch of text.replace(INVISIBLE, '')) {
+ if (canRender(ch)) {
+ out += ch
+ continue
+ }
+ const sub = SUBSTITUTIONS[ch]
+ if (sub !== undefined) out += sub
+ // No stand-in and no glyph: dropped, which keeps the surrounding text
+ // legible instead of drawing a blank box or a different character.
+ }
+ return out
+}
diff --git a/mcp-host/src/workflow/inlineMarkup.ts b/mcp-host/src/workflow/inlineMarkup.ts
new file mode 100644
index 000000000..ecbc01cdf
--- /dev/null
+++ b/mcp-host/src/workflow/inlineMarkup.ts
@@ -0,0 +1,449 @@
+/**
+ * Inline markdown, and the bits of HTML models mix into it, read once for the
+ * PDF and DOCX generators so both print the same text the same way.
+ *
+ * Every pattern here runs on text a model wrote, so none may backtrack across
+ * the input: each stops at the next tag, bracket or marker of its own kind.
+ */
+
+// A tag's attributes. Each takes a value unless it is one of HTML's boolean
+// attributes, so text such as "a<b and c>d" is not read as a <b> tag.
+const ATTRIBUTES =
+ '(?:\\s+(?:(?:allowfullscreen|async|checked|controls|default|defer|disabled|hidden|inert|' +
+ 'loop|multiple|muted|nowrap|open|readonly|required|reversed|selected)(?![-\\w:.=])|' +
+ '[A-Za-z_:][-\\w:.]*\\s*=\\s*(?:"[^"<>]*"|\'[^\'<>]*\'|[^\\s"\'=<>`]+)))*\\s*'
+
+/** Opening and closing tags named by the `names` alternatives, with their attributes. */
+const tag = (names: string) => `</?(?:${names})${ATTRIBUTES}>`
+
+const SCRIPT_OPEN = /<(script|style)\b[^<>]*>/gi
+const LINE_BREAK = /<br\s*\/?>/gi
+// A block or cell boundary ends a word even when no space surrounds the tags.
+const BLOCK_EDGE = new RegExp(
+ `(?:${tag(
+ 'article|blockquote|caption|dd|details|div|dt|figcaption|figure|footer|h[1-6]|header|li|ol|p|pre|section|summary|table|tr|ul'
+ )}\\s*)+`,
+ 'gi'
+)
+const CELL_EDGE = new RegExp(`(?:${tag('t[dh]')}\\s*)+`, 'gi')
+const BOLD_TAG = new RegExp(tag('b|strong'), 'gi')
+const ITALIC_TAG = new RegExp(tag('i|em'), 'gi')
+const CODE_TAG = new RegExp(tag('code|kbd|tt'), 'gi')
+const STRIKE_TAG = new RegExp(tag('del|s|strike'), 'gi')
+const LIST_TAG = new RegExp(`<(/?)(ul|ol|li)${ATTRIBUTES}>`, 'gi')
+const IMG_TAG = /<img\b[^<>]*>/gi
+const IMG_SRC = /\bsrc\s*=\s*(["'])([^"'<>]+)\1/i
+/** A backslash before ASCII punctuation, which CommonMark prints as that character. */
+const ESCAPE = /\\[!-/:-@[-`{-~]/
+// The label stops at the next anchor tag, so an unclosed <a> is not rescanned
+// to the end of the text from every opening.
+const ANCHOR =
+ /<a\s[^<>]*?href\s*=\s*["']((?:https?:\/\/|mailto:)[^"'\s<>]+)["'][^<>]*>((?:[^<]|<(?!\/?a[\s>]))*?)<\/a\s*>/gi
+
+// Only real element names are removed, so a placeholder such as <namespace>
+// in a command survives as text.
+const HTML_TAG = new RegExp(
+ '</?(?:' +
+ [
+ 'a',
+ 'abbr',
+ 'article',
+ 'aside',
+ 'big',
+ 'blockquote',
+ 'caption',
+ 'center',
+ 'cite',
+ 'dd',
+ 'del',
+ 'details',
+ 'div',
+ 'dl',
+ 'dt',
+ 'figcaption',
+ 'figure',
+ 'font',
+ 'footer',
+ 'h[1-6]',
+ 'header',
+ 'hr',
+ 'img',
+ 'ins',
+ 'label',
+ 'li',
+ 'mark',
+ 'nav',
+ 'ol',
+ 'p',
+ 'pre',
+ 's',
+ 'script',
+ 'section',
+ 'small',
+ 'span',
+ 'strike',
+ 'style',
+ 'sub',
+ 'summary',
+ 'sup',
+ 'table',
+ 'tbody',
+ 'td',
+ 'tfoot',
+ 'th',
+ 'thead',
+ 'time',
+ 'tr',
+ 'u',
+ 'ul',
+ ].join('|') +
+ `)${ATTRIBUTES}/?>`,
+ 'gi'
+)
+
+const NAMED_ENTITIES: Record<string, string> = {
+ amp: '&',
+ lt: '<',
+ gt: '>',
+ quot: '"',
+ apos: "'",
+ nbsp: '\u00A0',
+ ndash: '\u2013',
+ mdash: '\u2014',
+ hellip: '\u2026',
+ lsquo: '\u2018',
+ rsquo: '\u2019',
+ ldquo: '\u201C',
+ rdquo: '\u201D',
+ laquo: '\u00AB',
+ raquo: '\u00BB',
+ middot: '\u00B7',
+ bull: '\u2022',
+ times: '\u00D7',
+ divide: '\u00F7',
+ deg: '\u00B0',
+ copy: '\u00A9',
+ reg: '\u00AE',
+ trade: '\u2122',
+ euro: '\u20AC',
+ pound: '\u00A3',
+ yen: '\u00A5',
+ cent: '\u00A2',
+}
+
+/** Code points XML 1.0 can carry; a numeric reference to anything else stays literal. */
+function xmlAllowed(cp: number): boolean {
+ return (
+ cp === 0x9 ||
+ cp === 0xa ||
+ (cp >= 0x20 && cp <= 0xd7ff) ||
+ (cp >= 0xe000 && cp <= 0xfffd) ||
+ (cp >= 0x10000 && cp <= 0x10ffff)
+ )
+}
+
+/** Character references decoded; an unknown or unrepresentable one stays as written. */
+export function decodeEntities(text: string): string {
+ if (!text.includes('&')) return text
+ return text.replace(/&(#x[0-9a-f]{1,6}|#\d{1,7}|[a-z]{2,8});/gi, (entity, name: string) => {
+ if (name.startsWith('#')) {
+ const cp =
+ name[1] === 'x' || name[1] === 'X' ? parseInt(name.slice(2), 16) : parseInt(name.slice(1))
+ return xmlAllowed(cp) ? String.fromCodePoint(cp) : entity
+ }
+ return NAMED_ENTITIES[name.toLowerCase()] ?? entity
+ })
+}
+
+/** `text` without HTML comments, found in one pass; an unclosed one is left as written. */
+function withoutComments(text: string): string {
+ if (!text.includes('<!--')) return text
+ let out = ''
+ let at = 0
+ for (let open = text.indexOf('<!--'); open >= 0; open = text.indexOf('<!--', at)) {
+ const close = text.indexOf('-->', open + 4)
+ if (close < 0) break
+ out += text.slice(at, open)
+ at = close + 3
+ }
+ return out + text.slice(at)
+}
+
+/** `text` without <script> and <style> elements, found in one pass. */
+function withoutScripts(text: string): string {
+ if (!/<(?:script|style)\b/i.test(text)) return text
+ const lower = text.toLowerCase()
+ let out = ''
+ let at = 0
+ SCRIPT_OPEN.lastIndex = 0
+ for (let open = SCRIPT_OPEN.exec(text); open; open = SCRIPT_OPEN.exec(text)) {
+ const close = lower.indexOf(`</${open[1].toLowerCase()}`, SCRIPT_OPEN.lastIndex)
+ const end = close < 0 ? -1 : lower.indexOf('>', close)
+ if (end < 0) break
+ out += text.slice(at, open.index)
+ at = end + 1
+ SCRIPT_OPEN.lastIndex = at
+ }
+ return out + text.slice(at)
+}
+
+/**
+ * Replace `pattern` with `separator` between words, and with nothing at either
+ * end of `text`. A match that already spans a line break keeps the break.
+ */
+function separate(text: string, pattern: RegExp, separator: string): string {
+ return text.replace(pattern, (match: string, offset: number) =>
+ offset === 0 || offset + match.length === text.length
+ ? ''
+ : match.includes('\n')
+ ? '\n'
+ : separator
+ )
+}
+
+/**
+ * Each <li> given the marker its list shows, a bullet or its number, so a list
+ * written in HTML keeps its items apart once the tags are gone.
+ */
+function withListMarkers(text: string): string {
+ if (!/<li\b/i.test(text)) return text
+ const lists: Array<{ ordered: boolean; count: number }> = []
+ return text.replace(LIST_TAG, (tag: string, close: string, name: string) => {
+ const kind = name.toLowerCase()
+ if (kind !== 'li') {
+ if (close) lists.pop()
+ else lists.push({ ordered: kind === 'ol', count: 0 })
+ return tag
+ }
+ if (close) return tag
+ const list = lists[lists.length - 1]
+ return `${tag}${list?.ordered ? `${++list.count}. ` : '\u2022 '}`
+ })
+}
+
+/** An <img> tag as the markdown image it names, or nothing when it names no source. */
+function imageMarkdown(tag: string): string {
+ const src = IMG_SRC.exec(tag)?.[2].trim()
+ return src ? `![](${src})` : ''
+}
+
+function htmlSegmentToMarkdown(text: string): string {
+ const html = withListMarkers(withoutScripts(withoutComments(text))).replace(LINE_BREAK, '\n')
+ return separate(separate(html, BLOCK_EDGE, '\n'), CELL_EDGE, ' ')
+ .replace(IMG_TAG, imageMarkdown)
+ .replace(ANCHOR, (_m, href: string, label: string) => `[${label}](${href})`)
+ .replace(BOLD_TAG, '**')
+ .replace(ITALIC_TAG, '*')
+ .replace(CODE_TAG, '`')
+ .replace(STRIKE_TAG, '~~')
+ .replace(HTML_TAG, '')
+}
+
+function htmlSegmentToPlainText(text: string): string {
+ return decodeEntities(
+ withoutScripts(withoutComments(text))
+ .replace(LINE_BREAK, ' ')
+ .replace(BLOCK_EDGE, ' ')
+ .replace(CELL_EDGE, ' ')
+ .replace(ANCHOR, (_m, _href: string, label: string) => label)
+ .replace(BOLD_TAG, '')
+ .replace(ITALIC_TAG, '')
+ .replace(CODE_TAG, '')
+ .replace(STRIKE_TAG, '')
+ .replace(HTML_TAG, '')
+ )
+}
+
+function mapOutsideCode(text: string, convert: (segment: string) => string): string {
+ return text
+ .split(/(`[^`\n]+`)/)
+ .map((part, i) => (i % 2 === 1 ? part : convert(part)))
+ .join('')
+}
+
+/**
+ * Inline HTML as the markdown the span reader understands: <br> and block
+ * edges become line breaks, <b>/<i>/<code>/<s>/<a>/<img> their markdown forms,
+ * and other tags are dropped. Entities stay encoded until the spans are read,
+ * so an encoded asterisk prints instead of starting emphasis. Code spans are
+ * left as written.
+ */
+export function htmlToMarkdownInline(text: string): string {
+ if (!text.includes('<')) return text
+ return mapOutsideCode(text, htmlSegmentToMarkdown)
+}
+
+/** Inline HTML reduced to its text, for titles and other places that take no formatting. */
+export function htmlToPlainText(text: string): string {
+ const plain =
+ text.includes('<') || text.includes('&') ? mapOutsideCode(text, htmlSegmentToPlainText) : text
+ return plain.replace(/[ \t\r\n]+/g, ' ').trim()
+}
+
+/** Like htmlToPlainText, line by line: line breaks, <br> included, are kept. */
+export function htmlToPlainLines(text: string): string {
+ return text
+ .replace(LINE_BREAK, '\n')
+ .split('\n')
+ .map(line => htmlToPlainText(line))
+ .join('\n')
+}
+
+/** A heading's text without its optional closing run of hashes (`## Title ##`). */
+export function withoutClosingHashes(text: string): string {
+ const t = text.trimEnd()
+ let end = t.length
+ while (end > 0 && t[end - 1] === '#') end--
+ if (end === t.length) return t
+ if (end === 0) return ''
+ return /\s/.test(t[end - 1]) ? t.slice(0, end).trimEnd() : t
+}
+
+/**
+ * The paragraphs of a block quote, from its lines without their `>` marker. A
+ * quoted line left empty ends a paragraph; the lines of one paragraph run on,
+ * joined by a space. A quote with no text is one empty paragraph.
+ */
+export function quoteParagraphs(lines: string[]): string[] {
+ const paragraphs: string[] = []
+ let current: string[] = []
+ for (const line of [...lines, '']) {
+ if (line.trim()) {
+ current.push(line)
+ } else if (current.length > 0) {
+ paragraphs.push(current.join(' '))
+ current = []
+ }
+ }
+ return paragraphs.length > 0 ? paragraphs : ['']
+}
+
+// No part may run into the next opening bracket or parenthesis: otherwise an
+// unclosed image or link is rescanned to the end of the line from every
+// opening, which takes minutes on a long line. As in CommonMark, a marker with
+// a space on its inner side is not emphasis, so `5 * 3 * 2` keeps its
+// asterisks, and no emphasis may span a marker of its own kind, which keeps
+// every scan short.
+const INLINE_TOKEN = new RegExp(
+ [
+ /!\[[^[\]\n]*\]\((?:[^()\n]|\([^()\n]*\))*\)/.source,
+ /\[[^[\]\n]+\]\((?:https?:\/\/|mailto:)(?:[^\s()]|\([^\s()]*\))+\)/.source,
+ /`[^`]+`/.source,
+ ESCAPE.source,
+ /(?<!\*)\*\*\*(?![\s*])[^*]*[^\s*\\]\*\*\*(?!\*)/.source,
+ /\*\*(?![\s*])(?:[^*]|\*(?!\*))*?[^\s*\\]\*\*/.source,
+ /(?<!\*)\*(?![\s*])[^*]*[^\s*\\]\*(?!\*)/.source,
+ /~~(?![\s~])[^~\n]*[^\s~\\]~~/.source,
+ ].join('|'),
+ 'g'
+)
+
+function unescapeMarkdown(text: string): string {
+ return text.replace(new RegExp(ESCAPE.source, 'g'), escaped => escaped.slice(1))
+}
+
+/**
+ * The file named between the parentheses of `![alt](...)`: `<my chart.png>`,
+ * or `chart.png`, either with an optional title after it. The rest is read
+ * whole, so a name with spaces written without angle brackets still names its file.
+ */
+export function imageTarget(inside: string): string {
+ const t = inside.trim()
+ const angle = /^<([^<>\n]*)>/.exec(t)
+ const titled = /^(.*?)\s+(?:"[^"\n]*"|'[^'\n]*'|\([^()\n]*\))$/.exec(t)
+ return decodeEntities(unescapeMarkdown(angle ? angle[1] : titled ? titled[1] : t))
+}
+
+/** One stretch of inline text and the formatting it carries. */
+export interface InlineSpan {
+ text: string
+ bold?: boolean
+ italics?: boolean
+ strike?: boolean
+ code?: boolean
+ /** Target of a link; the span's text is its label. */
+ link?: string
+ /** An image written inside the text: the span's text is its alt text. */
+ image?: string
+}
+
+type SpanStyle = Pick<InlineSpan, 'bold' | 'italics' | 'strike'>
+
+/** Whether `span` can take on the text of `next`: both plain, formatted alike. */
+function joins(span: InlineSpan, next: InlineSpan): boolean {
+ return (
+ span.link === undefined &&
+ next.link === undefined &&
+ span.image === undefined &&
+ next.image === undefined &&
+ !span.code &&
+ !next.code &&
+ !!span.bold === !!next.bold &&
+ !!span.italics === !!next.italics &&
+ !!span.strike === !!next.strike
+ )
+}
+
+function appendSpans(source: string, style: SpanStyle, out: InlineSpan[]): void {
+ const pattern = new RegExp(INLINE_TOKEN)
+ let at = 0
+ const plain = (text: string) => {
+ if (text) out.push({ ...style, text: decodeEntities(text) })
+ }
+ for (let m = pattern.exec(source); m; m = pattern.exec(source)) {
+ plain(source.slice(at, m.index))
+ const token = m[0]
+ if (token.startsWith('![')) {
+ const split = token.indexOf('](')
+ out.push({
+ ...style,
+ text: decodeEntities(unescapeMarkdown(token.slice(2, split))),
+ image: imageTarget(token.slice(split + 2, -1)),
+ })
+ } else if (token.startsWith('[')) {
+ const split = token.indexOf('](')
+ out.push({
+ ...style,
+ text: decodeEntities(unescapeMarkdown(token.slice(1, split))),
+ link: decodeEntities(token.slice(split + 2, -1)),
+ })
+ } else if (token.startsWith('`')) {
+ out.push({ ...style, text: token.slice(1, -1), code: true })
+ } else if (token.startsWith('\\')) {
+ out.push({ ...style, text: token.slice(1) })
+ } else if (token.startsWith('***')) {
+ appendSpans(token.slice(3, -3), { ...style, bold: true, italics: true }, out)
+ } else if (token.startsWith('**')) {
+ appendSpans(token.slice(2, -2), { ...style, bold: true }, out)
+ } else if (token.startsWith('~~')) {
+ appendSpans(token.slice(2, -2), { ...style, strike: true }, out)
+ } else {
+ appendSpans(token.slice(1, -1), { ...style, italics: true }, out)
+ }
+ at = pattern.lastIndex
+ }
+ plain(source.slice(at))
+}
+
+/**
+ * The spans of one block of markdown already through htmlToMarkdownInline:
+ * **bold**, *italic*, ***both***, ~~strike~~, `code`, [links](https://...),
+ * ![images](file.png) and backslash escapes.
+ */
+export function markdownSpans(markdown: string): InlineSpan[] {
+ const spans: InlineSpan[] = []
+ appendSpans(markdown, {}, spans)
+ // An escape or an empty marker pair splits text that prints as one run.
+ const joined: InlineSpan[] = []
+ for (const span of spans) {
+ const last = joined[joined.length - 1]
+ if (last && joins(last, span)) last.text += span.text
+ else joined.push(span)
+ }
+ return joined
+}
+
+/** The spans of one block of inline markdown that may carry HTML. */
+export function inlineSpans(text: string): InlineSpan[] {
+ return markdownSpans(htmlToMarkdownInline(text))
+}
diff --git a/mcp-host/src/workflow/schemaArguments.ts b/mcp-host/src/workflow/schemaArguments.ts
new file mode 100644
index 000000000..ad455cc9e
--- /dev/null
+++ b/mcp-host/src/workflow/schemaArguments.ts
@@ -0,0 +1,129 @@
+/**
+ * A generator's arguments read against its own schema: a null sent for an
+ * optional argument counts as unset, and arguments the schema does not declare
+ * are reported back to the model instead of being dropped silently.
+ */
+
+type SchemaNode = {
+ type?: unknown
+ properties?: Record<string, SchemaNode>
+ required?: string[]
+ items?: SchemaNode
+ anyOf?: SchemaNode[]
+ additionalProperties?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function typesOf(node: SchemaNode | undefined): string[] {
+ const t = node?.type
+ return Array.isArray(t) ? t : typeof t === 'string' ? [t] : []
+}
+
+/** The node to follow for `value`: the node itself, or its anyOf branch of the value's type. */
+function nodeFor(node: SchemaNode | undefined, value: unknown): SchemaNode | undefined {
+ if (!node?.anyOf) return node
+ const type = Array.isArray(value) ? 'array' : isRecord(value) ? 'object' : undefined
+ return type ? node.anyOf.find(branch => typesOf(branch).includes(type)) : undefined
+}
+
+function allowsNull(node: SchemaNode | undefined): boolean {
+ return typesOf(node).includes('null') || !!node?.anyOf?.some(b => typesOf(b).includes('null'))
+}
+
+/**
+ * `value` without the null properties its schema neither requires nor allows.
+ * Many models send null for every optional argument they leave unset, and the
+ * runtimes already read null as absent.
+ */
+export function withoutUnsetNulls(schema: unknown, value: unknown, depth = 0): unknown {
+ const node = nodeFor(schema as SchemaNode, value)
+ if (!node || depth > 64) return value
+ if (Array.isArray(value)) {
+ return node.items ? value.map(item => withoutUnsetNulls(node.items, item, depth + 1)) : value
+ }
+ if (!isRecord(value) || !node.properties) return value
+ const required = new Set(node.required ?? [])
+ const out: Record<string, unknown> = {}
+ for (const [key, item] of Object.entries(value)) {
+ const child = node.properties[key]
+ if (item === null && child && !required.has(key) && !allowsNull(child)) continue
+ Object.defineProperty(out, key, {
+ value: child ? withoutUnsetNulls(child, item, depth + 1) : item,
+ enumerable: true,
+ writable: true,
+ configurable: true,
+ })
+ }
+ return out
+}
+
+function readablePath(parts: Array<string | number>): string {
+ return parts
+ .map((part, i) => (typeof part === 'number' ? `[${part}]` : i === 0 ? part : `.${part}`))
+ .join('')
+}
+
+interface UnknownArgument {
+ path: string
+ holder: Record<string, unknown>
+ key: string
+}
+
+function unknownEntries(schema: unknown, value: unknown): UnknownArgument[] {
+ const found: UnknownArgument[] = []
+ const visit = (raw: SchemaNode | undefined, item: unknown, at: Array<string | number>) => {
+ const node = nodeFor(raw, item)
+ if (!node || at.length > 64) return
+ if (Array.isArray(item)) {
+ if (node.items) item.forEach((entry, i) => visit(node.items, entry, [...at, i]))
+ return
+ }
+ if (!isRecord(item) || !node.properties || node.additionalProperties !== undefined) return
+ for (const [key, entry] of Object.entries(item)) {
+ const child = node.properties[key]
+ if (child) visit(child, entry, [...at, key])
+ else found.push({ path: readablePath([...at, key]), holder: item, key })
+ }
+ }
+ visit(schema as SchemaNode, value, [])
+ return found
+}
+
+/**
+ * Arguments the schema does not declare. An extra key is not a validation
+ * error (additionalProperties is not a field every provider accepts), so these
+ * are reported back instead. Objects that declare additionalProperties are
+ * open maps and are not checked.
+ */
+export function unknownArguments(schema: unknown, value: unknown): string[] {
+ return unknownEntries(schema, value).map(entry => entry.path)
+}
+
+/**
+ * The undeclared arguments of `value`, each made a getter that records whether
+ * it was read, so that after a generator ran `ignored()` names only the ones it
+ * never looked at. A generator reads some arguments under names the schema
+ * leaves out; those are not ignored. `value` must be the caller's own copy.
+ */
+export function watchUnknownArguments(schema: unknown, value: unknown): { ignored(): string[] } {
+ const entries = unknownEntries(schema, value)
+ const read = new Set<number>()
+ entries.forEach(({ holder, key }, i) => {
+ let current = holder[key]
+ Object.defineProperty(holder, key, {
+ get() {
+ read.add(i)
+ return current
+ },
+ set(next: unknown) {
+ current = next
+ },
+ enumerable: true,
+ configurable: true,
+ })
+ })
+ return { ignored: () => entries.filter((_, i) => !read.has(i)).map(entry => entry.path) }
+}
diff --git a/mcp-host/src/workflow/tableRows.ts b/mcp-host/src/workflow/tableRows.ts
new file mode 100644
index 000000000..8e110d1f3
--- /dev/null
+++ b/mcp-host/src/workflow/tableRows.ts
@@ -0,0 +1,78 @@
+/**
+ * Table rows in the shapes models send them, including `{Header: value}`
+ * records, as arrays of cells in header order.
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Header text as it is displayed: a year sent as 2026 is still a header. */
+export function headerText(header: unknown): string {
+ return header === null || header === undefined ? '' : String(header)
+}
+
+/**
+ * `rows` as arrays of cells. A record is read by header name, exactly or
+ * ignoring case and surrounding space; without headers its values are taken in
+ * key order. Anything else is dropped. Each kind of repair is reported once in
+ * `warnings`, prefixed with `label`.
+ */
+export function normalizeTableRows(
+ rows: unknown,
+ headers: unknown[] | undefined,
+ label: string,
+ warnings: string[]
+): unknown[][] {
+ if (rows === undefined || rows === null) return []
+ if (!Array.isArray(rows)) {
+ warnings.push(`${label}: rows must be an array of rows; they were left out.`)
+ return []
+ }
+ const names = (headers ?? []).map(h => headerText(h).trim().toLowerCase())
+ let fromRecords = 0
+ let dropped = 0
+ const unmatched = new Set<string>()
+ const out: unknown[][] = []
+ for (const row of rows) {
+ if (Array.isArray(row)) {
+ out.push(row)
+ } else if (isRecord(row)) {
+ fromRecords++
+ if (names.length === 0) {
+ out.push(Object.values(row))
+ continue
+ }
+ const byName = new Map(Object.entries(row).map(([k, v]) => [k.trim().toLowerCase(), v]))
+ for (const key of Object.keys(row)) {
+ if (!names.includes(key.trim().toLowerCase())) unmatched.add(key)
+ }
+ out.push(
+ (headers ?? []).map((h, i) =>
+ Object.prototype.hasOwnProperty.call(row, headerText(h))
+ ? row[headerText(h)]
+ : byName.get(names[i])
+ )
+ )
+ } else {
+ dropped++
+ }
+ }
+ if (fromRecords > 0) {
+ warnings.push(
+ `${label}: ${fromRecords} row(s) were objects and were read by header name; send each row as an array of cells in header order.`
+ )
+ }
+ if (unmatched.size > 0) {
+ warnings.push(
+ `${label}: the key(s) ${[...unmatched].map(k => `'${k}'`).join(', ')} match no header, so ` +
+ 'those values were left out.'
+ )
+ }
+ if (dropped > 0) {
+ warnings.push(
+ `${label}: ${dropped} row(s) were neither an array nor an object and were left out.`
+ )
+ }
+ return out
+}
diff --git a/mcp-host/src/workflow/toolText.ts b/mcp-host/src/workflow/toolText.ts
new file mode 100644
index 000000000..b1e243e21
--- /dev/null
+++ b/mcp-host/src/workflow/toolText.ts
@@ -0,0 +1,62 @@
+/**
+ * Text cleanup applied to the arguments of every document generator.
+ *
+ * DOCX, XLSX and PPTX are XML, and XML 1.0 forbids most C0 control characters,
+ * so one ANSI escape makes Word refuse a DOCX; the PDF renderer draws them as
+ * boxes, and the markdown parsers split on '\n' only. Cleaning the arguments
+ * once, before a generator reads them, covers every string that can reach a file.
+ */
+
+/** CSI and terminated OSC sequences, then any other escape and its next byte. */
+const ANSI_ESCAPE =
+ /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-_]?/g
+
+/** Characters XML 1.0 cannot carry, plus DEL. Tab and newline are kept. */
+const UNREPRESENTABLE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\uFFFE\uFFFF]/g
+
+/** Half of a surrogate pair, left behind when a string is cut mid-emoji. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+
+export function cleanText(text: string): string {
+ return text
+ .replace(/\r\n?|[\f\v\u2028\u2029]/g, '\n')
+ .replace(ANSI_ESCAPE, '')
+ .replace(UNREPRESENTABLE, '')
+ .replace(LONE_SURROGATE, '')
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ if (value === null || typeof value !== 'object') return false
+ const proto = Object.getPrototypeOf(value)
+ return proto === Object.prototype || proto === null
+}
+
+const MAX_DEPTH = 64
+
+/**
+ * A copy of `value` with every string, object key included, run through
+ * cleanText. A key that only matches another after cleaning is dropped: the
+ * arguments were validated before cleaning, so the key already clean is the one
+ * the schema checked. Values nested past MAX_DEPTH levels are kept as they are:
+ * no generator reads that deep, and walking them could overflow the stack.
+ */
+export function cleanToolArgs<T>(value: T, depth = 0): T {
+ if (depth > MAX_DEPTH) return value
+ if (typeof value === 'string') return cleanText(value) as T
+ if (Array.isArray(value)) return value.map(item => cleanToolArgs(item, depth + 1)) as T
+ if (!isPlainObject(value)) return value
+ const out: Record<string, unknown> = {}
+ for (const [key, item] of Object.entries(value)) {
+ const clean = cleanText(key)
+ if (Object.prototype.hasOwnProperty.call(out, clean)) continue
+ if (clean !== key && Object.prototype.hasOwnProperty.call(value, clean)) continue
+ // defineProperty keeps a key such as "__proto__" an ordinary own property.
+ Object.defineProperty(out, clean, {
+ value: cleanToolArgs(item, depth + 1),
+ enumerable: true,
+ writable: true,
+ configurable: true,
+ })
+ }
+ return out as T
+}