Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
refactor(mcp-host): name ignored arguments from the generators' own aliases (H-4)
marcoteb8dc315952373
diff --git a/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts b/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.tsindex dd38bf895..c2589f61b 100644--- a/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts+++ b/mcp-host/src/workflow/__tests__/ignoredArguments.contract.test.ts@@ -1,8 +1,8 @@-// Every generator reports each argument it does not read. The note is built-// from getters on the undeclared arguments (schemaArguments.ts), so a reader-// that copies or spreads an object would read them all and hide them; this-// contract puts an undeclared key in every object the schema closes and-// expects each one named.+// Every generator reports each argument it does not take: those its schema+// does not declare, less the ones it says it took under another name+// (prepared(), toolExecution.ts). This contract puts an undeclared key in+// every object the schema closes and expects each one named, so a generator+// that claims a field it does not show is caught.import { afterEach, beforeEach, describe, expect, it } from 'vitest'import * as fs from 'fs'import * as os from 'os'diff --git a/mcp-host/src/workflow/__tests__/ignoredArguments.test.ts b/mcp-host/src/workflow/__tests__/ignoredArguments.test.tsnew file mode 100644index 000000000..f2f7377ea--- /dev/null+++ b/mcp-host/src/workflow/__tests__/ignoredArguments.test.ts@@ -0,0 +1,169 @@+// The ignored-arguments note names what a generator does not take, whatever+// the generator does with its arguments: copying or spreading an object reads+// every field of it, and must not hide one the output leaves out (H-4).+import { afterEach, beforeEach, describe, expect, it } from 'vitest'+import * as fs from 'fs'+import * as os from 'os'+import * as path from 'path'+import { INTERNAL_TOOLS } from '../internalTools'+import { prepared } from '../toolExecution'+import type { InternalToolDefinition, InternalToolResult } from '../types'++const IGNORED = /Ignored arguments this tool does not read: (.*)\.$/m++function ignoredIn(result: InternalToolResult): string[] {+ const match = IGNORED.exec(result.content ?? '')+ return match ? match[1].split(', ').map(name => name.replace(/^'|'$/g, '')) : []+}++/** A tool that renders `title` and `rows[].label` and copies everything it is given. */+function copyingTool(aliased: string[] = []): InternalToolDefinition {+ return prepared({+ name: 'clerum__generate_test',+ description: 'test',+ parameters: {+ type: 'object',+ properties: {+ title: { type: 'string' },+ rows: {+ type: 'array',+ items: { type: 'object', properties: { label: { type: 'string' } } },+ },+ },+ },+ execute: async args => {+ // Every field is read here, the undeclared ones too.+ JSON.stringify(args)+ const rows = (args.rows as Array<Record<string, unknown>>).map(row => ({ ...row }))+ return {+ success: true,+ content: `File generated: ${String(args.title)} (${rows.map(r => r.label).join(', ')})`,+ aliasedArguments: aliased,+ }+ },+ })+}++describe('arguments a generator does not take are named', () => {+ it('names an undeclared nested field the generator copies along with its sibling', async () => {+ const result = await copyingTool().execute(+ { title: 'T', rows: [{ label: 'a', color: 'red' }, { label: 'b' }], extra: 1 },+ '/unused'+ )+ expect(result.success).toBe(true)+ expect(ignoredIn(result)).toEqual(['rows[0].color', 'extra'])+ })++ it('names an undeclared nested field that has no copied sibling', async () => {+ const result = await copyingTool().execute({ title: 'T', rows: [{ color: 'red' }] }, '/unused')+ expect(ignoredIn(result)).toEqual(['rows[0].color'])+ })++ it('leaves out an argument the generator says it took under another name', async () => {+ const result = await copyingTool(['extra']).execute(+ { title: 'T', rows: [{ label: 'a', color: 'red' }], extra: 1 },+ '/unused'+ )+ expect(ignoredIn(result)).toEqual(['rows[0].color'])+ // The list stays inside mcp-host.+ expect(result).not.toHaveProperty('aliasedArguments')+ })+})++describe('generators that take an argument under another name', () => {+ let dir: string++ beforeEach(() => {+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'clerum-aliases-'))+ })++ afterEach(() => {+ fs.rmSync(dir, { recursive: true, force: true })+ })++ const tool = (name: string) => INTERNAL_TOOLS.find(t => t.name === `clerum__generate_${name}`)!++ it('xlsx: places top-level images without naming them, and names a field of the copied sheet', async () => {+ await tool('chart').execute(+ { filename: 'c.png', type: 'bar', data: { labels: ['a'], datasets: [{ data: [1] }] } },+ dir+ )+ const result = await tool('xlsx').execute(+ {+ filename: 'a.xlsx',+ sheets: [{ name: 'S', rows: [['a'], [1]], freeze: true }],+ images: ['c.png'],+ },+ dir+ )+ expect(result.success, result.error).toBe(true)+ expect(fs.existsSync(path.join(dir, 'a.xlsx'))).toBe(true)+ expect(result.content).toContain('placed on the first sheet')+ expect(ignoredIn(result)).toEqual(['sheets[0].freeze'])+ })++ it('pptx: reads a template field under its snake-case name and a team member as a KPI card', async () => {+ const result = await tool('pptx').execute(+ {+ filename: 'p.pptx',+ template: 'pitch-deck',+ data: {+ company: 'Acme',+ tagline: 't',+ problem: 'p',+ solution: 's',+ market_size: { value: 1000 },+ team: [{ label: 'Ana', value: 'CEO', photo: 'ana.png' }],+ },+ },+ dir+ )+ expect(result.success, result.error).toBe(true)+ expect(fs.existsSync(path.join(dir, 'p.pptx'))).toBe(true)+ expect(result.content).toContain('data.market_size was read as data.marketSize')+ expect(ignoredIn(result)).toEqual(['data.team[0].photo'])+ })++ it('pptx: names a KPI-card field a team member sends beside its own name', async () => {+ const result = await tool('pptx').execute(+ {+ filename: 'q.pptx',+ template: 'pitch-deck',+ data: {+ company: 'Acme',+ tagline: 't',+ problem: 'p',+ solution: 's',+ team: [{ name: 'Ana', role: 'CEO', label: 'unused' }],+ },+ },+ dir+ )+ expect(result.success, result.error).toBe(true)+ expect(ignoredIn(result)).toEqual(['data.team[0].label'])+ })++ it('dashboard: reads services listed under items with their fields, and names one it does not show', async () => {+ const result = await tool('dashboard').execute(+ {+ filename: 'd.html',+ template: 'custom',+ data: {+ title: 'T',+ blocks: [+ {+ type: 'service-health',+ items: [{ name: 'API', status: 'healthy', metric: '42 ms', owner: 'ops' }],+ },+ { type: 'kpis', items: [{ label: 'R', value: 1, sparkline: [1, 2, 3] }] },+ ],+ },+ },+ dir+ )+ expect(result.success, result.error).toBe(true)+ expect(fs.existsSync(path.join(dir, 'd.html'))).toBe(true)+ expect(result.content).toContain('the list was read from items')+ expect(ignoredIn(result)).toEqual(['data.blocks[0].items[0].owner'])+ })+})diff --git a/mcp-host/src/workflow/dashboardComponents.ts b/mcp-host/src/workflow/dashboardComponents.tsindex 7b42afb2f..c500ab655 100644--- a/mcp-host/src/workflow/dashboardComponents.ts+++ b/mcp-host/src/workflow/dashboardComponents.ts@@ -30,6 +30,33 @@ export interface DashRender {rendered: number/** Why each part that could not be shown failed. */failures: string[]+ /**+ * Argument paths the page shows that their schema may not declare: a list+ * read under its other name, and the fields of an entry it renders+ * (InternalToolResult.aliasedArguments).+ */+ aliased: string[]+}++const KPI_CARD_FIELDS = [+ 'label',+ 'value',+ 'delta',+ 'deltaDirection',+ 'deltaSentiment',+ 'accent',+ 'sparkline',+] as const+const SERVICE_CARD_FIELDS = ['name', 'status', 'metric', 'delta', 'deltaDirection'] as const++/** Records the `fields` of `entry` a card shows (DashRender.aliased). */+function takenFields(+ ctx: DashRender,+ entry: Record<string, unknown>,+ at: string,+ fields: readonly string[]+): void {+ for (const key of fields) if (own(entry, key) !== undefined) ctx.aliased.push(`${at}.${key}`)}/**@@ -265,6 +292,7 @@ export function renderKpis(items: unknown, where: string, ctx: DashRender, titlewhere,(item, at) => {const kpi = dashRecord(item, at, 'a KPI object {label, value}')+ takenFields(ctx, kpi, at, KPI_CARD_FIELDS)// A year is not grouped: 2026, not 2,026. Only a figure that could be one// is taken for it; revenue per year is still grouped.const year =@@ -564,6 +592,8 @@ export function renderServiceHealthGrid(const sentiment = direction === 'up' ? 'good' : direction === 'down' ? 'bad' : 'neutral'const delta = deltaHtml(text, direction, sentiment)const metric = dashFigure(s.metric)+ // The fields a card shows, whichever list the entries came under.+ takenFields(ctx, s, at, SERVICE_CARD_FIELDS)return `<div class="health-card" data-status="${status}"><div class="health-card__head">diff --git a/mcp-host/src/workflow/dashboardRender.ts b/mcp-host/src/workflow/dashboardRender.tsindex 131b62348..8aa08dff2 100644--- a/mcp-host/src/workflow/dashboardRender.ts+++ b/mcp-host/src/workflow/dashboardRender.ts@@ -93,6 +93,7 @@ function renderDashboard(opts: DashboardRenderOptions): { html: string; ctx: DasskippedSparklines: 0,rendered: 0,failures,+ aliased: [],}const parts = (DASHBOARD_TEMPLATES[opts.template] ?? DASHBOARD_TEMPLATES['executive-brief'])(opts.data,@@ -196,7 +197,7 @@ export async function runGenerateDashboard(enforceQuota(outputDir, Buffer.byteLength(html, 'utf-8'), replacedBytes(target))writeArtifact(target, html)- return artifactResult(target, 'html', { warnings })+ return { ...artifactResult(target, 'html', { warnings }), aliasedArguments: ctx.aliased }} catch (err) {return { success: false, error: err instanceof Error ? err.message : String(err) }}diff --git a/mcp-host/src/workflow/dashboardTemplates.ts b/mcp-host/src/workflow/dashboardTemplates.tsindex 97fbd2e97..68a9f4a6d 100644--- a/mcp-host/src/workflow/dashboardTemplates.ts+++ b/mcp-host/src/workflow/dashboardTemplates.ts@@ -165,7 +165,9 @@ function blockList(const { field, alias, noun } = own(BLOCK_LISTS, String(block.type))!if (listUnderAlias(block)) {ctx.warnings.push(`${where}: the list was read from ${alias}; name it ${field}.`)- return { value: block[alias], at: `${where}.${alias}` }+ const at = `${where}.${alias}`+ ctx.aliased.push(at)+ return { value: block[alias], at }}if (isEmptyList(block[field])) {throw new Error(diff --git a/mcp-host/src/workflow/pptxDeck.ts b/mcp-host/src/workflow/pptxDeck.tsindex 95c051caa..73143043e 100644--- a/mcp-host/src/workflow/pptxDeck.ts+++ b/mcp-host/src/workflow/pptxDeck.ts@@ -72,9 +72,10 @@ function readDeck(args: Record<string, unknown>, ctx: ReadContext): PptxSlide[]export async function buildPptxDeck(args: Record<string, unknown>,outputDir: string,- warnings: string[]+ warnings: string[],+ aliased: string[] = []): Promise<{ buffer: Buffer; slides: number }> {- const ctx: ReadContext = { outputDir, warnings }+ const ctx: ReadContext = { outputDir, warnings, aliased }const specs = readDeck(args, ctx)const palette =PPTX_PALETTES[choose(args.palette, Object.keys(PPTX_PALETTES), 'default', 'palette', warnings)]diff --git a/mcp-host/src/workflow/pptxGenerator.ts b/mcp-host/src/workflow/pptxGenerator.tsindex ac61b146f..f283a09f9 100644--- a/mcp-host/src/workflow/pptxGenerator.ts+++ b/mcp-host/src/workflow/pptxGenerator.ts@@ -17,17 +17,21 @@ export async function runGeneratePptx(try {const filename = outputFilename(args.filename, 'pptx', 'deck')const warnings: string[] = []+ const aliased: string[] = []const { buildPptxDeck } = await import('./pptxDeck')- const { buffer, slides } = await buildPptxDeck(args, outputDir, warnings)+ const { buffer, slides } = await buildPptxDeck(args, outputDir, warnings, aliased)// Buffer first, quota check, then an atomic write.ensureDir(outputDir)const target = claimOutputFile(outputDir, filename)enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))writeArtifact(target, buffer)- return artifactResult(target, 'pptx', {- summary: `File generated: ${target.filename} (pptx), ${slides} slide${slides === 1 ? '' : 's'}.`,- warnings,- })+ return {+ ...artifactResult(target, 'pptx', {+ summary: `File generated: ${target.filename} (pptx), ${slides} slide${slides === 1 ? '' : 's'}.`,+ warnings,+ }),+ aliasedArguments: aliased,+ }} catch (err) {return { success: false, error: err instanceof Error ? err.message : String(err) }}diff --git a/mcp-host/src/workflow/pptxInput.ts b/mcp-host/src/workflow/pptxInput.tsindex 398ba38ec..ef4936909 100644--- a/mcp-host/src/workflow/pptxInput.ts+++ b/mcp-host/src/workflow/pptxInput.ts@@ -127,6 +127,8 @@ export function fieldPath(slide: PptxSlide, field: string): string {export interface ReadContext {outputDir: stringwarnings: string[]+ /** Undeclared argument paths taken under another name (InternalToolResult.aliasedArguments). */+ aliased?: string[]/** Set once a text field holding markup has been reported. */markupNoted?: boolean}@@ -409,6 +411,8 @@ export function readChart(value: unknown, where: string, ctx: ReadContext): Pptxtitle: readText(value.title, `${where}.title`, TEXT_LIMITS.title, ctx),caption: readText(value.caption, `${where}.caption`, TEXT_LIMITS.caption, ctx),}+ // Chart.js nests labels and datasets under data; they are read there too.+ if (isRecord(value.data)) ctx.aliased?.push(`${where}.data`)try {chart.native = readNativeChart(value, where, ctx.warnings)} catch (err) {diff --git a/mcp-host/src/workflow/pptxTemplates.ts b/mcp-host/src/workflow/pptxTemplates.tsindex c2c9da4d0..5f197ea93 100644--- a/mcp-host/src/workflow/pptxTemplates.ts+++ b/mcp-host/src/workflow/pptxTemplates.ts@@ -88,6 +88,7 @@ function placeFields(if (camel !== undefined) {fields[camel] = valuectx.warnings.push(`data.${key} was read as data.${camel}.`)+ ctx.aliased?.push(`data.${key}`)continue}unknown.push(key)@@ -356,6 +357,12 @@ function pitchDeck(f: Record<string, unknown>, ctx: ReadContext): PptxSlide[] {const at = `data.team[${i}]`if (!isRecord(p)) throw new PptxInputError(`${at} must be an object with name and role.`)// Workflows written against the KPI-card shape send {label: name, value: role}.+ if ((p.name === undefined || p.name === null) && p.label !== undefined) {+ ctx.aliased?.push(`${at}.label`)+ }+ if ((p.role === undefined || p.role === null) && p.value !== undefined) {+ ctx.aliased?.push(`${at}.value`)+ }const name = readText(p.name ?? p.label, `${at}.name`, TEXT_LIMITS.value, ctx)if (!name) throw new PptxInputError(`${at}.name is missing.`)return {@@ -438,6 +445,8 @@ export function buildTemplateSlides(throw new PptxInputError(`${message} As sent, the deck would hold only its cover.`)}ctx.warnings.push(`${message} ${unknown.length > 1 ? 'They were' : 'It was'} left out.`)+ // Named in the template's own note, so not again as ignored arguments.+ for (const k of unknown) ctx.aliased?.push(`data.${k}`)}return slides}diff --git a/mcp-host/src/workflow/schemaArguments.ts b/mcp-host/src/workflow/schemaArguments.tsindex ad455cc9e..51fc0772c 100644--- a/mcp-host/src/workflow/schemaArguments.ts+++ b/mcp-host/src/workflow/schemaArguments.ts@@ -66,14 +66,14 @@ function readablePath(parts: Array<string | number>): string {.join('')}-interface UnknownArgument {- path: string- holder: Record<string, unknown>- key: string-}--function unknownEntries(schema: unknown, value: unknown): UnknownArgument[] {- const found: UnknownArgument[] = []+/**+ * 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[] {+ const found: string[] = []const visit = (raw: SchemaNode | undefined, item: unknown, at: Array<string | number>) => {const node = nodeFor(raw, item)if (!node || at.length > 64) return@@ -85,45 +85,9 @@ function unknownEntries(schema: unknown, value: unknown): UnknownArgument[] {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 })+ else found.push(readablePath([...at, 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/toolExecution.ts b/mcp-host/src/workflow/toolExecution.tsindex 3c0ee9ae3..6d91c5a5c 100644--- a/mcp-host/src/workflow/toolExecution.ts+++ b/mcp-host/src/workflow/toolExecution.ts@@ -1,5 +1,5 @@/** How every internal tool runs: lazy generator modules and the argument preparation around them. */-import { watchUnknownArguments, withoutUnsetNulls } from './schemaArguments'+import { unknownArguments, withoutUnsetNulls } from './schemaArguments'import { cleanToolArgs } from './toolText'import type { InternalToolDefinition, InternalToolResult } from './types'@@ -23,7 +23,9 @@ export async function fromModule<M>(/*** A generator that runs on cleaned arguments (cleanToolArgs, unset nulls- * dropped, named images decoded) and reports the arguments it did not read.+ * dropped, named images decoded) and reports the arguments it does not take:+ * those its schema does not declare, less the ones the generator says it took+ * under another name (aliasedArguments).*/export function prepared(tool: InternalToolDefinition): InternalToolDefinition {return {@@ -41,14 +43,18 @@ export function prepared(tool: InternalToolDefinition): InternalToolDefinition {} catch (err) {return { success: false, error: err instanceof Error ? err.message : String(err) }}- const unknown = watchUnknownArguments(tool.parameters, clean)- let result: InternalToolResult+ // Named from the arguments as sent, before the generator runs, so nothing+ // it does with them (a copy, a spread) changes what is reported.+ const undeclared = unknownArguments(tool.parameters, clean)+ let outcome: InternalToolResulttry {- result = await tool.execute(clean, outputDir)+ outcome = await tool.execute(clean, outputDir)} finally {release()}- const ignored = unknown.ignored()+ const { aliasedArguments, ...result } = outcome+ const taken = new Set(aliasedArguments ?? [])+ const ignored = undeclared.filter(entry => !taken.has(entry))if (!result.success || ignored.length === 0) return resultconst listed = ignored.slice(0, 10).map(name => `'${name}'`)if (ignored.length > 10) listed.push(`and ${ignored.length - 10} more`)diff --git a/mcp-host/src/workflow/types.ts b/mcp-host/src/workflow/types.tsindex 0e78df198..be6a48b21 100644--- a/mcp-host/src/workflow/types.ts+++ b/mcp-host/src/workflow/types.ts@@ -224,6 +224,13 @@ export interface InternalToolResult {* is never sent to the model.*/writtenSha256?: string+ /**+ * Arguments the schema does not declare that the generator took under+ * another name, or named in a note of its own, as paths ("images",+ * "data.team[0].label"). The ignored-arguments note leaves them out. It is+ * never sent to the model.+ */+ aliasedArguments?: string[]}/**diff --git a/mcp-host/src/workflow/xlsxGenerator.ts b/mcp-host/src/workflow/xlsxGenerator.tsindex f87530938..81ef95837 100644--- a/mcp-host/src/workflow/xlsxGenerator.ts+++ b/mcp-host/src/workflow/xlsxGenerator.ts@@ -21,12 +21,14 @@ export async function runGenerateXlsx(try {const filename = outputFilename(args.filename, 'xlsx', 'output')const warnings: string[] = []+ const aliased: string[] = []const { buildXlsxWorkbook } = await import('./xlsxWorkbook')const built = await buildXlsxWorkbook(args,outputDir,{ width: XLSX_MAX_IMAGE_WIDTH, height: XLSX_MAX_IMAGE_HEIGHT },- warnings+ warnings,+ aliased)if (!built.ok) return { success: false, error: built.error }// The workbook is already in memory, so a quota breach leaves no partial file.@@ -34,10 +36,13 @@ export async function runGenerateXlsx(const target = claimOutputFile(outputDir, filename)enforceQuota(outputDir, built.buffer.byteLength, replacedBytes(target))writeArtifact(target, built.buffer)- return artifactResult(target, 'xlsx', {- summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,- warnings,- })+ return {+ ...artifactResult(target, 'xlsx', {+ summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,+ warnings,+ }),+ aliasedArguments: aliased,+ }} catch (err) {return { success: false, error: err instanceof Error ? err.message : String(err) }}diff --git a/mcp-host/src/workflow/xlsxWorkbook.ts b/mcp-host/src/workflow/xlsxWorkbook.tsindex d0ef314c9..ea173df66 100644--- a/mcp-host/src/workflow/xlsxWorkbook.ts+++ b/mcp-host/src/workflow/xlsxWorkbook.ts@@ -607,7 +607,8 @@ export async function buildXlsxWorkbook(args: Record<string, unknown>,outputDir: string,imageBox: ImageSize,- warnings: string[]+ warnings: string[],+ aliased: string[] = []): Promise<XlsxBuild> {const requested = args.sheetsif (!Array.isArray(requested) || requested.length === 0) {@@ -623,19 +624,8 @@ export async function buildXlsxWorkbook(if (topLevelImagesPlaced(args)) {const first = sheets[0] as Record<string, unknown>const own = Array.isArray(first.images) ? first.images : []- // A copy of the sheet's property descriptors, not of its values: a spread- // would read every field, and a field read counts as used (prepared()).- const moved = Object.defineProperties({}, Object.getOwnPropertyDescriptors(first)) as Record<- string,- unknown- >- Object.defineProperty(moved, 'images', {- value: [...own, ...(args.images as unknown[])],- enumerable: true,- writable: true,- configurable: true,- })- sheets = [moved, ...sheets.slice(1)]+ sheets = [{ ...first, images: [...own, ...(args.images as unknown[])] }, ...sheets.slice(1)]+ aliased.push('images')warnings.push('images belongs inside each sheet (sheets[i].images); the top-level images were placed on the first sheet.')