Skip to content

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

TypeScript

fix(mcp-host): check what a delivered file shows, not only what it stores

marcotebfc5ce9815677
diff --git a/mcp-host/src/__tests__/artifacts/officePackageText.test.ts b/mcp-host/src/__tests__/artifacts/officePackageText.test.ts
index 842b60d32..c204bda69 100644
--- a/mcp-host/src/__tests__/artifacts/officePackageText.test.ts
+++ b/mcp-host/src/__tests__/artifacts/officePackageText.test.ts
@@ -4,7 +4,12 @@
*/
import { describe, expect, it } from 'vitest'
import JSZip from 'jszip'
-import { OFFICE_PACKAGE_LIMITS, officePackageHasText } from '../../artifacts/officePackageText'
+import {
+ OFFICE_PACKAGE_LIMITS,
+ officePackageHasText,
+ officePackageTexts,
+} from '../../artifacts/officePackageText'
+import { withoutSeparators } from '../../artifacts/shownNumbers'
const needle = '3141592653'
const holds = (text: string) => text.includes(needle)
@@ -119,3 +124,126 @@ describe('officePackageHasText', () => {
).toBeNull()
})
})
+
+/** A workbook whose one cell stores `value` with style 1, which shows it through numFmt `id`. */
+function workbook(
+ value: string,
+ numFmt: { id: number; code?: string },
+ extra: Record<string, string> = {}
+) {
+ const custom = numFmt.code
+ ? `<numFmts count="1"><numFmt numFmtId="${numFmt.id}" formatCode="${numFmt.code}"/></numFmts>`
+ : ''
+ return pack({
+ 'xl/styles.xml': `<styleSheet>${custom}<cellXfs count="2"><xf numFmtId="0"/><xf numFmtId="${numFmt.id}"/></cellXfs></styleSheet>`,
+ 'xl/worksheets/sheet1.xml': `<worksheet><sheetData><row><c r="A1" s="1"><v>${value}</v></c></row></sheetData></worksheet>`,
+ ...extra,
+ })
+}
+
+/** Matches nothing as stored, and `shown` (without separators) as shown. */
+function shownOnly(
+ shown: string
+): [(text: string) => boolean, typeof OFFICE_PACKAGE_LIMITS, (text: string) => boolean] {
+ const target = withoutSeparators(shown)
+ return [() => false, OFFICE_PACKAGE_LIMITS, text => text.includes(target)]
+}
+
+describe('officePackageHasText, numbers as they are shown', () => {
+ it('reads a date serial as the date its custom format shows', async () => {
+ const xlsx = await workbook('46024', { id: 164, code: 'dd/mm/yyyy' })
+ expect(officePackageHasText(xlsx, ...shownOnly('02/01/2026'))).toBe(true)
+ // Witness: the shown reading does not find what the cell does not show.
+ expect(officePackageHasText(xlsx, ...shownOnly('03/01/2026'))).toBe(false)
+ })
+
+ it('reads a built-in short date in the patterns viewers use', async () => {
+ const xlsx = await workbook('46024', { id: 14 })
+ expect(officePackageHasText(xlsx, ...shownOnly('02.01.2026'))).toBe(true)
+ expect(officePackageHasText(xlsx, ...shownOnly('1/2/2026'))).toBe(true)
+ })
+
+ it('reads grouped digits in any locale, and quoted text beside them', async () => {
+ const grouped = await workbook('3141592653', { id: 3 })
+ expect(officePackageHasText(grouped, ...shownOnly('3.141.592.653'))).toBe(true)
+ const quoted = await workbook('123456', { id: 164, code: '&quot;sk-&quot;0' })
+ expect(officePackageHasText(quoted, ...shownOnly('sk-123456'))).toBe(true)
+ })
+
+ it('reads the numbers a chart caches through its label formats', async () => {
+ const deck = await pack({
+ 'ppt/charts/chart1.xml':
+ '<c:chartSpace><c:dLbls><c:numFmt formatCode="&quot;sk-&quot;0" sourceLinked="0"/></c:dLbls>' +
+ '<c:val><c:numRef><c:numCache><c:formatCode>General</c:formatCode><c:pt idx="0"><c:v>123456</c:v></c:pt>' +
+ '</c:numCache></c:numRef></c:val></c:chartSpace>',
+ })
+ expect(officePackageHasText(deck, ...shownOnly('sk-123456'))).toBe(true)
+ })
+
+ it.each([
+ ['a formula', () => pack({ 'xl/worksheets/sheet1.xml': '<c r="A1"><f>B1</f><v>1</v></c>' })],
+ [
+ 'the 1904 date system',
+ () =>
+ workbook(
+ '1',
+ { id: 14 },
+ { 'xl/workbook.xml': '<workbook><workbookPr date1904="1"/></workbook>' }
+ ),
+ ],
+ [
+ 'a conditional format with a number format',
+ () =>
+ pack({
+ 'xl/styles.xml':
+ '<styleSheet><dxfs count="1"><dxf><numFmt numFmtId="170" formatCode="0.0"/></dxf></dxfs></styleSheet>',
+ 'xl/worksheets/sheet1.xml': '<c r="A1"><v>1</v></c>',
+ }),
+ ],
+ ['a built-in id it does not model', () => workbook('5', { id: 5 })],
+ ['a system date format', () => workbook('46024', { id: 164, code: '[$-F800]dddd' })],
+ [
+ 'an ISO date cell',
+ () => pack({ 'xl/worksheets/sheet1.xml': '<c r="A1" t="d"><v>2026-01-02</v></c>' }),
+ ],
+ [
+ 'a chart format it does not model',
+ () =>
+ pack({
+ 'ppt/charts/chart1.xml':
+ '<c:numCache><c:formatCode>[DBNum1]0</c:formatCode><c:pt><c:v>1</c:v></c:pt></c:numCache>',
+ }),
+ ],
+ ])('reports %s as unreadable', async (_label, make) => {
+ expect(officePackageHasText(await make(), () => false)).toBeNull()
+ })
+
+ it('reports a package with more shown numbers than the bound as unreadable', async () => {
+ const xlsx = await workbook('46024', { id: 14 })
+ expect(
+ officePackageHasText(xlsx, () => false, { ...OFFICE_PACKAGE_LIMITS, maxShownValues: 0 })
+ ).toBeNull()
+ // An integer under General shows its stored digits and is not rendered.
+ const plain = await workbook('42', { id: 0 })
+ expect(
+ officePackageHasText(plain, () => false, { ...OFFICE_PACKAGE_LIMITS, maxShownValues: 0 })
+ ).toBe(false)
+ })
+
+ it('reads no numbers when told not to', async () => {
+ const xlsx = await workbook('46024', { id: 164, code: '[$-F800]dddd' })
+ expect(officePackageHasText(xlsx, () => false, OFFICE_PACKAGE_LIMITS, null)).toBe(false)
+ })
+})
+
+describe('officePackageTexts', () => {
+ it('lists the text and attribute values the scan reads, numbers as stored', async () => {
+ const xlsx = await pack({
+ 'xl/workbook.xml': '<workbook><sheet name="Revenue" sheetId="1"/></workbook>',
+ 'xl/worksheets/sheet1.xml': `<c><v>${needle}</v></c>`,
+ })
+ const texts = officePackageTexts(xlsx)
+ expect(texts).toEqual(expect.arrayContaining(['Revenue', needle]))
+ expect(officePackageTexts(Buffer.from('not a package'))).toBeNull()
+ })
+})
diff --git a/mcp-host/src/__tests__/artifacts/shownNumbers.test.ts b/mcp-host/src/__tests__/artifacts/shownNumbers.test.ts
new file mode 100644
index 000000000..4e95491a6
--- /dev/null
+++ b/mcp-host/src/__tests__/artifacts/shownNumbers.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import {
+ builtinFormatCode,
+ isModelledFormatCode,
+ shownForms,
+ withoutSeparators,
+} from '../../artifacts/shownNumbers'
+import { CURRENCY_SYMBOLS } from '../../workflow/xlsxCells'
+import { NUMBER_FORMATS, currencyFormat } from '../../workflow/xlsxFormats'
+
+/** 2026-01-02 as a spreadsheet date serial. */
+const JAN_2_2026 = 46024
+
+describe('isModelledFormatCode', () => {
+ // Every code the sheet writer and the deck charts can write must be read as
+ // shown, or the attachment check would withhold their files.
+ const emitted = [
+ ...Object.values(NUMBER_FORMATS),
+ ...Object.values(CURRENCY_SYMBOLS).flatMap(symbol =>
+ [0, 2].map(d => currencyFormat(symbol, d))
+ ),
+ currencyFormat('CHF ', 2),
+ ...[3, 4, 5, 6].map(places => `#,##0.${'0'.repeat(places)}`),
+ 'yyyy-mm-dd hh:mm:ss',
+ '#,##0.0',
+ '[>=1000]#,##0;[<=-1000]-#,##0;General',
+ 'General',
+ '+#,##0;-#,##0;#,##0',
+ '[Red]+#,##0;[Red]-#,##0;[Red]#,##0',
+ ]
+
+ it.each(emitted)('reads %s, which a generator writes', code => {
+ expect(isModelledFormatCode(code)).toBe(true)
+ })
+
+ it('reads every built-in format a package can name by id', () => {
+ const ids = [
+ 0, 1, 2, 3, 4, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 37, 38, 39, 40, 45, 46,
+ 47, 48, 49,
+ ]
+ for (const id of ids) expect(isModelledFormatCode(builtinFormatCode(id)!)).toBe(true)
+ expect(builtinFormatCode(5)).toBeUndefined()
+ expect(builtinFormatCode(164)).toBeUndefined()
+ })
+
+ it.each([
+ ['an unterminated quote', '"x'],
+ ['a system long date', '[$-F800]dddd, mmmm dd, yyyy'],
+ ['a system date', '[$-x-sysdate]dddd'],
+ ['native digits', '[DBNum1]0'],
+ ['another calendar', '[B2]yyyy'],
+ ['a code over 255 characters', `"${'x'.repeat(260)}"0`],
+ ['nothing', ''],
+ ])('does not read %s', (_label, code) => {
+ expect(isModelledFormatCode(code)).toBe(false)
+ })
+})
+
+describe('shownForms', () => {
+ it('shows a date serial as its date, in the code and without separators', () => {
+ expect(shownForms(JAN_2_2026, 'yyyy-mm-dd')).toContain('2026-01-02'.replace(/[.,]/g, ''))
+ expect(shownForms(JAN_2_2026, 'dd/mm/yyyy')).toContain('02/01/2026')
+ expect(shownForms(46024.62783564815, 'yyyy-mm-dd hh:mm:ss')).toContain('2026-01-0215:04:05')
+ })
+
+ it('shows a built-in short date in the patterns locales use', () => {
+ const forms = shownForms(JAN_2_2026, 'mm-dd-yy', true)
+ for (const shown of ['1/2/2026', '2/1/2026', '02012026', '2026-01-02']) {
+ expect(forms).toContain(withoutSeparators(shown))
+ }
+ })
+
+ it('shows grouped digits, and quoted text beside them', () => {
+ expect(shownForms(3141592653, '#,##0')).toEqual(['3141592653'])
+ expect(shownForms(123456, '"sk-"0')).toEqual(['sk-123456'])
+ })
+
+ it('shows month names in other languages', () => {
+ const forms = shownForms(JAN_2_2026, 'mmm d, yyyy')
+ expect(forms).toEqual(expect.arrayContaining(['Jan22026', 'janv22026', 'ene22026']))
+ })
+})
+
+describe('withoutSeparators', () => {
+ it.each([
+ ['1,234.5', '12345'],
+ ['1.234,5', '12345'],
+ ['1 234,5', '12345'],
+ ['1 234,5', '12345'],
+ ["1'234.5", '12345'],
+ ['1’234.5', '12345'],
+ ['3,14,15,92,653', '3141592653'],
+ ])('reads %s as %s', (shown, digits) => {
+ expect(withoutSeparators(shown)).toBe(digits)
+ })
+})
diff --git a/mcp-host/src/artifacts/officePackageText.ts b/mcp-host/src/artifacts/officePackageText.ts
index d6c72b283..c14733067 100644
--- a/mcp-host/src/artifacts/officePackageText.ts
+++ b/mcp-host/src/artifacts/officePackageText.ts
@@ -2,9 +2,19 @@
* The text an Office package (DOCX, XLSX, PPTX) holds, read from the bytes
* that are delivered rather than predicted from the arguments that produced
* them: a generator may write a value in a form its arguments never spelled,
- * as a sheet stores the text "3,141,592,653" as the number 3141592653.
+ * as a sheet stores the text "3,141,592,653" as the number 3141592653. Numbers
+ * are also read as they are shown: a cell's number format or a chart's label
+ * format turns a stored 46024 into "2026-01-02", and 3141592653 into
+ * "3,141,592,653" (shownNumbers.ts).
*/
import * as zlib from 'zlib'
+import {
+ builtinFormatCode,
+ isModelledFormatCode,
+ isShortDateId,
+ shownForms,
+ showsIntegerAsStored,
+} from './shownNumbers'
/** Bounds on one inspection; a package past them is reported as unreadable. */
export const OFFICE_PACKAGE_LIMITS = {
@@ -14,6 +24,12 @@ export const OFFICE_PACKAGE_LIMITS = {
maxInflatedBytes: 64 * 1024 * 1024,
/** Packages inside packages, such as the workbook behind a deck's chart. */
maxDepth: 2,
+ /**
+ * Numbers rendered through their format across the package and every
+ * package inside it (about 0.6 s at this bound); a larger package is not
+ * attached.
+ */
+ maxShownValues: 250_000,
}
export type OfficePackageLimits = typeof OFFICE_PACKAGE_LIMITS
@@ -43,27 +59,71 @@ interface ZipEntry {
/**
* Whether any text in the package satisfies `matches`: per XML part, its text
* nodes run together, so a value split across runs or cells reads whole, and
- * each attribute value on its own, with character references decoded.
+ * each attribute value on its own, with character references decoded; then
+ * each number a sheet cell or a chart holds, in every form it may be shown,
+ * passed to `matchesShown` without separators (shownNumbers.withoutSeparators);
+ * null skips them.
* Embedded packages are read too. Null when the bytes are not a package this
- * reader can read within `limits`; the caller then treats the file as unsafe.
+ * reader can read within `limits`, or show a number in a way it does not model
+ * (a formula, a system date format, the 1904 date system); the caller then
+ * treats the file as unsafe.
*/
export function officePackageHasText(
buffer: Buffer,
matches: (text: string) => boolean,
- limits: OfficePackageLimits = OFFICE_PACKAGE_LIMITS
+ limits: OfficePackageLimits = OFFICE_PACKAGE_LIMITS,
+ matchesShown: ((shown: string) => boolean) | null = matches
): boolean | null {
- return searchPackage(buffer, matches, limits, { inflated: 0 }, 0)
+ return searchPackage(
+ buffer,
+ matches,
+ limits,
+ { inflated: 0, shownValues: 0 },
+ 0,
+ matchesShown ?? undefined
+ )
+}
+
+/**
+ * Every text the scan above reads in the package, numbers as stored: per XML
+ * part, its text nodes run together, and each attribute value. Null when the
+ * package cannot be read within the limits.
+ */
+export function officePackageTexts(
+ buffer: Buffer,
+ limits: OfficePackageLimits = OFFICE_PACKAGE_LIMITS
+): string[] | null {
+ const texts: string[] = []
+ const read = searchPackage(
+ buffer,
+ text => {
+ texts.push(text)
+ return false
+ },
+ { ...limits, maxShownValues: 0 },
+ { inflated: 0, shownValues: 0 },
+ 0,
+ undefined
+ )
+ return read === null ? null : texts
+}
+
+interface ScanBudget {
+ inflated: number
+ shownValues: number
}
function searchPackage(
buffer: Buffer,
matches: (text: string) => boolean,
limits: OfficePackageLimits,
- budget: { inflated: number },
- depth: number
+ budget: ScanBudget,
+ depth: number,
+ matchesShown: ((shown: string) => boolean) | undefined
): boolean | null {
const entries = centralDirectory(buffer, limits.maxEntries)
if (!entries) return null
+ const parts = new Map<string, string>()
for (const entry of entries) {
const embedded = EMBEDDED_PACKAGE.test(entry.name)
if (!embedded && !TEXT_PART.test(entry.name)) continue
@@ -71,12 +131,17 @@ function searchPackage(
const data = entryData(buffer, entry, limits.maxInflatedBytes - budget.inflated)
if (!data) return null
budget.inflated += data.length
- const found = embedded
- ? searchPackage(data, matches, limits, budget, depth + 1)
- : xmlHasText(data.toString('utf8'), matches)
+ let found: boolean | null
+ if (embedded) {
+ found = searchPackage(data, matches, limits, budget, depth + 1, matchesShown)
+ } else {
+ const xml = data.toString('utf8')
+ parts.set(entry.name, xml)
+ found = xmlHasText(xml, matches)
+ }
if (found !== false) return found
}
- return false
+ return matchesShown ? numbersShow(parts, matchesShown, limits, budget) : false
}
/** Sections whose content is read as it stands, up to their end mark. */
@@ -190,3 +255,323 @@ function entryData(buffer: Buffer, entry: ZipEntry, remaining: number): Buffer |
return null
}
}
+
+// ─── Numbers as they are shown ───────────────────────────────────────
+
+const SHEET_PART = /^xl\/worksheets\/[^/]+\.xml$/
+const CHART_PART = /(?:^|\/)charts\/chart[^/]*\.xml$/
+
+/**
+ * Whether a number a sheet or a chart of this package shows satisfies
+ * `matches`. Null for a way of showing a number this reader does not model, or
+ * when the package holds more numbers than the limits allow.
+ */
+function numbersShow(
+ parts: Map<string, string>,
+ matches: (text: string) => boolean,
+ limits: OfficePackageLimits,
+ budget: ScanBudget
+): boolean | null {
+ const render = (value: number, code: string, shortDate: boolean): boolean | null => {
+ if (!shortDate && showsIntegerAsStored(code, value)) return false
+ if (++budget.shownValues > limits.maxShownValues) return null
+ return shownForms(value, code, shortDate).some(matches)
+ }
+ const sheets = [...parts.keys()].filter(name => SHEET_PART.test(name))
+ if (sheets.length > 0) {
+ // A workbook in the 1904 date system shows every serial four years later.
+ if (/\bdate1904\s*=\s*["'](?:1|true)["']/.test(parts.get('xl/workbook.xml') ?? '')) return null
+ const styles = readStyles(parts.get('xl/styles.xml'))
+ if (!styles) return null
+ for (const name of sheets) {
+ const found = sheetShows(parts.get(name)!, styles, render)
+ if (found !== false) return found
+ }
+ }
+ for (const name of [...parts.keys()].filter(part => CHART_PART.test(part))) {
+ const found = chartShows(parts.get(name)!, render)
+ if (found !== false) return found
+ }
+ return false
+}
+
+interface CellFormat {
+ code: string
+ /** A built-in short date, shown in the viewer's own date pattern. */
+ shortDate: boolean
+}
+
+interface StyleFormats {
+ /** The format of cell style `index`; null when it is not modelled. */
+ format(index: number): CellFormat | null
+}
+
+/** The number format of each cell style; null when a conditional format sets one. */
+function readStyles(xml: string | undefined): StyleFormats | null {
+ const custom = new Map<number, string>()
+ const xfFormats: number[] = []
+ let inCellXfs = false
+ let inDxf = false
+ let dxfFormat = false
+ if (xml) {
+ walkXml(xml, {
+ start(name, attrs, selfClosing) {
+ const local = localName(name)
+ if (local === 'cellXfs') inCellXfs = !selfClosing
+ else if (local === 'dxf') inDxf = !selfClosing
+ else if (local === 'numFmt') {
+ if (inDxf) dxfFormat = true
+ else if (attrs.numFmtId !== undefined && attrs.formatCode !== undefined) {
+ custom.set(Number(attrs.numFmtId), attrs.formatCode)
+ }
+ } else if (local === 'xf' && inCellXfs) {
+ xfFormats.push(Number(attrs.numFmtId ?? 0))
+ }
+ },
+ end(name) {
+ const local = localName(name)
+ if (local === 'cellXfs') inCellXfs = false
+ else if (local === 'dxf') inDxf = false
+ },
+ })
+ }
+ if (dxfFormat) return null
+ const known = new Map<number, CellFormat | null>()
+ return {
+ format(index) {
+ const cached = known.get(index)
+ if (cached !== undefined) return cached
+ const id = xfFormats[index] ?? (index === 0 ? 0 : undefined)
+ const code = id === undefined ? undefined : (custom.get(id) ?? builtinFormatCode(id))
+ const format =
+ id !== undefined && code !== undefined && isModelledFormatCode(code)
+ ? { code, shortDate: !custom.has(id) && isShortDateId(id) }
+ : null
+ known.set(index, format)
+ return format
+ },
+ }
+}
+
+type Render = (value: number, code: string, shortDate: boolean) => boolean | null
+
+/** Whether a number cell of the sheet shows text `render` matches; null for a formula. */
+function sheetShows(xml: string, styles: StyleFormats, render: Render): boolean | null {
+ let cell: { style: number; type?: string; value: string; inValue: boolean } | undefined
+ let result: boolean | null = false
+ walkXml(xml, {
+ start(name, attrs, selfClosing) {
+ const local = localName(name)
+ if (local === 'c') {
+ cell = selfClosing
+ ? undefined
+ : { style: Number(attrs.s ?? 0), type: attrs.t, value: '', inValue: false }
+ } else if (cell && local === 'v') {
+ cell.inValue = !selfClosing
+ } else if (cell && local === 'f') {
+ // A formula shows a result the package does not hold.
+ result = null
+ return true
+ }
+ return false
+ },
+ text(text) {
+ if (cell?.inValue) cell.value += text
+ return false
+ },
+ end(name) {
+ const local = localName(name)
+ if (local === 'v' && cell) cell.inValue = false
+ else if (local === 'c' && cell) {
+ const shown = cellShows(cell, styles, render)
+ cell = undefined
+ if (shown !== false) {
+ result = shown
+ return true
+ }
+ }
+ return false
+ },
+ })
+ return result
+}
+
+function cellShows(
+ cell: { style: number; type?: string; value: string },
+ styles: StyleFormats,
+ render: Render
+): boolean | null {
+ // An ISO date cell is shown through a format this reader does not apply.
+ if (cell.type === 'd') return null
+ // Text, booleans and errors are read as text.
+ if (cell.type !== undefined && cell.type !== 'n') return false
+ const stored = cell.value.trim()
+ const value = Number(stored)
+ if (!stored || !Number.isFinite(value)) return false
+ const format = styles.format(cell.style)
+ if (!format) return null
+ return render(value, format.code, format.shortDate)
+}
+
+/**
+ * Whether a number a chart caches shows text `render` matches. Each value is
+ * rendered with every format code of the chart part (series caches, data and
+ * axis labels), so the check covers what a label may show.
+ */
+function chartShows(xml: string, render: Render): boolean | null {
+ const codes = new Set<string>(['General'])
+ const values: number[] = []
+ let cacheDepth = 0
+ let value: string | undefined
+ let formatCode: string | undefined
+ walkXml(xml, {
+ start(name, attrs, selfClosing) {
+ const local = localName(name)
+ if (local === 'numCache' || local === 'numLit') {
+ if (!selfClosing) cacheDepth++
+ } else if ((local === 'numFmt' || local === 'pt') && attrs.formatCode !== undefined) {
+ codes.add(attrs.formatCode)
+ } else if (local === 'formatCode' && !selfClosing) {
+ formatCode = ''
+ } else if (local === 'v' && cacheDepth > 0 && !selfClosing) {
+ value = ''
+ }
+ return false
+ },
+ text(text) {
+ if (value !== undefined) value += text
+ if (formatCode !== undefined) formatCode += text
+ return false
+ },
+ end(name) {
+ const local = localName(name)
+ if (local === 'numCache' || local === 'numLit') cacheDepth = Math.max(0, cacheDepth - 1)
+ else if (local === 'formatCode' && formatCode !== undefined) {
+ codes.add(formatCode)
+ formatCode = undefined
+ } else if (local === 'v' && value !== undefined) {
+ const number = Number(value.trim())
+ if (value.trim() && Number.isFinite(number)) values.push(number)
+ value = undefined
+ }
+ return false
+ },
+ })
+ for (const code of codes) if (!isModelledFormatCode(code)) return null
+ for (const number of values) {
+ for (const code of codes) {
+ const found = render(number, code, false)
+ if (found !== false) return found
+ }
+ }
+ return false
+}
+
+function localName(name: string): string {
+ const colon = name.indexOf(':')
+ return colon < 0 ? name : name.slice(colon + 1)
+}
+
+interface XmlVisitor {
+ /** Each returns true to stop the walk. */
+ start?(name: string, attrs: Record<string, string>, selfClosing: boolean): boolean | void
+ end?(name: string): boolean | void
+ text?(text: string): boolean | void
+}
+
+/** Space, tab, newline and carriage return, the whitespace XML allows between attributes. */
+function isSpace(code: number): boolean {
+ return code === 32 || code === 9 || code === 10 || code === 13
+}
+
+/** Text with its character references decoded; most text has none. */
+function decodedText(text: string): string {
+ return text.includes('&') ? decodeReferences(text) : text
+}
+
+/**
+ * Walks the elements of one XML part in a single pass, tolerating malformed
+ * input: text and character data go to `text` with references decoded,
+ * comments, declarations and processing instructions are skipped, and each
+ * quoted attribute value is read whole, so a '>' it holds does not end its tag.
+ */
+function walkXml(xml: string, visit: XmlVisitor): void {
+ const LT = 60 // <
+ const GT = 62 // >
+ const SLASH = 47 // /
+ const EQ = 61 // =
+ let at = 0
+ while (at < xml.length) {
+ const open = xml.indexOf('<', at)
+ if (open < 0) {
+ visit.text?.(decodedText(xml.slice(at)))
+ return
+ }
+ if (open > at && visit.text?.(decodedText(xml.slice(at, open)))) return
+ if (xml.startsWith('<![CDATA[', open)) {
+ const close = xml.indexOf(']]>', open + 9)
+ const end = close < 0 ? xml.length : close
+ if (visit.text?.(xml.slice(open + 9, end))) return
+ at = end + 3
+ continue
+ }
+ if (xml.startsWith('<!--', open)) {
+ const close = xml.indexOf('-->', open + 4)
+ at = close < 0 ? xml.length : close + 3
+ continue
+ }
+ const second = xml.charCodeAt(open + 1)
+ if (second === 63 || second === 33) {
+ // <? ... ?> and <! ... >
+ const close = xml.indexOf('>', open)
+ at = close < 0 ? xml.length : close + 1
+ continue
+ }
+ const closing = second === SLASH
+ let i = open + (closing ? 2 : 1)
+ const nameStart = i
+ for (let c = xml.charCodeAt(i); i < xml.length; c = xml.charCodeAt(++i)) {
+ if (isSpace(c) || c === SLASH || c === GT || c === LT) break
+ }
+ const name = xml.slice(nameStart, i)
+ // No prototype: an attribute named "__proto__" stays a plain key.
+ const attrs: Record<string, string> = Object.create(null)
+ let selfClosing = false
+ while (i < xml.length) {
+ const c = xml.charCodeAt(i)
+ if (c === GT) break
+ if (c === SLASH) {
+ selfClosing = true
+ i++
+ continue
+ }
+ if (isSpace(c)) {
+ i++
+ continue
+ }
+ const attrStart = i
+ for (let d = xml.charCodeAt(i); i < xml.length; d = xml.charCodeAt(++i)) {
+ if (isSpace(d) || d === EQ || d === SLASH || d === GT) break
+ }
+ const attrName = xml.slice(attrStart, i)
+ while (i < xml.length && isSpace(xml.charCodeAt(i))) i++
+ if (xml.charCodeAt(i) !== EQ) continue
+ i++
+ while (i < xml.length && isSpace(xml.charCodeAt(i))) i++
+ const quote = xml[i]
+ if (quote !== '"' && quote !== "'") continue
+ const close = xml.indexOf(quote, i + 1)
+ const end = close < 0 ? xml.length : close
+ attrs[attrName] = decodedText(xml.slice(i + 1, end))
+ selfClosing = false
+ i = end + 1
+ }
+ at = i + 1
+ if (closing) {
+ if (visit.end?.(name)) return
+ } else {
+ if (visit.start?.(name, attrs, selfClosing)) return
+ if (selfClosing && visit.end?.(name)) return
+ }
+ }
+}
diff --git a/mcp-host/src/artifacts/shownNumbers.ts b/mcp-host/src/artifacts/shownNumbers.ts
new file mode 100644
index 000000000..ef0852606
--- /dev/null
+++ b/mcp-host/src/artifacts/shownNumbers.ts
@@ -0,0 +1,168 @@
+/**
+ * What a spreadsheet shows for a number under a number format code, so a
+ * protected value it displays is found although the file only stores the
+ * number: a date serial under a date format, digits under a grouping format or
+ * beside quoted text. A spreadsheet renders in its viewer's locale, so a value
+ * is compared without separators (any locale's grouping reads the same), in
+ * each language's month and day names, and, for the built-in short date, in
+ * the date patterns locales commonly use.
+ */
+import type * as Numfmt from 'numfmt'
+
+/** Excel's own limit on the length of a format code. */
+export const MAX_FORMAT_CODE_LENGTH = 255
+
+let formatter: typeof Numfmt | undefined
+function numfmt(): typeof Numfmt {
+ // Loaded on first use: only a scan with protected values configured needs it.
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ formatter ??= require('numfmt') as typeof Numfmt
+ return formatter
+}
+
+/**
+ * The built-in formats ExcelJS can write by id (ECMA-376 Part 1, 18.8.30),
+ * which a package names without a <numFmt> element. Other ids are not
+ * modelled.
+ */
+const BUILTIN_FORMATS: Readonly<Record<number, string>> = {
+ 0: 'General',
+ 1: '0',
+ 2: '0.00',
+ 3: '#,##0',
+ 4: '#,##0.00',
+ 9: '0%',
+ 10: '0.00%',
+ 11: '0.00E+00',
+ 12: '# ?/?',
+ 13: '# ??/??',
+ 14: 'mm-dd-yy',
+ 15: 'd-mmm-yy',
+ 16: 'd-mmm',
+ 17: 'mmm-yy',
+ 18: 'h:mm AM/PM',
+ 19: 'h:mm:ss AM/PM',
+ 20: 'h:mm',
+ 21: 'h:mm:ss',
+ 22: 'm/d/yy h:mm',
+ 37: '#,##0 ;(#,##0)',
+ 38: '#,##0 ;[Red](#,##0)',
+ 39: '#,##0.00;(#,##0.00)',
+ 40: '#,##0.00;[Red](#,##0.00)',
+ 45: 'mm:ss',
+ 46: '[h]:mm:ss',
+ 47: 'mmss.0',
+ 48: '##0.0E+0',
+ 49: '@',
+}
+
+/** Built-in ids a viewer shows with its own short date pattern. */
+const SHORT_DATE_IDS = new Set([14, 22])
+const SHORT_DATES = [
+ 'm/d/yyyy',
+ 'mm/dd/yyyy',
+ 'd/m/yyyy',
+ 'dd/mm/yyyy',
+ 'dd.mm.yyyy',
+ 'd.m.yyyy',
+ 'dd-mm-yyyy',
+ 'yyyy-mm-dd',
+ 'yyyy/mm/dd',
+ 'm/d/yy',
+ 'd/m/yy',
+ 'dd/mm/yy',
+ 'dd.mm.yy',
+ 'yy/mm/dd',
+]
+const SHORT_TIMES = ['h:mm', 'hh:mm', 'h:mm AM/PM']
+
+/** The format a built-in id stands for, or undefined when the id is not modelled. */
+export function builtinFormatCode(id: number): string | undefined {
+ return Object.prototype.hasOwnProperty.call(BUILTIN_FORMATS, id) ? BUILTIN_FORMATS[id] : undefined
+}
+
+export function isShortDateId(id: number): boolean {
+ return SHORT_DATE_IDS.has(id)
+}
+
+/** A locale tag that makes a viewer use its system format: [$-F800], [$-x-sysdate]. */
+const SYSTEM_LOCALE = /^-(?:F[0-9A-F]{3}|x-sys)/i
+
+/**
+ * Whether this module renders `code` the way a spreadsheet would: a code it
+ * parses, within Excel's length, with no system date or time, no native
+ * digit set (DBNum, NatNum) and no other calendar.
+ */
+export function isModelledFormatCode(code: string): boolean {
+ if (code.length === 0 || code.length > MAX_FORMAT_CODE_LENGTH) return false
+ const nf = numfmt()
+ if (!nf.isValidFormat(code)) return false
+ return nf
+ .tokenize(code)
+ .every(
+ token =>
+ token.type !== 'dbnum' &&
+ token.type !== 'natnum' &&
+ !(token.type === 'locale' && SYSTEM_LOCALE.test(String(token.value)))
+ )
+}
+
+/** Whether `code` shows an integer as its plain digits, which the stored value already spells. */
+export function showsIntegerAsStored(code: string, value: number): boolean {
+ return /^(?:general|0|@)$/i.test(code) && Number.isInteger(value) && Math.abs(value) < 1e11
+}
+
+/** Locales rendered natively: their month and day names differ. */
+const NAME_LOCALES = ['de', 'fr', 'es']
+
+/**
+ * Characters locales use to group digits or mark decimals: comma, period,
+ * apostrophe (de-CH), typographic apostrophe, no-break and narrow no-break
+ * space (fr), space.
+ */
+const SEPARATORS = /[,.'\u2019\u00A0\u202F ]/g
+
+/**
+ * `text` without separators. A value shown in any locale ("1,234.5",
+ * "1.234,5", "1 234,5", "1'234.5", "12,34,567") reads the same this way, so a
+ * protected value is compared in this form with each rendering: whenever it
+ * occurs in some locale's rendering, its separator-free form occurs in the
+ * separator-free rendering.
+ */
+export function withoutSeparators(text: string): string {
+ return text.replace(SEPARATORS, '')
+}
+
+const MEMO_LIMIT = 20_000
+const memo = new Map<string, string[]>()
+
+/**
+ * The ways a viewer may show `value` under `code` (`code` modelled), each
+ * without separators. For a built-in short date id, pass `shortDate` to render
+ * the common date patterns instead of `code`.
+ */
+export function shownForms(value: number, code: string, shortDate = false): string[] {
+ const key = `${shortDate ? 'S' : 'C'}\u0000${code}\u0000${value}`
+ const known = memo.get(key)
+ if (known) return known
+ const nf = numfmt()
+ const forms = new Set<string>()
+ const codes = shortDate
+ ? code.includes('h')
+ ? SHORT_DATES.flatMap(date => SHORT_TIMES.map(time => `${date} ${time}`))
+ : SHORT_DATES
+ : [code]
+ for (const each of codes) {
+ forms.add(withoutSeparators(nf.format(each, value, { locale: 'en', throws: false })))
+ // Month and day names, and AM/PM, are words a locale translates.
+ if (/m{3,}|d{3,}|AM\/PM|A\/P/i.test(each)) {
+ for (const locale of NAME_LOCALES) {
+ forms.add(withoutSeparators(nf.format(each, value, { locale, throws: false })))
+ }
+ }
+ }
+ const out = [...forms].filter(Boolean)
+ if (memo.size >= MEMO_LIMIT) memo.clear()
+ memo.set(key, out)
+ return out
+}
diff --git a/mcp-host/src/core/tools/__tests__/generatedArtifactAttachments.test.ts b/mcp-host/src/core/tools/__tests__/generatedArtifactAttachments.test.ts
index 6a3f999df..0a2ecc328 100644
--- a/mcp-host/src/core/tools/__tests__/generatedArtifactAttachments.test.ts
+++ b/mcp-host/src/core/tools/__tests__/generatedArtifactAttachments.test.ts
@@ -574,6 +574,167 @@ describe('generated internal artifact attachments', () => {
})
})
+ describe('what a delivered file shows that its arguments never spelled', () => {
+ function toolWith(name: string, secrets: string[]) {
+ process.env.CLERUM_OUTPUT_DIR = outputDir
+ const registry = new NativeToolRegistry(
+ {
+ workspacePath: outputDir,
+ shellTimeout: 5000,
+ toolTimeout: 60000,
+ toolProgressInterval: 30000,
+ httpAllowlist: [],
+ envAllowlist: ['PATH'],
+ memoryMaxSize: 1048576,
+ },
+ 'conv-1',
+ undefined,
+ undefined,
+ undefined,
+ undefined,
+ null,
+ {
+ maxBytes: 52_428_800,
+ secretEntriesProvider: () => secrets.map((value, i) => ({ name: `PROBE_${i}`, value })),
+ }
+ )
+ return registry.get(name)!
+ }
+
+ function packageXml(file: string): string {
+ return [...zipEntries(file)]
+ .filter(([name]) => name.endsWith('.xml'))
+ .map(([, data]) => data.toString('utf8'))
+ .join('\n')
+ }
+
+ function sheet(cell: unknown, format?: string) {
+ return {
+ filename: 'shown.xlsx',
+ sheets: [
+ { name: 'S', rows: [['D'], [cell]], ...(format ? { columnFormats: { D: format } } : {}) },
+ ],
+ }
+ }
+
+ it('holds back a date its arguments spell, through the argument check', async () => {
+ const result = await toolWith('clerum__generate_xlsx', ['2026-01-02']).execute(
+ sheet('2026-01-02')
+ )
+ expect(result.is_error).toBe(false)
+ expect(result.attachments ?? []).toHaveLength(0)
+ })
+
+ it.each([
+ ['a UTC time shown with a space', '2026-01-02 15:04:05', '2026-01-02T15:04:05Z', undefined],
+ [
+ 'a time with an offset shown in UTC',
+ '2026-01-02 09:34:05',
+ '2026-01-02T15:04:05+05:30',
+ undefined,
+ ],
+ ['a date under a day-first format', '02/01/2026', '2026-01-02', 'dd/mm/yyyy'],
+ ['grouped digits', '3,141,592,653', 3141592653, '#,##0'],
+ ['digits grouped the German way', '3.141.592.653', 3141592653, '#,##0'],
+ ['digits beside quoted text', 'sk-123456', 123456, '"sk-"0'],
+ ])('does not attach a sheet that shows %s', async (_label, secret, cell, format) => {
+ const result = await toolWith('clerum__generate_xlsx', [secret]).execute(sheet(cell, format))
+ expect(result.is_error).toBe(false)
+ // Witness: neither the arguments nor the package spell the value.
+ expect(JSON.stringify(sheet(cell, format))).not.toContain(secret)
+ expect(packageXml(path.join(outputDir, 'shown.xlsx'))).not.toContain(secret)
+ expect(result.attachments ?? []).toHaveLength(0)
+ })
+
+ it('attaches the same sheet when no protected value is shown', async () => {
+ const result = await toolWith('clerum__generate_xlsx', ['9,999,999,999']).execute(
+ sheet(3141592653, '#,##0')
+ )
+ expect(result.attachments ?? []).toHaveLength(1)
+ })
+
+ it('does not attach a deck whose chart label shows the protected value grouped', async () => {
+ const deck = {
+ filename: 'labels.pptx',
+ slides: [
+ {
+ layout: 'title-chart',
+ title: 'Revenue',
+ chart: { type: 'bar', labels: ['A'], datasets: [{ label: 'S', data: [3141592653] }] },
+ },
+ ],
+ }
+ const leaked = await toolWith('clerum__generate_pptx', ['3,141,592,653']).execute(deck)
+ expect(leaked.is_error).toBe(false)
+ expect(packageXml(path.join(outputDir, 'labels.pptx'))).not.toContain('3,141,592,653')
+ expect(leaked.attachments ?? []).toHaveLength(0)
+ const ordinary = await toolWith('clerum__generate_pptx', ['9,999,999,999']).execute(deck)
+ expect(ordinary.attachments ?? []).toHaveLength(1)
+ })
+
+ it('does not attach a chart image whose value label shows the protected value', async () => {
+ const chart = (filename: string) => ({
+ filename,
+ type: 'bar',
+ showValues: true,
+ valueFormat: 'plain',
+ data: { labels: ['A'], datasets: [{ label: 'S', data: [3141592653] }] },
+ })
+ const leaked = await toolWith('clerum__generate_chart', ['3,141,592,653']).execute(
+ chart('v.png')
+ )
+ expect(leaked.is_error).toBe(false)
+ expect(leaked.attachments ?? []).toHaveLength(0)
+ const ordinary = await toolWith('clerum__generate_chart', ['9,999,999,999']).execute(
+ chart('c.png')
+ )
+ expect(ordinary.attachments ?? []).toHaveLength(1)
+ })
+
+ it("attaches ordinary documents when a protected value is also the generators' own text", async () => {
+ const common = ['Office', '1000', 'Calibri', 'General', 'main', 'false', 'solid']
+ const calls: Array<[string, Record<string, unknown>]> = [
+ [
+ 'clerum__generate_docx',
+ { filename: 'o.docx', title: 'Quarterly', body: 'Revenue grew.' },
+ ],
+ ['clerum__generate_xlsx', sheet(1200, 'integer')],
+ [
+ 'clerum__generate_pptx',
+ {
+ filename: 'o.pptx',
+ slides: [
+ { layout: 'title-bullets', title: 'T', bullets: ['a'] },
+ {
+ layout: 'title-chart',
+ title: 'C',
+ chart: { type: 'bar', labels: ['A'], datasets: [{ label: 'S', data: [5] }] },
+ },
+ ],
+ },
+ ],
+ ]
+ for (const [name, args] of calls) {
+ const result = await toolWith(name, common).execute(args)
+ expect(result.attachments ?? [], name).toHaveLength(1)
+ }
+ }, 60_000)
+
+ it('does not attach markdown whose markup splits a protected value, and redacts a whole one', async () => {
+ const md = toolWith('clerum__generate_markdown', ['probe-redaction-value'])
+ const split = await md.execute({
+ filename: 's.md',
+ content: 'key: probe-**redaction**-value',
+ })
+ expect(split.attachments ?? []).toHaveLength(0)
+ const whole = await md.execute({ filename: 'w.md', content: 'key: probe-redaction-value' })
+ expect(whole.attachments).toHaveLength(1)
+ expect(decoded(whole.attachments![0]!).toString('utf8')).not.toContain(
+ 'probe-redaction-value'
+ )
+ })
+ })
+
it('native internal tools return generated artifact attachments through the adapter', async () => {
const config: NativeToolConfig = {
workspacePath: outputDir,
diff --git a/mcp-host/src/core/tools/generatedArtifactAttachments.ts b/mcp-host/src/core/tools/generatedArtifactAttachments.ts
index 7cbb0614f..5543cf36b 100644
--- a/mcp-host/src/core/tools/generatedArtifactAttachments.ts
+++ b/mcp-host/src/core/tools/generatedArtifactAttachments.ts
@@ -5,7 +5,8 @@ import {
redactArtifactForDelivery,
} from '../../artifacts/artifactBytes'
import type { ArtifactSecretEntry } from '../../artifacts/artifactRedaction'
-import { officePackageHasText } from '../../artifacts/officePackageText'
+import { OFFICE_PACKAGE_LIMITS, officePackageHasText } from '../../artifacts/officePackageText'
+import { withoutSeparators } from '../../artifacts/shownNumbers'
import { logger } from '../../logger'
import {
ArtifactPathError,
@@ -58,6 +59,12 @@ type BuildGeneratedArtifactAttachmentParams = {
maxBytes: number
sourcePayload?: unknown
secretEntriesProvider?: () => ArtifactSecretEntry[]
+ /**
+ * Texts every package of this format holds on its own (officeBoilerplate).
+ * A protected value found in them is left to the payload check, since the
+ * package scan cannot tell it from the generator's own text.
+ */
+ packageBoilerplate?: readonly string[]
}
function extension(filename: string | undefined): string {
@@ -143,10 +150,20 @@ function sourcePayloadContainsRedactableSecretEntry(
sourcePayload: unknown,
entries: ArtifactSecretEntry[]
): boolean {
- if (sourcePayload === undefined || entries.length === 0) return false
+ return payloadSecretEntries(sourcePayload, entries).length > 0
+}
+
+/** The entries `sourcePayload` holds anywhere in its strings, numbers and keys. */
+function payloadSecretEntries(
+ sourcePayload: unknown,
+ entries: ArtifactSecretEntry[]
+): ArtifactSecretEntry[] {
+ if (sourcePayload === undefined || entries.length === 0) return []
const texts: string[] = []
payloadTexts(sourcePayload, texts, new Set(), 0)
- return texts.some(text => textContainsRedactableSecretEntry(text, entries))
+ return entries.filter(entry =>
+ texts.some(text => textContainsRedactableSecretEntry(text, [entry]))
+ )
}
export function isInternalGeneratedArtifactSourceTool(sourceTool: string | undefined): boolean {
@@ -231,9 +248,21 @@ export function buildGeneratedArtifactAttachment(
// A generator can write a value in a form the payload never spelled, as
// a sheet stores the text "3,141,592,653" as the number 3141592653, so
// the package is read as delivered. One that cannot be read is withheld.
- if (secretEntries.length > 0 && OFFICE_PACKAGE_FORMATS.has(expectedFormat)) {
- const found = officePackageHasText(fileBuffer, text =>
- textContainsRedactableSecretEntry(text, secretEntries)
+ const boilerplate = params.packageBoilerplate ?? []
+ const packageEntries = secretEntries.filter(
+ entry => !boilerplate.some(text => text.includes(entry.value))
+ )
+ if (packageEntries.length > 0 && OFFICE_PACKAGE_FORMATS.has(expectedFormat)) {
+ // Numbers are compared as shown without separators, so any locale's
+ // grouping of a protected value matches.
+ const shownValues = packageEntries
+ .map(entry => withoutSeparators(entry.value))
+ .filter(value => value.length >= 4)
+ const found = officePackageHasText(
+ fileBuffer,
+ text => textContainsRedactableSecretEntry(text, packageEntries),
+ OFFICE_PACKAGE_LIMITS,
+ shownValues.length > 0 ? shown => shownValues.some(value => shown.includes(value)) : null
)
if (found !== false) {
warnSkip(
@@ -245,6 +274,19 @@ export function buildGeneratedArtifactAttachment(
}
}
}
+ // A text file is redacted byte by byte, which misses a protected value its
+ // markup splits ("probe-**redaction**-value") and a preview shows joined:
+ // such a file is withheld. The printed forms of the arguments carry it whole.
+ if (!isBinaryArtifactFormat(expectedFormat) && secretEntries.length > 0) {
+ const text = fileBuffer.toString('utf8')
+ const split = payloadSecretEntries(params.sourcePayload, secretEntries).filter(
+ entry => !text.includes(entry.value)
+ )
+ if (split.length > 0) {
+ warnSkip('text_redaction_unavailable', params.sourceTool, params.artifact)
+ return null
+ }
+ }
const redacted = redactArtifactForDelivery(expectedFormat, fileBuffer, secretEntries)
if (redacted.buffer.byteLength > params.maxBytes) {
warnSkip('redacted_artifact_too_large', params.sourceTool, params.artifact)
diff --git a/mcp-host/src/core/tools/nativeToolRegistry.ts b/mcp-host/src/core/tools/nativeToolRegistry.ts
index 86f41bc73..d21042c4d 100644
--- a/mcp-host/src/core/tools/nativeToolRegistry.ts
+++ b/mcp-host/src/core/tools/nativeToolRegistry.ts
@@ -19,6 +19,7 @@ import type { McpManager } from '../../mcp/manager'
import type { IncomingMessage } from '../../server'
import type { McpTool } from '../../types'
import { getOutputDir, resolveInternalTools } from '../../workflow/internalTools'
+import { boilerplateTexts } from '../../workflow/officeBoilerplate'
import { printedForms } from '../../workflow/toolText'
import type { InternalToolDefinition } from '../../workflow/types'
import { ScopedWorkspace } from '../../workspace/scopedWorkspace'
@@ -104,6 +105,14 @@ class InternalToolAdapter implements Tool {
result.artifact?.format ?? 'unknown'
})`)
: `Error: ${result.error ?? 'Unknown error'}`
+ const format = result.success ? result.artifact?.format : undefined
+ // Office packages carry the generator's own text; a protected value
+ // found only there is left to the payload check (officeBoilerplate).
+ const packageBoilerplate =
+ (format === 'docx' || format === 'xlsx' || format === 'pptx') &&
+ (this.attachmentOptions.secretEntriesProvider?.().length ?? 0) > 0
+ ? await boilerplateTexts(format)
+ : undefined
const attachment =
result.success && result.artifact
? buildGeneratedArtifactAttachment({
@@ -112,9 +121,11 @@ class InternalToolAdapter implements Tool {
outputDir: this.outputDir,
maxBytes: this.attachmentOptions.maxBytes,
// The file shows the arguments as the generator prints them, so a
- // secret split by a tag or an escape is checked whole too.
- sourcePayload: [params, printedForms(params)],
+ // secret split by a tag or an escape is checked whole too, and
+ // anything else it shows that they do not spell (chart labels).
+ sourcePayload: [params, printedForms(params), result.shownText ?? []],
secretEntriesProvider: this.attachmentOptions.secretEntriesProvider,
+ packageBoilerplate,
})
: null
const images = result.success
diff --git a/mcp-host/src/workflow/__tests__/xlsxFormatCodes.test.ts b/mcp-host/src/workflow/__tests__/xlsxFormatCodes.test.ts
new file mode 100644
index 000000000..b851fc468
--- /dev/null
+++ b/mcp-host/src/workflow/__tests__/xlsxFormatCodes.test.ts
@@ -0,0 +1,93 @@
+// The number formats the sheet writer emits must be ones the attachment check
+// reads as shown, or every workbook using them would be withheld.
+import { describe, expect, it } from 'vitest'
+import JSZip from 'jszip'
+import * as os from 'os'
+import { officePackageHasText } from '../../artifacts/officePackageText'
+import { builtinFormatCode, isModelledFormatCode } from '../../artifacts/shownNumbers'
+import { buildXlsxWorkbook } from '../xlsxWorkbook'
+
+async function build(rows: unknown[][], columnFormats?: Record<string, string>) {
+ const warnings: string[] = []
+ const built = await buildXlsxWorkbook(
+ { sheets: [{ name: 'S', rows, ...(columnFormats ? { columnFormats } : {}) }] },
+ os.tmpdir(),
+ { width: 640, height: 400 },
+ warnings
+ )
+ if (!built.ok) throw new Error(built.error)
+ return { buffer: built.buffer, warnings }
+}
+
+/** Every format code the workbook's cell styles use, custom or built in. */
+async function formatCodes(buffer: Buffer): Promise<string[]> {
+ const styles = await (await JSZip.loadAsync(buffer)).file('xl/styles.xml')!.async('string')
+ const custom = new Map(
+ [...styles.matchAll(/<numFmt numFmtId="(\d+)" formatCode="([^"]*)"/g)].map(m => [
+ Number(m[1]),
+ m[2]
+ .replace(/&quot;/g, '"')
+ .replace(/&gt;/g, '>')
+ .replace(/&lt;/g, '<')
+ .replace(/&amp;/g, '&'),
+ ])
+ )
+ const cellXfs = styles.slice(styles.indexOf('<cellXfs'), styles.indexOf('</cellXfs>'))
+ const ids = [...cellXfs.matchAll(/numFmtId="(\d+)"/g)].map(m => Number(m[1]))
+ return ids.map(id => custom.get(id) ?? builtinFormatCode(id) ?? `unmodelled id ${id}`)
+}
+
+describe('number formats the sheet writer emits', () => {
+ const rows = [
+ ['Plain', 'Money', 'Pct', 'Red', 'Text', 'Cond', 'Day', 'When', 'Euro'],
+ ['+5', '+$1,200', '+45%', '+5', '+5', '+1500', '2026-01-02', '2026-01-02T15:04:05Z', '+€3'],
+ ['-3', '-$5', '-5%', '-3', 'x', '-2000', '2026-01-03', '2026-01-02T10:00:00Z', '4'],
+ [7, 12.5, 0.25, 8, 'y', 900, '2026-01-04', '2026-01-02T10:00:30Z', '5,5'],
+ ]
+ const formats = {
+ Plain: 'integer',
+ Money: 'currencyUsd',
+ Pct: 'percent',
+ Red: '[Red]#,##0',
+ Text: '"Total: "@',
+ Cond: '[Red][>=1000]#,##0',
+ Day: 'dd/mm/yyyy',
+ When: 'datetime',
+ Euro: 'currency:EUR',
+ }
+
+ it('writes only codes the attachment check reads as shown, signed cells included', async () => {
+ const { buffer } = await build(rows, formats)
+ const codes = await formatCodes(buffer)
+ // Witness: the signed and tagged codes are among them.
+ expect(codes).toContain('[Red]+#,##0;[Red]-#,##0;[Red]#,##0')
+ for (const code of codes) expect(isModelledFormatCode(code), code).toBe(true)
+ expect(officePackageHasText(buffer, () => false)).toBe(false)
+ })
+
+ it('keeps a text or conditional format as it is when a cell is signed', async () => {
+ const codes = await formatCodes((await build(rows, formats)).buffer)
+ expect(codes).toContain('"Total: "@')
+ expect(codes).toContain('[Red][>=1000]#,##0')
+ expect(codes.some(code => code.startsWith('+"Total') || code.startsWith('+[Red][>='))).toBe(
+ false
+ )
+ })
+
+ it.each([
+ ['a system date', '[$-F800]dddd'],
+ ['native digits', '[DBNum1]0'],
+ ['a code over 255 characters', `"${'x'.repeat(260)}"0`],
+ ])('does not write %s, which the attachment check cannot read', async (_label, code) => {
+ const { buffer, warnings } = await build(
+ [
+ ['V', 'W'],
+ [46024, 1],
+ ],
+ { V: code }
+ )
+ expect(warnings.join(' ')).toContain('is not a format')
+ expect(await formatCodes(buffer)).not.toContain(code)
+ expect(officePackageHasText(buffer, () => false)).toBe(false)
+ })
+})
diff --git a/mcp-host/src/workflow/chartGenerator.ts b/mcp-host/src/workflow/chartGenerator.ts
index 3e8ad58fa..bb502acc3 100644
--- a/mcp-host/src/workflow/chartGenerator.ts
+++ b/mcp-host/src/workflow/chartGenerator.ts
@@ -36,6 +36,7 @@ import {
MAX_CHART_DIMENSION,
MIN_CHART_DIMENSION,
} from './chartThemes'
+import { drawnTexts, recordDrawnText } from './drawnText'
import { PNG_BASE_PPM } from './embeddedImages'
import { CHART_FONT_STACK, ensureFontsReady, sanitizeForFont } from './fonts'
import { choose } from './ownEntry'
@@ -923,6 +924,7 @@ export async function runGenerateChart(
// relative to the image.
const canvas = createCanvas(layoutWidth, layoutHeight)
const ctx = canvas.getContext('2d') as SKRSContext2D
+ const shownText = recordDrawnText(ctx)
// Chart.js types target a browser CanvasRenderingContext2D; the Skia
// context is API-compatible for the subset Chart.js uses.
chart = new Chart(ctx as any, config)
@@ -963,7 +965,10 @@ export async function runGenerateChart(
`sheets[].images: [{ path: '${target.filename}' }] to the XLSX generator, or ` +
`image: { path: '${target.filename}' } or chart: { path: '${target.filename}' } ` +
'on a PPTX slide.'
- return artifactResult(target, 'png', { summary, warnings })
+ return {
+ ...artifactResult(target, 'png', { summary, warnings }),
+ shownText: drawnTexts(shownText),
+ }
} catch (err) {
if (err instanceof ChartDataError) return { success: false, error: err.message }
return { success: false, error: err instanceof Error ? err.message : String(err) }
diff --git a/mcp-host/src/workflow/drawnText.ts b/mcp-host/src/workflow/drawnText.ts
new file mode 100644
index 000000000..493487b16
--- /dev/null
+++ b/mcp-host/src/workflow/drawnText.ts
@@ -0,0 +1,27 @@
+/** The 2D context methods that draw text. */
+interface TextDrawing {
+ fillText(text: string, x: number, y: number, maxWidth?: number): void
+ strokeText(text: string, x: number, y: number, maxWidth?: number): void
+}
+
+/**
+ * Records every string drawn on `ctx` from now on, so the attachment check
+ * reads what a chart image shows (title, legend, ticks, value labels) as it is
+ * drawn, numbers already formatted. Returns the live list.
+ */
+export function recordDrawnText(ctx: TextDrawing): string[] {
+ const drawn: string[] = []
+ for (const method of ['fillText', 'strokeText'] as const) {
+ const draw = ctx[method].bind(ctx)
+ ctx[method] = (text: string, x: number, y: number, maxWidth?: number) => {
+ drawn.push(String(text))
+ return maxWidth === undefined ? draw(text, x, y) : draw(text, x, y, maxWidth)
+ }
+ }
+ return drawn
+}
+
+/** The drawn strings once each, and all of them joined, so a value drawn in pieces reads whole. */
+export function drawnTexts(drawn: string[]): string[] {
+ return [...new Set(drawn), drawn.join('')]
+}
diff --git a/mcp-host/src/workflow/officeBoilerplate.ts b/mcp-host/src/workflow/officeBoilerplate.ts
new file mode 100644
index 000000000..8a81956f1
--- /dev/null
+++ b/mcp-host/src/workflow/officeBoilerplate.ts
@@ -0,0 +1,127 @@
+/**
+ * Text every package a document generator writes carries whatever its
+ * arguments: theme and font names, namespaces, part and style names, the
+ * generators' own labels. A protected value found in such text cannot be told
+ * apart from it, so the delivered-package scan leaves that value to the check
+ * of the arguments. Built once per format from a package the generator writes
+ * with neutral content, so it follows the generators as they change.
+ */
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+import { officePackageTexts } from '../artifacts/officePackageText'
+import { logger } from '../logger'
+import type { InternalToolResult } from './types'
+
+export type OfficeFormat = 'docx' | 'xlsx' | 'pptx'
+
+type Runner = (args: Record<string, unknown>, outputDir: string) => Promise<InternalToolResult>
+
+/** Each format's generator and a call that uses its layouts, with content too short to be a protected value. */
+const SAMPLES: Record<
+ OfficeFormat,
+ { load: () => Promise<Runner>; args: Record<string, unknown> }
+> = {
+ docx: {
+ load: async () => (await import('./docxGenerator')).runGenerateDocx,
+ args: {
+ filename: 'b.docx',
+ title: 'x',
+ body:
+ '# x\n\nx **x** *x* `x` [x](https://x.y)\n\n- x\n - x\n\n1. x\n\n| a | b |\n|---|--:|\n| x | 1 |\n\n' +
+ '> x\n\n```\nx\n```',
+ tables: [{ headers: ['a'], rows: [['x']] }],
+ },
+ },
+ xlsx: {
+ load: async () => (await import('./xlsxGenerator')).runGenerateXlsx,
+ args: {
+ filename: 'b.xlsx',
+ sheets: [
+ {
+ name: 'x',
+ titleRow: { text: 'x' },
+ rows: [
+ ['a', 'b', 'c'],
+ ['x', 1, 0.5],
+ ['y', 2, 0.25],
+ ],
+ columnFormats: { b: 'currency', c: 'percent' },
+ conditionalFormatting: [
+ { column: 'b', rules: [{ greaterThan: 1, fillColor: '#dcfce7' }] },
+ ],
+ },
+ ],
+ },
+ },
+ pptx: {
+ load: async () => (await import('./pptxGenerator')).runGeneratePptx,
+ args: {
+ filename: 'b.pptx',
+ title: 'x',
+ slides: [
+ { layout: 'cover', title: 'x', subtitle: 'x' },
+ { layout: 'section', title: 'x' },
+ { layout: 'title-bullets', title: 'x', bullets: ['x'] },
+ { layout: 'kpis', title: 'x', kpis: [{ label: 'x', value: '1' }] },
+ { layout: 'title-table', title: 'x', table: { headers: ['a'], rows: [['x']] } },
+ {
+ layout: 'title-chart',
+ title: 'x',
+ chart: { type: 'bar', labels: ['a'], datasets: [{ label: 'x', data: [1] }] },
+ },
+ {
+ layout: 'title-chart',
+ title: 'x',
+ chart: { type: 'pie', labels: ['a', 'b'], datasets: [{ label: 'x', data: [1, 2] }] },
+ },
+ {
+ layout: 'title-chart',
+ title: 'x',
+ chart: { type: 'line', labels: ['a', 'b'], datasets: [{ label: 'x', data: [1, 2] }] },
+ },
+ { layout: 'quote', quote: { text: 'x', attribution: 'x' } },
+ ],
+ },
+ },
+}
+
+const references = new Map<OfficeFormat, Promise<string[]>>()
+
+/**
+ * The texts a package of `format` holds on its own. Empty when the sample
+ * cannot be written, which leaves the scan as strict as before.
+ */
+export function boilerplateTexts(format: OfficeFormat): Promise<string[]> {
+ let reference = references.get(format)
+ if (!reference) {
+ reference = writeSample(format).catch((err: unknown) => {
+ logger.warn(
+ {
+ component: 'OfficeBoilerplate',
+ format,
+ error: err instanceof Error ? err.name : typeof err,
+ },
+ 'Could not build the reference package; protected values are checked against all its text'
+ )
+ return []
+ })
+ references.set(format, reference)
+ }
+ return reference
+}
+
+async function writeSample(format: OfficeFormat): Promise<string[]> {
+ const sample = SAMPLES[format]
+ const run = await sample.load()
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-boilerplate-'))
+ try {
+ const result = await run(sample.args, dir)
+ if (!result.success || !result.artifact) throw new Error(result.error ?? 'no artifact')
+ const texts = officePackageTexts(fs.readFileSync(result.artifact.path))
+ if (!texts) throw new Error('the reference package could not be read')
+ return texts
+ } finally {
+ fs.rmSync(dir, { recursive: true, force: true })
+ }
+}
diff --git a/mcp-host/src/workflow/types.ts b/mcp-host/src/workflow/types.ts
index 785a849aa..57496316d 100644
--- a/mcp-host/src/workflow/types.ts
+++ b/mcp-host/src/workflow/types.ts
@@ -212,6 +212,12 @@ export interface InternalToolResult {
*/
content?: string
error?: string
+ /**
+ * Text the file shows that its arguments do not spell, such as the value
+ * labels a chart image draws. The attachment check reads it with the
+ * arguments; it is never sent to the model.
+ */
+ shownText?: string[]
}
/**
diff --git a/mcp-host/src/workflow/xlsxColumns.ts b/mcp-host/src/workflow/xlsxColumns.ts
index 1eb7fc0a7..aef04e8a0 100644
--- a/mcp-host/src/workflow/xlsxColumns.ts
+++ b/mcp-host/src/workflow/xlsxColumns.ts
@@ -1,6 +1,7 @@
/**
* How a sheet column is read and formatted: requested formats, the plan per column, and the value and width each cell is written with.
*/
+import { isModelledFormatCode } from '../artifacts/shownNumbers'
import { headerText } from './tableRows'
import {
type SheetCell,
@@ -226,19 +227,51 @@ export function fits(spec: FormatSpec, cell: SheetCell): boolean {
}
}
-/** The value written for `cell` and the format it is shown with. */
+/** The sections of a format code, split at ';' outside quotes, brackets and escapes. */
+function formatSections(code: string): string[] {
+ const sections: string[] = []
+ let start = 0
+ for (let i = 0; i < code.length; i++) {
+ const ch = code[i]
+ if (ch === '\\') i++
+ else if (ch === '"' || ch === '[') {
+ const end = code.indexOf(ch === '"' ? '"' : ']', i + 1)
+ i = end < 0 ? code.length : end
+ } else if (ch === ';') {
+ sections.push(code.slice(start, i))
+ start = i + 1
+ }
+ }
+ sections.push(code.slice(start))
+ return sections
+}
+
+/** `section` with its color, condition and locale tags first, then `sign`. */
+function signed(section: string, sign: string): string {
+ const tags = /^(?:\[[^\]]*\])*/.exec(section)?.[0] ?? ''
+ return `${tags}${sign}${section.slice(tags.length)}`
+}
+
/**
* `numFmt` showing a "+" before a positive value, as the cell was written. A
* format of one section gets its negative and zero sections too, since Excel
- * would otherwise print a negative as "-+5".
+ * would otherwise print a negative as "-+5". The sign goes after the tags that
+ * open a section. A format with a text section or a condition keeps its
+ * sections as they are, as does one the sign would make invalid.
*/
function withPlus(numFmt: string | undefined): string {
const format = numFmt ?? 'General'
- const sections = format.split(';')
- if (sections.length === 1) return `+${format};-${format};${format}`
- return [`+${sections[0]}`, ...sections.slice(1)].join(';')
+ const sections = formatSections(format)
+ const plain = sections.map(section => section.replace(/"[^"]*"|\\./g, ''))
+ if (plain.some(section => section.includes('@') || /\[[<>=]/.test(section))) return format
+ const plus =
+ sections.length === 1
+ ? `${signed(format, '+')};${signed(format, '-')};${format}`
+ : [signed(sections[0], '+'), ...sections.slice(1)].join(';')
+ return isModelledFormatCode(plus) ? plus : format
}
+/** The value written for `cell` and the format it is shown with. */
export function cellOutput(
cell: SheetCell,
plan: ColumnPlan
diff --git a/mcp-host/src/workflow/xlsxFormats.ts b/mcp-host/src/workflow/xlsxFormats.ts
index 0f24391ca..1787143ce 100644
--- a/mcp-host/src/workflow/xlsxFormats.ts
+++ b/mcp-host/src/workflow/xlsxFormats.ts
@@ -2,6 +2,7 @@
* Number formats for XLSX columns: the keywords a caller may ask for, and the
* format a column gets from its header and values when nobody asked.
*/
+import { isModelledFormatCode } from '../artifacts/shownNumbers'
import { own } from './ownEntry'
import { CURRENCY_SYMBOLS } from './xlsxCells'
@@ -108,7 +109,10 @@ export function formatSpec(value: unknown): FormatSpec | undefined {
if (code !== key) return { type: 'currency', symbol: `${upper} ` }
}
const trimmed = value.trim()
- return looksLikeFormatCode(trimmed) ? { type: 'custom', numFmt: trimmed } : undefined
+ // A code is written only when the attachment check can read it as shown.
+ return looksLikeFormatCode(trimmed) && isModelledFormatCode(trimmed)
+ ? { type: 'custom', numFmt: trimmed }
+ : undefined
}
/** Header words, lowercased and without accents: "Tasa de conversión" → tasa, de, conversion. */