Skip to content

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

TypeScript

refactor(mcp-host): make internalTools a list of tools instead of a hub

marcotebeecff7d17689
diff --git a/mcp-host/src/workflow/chartGenerator.ts b/mcp-host/src/workflow/chartGenerator.ts
index 7b77803d4..5e4598d7b 100644
--- a/mcp-host/src/workflow/chartGenerator.ts
+++ b/mcp-host/src/workflow/chartGenerator.ts
@@ -478,16 +478,6 @@ function resolveChartType(
}
}
-// ─── Portable schema fragments ───────────────────────────────────────
-//
-// A tool schema does two jobs. The workflow path (stepRouter) compiles it with
-// AJV and REJECTS arguments that do not match before execute() runs, so it must
-// accept everything the runtime handles. And it reaches every provider
-// verbatim, so it must survive each SDK's translation. Unions are therefore
-// written as scalar type lists or `anyOf` branches — @google/genai turns both
-// into its own schema — and never as `oneOf`, which it passes through
-// untranslated for the Gemini API to reject. Every array declares `items`.
-
/** Nominal pixels are multiplied by this to keep charts sharp when scaled down. */
const CHART_PIXEL_RATIO = 2
diff --git a/mcp-host/src/workflow/internalTools.ts b/mcp-host/src/workflow/internalTools.ts
index b7974bae0..5e1c07ea5 100644
--- a/mcp-host/src/workflow/internalTools.ts
+++ b/mcp-host/src/workflow/internalTools.ts
@@ -5,316 +5,38 @@
* a document artifact (markdown, PDF, DOCX, XLSX, PPTX, PNG chart, HTML
* dashboard) and writes it to the output directory (getOutputDir).
*
- * This file holds the schemas. Each generator is its own module, loaded with
- * its library on first use: pdfmake (PDF), docx (DOCX), exceljs (XLSX),
- * pptxgenjs (PPTX), chart.js (PNG charts); markdown and the dashboard HTML are
- * written as strings. No headless browser is involved, but @napi-rs/canvas is
- * native, and charts, PDFs and the measuring of DOCX tables and slide text read
- * the fonts the image installs (fonts.ts).
+ * This file lists them. Each schema is in toolSchemas/, and each generator is
+ * its own module, loaded with its library on first use: pdfmake (PDF), docx
+ * (DOCX), exceljs (XLSX), pptxgenjs (PPTX), chart.js (PNG charts); markdown and
+ * the dashboard HTML are written as strings. No headless browser is involved,
+ * but @napi-rs/canvas is native, and charts, PDFs and the measuring of DOCX
+ * tables and slide text read the fonts the image installs (fonts.ts).
*/
-import * as fs from 'fs'
-import * as path from 'path'
-import { config } from '../config'
-import { WorkflowListTool, WorkflowStatusTool } from '../core/tools/workflowReadTools'
-import { WorkflowTriggerTool } from '../core/tools/workflowTriggerTool'
-import {
- artifactResult,
- claimOutputFile,
- enforceQuota,
- ensureDir,
- outputFilename,
- replacedBytes,
-} from './artifactOutput'
-import {
- DEFAULT_CHART_HEIGHT,
- DEFAULT_CHART_WIDTH,
- MAX_CHART_DIMENSION,
- MIN_CHART_DIMENSION,
-} from './chartThemes'
import { CONTEXT_FILES_TOOLS, loadContextFilesMounts } from './contextFiles'
import { runGenerateDashboard } from './dashboardRender'
-import {
- BLOCK_TYPES,
- CALLOUT_TONES,
- DASHBOARD_CHART_TYPES,
- DASHBOARD_TEMPLATE_NAMES,
- HERO_STATUSES,
- SECTION_TYPES,
-} from './dashboardVocabulary'
-import {
- DOCX_IMAGE_FILE_DESCRIPTION,
- IMAGE_FILE_DESCRIPTION,
- PDF_MAX_FOOTER_LINES,
- PDF_PORTRAIT_WIDTH,
-} from './documentSchema'
-import {
- NATIVE_CHART_TYPES,
- PPTX_ASPECT_RATIOS,
- PPTX_PALETTES,
- PPTX_TEMPLATES,
- SEVERITIES,
- SLIDE_LAYOUTS,
- STATUSES,
-} from './pptxVocabulary'
-import { watchUnknownArguments, withoutUnsetNulls } from './schemaArguments'
-import { cleanToolArgs } from './toolText'
+import { runGenerateMarkdown } from './markdownGenerator'
+import { runGeneratePptx } from './pptxGenerator'
+import { fromModule, nullsUnset, prepared } from './toolExecution'
+import { CHART_TOOL } from './toolSchemas/chart'
+import { DASHBOARD_TOOL } from './toolSchemas/dashboard'
+import { DOCX_TOOL } from './toolSchemas/docx'
+import { MARKDOWN_TOOL } from './toolSchemas/markdown'
+import { PDF_TOOL } from './toolSchemas/pdf'
+import { PPTX_TOOL } from './toolSchemas/pptx'
+import { XLSX_TOOL } from './toolSchemas/xlsx'
import type { InternalToolDefinition, InternalToolResult } from './types'
+import { listWorkflows, readWorkflow, triggerWorkflow } from './workflowTools'
+import { runGenerateXlsx } from './xlsxGenerator'
export { enforceQuota, getDirectorySize } from './artifactOutput'
export { CHART_THEMES } from './chartThemes'
export type { ChartTheme } from './chartThemes'
export { escapeHtmlAttr, safeJsonForScript } from './dashboardHtml'
export { loadChartJsBundle } from './dashboardChartJs'
-
-// Accessor to the current Host CRD, injected by main (avoids a circular import).
-// Re-read on every getOutputDir() call because `currentHost` is hydrated async
-// after boot — caching the path at module load would freeze it to the fallback.
-type WorkspaceHostAccessor = () =>
- | { spec?: { memory?: { workspacePath?: string } } }
- | null
- | undefined
-let outputDirHostAccessor: WorkspaceHostAccessor | null = null
-
-/** Wire the Host CRD accessor so chat-mode artifacts resolve to the workspace PVC. */
-export function setOutputDirHostAccessor(accessor: WorkspaceHostAccessor): void {
- outputDirHostAccessor = accessor
-}
-
-// ─── Security helpers ────────────────────────────────────────────────
-//
-// Boundary primitives applied at the seam between LLM-supplied data
-// and the generated artifact. They guard against XSS in HTML output,
-// path traversal when reading user-named files, and formula injection
-// in spreadsheet cells.
-
-/**
- * Resolve `p` against `outputDir` and ensure the result stays inside
- * `outputDir`. Throws on traversal attempts (`../etc/passwd`, absolute
- * paths outside the dir, symlink-style escapes). Returns the absolute
- * resolved path.
- *
- * The caller decides whether the file must already exist; this helper
- * only enforces the path-containment invariant.
- */
-export function validateOutputPath(p: string, outputDir: string): string {
- if (typeof p !== 'string' || p.length === 0) {
- throw new Error('path must be a non-empty string')
- }
- const root = path.resolve(outputDir)
- const resolved = path.resolve(root, p)
- if (resolved !== root && !resolved.startsWith(root + path.sep)) {
- throw new Error(`path traversal blocked: ${p}`)
- }
- return resolved
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────
-
-/**
- * The types of a table or sheet cell: text, a number, true/false, or null for
- * an empty cell. Each runtime stringifies or formats what arrives.
- */
-const CELL_TYPES = ['string', 'number', 'boolean', 'null']
-
-/**
- * A row sent as a {header: cell} record, which every runtime reads by header
- * name. Gemini rejects an object schema with no properties, so it declares one
- * example key; additionalProperties keeps the others valid. The example is a
- * column index, which the runtime reads as that column.
- */
-const RECORD_ROW_SCHEMA = {
- type: 'object',
- properties: { '0': { type: CELL_TYPES, description: 'Column 0, or a header.' } },
- additionalProperties: { type: CELL_TYPES },
-}
-
-/** One row of cells, left to right in header order, or a record. */
-const ROW_SCHEMA = { anyOf: [{ type: 'array', items: { type: CELL_TYPES } }, RECORD_ROW_SCHEMA] }
-
-/** A single color, or one per data point. */
-function colorSchema(what: string): Record<string, unknown> {
- return {
- anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
- description: `${what}: a hex color, or an array of one per point.`,
- }
-}
-
-/**
- * One chart data point. Numbers are the norm; the rest are shapes models send
- * that normalizeChartData repairs or needs — text such as "1,200", null for a
- * gap, {x, y[, r]} or [x, y[, r]] for scatter and bubble, {x, y} with a
- * category x, and {label, value} records or [label, value] pairs.
- */
-const CHART_POINT_SCHEMA = {
- anyOf: [
- { type: 'number' },
- { type: 'string' },
- { type: 'null' },
- { type: 'array', items: { type: ['number', 'string'] } },
- {
- type: 'object',
- properties: {
- x: { type: ['number', 'string'], description: 'X value.' },
- y: { type: 'number', description: 'Y value.' },
- r: { type: 'number', description: 'Bubble radius (px).' },
- label: { type: 'string', description: 'Category.' },
- value: { type: ['number', 'string'], description: 'Value.' },
- },
- },
- ],
- description: 'A number, null for a gap, or {x, y} / {x, y, r} or [x, y] for scatter / bubble.',
-}
-
-/**
- * Runs a generator from its own module, loaded on first use so that starting
- * the host loads no document library. A module that fails to load fails the
- * call the way a generator error does.
- */
-async function fromModule<M>(
- load: () => Promise<M>,
- run: (loaded: M) => Promise<InternalToolResult>
-): Promise<InternalToolResult> {
- let loaded: M
- try {
- loaded = await load()
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- return run(loaded)
-}
+export { getOutputDir, setOutputDirHostAccessor, validateOutputPath } from './outputDirectory'
const generateChart: InternalToolDefinition = {
- name: 'clerum__generate_chart',
- description:
- 'Render a chart as a PNG image, with values printed on it by default. Returns the file ' +
- 'name it was saved under, such as "sales.png"; pass it as images[].path to the PDF or ' +
- 'DOCX generator, as sheets[].images[].path to the XLSX generator, or as a PPTX slide ' +
- 'image.path or chart.path.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename (e.g. 'revenue.png'); .png added if missing.",
- },
- type: {
- type: 'string',
- enum: [
- 'line',
- 'bar',
- 'horizontalBar',
- 'pie',
- 'doughnut',
- 'area',
- 'scatter',
- 'radar',
- 'polarArea',
- 'bubble',
- 'stackedBar',
- 'stackedArea',
- 'mixedBarLine',
- 'gauge',
- 'waterfall',
- 'funnel',
- ],
- description:
- 'area: filled line. mixedBarLine: first dataset as bars, the rest as lines. ' +
- 'gauge: one value 0..gaugeMax as a half dial. waterfall: one series of deltas, ' +
- 'drawn as steps plus a total bar. funnel: one series, sorted descending.',
- },
- title: {
- type: 'string',
- description: 'Title above the plot. Always set one.',
- },
- width: {
- type: 'number',
- description:
- `Width in px (default ${DEFAULT_CHART_WIDTH}, ${MIN_CHART_DIMENSION}-${MAX_CHART_DIMENSION}; ` +
- 'width × height up to about 13 million). The PNG is up to 2× this.',
- },
- height: {
- type: 'number',
- description: `Height in px (default ${DEFAULT_CHART_HEIGHT}, ${MIN_CHART_DIMENSION}-${MAX_CHART_DIMENSION}).`,
- },
- theme: {
- type: 'string',
- enum: ['light', 'dark', 'corporate', 'warm', 'warm-dark'],
- description: "Color theme. Default 'light'.",
- },
- data: {
- type: 'object',
- description: 'Series to plot. Colors come from the theme unless a dataset sets them.',
- properties: {
- labels: {
- type: 'array',
- items: { type: ['string', 'number'] },
- description:
- 'One per value: X-axis categories, or slice names (required) for ' +
- 'pie/doughnut/polarArea. Unused by scatter/bubble.',
- },
- datasets: {
- type: 'array',
- description: 'One or more series.',
- items: {
- type: 'object',
- required: ['data'],
- properties: {
- label: {
- type: 'string',
- description: 'Series name, shown in the legend.',
- },
- data: {
- type: 'array',
- items: CHART_POINT_SCHEMA,
- description: 'One point per label, in labels order.',
- },
- backgroundColor: colorSchema('Fill color'),
- borderColor: colorSchema('Line/border color'),
- fill: { type: 'boolean', description: 'Fill under a line series.' },
- },
- },
- },
- },
- required: ['datasets'],
- },
- yAxisLabel: { type: 'string', description: 'Y-axis title, e.g. "USD".' },
- xAxisLabel: { type: 'string', description: 'X-axis title.' },
- showValues: {
- type: 'boolean',
- description:
- 'Print each value on the chart. Default on, except scatter, bubble, radar, gauge and stacked types.',
- },
- valueFormat: {
- type: 'string',
- enum: ['auto', 'plain', 'compact', 'currency', 'percent'],
- description:
- 'Number style on the chart and value axis. auto: abbreviate above 10,000; compact: ' +
- 'always (1.2M); currency: prefix currencySymbol; percent: append %.',
- },
- currencySymbol: {
- type: 'string',
- description: "For valueFormat 'currency'. Default '$'.",
- },
- decimals: {
- type: 'number',
- description: 'Decimal places on printed values. Default: per value.',
- },
- showLegend: {
- type: 'boolean',
- description:
- 'Legend on or off. Default: on for several series, or one the titles do not name.',
- },
- dualAxis: {
- type: 'boolean',
- description: 'mixedBarLine only: put the line series on a second, right-hand axis.',
- },
- gaugeMax: {
- type: 'number',
- description: 'gauge only: dial maximum (default 100).',
- },
- },
- required: ['filename', 'type', 'data'],
- },
+ ...CHART_TOOL,
execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
return fromModule(
() => import('./chartGenerator'),
@@ -323,192 +45,10 @@ const generateChart: InternalToolDefinition = {
},
}
-/** The file text, or an error saying what content must be; never a stringified array or object. */
-function markdownContent(value: unknown): string | { error: string } {
- if (value === undefined || value === null) {
- return { error: 'content is required: pass the markdown text to write.' }
- }
- const lines = Array.isArray(value) ? value : [value]
- if (!lines.every(line => typeof line === 'string')) {
- const received = Array.isArray(value)
- ? 'an array with entries that are not text'
- : `a ${typeof value}`
- return {
- error: `content must be the markdown text as a string, or an array of lines; received ${received}.`,
- }
- }
- const text = lines.join('\n')
- if (!text.trim()) return { error: 'content is empty: pass the markdown text to write.' }
- return text
-}
-
-const generateMarkdown: InternalToolDefinition = {
- name: 'clerum__generate_markdown',
- description: 'Generate a Markdown (.md) file. Provide the filename and full markdown content.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename (e.g. 'report.md'). Extension .md added if missing.",
- },
- content: {
- anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
- description: 'Full markdown text, as one string or an array of lines.',
- },
- },
- required: ['filename', 'content'],
- },
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'md', 'output')
- const content = markdownContent(args.content)
- if (typeof content !== 'string') return { success: false, error: content.error }
-
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, Buffer.byteLength(content, 'utf-8'), replacedBytes(target))
- fs.writeFileSync(target.filePath, content, 'utf-8')
-
- return artifactResult(target, 'md')
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- },
-}
-
-// ─── generate_pdf ────────────────────────────────────────────────────
-
-/** Drawn size for a spreadsheet image, in pixels. */
-const XLSX_MAX_IMAGE_WIDTH = 640
-const XLSX_MAX_IMAGE_HEIGHT = 400
+const generateMarkdown: InternalToolDefinition = { ...MARKDOWN_TOOL, execute: runGenerateMarkdown }
const generatePdf: InternalToolDefinition = {
- name: 'clerum__generate_pdf',
- description:
- 'Generate a print-quality PDF from a markdown body, with optional images, tables, a cover ' +
- 'page with a status band, page numbers and a branded footer.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename, e.g. 'report.pdf'.",
- },
- title: {
- type: 'string',
- description: 'Document title, shown at the top of the first page.',
- },
- body: {
- type: 'string',
- description:
- 'Markdown: # to ### headings, **bold**, *italic*, ~~strike~~, `code`, [links](url), ' +
- 'fenced code, "- " and "1. " lists, GFM pipe tables, "> " quotes, "---" rules, <br>/<b>/<i>, ' +
- 'and ![alt](file.png) on its own line to place an image from the output folder.',
- },
- palette: {
- type: 'string',
- enum: ['default', 'corporate', 'warm', 'alert'],
- description: "Color palette. Default 'default'.",
- },
- coverPage: {
- type: 'boolean',
- description: 'Add a cover page with the title, headline, logo and status band.',
- },
- headline: {
- type: 'string',
- description: 'One-line subtitle under the title on the cover page.',
- },
- statusColor: {
- type: 'string',
- enum: ['green', 'yellow', 'red'],
- description: 'Color of the status band on the cover page.',
- },
- images: {
- type: 'array',
- description:
- 'Images (charts, logos) placed after the body and tables, in order; ' +
- 'put ![alt](file.png) on a line of the body to place one there.',
- items: {
- anyOf: [
- { type: 'string', description: IMAGE_FILE_DESCRIPTION },
- {
- type: 'object',
- required: ['path'],
- properties: {
- path: { type: 'string', description: IMAGE_FILE_DESCRIPTION },
- width: {
- type: 'number',
- description: `Width in points (the page is ${PDF_PORTRAIT_WIDTH} wide); the height follows.`,
- },
- height: {
- type: 'number',
- description: 'Height in points. With width too, the image fits inside both.',
- },
- alignment: {
- type: 'string',
- enum: ['left', 'center', 'right'],
- description: "Default 'center'.",
- },
- },
- },
- ],
- description: 'A file name, or an object with path and size.',
- },
- },
- tables: {
- type: 'array',
- description: 'Tables placed after the body.',
- items: {
- type: 'object',
- required: ['headers', 'rows'],
- properties: {
- headers: {
- type: 'array',
- items: { type: ['string', 'number'], description: 'One column heading.' },
- description: 'Column headings, left to right.',
- },
- rows: {
- type: 'array',
- items: ROW_SCHEMA,
- description: 'Rows, each an array of cells in header order.',
- },
- widths: {
- type: 'array',
- items: { type: ['string', 'number'], description: 'One column width.' },
- description:
- "One per header: points, a percentage such as '30%', 'auto' or '*' (share the rest). " +
- 'Omit to size columns by content.',
- },
- layout: {
- type: 'string',
- enum: ['striped', 'minimal', 'grid'],
- description: "Default 'striped'.",
- },
- },
- },
- },
- branding: {
- type: 'object',
- description: 'Header and footer branding.',
- properties: {
- logoPath: {
- type: 'string',
- description: `Logo drawn on the cover page (needs coverPage: true). ${IMAGE_FILE_DESCRIPTION}`,
- },
- companyName: {
- type: 'string',
- description: 'Shown in the running header.',
- },
- footerText: {
- type: 'string',
- description: `Footer on every page, up to ${PDF_MAX_FOOTER_LINES} lines.`,
- },
- },
- },
- },
- required: ['filename', 'body'],
- },
+ ...PDF_TOOL,
execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
return fromModule(
() => import('./pdfGenerator'),
@@ -517,115 +57,8 @@ const generatePdf: InternalToolDefinition = {
},
}
-// ─── generate_docx ───────────────────────────────────────────────────
-
const generateDocx: InternalToolDefinition = {
- name: 'clerum__generate_docx',
- description:
- 'Generate a styled Word (.docx) file from a markdown body, with optional tables, images, ' +
- 'a palette and a branded header and footer with page numbers. The result lists anything ' +
- 'left out.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename (e.g. 'report.docx'); .docx added if missing.",
- },
- title: {
- type: 'string',
- description: 'Title at the top, also in the running header.',
- },
- body: {
- type: 'string',
- description:
- 'Markdown: # to ###### headings, **bold**, *italic*, `code`, [links](https://...), ' +
- '"- " and "1. " lists (indent to nest), GFM pipe tables, ``` code blocks, > quotes, ' +
- '--- rules, <br>. ![alt](chart.png) on its own line embeds an image from the output folder.',
- },
- palette: {
- type: 'string',
- enum: ['default', 'corporate', 'warm', 'alert'],
- description: "Color palette. Default 'default'.",
- },
- headline: {
- type: 'string',
- description: 'One-line subtitle under the title.',
- },
- images: {
- type: 'array',
- description: 'Images added after the body and tables, in order.',
- items: {
- anyOf: [
- { type: 'string', description: DOCX_IMAGE_FILE_DESCRIPTION },
- {
- type: 'object',
- required: ['path'],
- properties: {
- path: { type: 'string', description: 'Same as the string form.' },
- width: {
- type: 'number',
- description: 'Width in px; proportions are kept and the image fits the page.',
- },
- height: { type: 'number', description: 'Height in px; as for width.' },
- alignment: {
- type: 'string',
- enum: ['left', 'center', 'right'],
- description: "Default 'left'.",
- },
- },
- },
- ],
- description: 'An image file name, or {path, width, height, alignment}.',
- },
- },
- tables: {
- type: 'array',
- description: 'Tables added after the body.',
- items: {
- type: 'object',
- required: ['headers', 'rows'],
- properties: {
- headers: {
- type: 'array',
- items: {
- type: ['string', 'number'],
- description: 'Heading text or number.',
- },
- description: 'Column headings, left to right.',
- },
- rows: {
- type: 'array',
- items: ROW_SCHEMA,
- description: 'Rows of cells in header order. Cells take inline markdown and <br>.',
- },
- layout: {
- type: 'string',
- enum: ['striped', 'minimal', 'grid'],
- description:
- "striped: alternating fills; minimal: a rule under the header; grid: all borders. Default 'striped'.",
- },
- },
- },
- },
- branding: {
- type: 'object',
- description: 'Branding for the header, footer and first page.',
- properties: {
- companyName: { type: 'string', description: 'Left side of the running header.' },
- logoPath: {
- type: 'string',
- description: 'Logo above the title; an image file name as in images.',
- },
- footerText: {
- type: 'string',
- description: 'Text at the left of every footer; \\n starts a new line (up to 6).',
- },
- },
- },
- },
- required: ['filename', 'body'],
- },
+ ...DOCX_TOOL,
execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
return fromModule(
() => import('./docxGenerator'),
@@ -634,1208 +67,16 @@ const generateDocx: InternalToolDefinition = {
},
}
-// ─── generate_xlsx ───────────────────────────────────────────────────
-
-const XLSX_CELL_SCHEMA = {
- type: ['string', 'number', 'boolean', 'null'],
- description:
- 'A number, text, true/false, or null for empty. Text like "1,234.50", "$1,200", "45%" ' +
- 'or an ISO date or datetime ("2026-09-22") is stored as a number or date; leading-zero codes and ' +
- 'numbers over 15 digits stay text.',
-}
-
-const XLSX_IMAGE_PATH_DESCRIPTION =
- "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png')."
-
-const XLSX_COLOR = 'hex such as "#1e3a8a" or a basic color name such as "green"'
-
-const generateXlsx: InternalToolDefinition = {
- name: 'clerum__generate_xlsx',
- description:
- 'Generate a styled Excel (.xlsx) workbook: per sheet, rows plus an optional title row, ' +
- 'column formats, conditional formatting and images such as charts. Formulas are not ' +
- 'supported: text starting with "=" stays text.',
- parameters: {
- type: 'object',
- properties: {
- filename: {
- type: 'string',
- description: "Output filename (e.g. 'data.xlsx'); .xlsx added if missing.",
- },
- palette: {
- type: 'string',
- enum: ['default', 'corporate', 'warm', 'alert'],
- description: "Color palette. Default 'default'.",
- },
- branding: {
- type: 'object',
- description: 'Workbook-level branding.',
- properties: {
- companyName: { type: 'string', description: 'Author/company in workbook properties.' },
- logoPath: {
- type: 'string',
- description:
- 'Logo at the top of the first sheet; an image file name as in sheets[].images.',
- },
- },
- },
- sheets: {
- type: 'array',
- description: 'Worksheets, in tab order.',
- items: {
- type: 'object',
- required: ['name', 'rows'],
- properties: {
- name: {
- type: 'string',
- description: 'Tab name: up to 31 characters, none of \\ / ? * : [ ].',
- },
- headers: {
- type: 'array',
- description: 'Header row, when it is not the first row of rows.',
- items: { type: ['string', 'number'], description: 'Column header.' },
- },
- rows: {
- type: 'array',
- description:
- 'Rows of cells; the first is the header row unless headers is given. [] for an images-only sheet.',
- items: {
- anyOf: [
- {
- type: 'array',
- description: 'One row, left to right.',
- items: XLSX_CELL_SCHEMA,
- },
- RECORD_ROW_SCHEMA,
- ],
- },
- },
- titleRow: {
- type: 'object',
- description: 'Merged title row above the header.',
- properties: {
- text: { type: 'string', description: 'Title text.' },
- fillColor: { type: 'string', description: `Background: ${XLSX_COLOR}.` },
- fontColor: { type: 'string', description: `Text color: ${XLSX_COLOR}.` },
- },
- required: ['text'],
- },
- columnFormats: {
- type: 'object',
- description:
- "Format per column, keyed by header text, letter ('B') or 0-based index: " +
- 'currencyUsd, currencyUsdInt, currency:EUR (any ISO code), percent (0.45 = 45%), ' +
- 'percentPoints (45 = 45%), integer, decimal, plain (no separators: years, IDs), ' +
- "date, datetime, text (as sent), or an Excel code like '#,##0.0'. Others are inferred.",
- },
- conditionalFormatting: {
- type: 'array',
- description: "Style a column's cells that match a rule.",
- items: {
- type: 'object',
- required: ['column', 'rules'],
- properties: {
- column: {
- type: ['string', 'number'],
- description: "Header text, letter ('B') or 0-based index.",
- },
- rules: {
- type: 'array',
- description:
- "Tested in order; the first match styles the cell. '45%' compares as 45, '$1,200' as 1200.",
- items: {
- type: 'object',
- properties: {
- equals: {
- type: ['string', 'number', 'boolean'],
- description: 'Cell equals this (text ignores case and outer spaces).',
- },
- notEquals: {
- type: ['string', 'number', 'boolean'],
- description: 'Cell differs from this, compared as for equals.',
- },
- greaterThan: {
- type: 'number',
- description: 'Cell is a number above this.',
- },
- lessThan: {
- type: 'number',
- description: 'Cell is a number below this.',
- },
- between: {
- type: 'array',
- items: { type: 'number' },
- minItems: 2,
- maxItems: 2,
- description: 'Inclusive [min, max].',
- },
- contains: {
- type: 'string',
- description: 'Cell text contains this, ignoring case.',
- },
- regex: {
- type: 'string',
- maxLength: 256,
- description:
- 'Regex tested on the cell text. Invalid patterns and nested unbounded quantifiers are skipped with a warning.',
- },
- fillColor: {
- type: 'string',
- description: `Background: ${XLSX_COLOR}.`,
- },
- fontColor: {
- type: 'string',
- description: `Text color: ${XLSX_COLOR}.`,
- },
- bold: {
- type: 'boolean',
- description: 'Bold the text.',
- },
- },
- },
- },
- },
- },
- },
- freezeHeader: {
- type: 'boolean',
- description: 'Freeze the header row. Default true.',
- },
- autoFilter: {
- type: 'boolean',
- description: 'Filter buttons on the header. Default true.',
- },
- images: {
- type: 'array',
- description:
- 'Images such as charts; without anchor or range they stack below the data.',
- items: {
- anyOf: [
- { type: 'string', description: XLSX_IMAGE_PATH_DESCRIPTION },
- {
- type: 'object',
- required: ['path'],
- properties: {
- path: { type: 'string', description: 'Same as the string form.' },
- anchor: { type: 'string', description: "Top-left cell, e.g. 'F2'." },
- range: { type: 'string', description: "Cells to fill, e.g. 'F2:M20'." },
- width: {
- type: 'number',
- description: 'Width in px; proportions are kept. Omit for automatic.',
- },
- height: { type: 'number', description: 'Height in px; as for width.' },
- },
- },
- ],
- description: 'An image file name, or {path, anchor | range, width, height}.',
- },
- },
- },
- },
- },
- },
- required: ['filename', 'sheets'],
- },
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'xlsx', 'output')
- const warnings: string[] = []
- const { buildXlsxWorkbook } = await import('./xlsxWorkbook')
- const built = await buildXlsxWorkbook(
- args,
- outputDir,
- { width: XLSX_MAX_IMAGE_WIDTH, height: XLSX_MAX_IMAGE_HEIGHT },
- warnings
- )
- if (!built.ok) return { success: false, error: built.error }
- // The workbook is already in memory, so a quota breach leaves no partial file.
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, built.buffer.byteLength, replacedBytes(target))
- fs.writeFileSync(target.filePath, built.buffer)
- return artifactResult(target, 'xlsx', {
- summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,
- warnings,
- })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- },
-}
-
-// ════════════════════════════════════════════════════════════════════
-// ─── DASHBOARD GENERATION (clerum__generate_dashboard) ──────────────
-// ════════════════════════════════════════════════════════════════════
-//
-// Self-contained HTML dashboard renderer. Produces a single .html file
-// with inlined CSS, plus the Chart.js bundle when the page has charts;
-// works offline and prints cleanly.
-//
-// Templates (4 fixed presets):
-// - executive-brief general-purpose daily/weekly executive report
-// - operations-pulse engineering / SRE / oncall view
-// - financial-review finance with hero chart + dense tables
-// - technical-report long-form engineering writeup with code blocks
-//
-// Themes: default | corporate | warm | alert (light + dark variants)
-
-// ─── CSS builder ────────────────────────────────────────────────────
-
-const DELTA_DIRECTION_SCHEMA = {
- type: 'string',
- enum: ['up', 'down', 'neutral'],
- description: 'Arrow direction.',
-}
-
-const DASH_KPI_SCHEMA = {
- type: 'object',
- required: ['label', 'value'],
- properties: {
- label: { type: 'string', description: 'What it measures.' },
- value: { type: ['string', 'number'], description: 'Number or formatted text, e.g. "$1.2M".' },
- delta: { type: ['string', 'number'], description: 'Change, e.g. "+12%" or -0.3.' },
- deltaDirection: DELTA_DIRECTION_SCHEMA,
- deltaSentiment: {
- type: 'string',
- enum: ['good', 'bad', 'neutral'],
- description:
- 'Delta color: good green, bad red. Default follows the arrow (up good); churn falling ' +
- 'is down + good.',
- },
- sparkline: {
- type: 'array',
- items: { type: ['number', 'string', 'null'] },
- description: 'Trend, oldest first, 2+ numbers.',
- },
- accent: {
- type: 'string',
- enum: ['success', 'warning', 'danger', 'neutral'],
- description: 'Top bar color.',
- },
- },
-}
-
-const XYR_PROPERTIES = {
- x: { type: ['number', 'string'], description: 'X.' },
- y: { type: 'number', description: 'Y.' },
- r: { type: 'number', description: 'Radius (px).' },
-}
-
-/**
- * One chart value: a number, text such as "1,200", null for a gap, an [x, y]
- * or [label, value] pair, or an object.
- */
-function dashPoint(objectProperties: Record<string, unknown>): Record<string, unknown> {
- return {
- anyOf: [
- { type: 'number' },
- { type: 'string' },
- { type: 'null' },
- { type: 'array', items: { type: ['number', 'string'] } },
- { type: 'object', properties: objectProperties },
- ],
- }
-}
-
-/** normalizeChartData also reads {label, value} records. */
-const DASH_POINT_SCHEMA = dashPoint({
- ...XYR_PROPERTIES,
- label: { type: 'string', description: 'Category.' },
- value: { type: ['number', 'string'], description: 'Value.' },
-})
-
-function dashColor(what: string): Record<string, unknown> {
- return {
- anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
- description: `${what}: hex, or one per point.`,
- }
-}
-
-const DASH_CHART_SCHEMA = {
- type: 'object',
- required: ['type', 'datasets'],
- properties: {
- type: {
- type: 'string',
- enum: [...DASHBOARD_CHART_TYPES],
- description:
- 'As in clerum__generate_chart. area: filled line; stacked*: stacked series; ' +
- 'mixedBarLine: 1st series bars, rest lines; gauge: 1st value on a 0-gaugeMax dial; ' +
- 'waterfall: steps, then the total; funnel: one series, descending; scatter, bubble: ' +
- '{x, y[, r]} points.',
- },
- title: { type: 'string', description: 'Heading.' },
- labels: {
- type: 'array',
- items: { type: ['string', 'number'] },
- description: 'X categories or slice names, one per value.',
- },
- datasets: {
- type: 'array',
- description: 'Series.',
- items: {
- type: 'object',
- required: ['data'],
- properties: {
- label: { type: 'string', description: 'Legend name.' },
- data: {
- type: 'array',
- items: DASH_POINT_SCHEMA,
- description: 'One value per label; null for a gap.',
- },
- backgroundColor: dashColor('Fill'),
- borderColor: dashColor('Line'),
- fill: { type: 'boolean', description: 'Fill under a line.' },
- },
- },
- },
- yAxisLabel: { type: 'string', description: 'Y-axis title.' },
- xAxisLabel: { type: 'string', description: 'X-axis title.' },
- gaugeMax: { type: ['number', 'string'], description: 'Gauge dial end (default 100).' },
- },
-}
-
-const CHART_POINTER = 'As data.charts[].'
-
-/**
- * The data.charts[] fields that carry a contract (type enum, required series,
- * value types), for the places that repeat that shape and point to it for the
- * rest: every model request carries the schema.
- */
-const CHART_COPY_PROPERTIES = {
- type: { type: 'string', enum: [...DASHBOARD_CHART_TYPES], description: CHART_POINTER },
- title: { type: 'string', description: 'Heading.' },
- labels: { type: 'array', items: { type: ['string', 'number'] }, description: CHART_POINTER },
- datasets: {
- type: 'array',
- description: CHART_POINTER,
- items: {
- type: 'object',
- required: ['data'],
- properties: {
- label: { type: 'string', description: 'Legend name.' },
- data: { type: 'array', items: dashPoint(XYR_PROPERTIES), description: CHART_POINTER },
- },
- },
- },
- gaugeMax: { type: ['number', 'string'], description: CHART_POINTER },
-}
-
-const DASH_TABLE_SCHEMA = {
- type: 'object',
- required: ['headers', 'rows'],
- properties: {
- title: { type: 'string', description: 'Heading.' },
- headers: {
- type: 'array',
- items: { type: ['string', 'number'] },
- description: 'Column headings.',
- },
- rows: { type: 'array', items: ROW_SCHEMA, description: 'Rows, cells in header order.' },
- columnTypes: {
- type: 'object',
- // Gemini rejects an object schema with no properties, so the map declares
- // one example key. additionalProperties, which Gemini's SDK drops, keeps
- // the other keys valid and marks the object as a map.
- properties: {
- '0': { type: 'string', description: 'Column 0: plain, severity, priority or status.' },
- },
- // A plain string, not an enum: an unknown type shows the column as plain
- // text with a note, the same on every path, as it did before types were listed.
- additionalProperties: { type: 'string' },
- description:
- 'Badge columns: header or 0-based index to plain, severity, priority or status, e.g. ' +
- '{"Status": "severity"}. Values such as critical, high, medium, low, info, p0-p2, ' +
- 'healthy, degraded, down then show as colored badges.',
- },
- },
-}
-
-const DASH_SERVICE_SCHEMA = {
- type: 'object',
- required: ['name', 'status'],
- properties: {
- name: { type: 'string', description: 'Name.' },
- status: {
- type: 'string',
- description: 'Card color: healthy, degraded, down or maintenance.',
- },
- metric: { type: ['string', 'number'], description: 'e.g. "142 ms".' },
- delta: { type: ['string', 'number'], description: 'e.g. "+0.2pp".' },
- deltaDirection: DELTA_DIRECTION_SCHEMA,
- },
-}
-
-const DASH_INCIDENT_SCHEMA = {
- type: 'object',
- required: ['title'],
- properties: {
- time: { type: 'string', description: 'Start, e.g. "10:42".' },
- title: { type: 'string', description: 'What happened.' },
- severity: { type: 'string', description: 'critical, high, medium, low or info (default).' },
- description: { type: 'string', description: 'Detail.' },
- resolvedAt: { type: 'string', description: 'When resolved; unset shows it open.' },
- },
-}
-
-const DASH_SECTION_CONTENT_SCHEMA = {
- anyOf: [{ type: ['string', 'number'] }, { type: 'array', items: { type: ['string', 'number'] } }],
- description: 'A paragraph, or an array of paragraphs or bullets. Inline markdown.',
-}
-
-const HERO_ONLY = 'hero: as in data.'
+const generateXlsx: InternalToolDefinition = { ...XLSX_TOOL, execute: runGenerateXlsx }
const generateDashboardTool: InternalToolDefinition = {
- name: 'clerum__generate_dashboard',
- description:
- 'Generate a standalone HTML dashboard: one .html file, CSS and Chart.js inlined, that ' +
- 'works offline, follows light/dark mode and prints cleanly. Templates: executive-brief ' +
- '(general), operations-pulse (+services, incidents), financial-review (+heroChart, ' +
- 'period), technical-report (sections first), custom (data.blocks[] only). The result ' +
- 'lists anything not shown, to fix and regenerate.',
- parameters: {
- type: 'object',
- properties: {
- filename: { type: 'string', description: 'Output name; .html added if missing.' },
- template: {
- type: 'string',
- enum: [...DASHBOARD_TEMPLATE_NAMES],
- description: 'Default executive-brief.',
- },
- theme: {
- type: 'string',
- enum: ['default', 'corporate', 'warm', 'alert'],
- description: 'default slate, corporate navy, warm amber, alert rose.',
- },
- defaultThemeMode: {
- type: 'string',
- enum: ['light', 'dark'],
- description: "Omit to follow the viewer's color scheme; set to force it.",
- },
- inlineChartJs: {
- type: 'boolean',
- description:
- 'Default true (adds ~210 KB when charts are used). false: charts become value tables, ' +
- 'no sparklines.',
- },
- branding: {
- type: 'object',
- description: 'Footer.',
- properties: {
- companyName: { type: 'string', description: 'Left side.' },
- footerText: { type: 'string', description: 'Beside the date.' },
- },
- },
- data: {
- type: 'object',
- description:
- 'Page content. A field that names a template shows only in it; custom reads only ' +
- 'title, blocks and meta.',
- required: ['title'],
- properties: {
- eyebrow: { type: 'string', description: 'Label above the title.' },
- title: { type: 'string', description: 'Heading.' },
- headline: { type: 'string', description: 'Summary under the title.' },
- status: {
- type: 'string',
- enum: [...HERO_STATUSES],
- description: 'Badge beside the title.',
- },
- statusLabel: { type: 'string', description: 'Badge text, e.g. "On track".' },
- period: {
- type: 'string',
- description: 'financial-review: e.g. "Q3 2026", above the title if no eyebrow.',
- },
- kpis: { type: 'array', description: 'Figure cards.', items: DASH_KPI_SCHEMA },
- charts: { type: 'array', description: 'Chart cards.', items: DASH_CHART_SCHEMA },
- heroChart: {
- type: 'object',
- required: ['type', 'datasets'],
- description: `financial-review: one wide chart above charts. ${CHART_POINTER}`,
- properties: CHART_COPY_PROPERTIES,
- },
- services: {
- type: 'array',
- description: 'operations-pulse: status cards.',
- items: DASH_SERVICE_SCHEMA,
- },
- incidents: {
- type: 'array',
- description: 'operations-pulse: timeline, in order.',
- items: DASH_INCIDENT_SCHEMA,
- },
- tables: { type: 'array', description: 'Tables.', items: DASH_TABLE_SCHEMA },
- sections: {
- type: 'array',
- description: 'Prose after the tables.',
- items: {
- type: 'object',
- required: ['type', 'content'],
- properties: {
- title: { type: 'string', description: 'Heading.' },
- type: {
- type: 'string',
- enum: [...SECTION_TYPES],
- description: 'Paragraphs, list, tinted box or monospaced block.',
- },
- content: DASH_SECTION_CONTENT_SCHEMA,
- tone: { type: 'string', enum: [...CALLOUT_TONES], description: 'callout color.' },
- language: { type: 'string', description: 'code language label.' },
- },
- },
- },
- blocks: {
- type: 'array',
- description: 'custom: blocks in page order; each field names the types that read it.',
- items: {
- type: 'object',
- required: ['type'],
- properties: {
- type: { type: 'string', enum: [...BLOCK_TYPES], description: 'Block type.' },
- title: { type: 'string', description: 'Heading (hero: page title).' },
- eyebrow: { type: 'string', description: HERO_ONLY },
- headline: { type: 'string', description: HERO_ONLY },
- status: { type: 'string', enum: [...HERO_STATUSES], description: HERO_ONLY },
- statusLabel: { type: 'string', description: HERO_ONLY },
- items: {
- type: 'array',
- items: {
- anyOf: [
- { type: ['string', 'number'] },
- {
- type: 'object',
- properties: {
- label: { type: ['string', 'number'], description: 'KPI label.' },
- value: { type: ['string', 'number'], description: 'KPI value.' },
- delta: { type: ['string', 'number'], description: 'KPI delta.' },
- deltaDirection: DELTA_DIRECTION_SCHEMA,
- deltaSentiment: {
- ...DASH_KPI_SCHEMA.properties.deltaSentiment,
- description: 'As data.kpis[].',
- },
- accent: {
- ...DASH_KPI_SCHEMA.properties.accent,
- description: 'KPI accent.',
- },
- ...CHART_COPY_PROPERTIES,
- time: { type: 'string', description: 'Incident time.' },
- severity: DASH_INCIDENT_SCHEMA.properties.severity,
- resolvedAt: { type: 'string', description: 'As data.incidents[].' },
- title: { type: 'string', description: 'Chart or incident title.' },
- },
- },
- ],
- },
- description:
- 'bullets: strings. kpis, charts-grid, incidents: objects as in ' +
- 'data.kpis[], charts[], incidents[].',
- },
- services: {
- type: 'array',
- description: 'service-health: as in data.services[].',
- items: {
- type: 'object',
- required: ['name', 'status'],
- properties: {
- name: { type: 'string', description: 'Name.' },
- status: DASH_SERVICE_SCHEMA.properties.status,
- deltaDirection: DELTA_DIRECTION_SCHEMA,
- },
- },
- },
- spec: {
- type: 'object',
- properties: {
- ...CHART_COPY_PROPERTIES,
- headers: DASH_TABLE_SCHEMA.properties.headers,
- rows: {
- type: 'array',
- items: ROW_SCHEMA,
- description: 'As data.tables[].',
- },
- },
- description: 'chart: as data.charts[]; table: as data.tables[].',
- },
- content: {
- ...DASH_SECTION_CONTENT_SCHEMA,
- description: 'narrative, code, callout: as data.sections[].content.',
- },
- language: { type: 'string', description: 'code: label.' },
- tone: { type: 'string', enum: [...CALLOUT_TONES], description: 'callout: color.' },
- size: { type: 'string', enum: ['sm', 'md', 'lg'], description: 'spacer: height.' },
- },
- },
- },
- meta: {
- type: 'object',
- description: 'Footer provenance.',
- properties: {
- date: { type: ['string', 'number'], description: 'Default: today.' },
- author: { type: 'string', description: 'Author.' },
- runId: { type: 'string', description: 'Run ID.' },
- },
- },
- },
- },
- },
- required: ['filename', 'data'],
- },
+ ...DASHBOARD_TOOL,
execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
return runGenerateDashboard(args, outputDir)
},
}
-// ════════════════════════════════════════════════════════════════════
-// ─── PPTX GENERATION (clerum__generate_pptx) ────────────────────────
-// ════════════════════════════════════════════════════════════════════
-//
-// The deck is built by pptxDeck.ts from arguments read by pptxInput.ts and,
-// for the preset decks, pptxTemplates.ts. The workflow path validates against
-// this schema before the tool runs.
-
-// Each shape is described in full once, under slides[]. The template fields in
-// `data` repeat its structure with short descriptions that point back there:
-// the schema goes out with every request and JSON Schema $ref is not portable.
-
-const PPTX_IMAGE_PATH_DESCRIPTION =
- "Image file name in the output folder, e.g. from clerum__generate_chart ('sales.png'). " +
- 'PNG, JPEG, GIF, WebP or SVG.'
-
-const PPTX_PATH_SHORT = 'File name from clerum__generate_chart.'
-
-/** An array of short texts, or one string read as one item per line. */
-function pptxTextList(description: string): Record<string, unknown> {
- return {
- anyOf: [{ type: 'array', items: { type: ['string', 'number'] } }, { type: 'string' }],
- description,
- }
-}
-
-function pptxImage(
- description: string,
- about: { path: string; caption: string; width: string; height: string }
-): Record<string, unknown> {
- return {
- anyOf: [
- { type: 'string' },
- {
- type: 'object',
- required: ['path'],
- properties: {
- path: { type: 'string', description: about.path },
- caption: { type: 'string', description: about.caption },
- width: { type: 'number', description: about.width },
- height: { type: 'number', description: about.height },
- },
- },
- ],
- description,
- }
-}
-
-function pptxKpis(
- description: string,
- about: { label: string; value: string; delta: string; deltaDirection: string }
-): Record<string, unknown> {
- return {
- type: 'array',
- description,
- items: {
- type: 'object',
- required: ['label', 'value'],
- properties: {
- label: { type: 'string', description: about.label },
- value: { type: ['string', 'number'], description: about.value },
- delta: { type: ['string', 'number'], description: about.delta },
- deltaDirection: {
- type: 'string',
- enum: ['up', 'down', 'neutral'],
- description: about.deltaDirection,
- },
- },
- },
- }
-}
-
-function pptxTable(description: string, headers: string, rows: string): Record<string, unknown> {
- return {
- type: 'object',
- required: ['headers', 'rows'],
- description,
- properties: {
- headers: { type: 'array', items: { type: ['string', 'number'] }, description: headers },
- rows: { type: 'array', items: ROW_SCHEMA, description: rows },
- },
- }
-}
-
-/** A chart value; text such as "1,200" and {label, value} records are read too. */
-const PPTX_CHART_POINT_SCHEMA = {
- anyOf: [
- { type: 'number' },
- { type: 'string' },
- { type: 'null' },
- {
- type: 'object',
- properties: {
- label: { type: 'string', description: 'Category.' },
- value: { type: ['number', 'string'], description: 'Value.' },
- },
- },
- ],
-}
-
-function pptxChartSeries(about: {
- labels: string
- datasets: string
- label: string
- data: string
-}): Record<string, Record<string, unknown>> {
- return {
- labels: { type: 'array', items: { type: ['string', 'number'] }, description: about.labels },
- datasets: {
- type: 'array',
- description: about.datasets,
- items: {
- type: 'object',
- required: ['data'],
- properties: {
- label: { type: 'string', description: about.label },
- data: { type: 'array', items: PPTX_CHART_POINT_SCHEMA, description: about.data },
- },
- },
- },
- }
-}
-
-const PPTX_SERIES_SHORT = {
- labels: 'Categories.',
- datasets: 'Series.',
- label: 'Name.',
- data: 'Values.',
-}
-
-/** What a chart's fields say: in full under slides[].chart, briefly in each template chart. */
-interface PptxChartAbout {
- path: string
- type: string
- title: string
- series: Parameters<typeof pptxChartSeries>[0]
- /** The labels and datasets nested under `data`; declared only where this is set. */
- nested?: string
- caption: string
-}
-
-/**
- * A chart, as slides[].chart and every template chart declare it. Both are
- * built here, so each declares the same fields with the same types and only
- * the descriptions differ: a provider or client that builds the call from the
- * declared fields sends no other, so a field named only in prose never arrives.
- */
-function pptxChart(description: string, about: PptxChartAbout): Record<string, unknown> {
- return {
- type: 'object',
- description,
- properties: {
- path: { type: 'string', description: about.path },
- type: { type: 'string', enum: [...NATIVE_CHART_TYPES], description: about.type },
- title: { type: 'string', description: about.title },
- ...pptxChartSeries(about.series),
- ...(about.nested === undefined
- ? {}
- : {
- data: {
- type: 'object',
- description: about.nested,
- properties: pptxChartSeries(PPTX_SERIES_SHORT),
- },
- }),
- caption: { type: 'string', description: about.caption },
- },
- }
-}
-
-const PPTX_CHART_SCHEMA = pptxChart(
- 'A native, editable chart { type, labels, datasets }, or { path } for a chart image.',
- {
- path:
- "Chart image file name from clerum__generate_chart (e.g. 'sales.png'), for " +
- 'types the native list lacks. Native data given too is drawn if the file cannot be used.',
- type: 'Native chart type. Only for native charts: with path, leave it out.',
- title: 'Heading, unless it repeats the slide title.',
- series: {
- labels: 'Category labels, one per value.',
- datasets: 'Series; a pie or doughnut draws only the first.',
- label: 'Legend name.',
- data: 'One value per label; null leaves a gap.',
- },
- nested: 'Or labels and datasets nested here, as clerum__generate_chart takes them.',
- caption: 'Note under the chart.',
- }
-)
-
-/**
- * A template chart: slides[].chart with short descriptions and without its
- * nested `data` form, which the flat fields make unnecessary. The deck builder
- * reads both the same way (readChart).
- */
-function pptxTemplateChart(description: string): Record<string, unknown> {
- return pptxChart(`${description} As slides[].chart.`, {
- path: PPTX_PATH_SHORT,
- type: 'Chart type.',
- title: 'Slide title.',
- series: PPTX_SERIES_SHORT,
- caption: 'Note.',
- })
-}
-
-function pptxColumn(description: string): Record<string, unknown> {
- return {
- type: 'object',
- required: ['type'],
- description,
- properties: {
- type: {
- type: 'string',
- enum: ['bullets', 'narrative', 'image'],
- description: 'Which field below it uses.',
- },
- bullets: pptxTextList("For type 'bullets'."),
- text: { type: 'string', description: "For type 'narrative'." },
- image: pptxImage("For type 'image'; as slides[].image.", {
- path: PPTX_PATH_SHORT,
- caption: 'Note.',
- width: 'Inches.',
- height: 'Inches.',
- }),
- },
- }
-}
-
-/** The fields of every template's `data`; each description names the templates that read it. */
-const PPTX_TEMPLATE_DATA_PROPERTIES: Record<string, Record<string, unknown>> = {
- title: {
- type: ['string', 'number'],
- description: 'executive-brief, quarterly-review, incident-review: cover title.',
- },
- subtitle: { type: ['string', 'number'], description: 'executive-brief: line under the title.' },
- status: {
- type: 'string',
- enum: [...STATUSES],
- description: 'executive-brief, quarterly-review: cover band color.',
- },
- kpis: pptxKpis('executive-brief, quarterly-review: cards, as slides[].kpis.', {
- label: 'Label.',
- value: 'Figure.',
- delta: 'Change.',
- deltaDirection: 'Delta color.',
- }),
- charts: {
- type: 'array',
- items: pptxTemplateChart('One chart.'),
- description: 'executive-brief: one slide per chart.',
- },
- takeaways: pptxTextList('executive-brief: Key Takeaways slide.'),
- nextSteps: pptxTextList('executive-brief: Next Steps slide.'),
- period: { type: ['string', 'number'], description: 'quarterly-review: period, e.g. "Q3 2026".' },
- highlights: pptxTextList('quarterly-review: highlights.'),
- revenueChart: pptxTemplateChart('quarterly-review: revenue trend.'),
- breakdownChart: pptxTemplateChart('quarterly-review: revenue breakdown.'),
- metricsTable: pptxTable('quarterly-review: metrics, as slides[].table.', 'Headings.', 'Rows.'),
- outlook: pptxTextList('quarterly-review: next-period priorities.'),
- severity: {
- type: 'string',
- enum: [...SEVERITIES],
- description: 'incident-review: colors the cover.',
- },
- date: { type: ['string', 'number'], description: 'incident-review: when it happened.' },
- summary: { type: ['string', 'number'], description: 'incident-review: what happened, briefly.' },
- timelineTable: pptxTable(
- 'incident-review: timeline, as slides[].table.',
- 'e.g. ["Time", "Event"].',
- 'Rows.'
- ),
- impact: pptxTextList('incident-review: who and what was affected.'),
- rootCause: { type: ['string', 'number'], description: 'incident-review: root cause.' },
- remediation: pptxTextList('incident-review: fixes made or planned.'),
- lessons: pptxTextList('incident-review: lessons learned.'),
- company: { type: ['string', 'number'], description: 'pitch-deck: company name.' },
- tagline: { type: ['string', 'number'], description: 'pitch-deck: one line under the name.' },
- problem: { type: ['string', 'number'], description: 'pitch-deck: the problem, briefly.' },
- solution: { type: ['string', 'number'], description: 'pitch-deck: the solution, briefly.' },
- marketSize: {
- type: 'object',
- required: ['value'],
- description: 'pitch-deck: addressable market.',
- properties: {
- value: { type: ['string', 'number'], description: 'e.g. "$12B".' },
- description: { type: 'string', description: 'Scope and source.' },
- },
- },
- tractionChart: pptxTemplateChart('pitch-deck: traction.'),
- team: {
- type: 'array',
- description: 'pitch-deck: one card per person.',
- items: {
- type: 'object',
- properties: {
- name: { type: 'string', description: 'Name.' },
- role: { type: 'string', description: 'e.g. "CEO".' },
- },
- },
- },
- ask: {
- type: 'object',
- required: ['amount'],
- description: 'pitch-deck: the raise.',
- properties: {
- amount: { type: ['string', 'number'], description: 'e.g. "$5M".' },
- useOfFunds: pptxTextList('Use of funds.'),
- },
- },
-}
-
-const generatePptxTool: InternalToolDefinition = {
- name: 'clerum__generate_pptx',
- description:
- 'Generate a styled PowerPoint (.pptx) deck: set `template` and fill `data`, or pass ' +
- '`slides[]`, each with a `layout`. A list of texts may also be one string, one item per ' +
- 'line. Text is plain: markdown is not read. Lists, tables and KPI cards that do not fit ' +
- 'continue on further slides and long text is set smaller; the result says when.',
- parameters: {
- type: 'object',
- properties: {
- filename: { type: 'string', description: "e.g. 'deck.pptx'; .pptx is added if missing." },
- title: { type: 'string', description: 'File metadata; not shown on a slide.' },
- subject: { type: 'string', description: 'File metadata.' },
- author: { type: 'string', description: 'File metadata.' },
- template: {
- type: 'string',
- enum: [...PPTX_TEMPLATES, 'custom'],
- description:
- 'Preset deck from `data`. Required: executive-brief title; quarterly-review title, ' +
- 'period; incident-review title, severity, summary; pitch-deck company, tagline, ' +
- "problem, solution. 'custom' (default): use `slides[]`.",
- },
- data: {
- type: 'object',
- description: 'Fields for `template`.',
- properties: PPTX_TEMPLATE_DATA_PROPERTIES,
- },
- palette: {
- type: 'string',
- enum: Object.keys(PPTX_PALETTES),
- description: "Default 'default'.",
- },
- aspectRatio: {
- type: 'string',
- enum: Object.keys(PPTX_ASPECT_RATIOS),
- description: "Default 'wide' (13.33×7.5 in).",
- },
- branding: {
- type: 'object',
- description: 'Footer on every slide but the cover; logo on the cover.',
- properties: {
- companyName: { type: 'string', description: 'Footer, left.' },
- logoPath: {
- type: 'string',
- description:
- 'Logo image file name in the output folder; formats as slides[].image.path.',
- },
- footerText: { type: 'string', description: 'Footer, after the company name.' },
- },
- },
- slides: {
- type: 'array',
- minItems: 1,
- description: 'The slides, in order.',
- items: {
- type: 'object',
- required: ['layout'],
- properties: {
- layout: {
- type: 'string',
- enum: [...SLIDE_LAYOUTS],
- description:
- 'Needs: cover, section a title; title-bullets bullets; title-chart chart; ' +
- 'title-table table; kpis kpis; two-column columns; image image; quote quote.',
- },
- title: { type: 'string', description: 'Heading.' },
- eyebrow: { type: 'string', description: 'Section: label above the title.' },
- subtitle: { type: 'string', description: 'Cover, section: line under the title.' },
- status: {
- type: 'string',
- enum: [...STATUSES],
- description: 'Cover: color of the top band.',
- },
- bullets: pptxTextList('Bullet points.'),
- table: pptxTable('A table.', 'Column headings.', 'Rows of cells, in header order.'),
- kpis: pptxKpis('Figures as cards, up to 8 per slide.', {
- label: 'What it measures.',
- value: 'A number, or formatted text, e.g. "$1.2M".',
- delta: 'Change, e.g. "+12%".',
- deltaDirection: 'Delta color: up good, down bad, neutral grey.',
- }),
- chart: PPTX_CHART_SCHEMA,
- image: pptxImage('A file name, or { path, caption, width, height }.', {
- path: PPTX_IMAGE_PATH_DESCRIPTION,
- caption: 'Note under it.',
- width:
- 'Inches. With width or height the other keeps the proportions; with both the ' +
- 'image fits inside that box; with neither it fills the space, up to twice its size.',
- height: 'Inches; see width.',
- }),
- quote: {
- type: 'object',
- description: 'Pull quote.',
- required: ['text'],
- properties: {
- text: { type: 'string', description: 'The words.' },
- attribution: { type: 'string', description: 'Who said it.' },
- },
- },
- columns: {
- type: 'object',
- description: 'Two columns.',
- required: ['left', 'right'],
- properties: {
- left: pptxColumn('Left column.'),
- right: pptxColumn('Right column.'),
- },
- },
- notes: { type: 'string', description: 'Speaker notes.' },
- },
- },
- },
- },
- required: ['filename'],
- },
- async execute(args: Record<string, unknown>, outputDir: string): Promise<InternalToolResult> {
- try {
- const filename = outputFilename(args.filename, 'pptx', 'deck')
- const warnings: string[] = []
- const { buildPptxDeck } = await import('./pptxDeck')
- const { buffer, slides } = await buildPptxDeck(args, outputDir, warnings)
- // Buffer first, quota check, then write — atomic, no partial files.
- ensureDir(outputDir)
- const target = claimOutputFile(outputDir, filename)
- enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))
- fs.writeFileSync(target.filePath, buffer)
- return artifactResult(target, 'pptx', {
- summary: `File generated: ${target.filename} (pptx), ${slides} slide${slides === 1 ? '' : 's'}.`,
- warnings,
- })
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- },
-}
-
-// ─── Registry ────────────────────────────────────────────────────────
-
-// ─── clerum__list_workflows ───────────────────────────────────────────
-
-const listWorkflowTool = new WorkflowListTool()
-
-const listWorkflows: InternalToolDefinition = {
- name: 'clerum__list_workflows',
- description: listWorkflowTool.description(),
- parameters: listWorkflowTool.parametersSchema(),
- execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
- const result = await listWorkflowTool.execute(args)
- if (result.is_error) {
- return { success: false, error: result.content }
- }
- return { success: true, content: result.content }
- },
-}
-
-const readWorkflowTool = new WorkflowStatusTool()
-
-const readWorkflow: InternalToolDefinition = {
- name: 'clerum__read_workflow',
- description: readWorkflowTool.description(),
- parameters: readWorkflowTool.parametersSchema(),
- execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
- const result = await readWorkflowTool.execute(args)
- if (result.is_error) {
- return { success: false, error: result.content }
- }
- return { success: true, content: result.content }
- },
-}
-
-const triggerWorkflowTool = new WorkflowTriggerTool()
-
-const triggerWorkflow: InternalToolDefinition = {
- name: 'clerum__trigger_workflow',
- description: triggerWorkflowTool.description(),
- parameters: triggerWorkflowTool.parametersSchema(),
- execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
- const result = await triggerWorkflowTool.execute(args)
- if (result.is_error) {
- return { success: false, error: result.content }
- }
- return { success: true, content: result.content }
- },
-}
-
-/**
- * A generator that runs on cleaned arguments (cleanToolArgs, unset nulls
- * dropped, named images decoded) and reports the arguments it did not read.
- */
-function prepared(tool: InternalToolDefinition): InternalToolDefinition {
- return {
- ...tool,
- execute: async (args, outputDir) => {
- let clean: Record<string, unknown>
- let release: () => void
- try {
- clean = withoutUnsetNulls(tool.parameters, cleanToolArgs(args ?? {})) as Record<
- string,
- unknown
- >
- const { predecodeImages } = await import('./embeddedImages')
- release = await predecodeImages(clean, outputDir)
- } catch (err) {
- return { success: false, error: err instanceof Error ? err.message : String(err) }
- }
- const unknown = watchUnknownArguments(tool.parameters, clean)
- let result: InternalToolResult
- try {
- result = await tool.execute(clean, outputDir)
- } finally {
- release()
- }
- const ignored = unknown.ignored()
- if (!result.success || ignored.length === 0) return result
- const listed = ignored.slice(0, 10).map(name => `'${name}'`)
- if (ignored.length > 10) listed.push(`and ${ignored.length - 10} more`)
- const note = `Ignored arguments this tool does not read: ${listed.join(', ')}.`
- const content = result.content ?? ''
- return {
- ...result,
- content: /\nNotes: /.test(content) ? `${content} ${note}` : `${content}\nNotes: ${note}`,
- }
- },
- }
-}
-
-/**
- * A tool that reads a null sent for an optional argument as unset, as the
- * generators do, so a call means the same from chat and from a workflow step.
- */
-function nullsUnset(tool: InternalToolDefinition): InternalToolDefinition {
- return {
- ...tool,
- execute: (args, outputDir, options) =>
- tool.execute(
- withoutUnsetNulls(tool.parameters, args ?? {}) as Record<string, unknown>,
- outputDir,
- options
- ),
- }
-}
+const generatePptxTool: InternalToolDefinition = { ...PPTX_TOOL, execute: runGeneratePptx }
/** All internal tools available to workflow steps. */
export const INTERNAL_TOOLS: InternalToolDefinition[] = [
@@ -1879,29 +120,3 @@ export function resolveInternalTools(
if (loadContextFilesMounts(env).length > 0) return INTERNAL_TOOLS
return INTERNAL_TOOLS.filter(t => !CONTEXT_FILES_TOOL_NAMES.has(t.name))
}
-
-/**
- * Resolve the directory for generated artifacts. Re-evaluated on every call.
- *
- * Resolution order:
- * 1. `CLERUM_OUTPUT_DIR` — explicit override (dev / tests / ad-hoc).
- * 2. Workflow mode (`CLERUM_WORKFLOW_ENABLED=true`) → `/output` (per-run PVC).
- * 3. Chat mode → `${workspacePath}/outputs`, where workspacePath comes from the
- * Host CRD (via the injected accessor), else mirrors `config.memory.workspacePath`
- * (`CLERUM_MEMORY_WORKSPACE_PATH`, dev-aware default). Reusing the durable
- * workspace PVC (instead of the old `/tmp/clerum-output` emptyDir) is what
- * keeps Download links working after a Host pod restart (D.2b).
- */
-export function getOutputDir(): string {
- if (process.env.CLERUM_OUTPUT_DIR) return process.env.CLERUM_OUTPUT_DIR
- if (process.env.CLERUM_WORKFLOW_ENABLED === 'true') return '/output'
- // Mirror config.memory.workspacePath — the var that actually backs the
- // workspace PVC (where state.db / spillover also live), NOT CLERUM_WORKSPACE_PATH
- // (the native-tool sandbox root, config.ts:515). CRD accessor wins in prod; the
- // env/dev default only applies when running without a Host CRD.
- const workspacePath =
- outputDirHostAccessor?.()?.spec?.memory?.workspacePath ||
- process.env.CLERUM_MEMORY_WORKSPACE_PATH ||
- (config.devMode ? './workspace' : '/workspace')
- return path.join(workspacePath, 'outputs')
-}
diff --git a/mcp-host/src/workflow/markdownGenerator.ts b/mcp-host/src/workflow/markdownGenerator.ts
new file mode 100644
index 000000000..c91c774a8
--- /dev/null
+++ b/mcp-host/src/workflow/markdownGenerator.ts
@@ -0,0 +1,50 @@
+/** clerum__generate_markdown: the text, written as given. */
+import * as fs from 'fs'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import type { InternalToolResult } from './types'
+
+/** The file text, or an error saying what content must be; never a stringified array or object. */
+function markdownContent(value: unknown): string | { error: string } {
+ if (value === undefined || value === null) {
+ return { error: 'content is required: pass the markdown text to write.' }
+ }
+ const lines = Array.isArray(value) ? value : [value]
+ if (!lines.every(line => typeof line === 'string')) {
+ const received = Array.isArray(value)
+ ? 'an array with entries that are not text'
+ : `a ${typeof value}`
+ return {
+ error: `content must be the markdown text as a string, or an array of lines; received ${received}.`,
+ }
+ }
+ const text = lines.join('\n')
+ if (!text.trim()) return { error: 'content is empty: pass the markdown text to write.' }
+ return text
+}
+
+export async function runGenerateMarkdown(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'md', 'output')
+ const content = markdownContent(args.content)
+ if (typeof content !== 'string') return { success: false, error: content.error }
+
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, Buffer.byteLength(content, 'utf-8'), replacedBytes(target))
+ fs.writeFileSync(target.filePath, content, 'utf-8')
+
+ return artifactResult(target, 'md')
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}
diff --git a/mcp-host/src/workflow/outputDirectory.ts b/mcp-host/src/workflow/outputDirectory.ts
new file mode 100644
index 000000000..6b7aa7e0b
--- /dev/null
+++ b/mcp-host/src/workflow/outputDirectory.ts
@@ -0,0 +1,71 @@
+/** Where generated artifacts are written: the run's /output in a workflow, the Host workspace in chat. */
+import * as path from 'path'
+import { config } from '../config'
+
+// Accessor to the current Host CRD, injected by main (avoids a circular import).
+// Re-read on every getOutputDir() call because `currentHost` is hydrated async
+// after boot — caching the path at module load would freeze it to the fallback.
+type WorkspaceHostAccessor = () =>
+ | { spec?: { memory?: { workspacePath?: string } } }
+ | null
+ | undefined
+let outputDirHostAccessor: WorkspaceHostAccessor | null = null
+
+/** Wire the Host CRD accessor so chat-mode artifacts resolve to the workspace PVC. */
+export function setOutputDirHostAccessor(accessor: WorkspaceHostAccessor): void {
+ outputDirHostAccessor = accessor
+}
+
+// ─── Security helpers ────────────────────────────────────────────────
+//
+// Boundary primitives applied at the seam between LLM-supplied data
+// and the generated artifact. They guard against XSS in HTML output,
+// path traversal when reading user-named files, and formula injection
+// in spreadsheet cells.
+
+/**
+ * Resolve `p` against `outputDir` and ensure the result stays inside
+ * `outputDir`. Throws on traversal attempts (`../etc/passwd`, absolute
+ * paths outside the dir, symlink-style escapes). Returns the absolute
+ * resolved path.
+ *
+ * The caller decides whether the file must already exist; this helper
+ * only enforces the path-containment invariant.
+ */
+export function validateOutputPath(p: string, outputDir: string): string {
+ if (typeof p !== 'string' || p.length === 0) {
+ throw new Error('path must be a non-empty string')
+ }
+ const root = path.resolve(outputDir)
+ const resolved = path.resolve(root, p)
+ if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+ throw new Error(`path traversal blocked: ${p}`)
+ }
+ return resolved
+}
+
+/**
+ * Resolve the directory for generated artifacts. Re-evaluated on every call.
+ *
+ * Resolution order:
+ * 1. `CLERUM_OUTPUT_DIR` — explicit override (dev / tests / ad-hoc).
+ * 2. Workflow mode (`CLERUM_WORKFLOW_ENABLED=true`) → `/output` (per-run PVC).
+ * 3. Chat mode → `${workspacePath}/outputs`, where workspacePath comes from the
+ * Host CRD (via the injected accessor), else mirrors `config.memory.workspacePath`
+ * (`CLERUM_MEMORY_WORKSPACE_PATH`, dev-aware default). Reusing the durable
+ * workspace PVC (instead of the old `/tmp/clerum-output` emptyDir) is what
+ * keeps Download links working after a Host pod restart (D.2b).
+ */
+export function getOutputDir(): string {
+ if (process.env.CLERUM_OUTPUT_DIR) return process.env.CLERUM_OUTPUT_DIR
+ if (process.env.CLERUM_WORKFLOW_ENABLED === 'true') return '/output'
+ // Mirror config.memory.workspacePath — the var that actually backs the
+ // workspace PVC (where state.db / spillover also live), NOT CLERUM_WORKSPACE_PATH
+ // (the native-tool sandbox root, config.ts:515). CRD accessor wins in prod; the
+ // env/dev default only applies when running without a Host CRD.
+ const workspacePath =
+ outputDirHostAccessor?.()?.spec?.memory?.workspacePath ||
+ process.env.CLERUM_MEMORY_WORKSPACE_PATH ||
+ (config.devMode ? './workspace' : '/workspace')
+ return path.join(workspacePath, 'outputs')
+}
diff --git a/mcp-host/src/workflow/pptxGenerator.ts b/mcp-host/src/workflow/pptxGenerator.ts
new file mode 100644
index 000000000..6b9581c9e
--- /dev/null
+++ b/mcp-host/src/workflow/pptxGenerator.ts
@@ -0,0 +1,34 @@
+/** clerum__generate_pptx: builds the deck (pptxDeck, loaded on first use) and writes it. */
+import * as fs from 'fs'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import type { InternalToolResult } from './types'
+
+export async function runGeneratePptx(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'pptx', 'deck')
+ const warnings: string[] = []
+ const { buildPptxDeck } = await import('./pptxDeck')
+ const { buffer, slides } = await buildPptxDeck(args, outputDir, warnings)
+ // Buffer first, quota check, then write — atomic, no partial files.
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, buffer.byteLength, replacedBytes(target))
+ fs.writeFileSync(target.filePath, buffer)
+ return artifactResult(target, 'pptx', {
+ summary: `File generated: ${target.filename} (pptx), ${slides} slide${slides === 1 ? '' : 's'}.`,
+ warnings,
+ })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}
diff --git a/mcp-host/src/workflow/toolExecution.ts b/mcp-host/src/workflow/toolExecution.ts
new file mode 100644
index 000000000..3c0ee9ae3
--- /dev/null
+++ b/mcp-host/src/workflow/toolExecution.ts
@@ -0,0 +1,79 @@
+/** How every internal tool runs: lazy generator modules and the argument preparation around them. */
+import { watchUnknownArguments, withoutUnsetNulls } from './schemaArguments'
+import { cleanToolArgs } from './toolText'
+import type { InternalToolDefinition, InternalToolResult } from './types'
+
+/**
+ * Runs a generator from its own module, loaded on first use so that starting
+ * the host loads no document library. A module that fails to load fails the
+ * call the way a generator error does.
+ */
+export async function fromModule<M>(
+ load: () => Promise<M>,
+ run: (loaded: M) => Promise<InternalToolResult>
+): Promise<InternalToolResult> {
+ let loaded: M
+ try {
+ loaded = await load()
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+ return run(loaded)
+}
+
+/**
+ * A generator that runs on cleaned arguments (cleanToolArgs, unset nulls
+ * dropped, named images decoded) and reports the arguments it did not read.
+ */
+export function prepared(tool: InternalToolDefinition): InternalToolDefinition {
+ return {
+ ...tool,
+ execute: async (args, outputDir) => {
+ let clean: Record<string, unknown>
+ let release: () => void
+ try {
+ clean = withoutUnsetNulls(tool.parameters, cleanToolArgs(args ?? {})) as Record<
+ string,
+ unknown
+ >
+ const { predecodeImages } = await import('./embeddedImages')
+ release = await predecodeImages(clean, outputDir)
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+ const unknown = watchUnknownArguments(tool.parameters, clean)
+ let result: InternalToolResult
+ try {
+ result = await tool.execute(clean, outputDir)
+ } finally {
+ release()
+ }
+ const ignored = unknown.ignored()
+ if (!result.success || ignored.length === 0) return result
+ const listed = ignored.slice(0, 10).map(name => `'${name}'`)
+ if (ignored.length > 10) listed.push(`and ${ignored.length - 10} more`)
+ const note = `Ignored arguments this tool does not read: ${listed.join(', ')}.`
+ const content = result.content ?? ''
+ return {
+ ...result,
+ content: /\nNotes: /.test(content) ? `${content} ${note}` : `${content}\nNotes: ${note}`,
+ }
+ },
+ }
+}
+
+/**
+ * A tool that reads a null sent for an optional argument as unset, as the
+ * generators do, so a call means the same from chat and from a workflow step.
+ */
+export function nullsUnset(tool: InternalToolDefinition): InternalToolDefinition {
+ return {
+ ...tool,
+ execute: (args, outputDir, options) =>
+ tool.execute(
+ withoutUnsetNulls(tool.parameters, args ?? {}) as Record<string, unknown>,
+ outputDir,
+ options
+ ),
+ }
+}
diff --git a/mcp-host/src/workflow/toolSchemas/chart.ts b/mcp-host/src/workflow/toolSchemas/chart.ts
new file mode 100644
index 000000000..f6c5f3345
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/chart.ts
@@ -0,0 +1,175 @@
+import {
+ DEFAULT_CHART_HEIGHT,
+ DEFAULT_CHART_WIDTH,
+ MAX_CHART_DIMENSION,
+ MIN_CHART_DIMENSION,
+} from '../chartThemes'
+import { type ToolSchema } from './shared'
+
+/** A single color, or one per data point. */
+function colorSchema(what: string): Record<string, unknown> {
+ return {
+ anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+ description: `${what}: a hex color, or an array of one per point.`,
+ }
+}
+
+/**
+ * One chart data point. Numbers are the norm; the rest are shapes models send
+ * that normalizeChartData repairs or needs — text such as "1,200", null for a
+ * gap, {x, y[, r]} or [x, y[, r]] for scatter and bubble, {x, y} with a
+ * category x, and {label, value} records or [label, value] pairs.
+ */
+const CHART_POINT_SCHEMA = {
+ anyOf: [
+ { type: 'number' },
+ { type: 'string' },
+ { type: 'null' },
+ { type: 'array', items: { type: ['number', 'string'] } },
+ {
+ type: 'object',
+ properties: {
+ x: { type: ['number', 'string'], description: 'X value.' },
+ y: { type: 'number', description: 'Y value.' },
+ r: { type: 'number', description: 'Bubble radius (px).' },
+ label: { type: 'string', description: 'Category.' },
+ value: { type: ['number', 'string'], description: 'Value.' },
+ },
+ },
+ ],
+ description: 'A number, null for a gap, or {x, y} / {x, y, r} or [x, y] for scatter / bubble.',
+}
+
+export const CHART_TOOL: ToolSchema = {
+ name: 'clerum__generate_chart',
+ description:
+ 'Render a chart as a PNG image, with values printed on it by default. Returns the file ' +
+ 'name it was saved under, such as "sales.png"; pass it as images[].path to the PDF or ' +
+ 'DOCX generator, as sheets[].images[].path to the XLSX generator, or as a PPTX slide ' +
+ 'image.path or chart.path.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename (e.g. 'revenue.png'); .png added if missing.",
+ },
+ type: {
+ type: 'string',
+ enum: [
+ 'line',
+ 'bar',
+ 'horizontalBar',
+ 'pie',
+ 'doughnut',
+ 'area',
+ 'scatter',
+ 'radar',
+ 'polarArea',
+ 'bubble',
+ 'stackedBar',
+ 'stackedArea',
+ 'mixedBarLine',
+ 'gauge',
+ 'waterfall',
+ 'funnel',
+ ],
+ description:
+ 'area: filled line. mixedBarLine: first dataset as bars, the rest as lines. ' +
+ 'gauge: one value 0..gaugeMax as a half dial. waterfall: one series of deltas, ' +
+ 'drawn as steps plus a total bar. funnel: one series, sorted descending.',
+ },
+ title: {
+ type: 'string',
+ description: 'Title above the plot. Always set one.',
+ },
+ width: {
+ type: 'number',
+ description:
+ `Width in px (default ${DEFAULT_CHART_WIDTH}, ${MIN_CHART_DIMENSION}-${MAX_CHART_DIMENSION}; ` +
+ 'width × height up to about 13 million). The PNG is up to 2× this.',
+ },
+ height: {
+ type: 'number',
+ description: `Height in px (default ${DEFAULT_CHART_HEIGHT}, ${MIN_CHART_DIMENSION}-${MAX_CHART_DIMENSION}).`,
+ },
+ theme: {
+ type: 'string',
+ enum: ['light', 'dark', 'corporate', 'warm', 'warm-dark'],
+ description: "Color theme. Default 'light'.",
+ },
+ data: {
+ type: 'object',
+ description: 'Series to plot. Colors come from the theme unless a dataset sets them.',
+ properties: {
+ labels: {
+ type: 'array',
+ items: { type: ['string', 'number'] },
+ description:
+ 'One per value: X-axis categories, or slice names (required) for ' +
+ 'pie/doughnut/polarArea. Unused by scatter/bubble.',
+ },
+ datasets: {
+ type: 'array',
+ description: 'One or more series.',
+ items: {
+ type: 'object',
+ required: ['data'],
+ properties: {
+ label: {
+ type: 'string',
+ description: 'Series name, shown in the legend.',
+ },
+ data: {
+ type: 'array',
+ items: CHART_POINT_SCHEMA,
+ description: 'One point per label, in labels order.',
+ },
+ backgroundColor: colorSchema('Fill color'),
+ borderColor: colorSchema('Line/border color'),
+ fill: { type: 'boolean', description: 'Fill under a line series.' },
+ },
+ },
+ },
+ },
+ required: ['datasets'],
+ },
+ yAxisLabel: { type: 'string', description: 'Y-axis title, e.g. "USD".' },
+ xAxisLabel: { type: 'string', description: 'X-axis title.' },
+ showValues: {
+ type: 'boolean',
+ description:
+ 'Print each value on the chart. Default on, except scatter, bubble, radar, gauge and stacked types.',
+ },
+ valueFormat: {
+ type: 'string',
+ enum: ['auto', 'plain', 'compact', 'currency', 'percent'],
+ description:
+ 'Number style on the chart and value axis. auto: abbreviate above 10,000; compact: ' +
+ 'always (1.2M); currency: prefix currencySymbol; percent: append %.',
+ },
+ currencySymbol: {
+ type: 'string',
+ description: "For valueFormat 'currency'. Default '$'.",
+ },
+ decimals: {
+ type: 'number',
+ description: 'Decimal places on printed values. Default: per value.',
+ },
+ showLegend: {
+ type: 'boolean',
+ description:
+ 'Legend on or off. Default: on for several series, or one the titles do not name.',
+ },
+ dualAxis: {
+ type: 'boolean',
+ description: 'mixedBarLine only: put the line series on a second, right-hand axis.',
+ },
+ gaugeMax: {
+ type: 'number',
+ description: 'gauge only: dial maximum (default 100).',
+ },
+ },
+ required: ['filename', 'type', 'data'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/dashboard.ts b/mcp-host/src/workflow/toolSchemas/dashboard.ts
new file mode 100644
index 000000000..6a8844733
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/dashboard.ts
@@ -0,0 +1,426 @@
+import {
+ BLOCK_TYPES,
+ CALLOUT_TONES,
+ DASHBOARD_CHART_TYPES,
+ DASHBOARD_TEMPLATE_NAMES,
+ HERO_STATUSES,
+ SECTION_TYPES,
+} from '../dashboardVocabulary'
+import { ROW_SCHEMA, type ToolSchema } from './shared'
+
+// ════════════════════════════════════════════════════════════════════
+// ─── DASHBOARD GENERATION (clerum__generate_dashboard) ──────────────
+// ════════════════════════════════════════════════════════════════════
+//
+// Self-contained HTML dashboard renderer. Produces a single .html file
+// with inlined CSS, plus the Chart.js bundle when the page has charts;
+// works offline and prints cleanly.
+//
+// Templates (4 fixed presets):
+// - executive-brief general-purpose daily/weekly executive report
+// - operations-pulse engineering / SRE / oncall view
+// - financial-review finance with hero chart + dense tables
+// - technical-report long-form engineering writeup with code blocks
+//
+// Themes: default | corporate | warm | alert (light + dark variants)
+
+const DELTA_DIRECTION_SCHEMA = {
+ type: 'string',
+ enum: ['up', 'down', 'neutral'],
+ description: 'Arrow direction.',
+}
+
+const DASH_KPI_SCHEMA = {
+ type: 'object',
+ required: ['label', 'value'],
+ properties: {
+ label: { type: 'string', description: 'What it measures.' },
+ value: { type: ['string', 'number'], description: 'Number or formatted text, e.g. "$1.2M".' },
+ delta: { type: ['string', 'number'], description: 'Change, e.g. "+12%" or -0.3.' },
+ deltaDirection: DELTA_DIRECTION_SCHEMA,
+ deltaSentiment: {
+ type: 'string',
+ enum: ['good', 'bad', 'neutral'],
+ description:
+ 'Delta color: good green, bad red. Default follows the arrow (up good); churn falling ' +
+ 'is down + good.',
+ },
+ sparkline: {
+ type: 'array',
+ items: { type: ['number', 'string', 'null'] },
+ description: 'Trend, oldest first, 2+ numbers.',
+ },
+ accent: {
+ type: 'string',
+ enum: ['success', 'warning', 'danger', 'neutral'],
+ description: 'Top bar color.',
+ },
+ },
+}
+
+const XYR_PROPERTIES = {
+ x: { type: ['number', 'string'], description: 'X.' },
+ y: { type: 'number', description: 'Y.' },
+ r: { type: 'number', description: 'Radius (px).' },
+}
+
+/**
+ * One chart value: a number, text such as "1,200", null for a gap, an [x, y]
+ * or [label, value] pair, or an object.
+ */
+function dashPoint(objectProperties: Record<string, unknown>): Record<string, unknown> {
+ return {
+ anyOf: [
+ { type: 'number' },
+ { type: 'string' },
+ { type: 'null' },
+ { type: 'array', items: { type: ['number', 'string'] } },
+ { type: 'object', properties: objectProperties },
+ ],
+ }
+}
+
+/** normalizeChartData also reads {label, value} records. */
+const DASH_POINT_SCHEMA = dashPoint({
+ ...XYR_PROPERTIES,
+ label: { type: 'string', description: 'Category.' },
+ value: { type: ['number', 'string'], description: 'Value.' },
+})
+
+function dashColor(what: string): Record<string, unknown> {
+ return {
+ anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+ description: `${what}: hex, or one per point.`,
+ }
+}
+
+const DASH_CHART_SCHEMA = {
+ type: 'object',
+ required: ['type', 'datasets'],
+ properties: {
+ type: {
+ type: 'string',
+ enum: [...DASHBOARD_CHART_TYPES],
+ description:
+ 'As in clerum__generate_chart. area: filled line; stacked*: stacked series; ' +
+ 'mixedBarLine: 1st series bars, rest lines; gauge: 1st value on a 0-gaugeMax dial; ' +
+ 'waterfall: steps, then the total; funnel: one series, descending; scatter, bubble: ' +
+ '{x, y[, r]} points.',
+ },
+ title: { type: 'string', description: 'Heading.' },
+ labels: {
+ type: 'array',
+ items: { type: ['string', 'number'] },
+ description: 'X categories or slice names, one per value.',
+ },
+ datasets: {
+ type: 'array',
+ description: 'Series.',
+ items: {
+ type: 'object',
+ required: ['data'],
+ properties: {
+ label: { type: 'string', description: 'Legend name.' },
+ data: {
+ type: 'array',
+ items: DASH_POINT_SCHEMA,
+ description: 'One value per label; null for a gap.',
+ },
+ backgroundColor: dashColor('Fill'),
+ borderColor: dashColor('Line'),
+ fill: { type: 'boolean', description: 'Fill under a line.' },
+ },
+ },
+ },
+ yAxisLabel: { type: 'string', description: 'Y-axis title.' },
+ xAxisLabel: { type: 'string', description: 'X-axis title.' },
+ gaugeMax: { type: ['number', 'string'], description: 'Gauge dial end (default 100).' },
+ },
+}
+
+const CHART_POINTER = 'As data.charts[].'
+
+/**
+ * The data.charts[] fields that carry a contract (type enum, required series,
+ * value types), for the places that repeat that shape and point to it for the
+ * rest: every model request carries the schema.
+ */
+const CHART_COPY_PROPERTIES = {
+ type: { type: 'string', enum: [...DASHBOARD_CHART_TYPES], description: CHART_POINTER },
+ title: { type: 'string', description: 'Heading.' },
+ labels: { type: 'array', items: { type: ['string', 'number'] }, description: CHART_POINTER },
+ datasets: {
+ type: 'array',
+ description: CHART_POINTER,
+ items: {
+ type: 'object',
+ required: ['data'],
+ properties: {
+ label: { type: 'string', description: 'Legend name.' },
+ data: { type: 'array', items: dashPoint(XYR_PROPERTIES), description: CHART_POINTER },
+ },
+ },
+ },
+ gaugeMax: { type: ['number', 'string'], description: CHART_POINTER },
+}
+
+const DASH_TABLE_SCHEMA = {
+ type: 'object',
+ required: ['headers', 'rows'],
+ properties: {
+ title: { type: 'string', description: 'Heading.' },
+ headers: {
+ type: 'array',
+ items: { type: ['string', 'number'] },
+ description: 'Column headings.',
+ },
+ rows: { type: 'array', items: ROW_SCHEMA, description: 'Rows, cells in header order.' },
+ columnTypes: {
+ type: 'object',
+ // Gemini rejects an object schema with no properties, so the map declares
+ // one example key. additionalProperties, which Gemini's SDK drops, keeps
+ // the other keys valid and marks the object as a map.
+ properties: {
+ '0': { type: 'string', description: 'Column 0: plain, severity, priority or status.' },
+ },
+ // A plain string, not an enum: an unknown type shows the column as plain
+ // text with a note, the same on every path, as it did before types were listed.
+ additionalProperties: { type: 'string' },
+ description:
+ 'Badge columns: header or 0-based index to plain, severity, priority or status, e.g. ' +
+ '{"Status": "severity"}. Values such as critical, high, medium, low, info, p0-p2, ' +
+ 'healthy, degraded, down then show as colored badges.',
+ },
+ },
+}
+
+const DASH_SERVICE_SCHEMA = {
+ type: 'object',
+ required: ['name', 'status'],
+ properties: {
+ name: { type: 'string', description: 'Name.' },
+ status: {
+ type: 'string',
+ description: 'Card color: healthy, degraded, down or maintenance.',
+ },
+ metric: { type: ['string', 'number'], description: 'e.g. "142 ms".' },
+ delta: { type: ['string', 'number'], description: 'e.g. "+0.2pp".' },
+ deltaDirection: DELTA_DIRECTION_SCHEMA,
+ },
+}
+
+const DASH_INCIDENT_SCHEMA = {
+ type: 'object',
+ required: ['title'],
+ properties: {
+ time: { type: 'string', description: 'Start, e.g. "10:42".' },
+ title: { type: 'string', description: 'What happened.' },
+ severity: { type: 'string', description: 'critical, high, medium, low or info (default).' },
+ description: { type: 'string', description: 'Detail.' },
+ resolvedAt: { type: 'string', description: 'When resolved; unset shows it open.' },
+ },
+}
+
+const DASH_SECTION_CONTENT_SCHEMA = {
+ anyOf: [{ type: ['string', 'number'] }, { type: 'array', items: { type: ['string', 'number'] } }],
+ description: 'A paragraph, or an array of paragraphs or bullets. Inline markdown.',
+}
+
+const HERO_ONLY = 'hero: as in data.'
+
+export const DASHBOARD_TOOL: ToolSchema = {
+ name: 'clerum__generate_dashboard',
+ description:
+ 'Generate a standalone HTML dashboard: one .html file, CSS and Chart.js inlined, that ' +
+ 'works offline, follows light/dark mode and prints cleanly. Templates: executive-brief ' +
+ '(general), operations-pulse (+services, incidents), financial-review (+heroChart, ' +
+ 'period), technical-report (sections first), custom (data.blocks[] only). The result ' +
+ 'lists anything not shown, to fix and regenerate.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: { type: 'string', description: 'Output name; .html added if missing.' },
+ template: {
+ type: 'string',
+ enum: [...DASHBOARD_TEMPLATE_NAMES],
+ description: 'Default executive-brief.',
+ },
+ theme: {
+ type: 'string',
+ enum: ['default', 'corporate', 'warm', 'alert'],
+ description: 'default slate, corporate navy, warm amber, alert rose.',
+ },
+ defaultThemeMode: {
+ type: 'string',
+ enum: ['light', 'dark'],
+ description: "Omit to follow the viewer's color scheme; set to force it.",
+ },
+ inlineChartJs: {
+ type: 'boolean',
+ description:
+ 'Default true (adds ~210 KB when charts are used). false: charts become value tables, ' +
+ 'no sparklines.',
+ },
+ branding: {
+ type: 'object',
+ description: 'Footer.',
+ properties: {
+ companyName: { type: 'string', description: 'Left side.' },
+ footerText: { type: 'string', description: 'Beside the date.' },
+ },
+ },
+ data: {
+ type: 'object',
+ description:
+ 'Page content. A field that names a template shows only in it; custom reads only ' +
+ 'title, blocks and meta.',
+ required: ['title'],
+ properties: {
+ eyebrow: { type: 'string', description: 'Label above the title.' },
+ title: { type: 'string', description: 'Heading.' },
+ headline: { type: 'string', description: 'Summary under the title.' },
+ status: {
+ type: 'string',
+ enum: [...HERO_STATUSES],
+ description: 'Badge beside the title.',
+ },
+ statusLabel: { type: 'string', description: 'Badge text, e.g. "On track".' },
+ period: {
+ type: 'string',
+ description: 'financial-review: e.g. "Q3 2026", above the title if no eyebrow.',
+ },
+ kpis: { type: 'array', description: 'Figure cards.', items: DASH_KPI_SCHEMA },
+ charts: { type: 'array', description: 'Chart cards.', items: DASH_CHART_SCHEMA },
+ heroChart: {
+ type: 'object',
+ required: ['type', 'datasets'],
+ description: `financial-review: one wide chart above charts. ${CHART_POINTER}`,
+ properties: CHART_COPY_PROPERTIES,
+ },
+ services: {
+ type: 'array',
+ description: 'operations-pulse: status cards.',
+ items: DASH_SERVICE_SCHEMA,
+ },
+ incidents: {
+ type: 'array',
+ description: 'operations-pulse: timeline, in order.',
+ items: DASH_INCIDENT_SCHEMA,
+ },
+ tables: { type: 'array', description: 'Tables.', items: DASH_TABLE_SCHEMA },
+ sections: {
+ type: 'array',
+ description: 'Prose after the tables.',
+ items: {
+ type: 'object',
+ required: ['type', 'content'],
+ properties: {
+ title: { type: 'string', description: 'Heading.' },
+ type: {
+ type: 'string',
+ enum: [...SECTION_TYPES],
+ description: 'Paragraphs, list, tinted box or monospaced block.',
+ },
+ content: DASH_SECTION_CONTENT_SCHEMA,
+ tone: { type: 'string', enum: [...CALLOUT_TONES], description: 'callout color.' },
+ language: { type: 'string', description: 'code language label.' },
+ },
+ },
+ },
+ blocks: {
+ type: 'array',
+ description: 'custom: blocks in page order; each field names the types that read it.',
+ items: {
+ type: 'object',
+ required: ['type'],
+ properties: {
+ type: { type: 'string', enum: [...BLOCK_TYPES], description: 'Block type.' },
+ title: { type: 'string', description: 'Heading (hero: page title).' },
+ eyebrow: { type: 'string', description: HERO_ONLY },
+ headline: { type: 'string', description: HERO_ONLY },
+ status: { type: 'string', enum: [...HERO_STATUSES], description: HERO_ONLY },
+ statusLabel: { type: 'string', description: HERO_ONLY },
+ items: {
+ type: 'array',
+ items: {
+ anyOf: [
+ { type: ['string', 'number'] },
+ {
+ type: 'object',
+ properties: {
+ label: { type: ['string', 'number'], description: 'KPI label.' },
+ value: { type: ['string', 'number'], description: 'KPI value.' },
+ delta: { type: ['string', 'number'], description: 'KPI delta.' },
+ deltaDirection: DELTA_DIRECTION_SCHEMA,
+ deltaSentiment: {
+ ...DASH_KPI_SCHEMA.properties.deltaSentiment,
+ description: 'As data.kpis[].',
+ },
+ accent: {
+ ...DASH_KPI_SCHEMA.properties.accent,
+ description: 'KPI accent.',
+ },
+ ...CHART_COPY_PROPERTIES,
+ time: { type: 'string', description: 'Incident time.' },
+ severity: DASH_INCIDENT_SCHEMA.properties.severity,
+ resolvedAt: { type: 'string', description: 'As data.incidents[].' },
+ title: { type: 'string', description: 'Chart or incident title.' },
+ },
+ },
+ ],
+ },
+ description:
+ 'bullets: strings. kpis, charts-grid, incidents: objects as in ' +
+ 'data.kpis[], charts[], incidents[].',
+ },
+ services: {
+ type: 'array',
+ description: 'service-health: as in data.services[].',
+ items: {
+ type: 'object',
+ required: ['name', 'status'],
+ properties: {
+ name: { type: 'string', description: 'Name.' },
+ status: DASH_SERVICE_SCHEMA.properties.status,
+ deltaDirection: DELTA_DIRECTION_SCHEMA,
+ },
+ },
+ },
+ spec: {
+ type: 'object',
+ properties: {
+ ...CHART_COPY_PROPERTIES,
+ headers: DASH_TABLE_SCHEMA.properties.headers,
+ rows: {
+ type: 'array',
+ items: ROW_SCHEMA,
+ description: 'As data.tables[].',
+ },
+ },
+ description: 'chart: as data.charts[]; table: as data.tables[].',
+ },
+ content: {
+ ...DASH_SECTION_CONTENT_SCHEMA,
+ description: 'narrative, code, callout: as data.sections[].content.',
+ },
+ language: { type: 'string', description: 'code: label.' },
+ tone: { type: 'string', enum: [...CALLOUT_TONES], description: 'callout: color.' },
+ size: { type: 'string', enum: ['sm', 'md', 'lg'], description: 'spacer: height.' },
+ },
+ },
+ },
+ meta: {
+ type: 'object',
+ description: 'Footer provenance.',
+ properties: {
+ date: { type: ['string', 'number'], description: 'Default: today.' },
+ author: { type: 'string', description: 'Author.' },
+ runId: { type: 'string', description: 'Run ID.' },
+ },
+ },
+ },
+ },
+ },
+ required: ['filename', 'data'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/docx.ts b/mcp-host/src/workflow/toolSchemas/docx.ts
new file mode 100644
index 000000000..3bd1b3167
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/docx.ts
@@ -0,0 +1,113 @@
+import { DOCX_IMAGE_FILE_DESCRIPTION } from '../documentSchema'
+import { ROW_SCHEMA, type ToolSchema } from './shared'
+
+// ─── generate_docx ───────────────────────────────────────────────────
+
+export const DOCX_TOOL: ToolSchema = {
+ name: 'clerum__generate_docx',
+ description:
+ 'Generate a styled Word (.docx) file from a markdown body, with optional tables, images, ' +
+ 'a palette and a branded header and footer with page numbers. The result lists anything ' +
+ 'left out.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename (e.g. 'report.docx'); .docx added if missing.",
+ },
+ title: {
+ type: 'string',
+ description: 'Title at the top, also in the running header.',
+ },
+ body: {
+ type: 'string',
+ description:
+ 'Markdown: # to ###### headings, **bold**, *italic*, `code`, [links](https://...), ' +
+ '"- " and "1. " lists (indent to nest), GFM pipe tables, ``` code blocks, > quotes, ' +
+ '--- rules, <br>. ![alt](chart.png) on its own line embeds an image from the output folder.',
+ },
+ palette: {
+ type: 'string',
+ enum: ['default', 'corporate', 'warm', 'alert'],
+ description: "Color palette. Default 'default'.",
+ },
+ headline: {
+ type: 'string',
+ description: 'One-line subtitle under the title.',
+ },
+ images: {
+ type: 'array',
+ description: 'Images added after the body and tables, in order.',
+ items: {
+ anyOf: [
+ { type: 'string', description: DOCX_IMAGE_FILE_DESCRIPTION },
+ {
+ type: 'object',
+ required: ['path'],
+ properties: {
+ path: { type: 'string', description: 'Same as the string form.' },
+ width: {
+ type: 'number',
+ description: 'Width in px; proportions are kept and the image fits the page.',
+ },
+ height: { type: 'number', description: 'Height in px; as for width.' },
+ alignment: {
+ type: 'string',
+ enum: ['left', 'center', 'right'],
+ description: "Default 'left'.",
+ },
+ },
+ },
+ ],
+ description: 'An image file name, or {path, width, height, alignment}.',
+ },
+ },
+ tables: {
+ type: 'array',
+ description: 'Tables added after the body.',
+ items: {
+ type: 'object',
+ required: ['headers', 'rows'],
+ properties: {
+ headers: {
+ type: 'array',
+ items: {
+ type: ['string', 'number'],
+ description: 'Heading text or number.',
+ },
+ description: 'Column headings, left to right.',
+ },
+ rows: {
+ type: 'array',
+ items: ROW_SCHEMA,
+ description: 'Rows of cells in header order. Cells take inline markdown and <br>.',
+ },
+ layout: {
+ type: 'string',
+ enum: ['striped', 'minimal', 'grid'],
+ description:
+ "striped: alternating fills; minimal: a rule under the header; grid: all borders. Default 'striped'.",
+ },
+ },
+ },
+ },
+ branding: {
+ type: 'object',
+ description: 'Branding for the header, footer and first page.',
+ properties: {
+ companyName: { type: 'string', description: 'Left side of the running header.' },
+ logoPath: {
+ type: 'string',
+ description: 'Logo above the title; an image file name as in images.',
+ },
+ footerText: {
+ type: 'string',
+ description: 'Text at the left of every footer; \\n starts a new line (up to 6).',
+ },
+ },
+ },
+ },
+ required: ['filename', 'body'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/markdown.ts b/mcp-host/src/workflow/toolSchemas/markdown.ts
new file mode 100644
index 000000000..c50d09467
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/markdown.ts
@@ -0,0 +1,20 @@
+import { type ToolSchema } from './shared'
+
+export const MARKDOWN_TOOL: ToolSchema = {
+ name: 'clerum__generate_markdown',
+ description: 'Generate a Markdown (.md) file. Provide the filename and full markdown content.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename (e.g. 'report.md'). Extension .md added if missing.",
+ },
+ content: {
+ anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
+ description: 'Full markdown text, as one string or an array of lines.',
+ },
+ },
+ required: ['filename', 'content'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/pdf.ts b/mcp-host/src/workflow/toolSchemas/pdf.ts
new file mode 100644
index 000000000..bb3fbde4f
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/pdf.ts
@@ -0,0 +1,134 @@
+import { IMAGE_FILE_DESCRIPTION, PDF_MAX_FOOTER_LINES, PDF_PORTRAIT_WIDTH } from '../documentSchema'
+import { ROW_SCHEMA, type ToolSchema } from './shared'
+
+// ─── generate_pdf ────────────────────────────────────────────────────
+
+/** Drawn size for a spreadsheet image, in pixels. */
+
+export const PDF_TOOL: ToolSchema = {
+ name: 'clerum__generate_pdf',
+ description:
+ 'Generate a print-quality PDF from a markdown body, with optional images, tables, a cover ' +
+ 'page with a status band, page numbers and a branded footer.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename, e.g. 'report.pdf'.",
+ },
+ title: {
+ type: 'string',
+ description: 'Document title, shown at the top of the first page.',
+ },
+ body: {
+ type: 'string',
+ description:
+ 'Markdown: # to ### headings, **bold**, *italic*, ~~strike~~, `code`, [links](url), ' +
+ 'fenced code, "- " and "1. " lists, GFM pipe tables, "> " quotes, "---" rules, <br>/<b>/<i>, ' +
+ 'and ![alt](file.png) on its own line to place an image from the output folder.',
+ },
+ palette: {
+ type: 'string',
+ enum: ['default', 'corporate', 'warm', 'alert'],
+ description: "Color palette. Default 'default'.",
+ },
+ coverPage: {
+ type: 'boolean',
+ description: 'Add a cover page with the title, headline, logo and status band.',
+ },
+ headline: {
+ type: 'string',
+ description: 'One-line subtitle under the title on the cover page.',
+ },
+ statusColor: {
+ type: 'string',
+ enum: ['green', 'yellow', 'red'],
+ description: 'Color of the status band on the cover page.',
+ },
+ images: {
+ type: 'array',
+ description:
+ 'Images (charts, logos) placed after the body and tables, in order; ' +
+ 'put ![alt](file.png) on a line of the body to place one there.',
+ items: {
+ anyOf: [
+ { type: 'string', description: IMAGE_FILE_DESCRIPTION },
+ {
+ type: 'object',
+ required: ['path'],
+ properties: {
+ path: { type: 'string', description: IMAGE_FILE_DESCRIPTION },
+ width: {
+ type: 'number',
+ description: `Width in points (the page is ${PDF_PORTRAIT_WIDTH} wide); the height follows.`,
+ },
+ height: {
+ type: 'number',
+ description: 'Height in points. With width too, the image fits inside both.',
+ },
+ alignment: {
+ type: 'string',
+ enum: ['left', 'center', 'right'],
+ description: "Default 'center'.",
+ },
+ },
+ },
+ ],
+ description: 'A file name, or an object with path and size.',
+ },
+ },
+ tables: {
+ type: 'array',
+ description: 'Tables placed after the body.',
+ items: {
+ type: 'object',
+ required: ['headers', 'rows'],
+ properties: {
+ headers: {
+ type: 'array',
+ items: { type: ['string', 'number'], description: 'One column heading.' },
+ description: 'Column headings, left to right.',
+ },
+ rows: {
+ type: 'array',
+ items: ROW_SCHEMA,
+ description: 'Rows, each an array of cells in header order.',
+ },
+ widths: {
+ type: 'array',
+ items: { type: ['string', 'number'], description: 'One column width.' },
+ description:
+ "One per header: points, a percentage such as '30%', 'auto' or '*' (share the rest). " +
+ 'Omit to size columns by content.',
+ },
+ layout: {
+ type: 'string',
+ enum: ['striped', 'minimal', 'grid'],
+ description: "Default 'striped'.",
+ },
+ },
+ },
+ },
+ branding: {
+ type: 'object',
+ description: 'Header and footer branding.',
+ properties: {
+ logoPath: {
+ type: 'string',
+ description: `Logo drawn on the cover page (needs coverPage: true). ${IMAGE_FILE_DESCRIPTION}`,
+ },
+ companyName: {
+ type: 'string',
+ description: 'Shown in the running header.',
+ },
+ footerText: {
+ type: 'string',
+ description: `Footer on every page, up to ${PDF_MAX_FOOTER_LINES} lines.`,
+ },
+ },
+ },
+ },
+ required: ['filename', 'body'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/pptx.ts b/mcp-host/src/workflow/toolSchemas/pptx.ts
new file mode 100644
index 000000000..b4951f2cf
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/pptx.ts
@@ -0,0 +1,437 @@
+import {
+ NATIVE_CHART_TYPES,
+ PPTX_ASPECT_RATIOS,
+ PPTX_PALETTES,
+ PPTX_TEMPLATES,
+ SEVERITIES,
+ SLIDE_LAYOUTS,
+ STATUSES,
+} from '../pptxVocabulary'
+import { ROW_SCHEMA, type ToolSchema } from './shared'
+
+// ════════════════════════════════════════════════════════════════════
+// ─── PPTX GENERATION (clerum__generate_pptx) ────────────────────────
+// ════════════════════════════════════════════════════════════════════
+//
+// The deck is built by pptxDeck.ts from arguments read by pptxInput.ts and,
+// for the preset decks, pptxTemplates.ts. The workflow path validates against
+// this schema before the tool runs.
+
+// Each shape is described in full once, under slides[]. The template fields in
+// `data` repeat its structure with short descriptions that point back there:
+// the schema goes out with every request and JSON Schema $ref is not portable.
+
+const PPTX_IMAGE_PATH_DESCRIPTION =
+ "Image file name in the output folder, e.g. from clerum__generate_chart ('sales.png'). " +
+ 'PNG, JPEG, GIF, WebP or SVG.'
+
+const PPTX_PATH_SHORT = 'File name from clerum__generate_chart.'
+
+/** An array of short texts, or one string read as one item per line. */
+function pptxTextList(description: string): Record<string, unknown> {
+ return {
+ anyOf: [{ type: 'array', items: { type: ['string', 'number'] } }, { type: 'string' }],
+ description,
+ }
+}
+
+function pptxImage(
+ description: string,
+ about: { path: string; caption: string; width: string; height: string }
+): Record<string, unknown> {
+ return {
+ anyOf: [
+ { type: 'string' },
+ {
+ type: 'object',
+ required: ['path'],
+ properties: {
+ path: { type: 'string', description: about.path },
+ caption: { type: 'string', description: about.caption },
+ width: { type: 'number', description: about.width },
+ height: { type: 'number', description: about.height },
+ },
+ },
+ ],
+ description,
+ }
+}
+
+function pptxKpis(
+ description: string,
+ about: { label: string; value: string; delta: string; deltaDirection: string }
+): Record<string, unknown> {
+ return {
+ type: 'array',
+ description,
+ items: {
+ type: 'object',
+ required: ['label', 'value'],
+ properties: {
+ label: { type: 'string', description: about.label },
+ value: { type: ['string', 'number'], description: about.value },
+ delta: { type: ['string', 'number'], description: about.delta },
+ deltaDirection: {
+ type: 'string',
+ enum: ['up', 'down', 'neutral'],
+ description: about.deltaDirection,
+ },
+ },
+ },
+ }
+}
+
+function pptxTable(description: string, headers: string, rows: string): Record<string, unknown> {
+ return {
+ type: 'object',
+ required: ['headers', 'rows'],
+ description,
+ properties: {
+ headers: { type: 'array', items: { type: ['string', 'number'] }, description: headers },
+ rows: { type: 'array', items: ROW_SCHEMA, description: rows },
+ },
+ }
+}
+
+/** A chart value; text such as "1,200" and {label, value} records are read too. */
+const PPTX_CHART_POINT_SCHEMA = {
+ anyOf: [
+ { type: 'number' },
+ { type: 'string' },
+ { type: 'null' },
+ {
+ type: 'object',
+ properties: {
+ label: { type: 'string', description: 'Category.' },
+ value: { type: ['number', 'string'], description: 'Value.' },
+ },
+ },
+ ],
+}
+
+function pptxChartSeries(about: {
+ labels: string
+ datasets: string
+ label: string
+ data: string
+}): Record<string, Record<string, unknown>> {
+ return {
+ labels: { type: 'array', items: { type: ['string', 'number'] }, description: about.labels },
+ datasets: {
+ type: 'array',
+ description: about.datasets,
+ items: {
+ type: 'object',
+ required: ['data'],
+ properties: {
+ label: { type: 'string', description: about.label },
+ data: { type: 'array', items: PPTX_CHART_POINT_SCHEMA, description: about.data },
+ },
+ },
+ },
+ }
+}
+
+const PPTX_SERIES_SHORT = {
+ labels: 'Categories.',
+ datasets: 'Series.',
+ label: 'Name.',
+ data: 'Values.',
+}
+
+/** What a chart's fields say: in full under slides[].chart, briefly in each template chart. */
+interface PptxChartAbout {
+ path: string
+ type: string
+ title: string
+ series: Parameters<typeof pptxChartSeries>[0]
+ /** The labels and datasets nested under `data`; declared only where this is set. */
+ nested?: string
+ caption: string
+}
+
+/**
+ * A chart, as slides[].chart and every template chart declare it. Both are
+ * built here, so each declares the same fields with the same types and only
+ * the descriptions differ: a provider or client that builds the call from the
+ * declared fields sends no other, so a field named only in prose never arrives.
+ */
+function pptxChart(description: string, about: PptxChartAbout): Record<string, unknown> {
+ return {
+ type: 'object',
+ description,
+ properties: {
+ path: { type: 'string', description: about.path },
+ type: { type: 'string', enum: [...NATIVE_CHART_TYPES], description: about.type },
+ title: { type: 'string', description: about.title },
+ ...pptxChartSeries(about.series),
+ ...(about.nested === undefined
+ ? {}
+ : {
+ data: {
+ type: 'object',
+ description: about.nested,
+ properties: pptxChartSeries(PPTX_SERIES_SHORT),
+ },
+ }),
+ caption: { type: 'string', description: about.caption },
+ },
+ }
+}
+
+const PPTX_CHART_SCHEMA = pptxChart(
+ 'A native, editable chart { type, labels, datasets }, or { path } for a chart image.',
+ {
+ path:
+ "Chart image file name from clerum__generate_chart (e.g. 'sales.png'), for " +
+ 'types the native list lacks. Native data given too is drawn if the file cannot be used.',
+ type: 'Native chart type. Only for native charts: with path, leave it out.',
+ title: 'Heading, unless it repeats the slide title.',
+ series: {
+ labels: 'Category labels, one per value.',
+ datasets: 'Series; a pie or doughnut draws only the first.',
+ label: 'Legend name.',
+ data: 'One value per label; null leaves a gap.',
+ },
+ nested: 'Or labels and datasets nested here, as clerum__generate_chart takes them.',
+ caption: 'Note under the chart.',
+ }
+)
+
+/**
+ * A template chart: slides[].chart with short descriptions and without its
+ * nested `data` form, which the flat fields make unnecessary. The deck builder
+ * reads both the same way (readChart).
+ */
+function pptxTemplateChart(description: string): Record<string, unknown> {
+ return pptxChart(`${description} As slides[].chart.`, {
+ path: PPTX_PATH_SHORT,
+ type: 'Chart type.',
+ title: 'Slide title.',
+ series: PPTX_SERIES_SHORT,
+ caption: 'Note.',
+ })
+}
+
+function pptxColumn(description: string): Record<string, unknown> {
+ return {
+ type: 'object',
+ required: ['type'],
+ description,
+ properties: {
+ type: {
+ type: 'string',
+ enum: ['bullets', 'narrative', 'image'],
+ description: 'Which field below it uses.',
+ },
+ bullets: pptxTextList("For type 'bullets'."),
+ text: { type: 'string', description: "For type 'narrative'." },
+ image: pptxImage("For type 'image'; as slides[].image.", {
+ path: PPTX_PATH_SHORT,
+ caption: 'Note.',
+ width: 'Inches.',
+ height: 'Inches.',
+ }),
+ },
+ }
+}
+
+/** The fields of every template's `data`; each description names the templates that read it. */
+const PPTX_TEMPLATE_DATA_PROPERTIES: Record<string, Record<string, unknown>> = {
+ title: {
+ type: ['string', 'number'],
+ description: 'executive-brief, quarterly-review, incident-review: cover title.',
+ },
+ subtitle: { type: ['string', 'number'], description: 'executive-brief: line under the title.' },
+ status: {
+ type: 'string',
+ enum: [...STATUSES],
+ description: 'executive-brief, quarterly-review: cover band color.',
+ },
+ kpis: pptxKpis('executive-brief, quarterly-review: cards, as slides[].kpis.', {
+ label: 'Label.',
+ value: 'Figure.',
+ delta: 'Change.',
+ deltaDirection: 'Delta color.',
+ }),
+ charts: {
+ type: 'array',
+ items: pptxTemplateChart('One chart.'),
+ description: 'executive-brief: one slide per chart.',
+ },
+ takeaways: pptxTextList('executive-brief: Key Takeaways slide.'),
+ nextSteps: pptxTextList('executive-brief: Next Steps slide.'),
+ period: { type: ['string', 'number'], description: 'quarterly-review: period, e.g. "Q3 2026".' },
+ highlights: pptxTextList('quarterly-review: highlights.'),
+ revenueChart: pptxTemplateChart('quarterly-review: revenue trend.'),
+ breakdownChart: pptxTemplateChart('quarterly-review: revenue breakdown.'),
+ metricsTable: pptxTable('quarterly-review: metrics, as slides[].table.', 'Headings.', 'Rows.'),
+ outlook: pptxTextList('quarterly-review: next-period priorities.'),
+ severity: {
+ type: 'string',
+ enum: [...SEVERITIES],
+ description: 'incident-review: colors the cover.',
+ },
+ date: { type: ['string', 'number'], description: 'incident-review: when it happened.' },
+ summary: { type: ['string', 'number'], description: 'incident-review: what happened, briefly.' },
+ timelineTable: pptxTable(
+ 'incident-review: timeline, as slides[].table.',
+ 'e.g. ["Time", "Event"].',
+ 'Rows.'
+ ),
+ impact: pptxTextList('incident-review: who and what was affected.'),
+ rootCause: { type: ['string', 'number'], description: 'incident-review: root cause.' },
+ remediation: pptxTextList('incident-review: fixes made or planned.'),
+ lessons: pptxTextList('incident-review: lessons learned.'),
+ company: { type: ['string', 'number'], description: 'pitch-deck: company name.' },
+ tagline: { type: ['string', 'number'], description: 'pitch-deck: one line under the name.' },
+ problem: { type: ['string', 'number'], description: 'pitch-deck: the problem, briefly.' },
+ solution: { type: ['string', 'number'], description: 'pitch-deck: the solution, briefly.' },
+ marketSize: {
+ type: 'object',
+ required: ['value'],
+ description: 'pitch-deck: addressable market.',
+ properties: {
+ value: { type: ['string', 'number'], description: 'e.g. "$12B".' },
+ description: { type: 'string', description: 'Scope and source.' },
+ },
+ },
+ tractionChart: pptxTemplateChart('pitch-deck: traction.'),
+ team: {
+ type: 'array',
+ description: 'pitch-deck: one card per person.',
+ items: {
+ type: 'object',
+ properties: {
+ name: { type: 'string', description: 'Name.' },
+ role: { type: 'string', description: 'e.g. "CEO".' },
+ },
+ },
+ },
+ ask: {
+ type: 'object',
+ required: ['amount'],
+ description: 'pitch-deck: the raise.',
+ properties: {
+ amount: { type: ['string', 'number'], description: 'e.g. "$5M".' },
+ useOfFunds: pptxTextList('Use of funds.'),
+ },
+ },
+}
+
+export const PPTX_TOOL: ToolSchema = {
+ name: 'clerum__generate_pptx',
+ description:
+ 'Generate a styled PowerPoint (.pptx) deck: set `template` and fill `data`, or pass ' +
+ '`slides[]`, each with a `layout`. A list of texts may also be one string, one item per ' +
+ 'line. Text is plain: markdown is not read. Lists, tables and KPI cards that do not fit ' +
+ 'continue on further slides and long text is set smaller; the result says when.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: { type: 'string', description: "e.g. 'deck.pptx'; .pptx is added if missing." },
+ title: { type: 'string', description: 'File metadata; not shown on a slide.' },
+ subject: { type: 'string', description: 'File metadata.' },
+ author: { type: 'string', description: 'File metadata.' },
+ template: {
+ type: 'string',
+ enum: [...PPTX_TEMPLATES, 'custom'],
+ description:
+ 'Preset deck from `data`. Required: executive-brief title; quarterly-review title, ' +
+ 'period; incident-review title, severity, summary; pitch-deck company, tagline, ' +
+ "problem, solution. 'custom' (default): use `slides[]`.",
+ },
+ data: {
+ type: 'object',
+ description: 'Fields for `template`.',
+ properties: PPTX_TEMPLATE_DATA_PROPERTIES,
+ },
+ palette: {
+ type: 'string',
+ enum: Object.keys(PPTX_PALETTES),
+ description: "Default 'default'.",
+ },
+ aspectRatio: {
+ type: 'string',
+ enum: Object.keys(PPTX_ASPECT_RATIOS),
+ description: "Default 'wide' (13.33×7.5 in).",
+ },
+ branding: {
+ type: 'object',
+ description: 'Footer on every slide but the cover; logo on the cover.',
+ properties: {
+ companyName: { type: 'string', description: 'Footer, left.' },
+ logoPath: {
+ type: 'string',
+ description:
+ 'Logo image file name in the output folder; formats as slides[].image.path.',
+ },
+ footerText: { type: 'string', description: 'Footer, after the company name.' },
+ },
+ },
+ slides: {
+ type: 'array',
+ minItems: 1,
+ description: 'The slides, in order.',
+ items: {
+ type: 'object',
+ required: ['layout'],
+ properties: {
+ layout: {
+ type: 'string',
+ enum: [...SLIDE_LAYOUTS],
+ description:
+ 'Needs: cover, section a title; title-bullets bullets; title-chart chart; ' +
+ 'title-table table; kpis kpis; two-column columns; image image; quote quote.',
+ },
+ title: { type: 'string', description: 'Heading.' },
+ eyebrow: { type: 'string', description: 'Section: label above the title.' },
+ subtitle: { type: 'string', description: 'Cover, section: line under the title.' },
+ status: {
+ type: 'string',
+ enum: [...STATUSES],
+ description: 'Cover: color of the top band.',
+ },
+ bullets: pptxTextList('Bullet points.'),
+ table: pptxTable('A table.', 'Column headings.', 'Rows of cells, in header order.'),
+ kpis: pptxKpis('Figures as cards, up to 8 per slide.', {
+ label: 'What it measures.',
+ value: 'A number, or formatted text, e.g. "$1.2M".',
+ delta: 'Change, e.g. "+12%".',
+ deltaDirection: 'Delta color: up good, down bad, neutral grey.',
+ }),
+ chart: PPTX_CHART_SCHEMA,
+ image: pptxImage('A file name, or { path, caption, width, height }.', {
+ path: PPTX_IMAGE_PATH_DESCRIPTION,
+ caption: 'Note under it.',
+ width:
+ 'Inches. With width or height the other keeps the proportions; with both the ' +
+ 'image fits inside that box; with neither it fills the space, up to twice its size.',
+ height: 'Inches; see width.',
+ }),
+ quote: {
+ type: 'object',
+ description: 'Pull quote.',
+ required: ['text'],
+ properties: {
+ text: { type: 'string', description: 'The words.' },
+ attribution: { type: 'string', description: 'Who said it.' },
+ },
+ },
+ columns: {
+ type: 'object',
+ description: 'Two columns.',
+ required: ['left', 'right'],
+ properties: {
+ left: pptxColumn('Left column.'),
+ right: pptxColumn('Right column.'),
+ },
+ },
+ notes: { type: 'string', description: 'Speaker notes.' },
+ },
+ },
+ },
+ },
+ required: ['filename'],
+ },
+}
diff --git a/mcp-host/src/workflow/toolSchemas/shared.ts b/mcp-host/src/workflow/toolSchemas/shared.ts
new file mode 100644
index 000000000..2379cccd0
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/shared.ts
@@ -0,0 +1,37 @@
+import type { InternalToolDefinition } from '../types'
+
+// ─── Portable schema fragments ───────────────────────────────────────
+//
+// A tool schema does two jobs. The workflow path (stepRouter) compiles it with
+// AJV and REJECTS arguments that do not match before execute() runs, so it must
+// accept everything the runtime handles. And it reaches every provider
+// verbatim, so it must survive each SDK's translation. Unions are therefore
+// written as scalar type lists or `anyOf` branches — @google/genai turns both
+// into its own schema — and never as `oneOf`, which it passes through
+// untranslated for the Gemini API to reject. Every array declares `items`.
+
+/** What a tool offers a model: everything but how it runs. */
+export type ToolSchema = Pick<InternalToolDefinition, 'name' | 'description' | 'parameters'>
+
+/**
+ * The types of a table or sheet cell: text, a number, true/false, or null for
+ * an empty cell. Each runtime stringifies or formats what arrives.
+ */
+export const CELL_TYPES = ['string', 'number', 'boolean', 'null']
+
+/**
+ * A row sent as a {header: cell} record, which every runtime reads by header
+ * name. Gemini rejects an object schema with no properties, so it declares one
+ * example key; additionalProperties keeps the others valid. The example is a
+ * column index, which the runtime reads as that column.
+ */
+export const RECORD_ROW_SCHEMA = {
+ type: 'object',
+ properties: { '0': { type: CELL_TYPES, description: 'Column 0, or a header.' } },
+ additionalProperties: { type: CELL_TYPES },
+}
+
+/** One row of cells, left to right in header order, or a record. */
+export const ROW_SCHEMA = {
+ anyOf: [{ type: 'array', items: { type: CELL_TYPES } }, RECORD_ROW_SCHEMA],
+}
diff --git a/mcp-host/src/workflow/toolSchemas/xlsx.ts b/mcp-host/src/workflow/toolSchemas/xlsx.ts
new file mode 100644
index 000000000..bff13c937
--- /dev/null
+++ b/mcp-host/src/workflow/toolSchemas/xlsx.ts
@@ -0,0 +1,205 @@
+import { RECORD_ROW_SCHEMA, type ToolSchema } from './shared'
+
+// ─── generate_xlsx ───────────────────────────────────────────────────
+
+const XLSX_CELL_SCHEMA = {
+ type: ['string', 'number', 'boolean', 'null'],
+ description:
+ 'A number, text, true/false, or null for empty. Text like "1,234.50", "$1,200", "45%" ' +
+ 'or an ISO date or datetime ("2026-09-22") is stored as a number or date; leading-zero codes and ' +
+ 'numbers over 15 digits stay text.',
+}
+
+const XLSX_IMAGE_PATH_DESCRIPTION =
+ "File name in the output folder, as returned by clerum__generate_chart (e.g. 'sales.png')."
+
+const XLSX_COLOR = 'hex such as "#1e3a8a" or a basic color name such as "green"'
+
+export const XLSX_TOOL: ToolSchema = {
+ name: 'clerum__generate_xlsx',
+ description:
+ 'Generate a styled Excel (.xlsx) workbook: per sheet, rows plus an optional title row, ' +
+ 'column formats, conditional formatting and images such as charts. Formulas are not ' +
+ 'supported: text starting with "=" stays text.',
+ parameters: {
+ type: 'object',
+ properties: {
+ filename: {
+ type: 'string',
+ description: "Output filename (e.g. 'data.xlsx'); .xlsx added if missing.",
+ },
+ palette: {
+ type: 'string',
+ enum: ['default', 'corporate', 'warm', 'alert'],
+ description: "Color palette. Default 'default'.",
+ },
+ branding: {
+ type: 'object',
+ description: 'Workbook-level branding.',
+ properties: {
+ companyName: { type: 'string', description: 'Author/company in workbook properties.' },
+ logoPath: {
+ type: 'string',
+ description:
+ 'Logo at the top of the first sheet; an image file name as in sheets[].images.',
+ },
+ },
+ },
+ sheets: {
+ type: 'array',
+ description: 'Worksheets, in tab order.',
+ items: {
+ type: 'object',
+ required: ['name', 'rows'],
+ properties: {
+ name: {
+ type: 'string',
+ description: 'Tab name: up to 31 characters, none of \\ / ? * : [ ].',
+ },
+ headers: {
+ type: 'array',
+ description: 'Header row, when it is not the first row of rows.',
+ items: { type: ['string', 'number'], description: 'Column header.' },
+ },
+ rows: {
+ type: 'array',
+ description:
+ 'Rows of cells; the first is the header row unless headers is given. [] for an images-only sheet.',
+ items: {
+ anyOf: [
+ {
+ type: 'array',
+ description: 'One row, left to right.',
+ items: XLSX_CELL_SCHEMA,
+ },
+ RECORD_ROW_SCHEMA,
+ ],
+ },
+ },
+ titleRow: {
+ type: 'object',
+ description: 'Merged title row above the header.',
+ properties: {
+ text: { type: 'string', description: 'Title text.' },
+ fillColor: { type: 'string', description: `Background: ${XLSX_COLOR}.` },
+ fontColor: { type: 'string', description: `Text color: ${XLSX_COLOR}.` },
+ },
+ required: ['text'],
+ },
+ columnFormats: {
+ type: 'object',
+ description:
+ "Format per column, keyed by header text, letter ('B') or 0-based index: " +
+ 'currencyUsd, currencyUsdInt, currency:EUR (any ISO code), percent (0.45 = 45%), ' +
+ 'percentPoints (45 = 45%), integer, decimal, plain (no separators: years, IDs), ' +
+ "date, datetime, text (as sent), or an Excel code like '#,##0.0'. Others are inferred.",
+ },
+ conditionalFormatting: {
+ type: 'array',
+ description: "Style a column's cells that match a rule.",
+ items: {
+ type: 'object',
+ required: ['column', 'rules'],
+ properties: {
+ column: {
+ type: ['string', 'number'],
+ description: "Header text, letter ('B') or 0-based index.",
+ },
+ rules: {
+ type: 'array',
+ description:
+ "Tested in order; the first match styles the cell. '45%' compares as 45, '$1,200' as 1200.",
+ items: {
+ type: 'object',
+ properties: {
+ equals: {
+ type: ['string', 'number', 'boolean'],
+ description: 'Cell equals this (text ignores case and outer spaces).',
+ },
+ notEquals: {
+ type: ['string', 'number', 'boolean'],
+ description: 'Cell differs from this, compared as for equals.',
+ },
+ greaterThan: {
+ type: 'number',
+ description: 'Cell is a number above this.',
+ },
+ lessThan: {
+ type: 'number',
+ description: 'Cell is a number below this.',
+ },
+ between: {
+ type: 'array',
+ items: { type: 'number' },
+ minItems: 2,
+ maxItems: 2,
+ description: 'Inclusive [min, max].',
+ },
+ contains: {
+ type: 'string',
+ description: 'Cell text contains this, ignoring case.',
+ },
+ regex: {
+ type: 'string',
+ maxLength: 256,
+ description:
+ 'Regex tested on the cell text. Invalid patterns and nested unbounded quantifiers are skipped with a warning.',
+ },
+ fillColor: {
+ type: 'string',
+ description: `Background: ${XLSX_COLOR}.`,
+ },
+ fontColor: {
+ type: 'string',
+ description: `Text color: ${XLSX_COLOR}.`,
+ },
+ bold: {
+ type: 'boolean',
+ description: 'Bold the text.',
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ freezeHeader: {
+ type: 'boolean',
+ description: 'Freeze the header row. Default true.',
+ },
+ autoFilter: {
+ type: 'boolean',
+ description: 'Filter buttons on the header. Default true.',
+ },
+ images: {
+ type: 'array',
+ description:
+ 'Images such as charts; without anchor or range they stack below the data.',
+ items: {
+ anyOf: [
+ { type: 'string', description: XLSX_IMAGE_PATH_DESCRIPTION },
+ {
+ type: 'object',
+ required: ['path'],
+ properties: {
+ path: { type: 'string', description: 'Same as the string form.' },
+ anchor: { type: 'string', description: "Top-left cell, e.g. 'F2'." },
+ range: { type: 'string', description: "Cells to fill, e.g. 'F2:M20'." },
+ width: {
+ type: 'number',
+ description: 'Width in px; proportions are kept. Omit for automatic.',
+ },
+ height: { type: 'number', description: 'Height in px; as for width.' },
+ },
+ },
+ ],
+ description: 'An image file name, or {path, anchor | range, width, height}.',
+ },
+ },
+ },
+ },
+ },
+ },
+ required: ['filename', 'sheets'],
+ },
+}
diff --git a/mcp-host/src/workflow/workflowTools.ts b/mcp-host/src/workflow/workflowTools.ts
new file mode 100644
index 000000000..9f7fd8ad2
--- /dev/null
+++ b/mcp-host/src/workflow/workflowTools.ts
@@ -0,0 +1,51 @@
+/** The workflow list, read and trigger tools, as internal tools. */
+import { WorkflowListTool, WorkflowStatusTool } from '../core/tools/workflowReadTools'
+import { WorkflowTriggerTool } from '../core/tools/workflowTriggerTool'
+import type { InternalToolDefinition, InternalToolResult } from './types'
+
+// ─── clerum__list_workflows ───────────────────────────────────────────
+
+const listWorkflowTool = new WorkflowListTool()
+
+export const listWorkflows: InternalToolDefinition = {
+ name: 'clerum__list_workflows',
+ description: listWorkflowTool.description(),
+ parameters: listWorkflowTool.parametersSchema(),
+ execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
+ const result = await listWorkflowTool.execute(args)
+ if (result.is_error) {
+ return { success: false, error: result.content }
+ }
+ return { success: true, content: result.content }
+ },
+}
+
+const readWorkflowTool = new WorkflowStatusTool()
+
+export const readWorkflow: InternalToolDefinition = {
+ name: 'clerum__read_workflow',
+ description: readWorkflowTool.description(),
+ parameters: readWorkflowTool.parametersSchema(),
+ execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
+ const result = await readWorkflowTool.execute(args)
+ if (result.is_error) {
+ return { success: false, error: result.content }
+ }
+ return { success: true, content: result.content }
+ },
+}
+
+const triggerWorkflowTool = new WorkflowTriggerTool()
+
+export const triggerWorkflow: InternalToolDefinition = {
+ name: 'clerum__trigger_workflow',
+ description: triggerWorkflowTool.description(),
+ parameters: triggerWorkflowTool.parametersSchema(),
+ execute: async (args: Record<string, unknown>): Promise<InternalToolResult> => {
+ const result = await triggerWorkflowTool.execute(args)
+ if (result.is_error) {
+ return { success: false, error: result.content }
+ }
+ return { success: true, content: result.content }
+ },
+}
diff --git a/mcp-host/src/workflow/xlsxGenerator.ts b/mcp-host/src/workflow/xlsxGenerator.ts
new file mode 100644
index 000000000..cde925fc5
--- /dev/null
+++ b/mcp-host/src/workflow/xlsxGenerator.ts
@@ -0,0 +1,44 @@
+/** clerum__generate_xlsx: builds the workbook (xlsxWorkbook, loaded on first use) and writes it. */
+import * as fs from 'fs'
+import {
+ artifactResult,
+ claimOutputFile,
+ enforceQuota,
+ ensureDir,
+ outputFilename,
+ replacedBytes,
+} from './artifactOutput'
+import type { InternalToolResult } from './types'
+
+/** Largest box an image placed in a sheet is fitted into, in pixels. */
+const XLSX_MAX_IMAGE_WIDTH = 640
+const XLSX_MAX_IMAGE_HEIGHT = 400
+
+export async function runGenerateXlsx(
+ args: Record<string, unknown>,
+ outputDir: string
+): Promise<InternalToolResult> {
+ try {
+ const filename = outputFilename(args.filename, 'xlsx', 'output')
+ const warnings: string[] = []
+ const { buildXlsxWorkbook } = await import('./xlsxWorkbook')
+ const built = await buildXlsxWorkbook(
+ args,
+ outputDir,
+ { width: XLSX_MAX_IMAGE_WIDTH, height: XLSX_MAX_IMAGE_HEIGHT },
+ warnings
+ )
+ if (!built.ok) return { success: false, error: built.error }
+ // The workbook is already in memory, so a quota breach leaves no partial file.
+ ensureDir(outputDir)
+ const target = claimOutputFile(outputDir, filename)
+ enforceQuota(outputDir, built.buffer.byteLength, replacedBytes(target))
+ fs.writeFileSync(target.filePath, built.buffer)
+ return artifactResult(target, 'xlsx', {
+ summary: `File generated: ${target.filename} (xlsx): ${built.summary}.`,
+ warnings,
+ })
+ } catch (err) {
+ return { success: false, error: err instanceof Error ? err.message : String(err) }
+ }
+}
diff --git a/workflow-recipes/tests/unit/workflow/regressionGuard.test.ts b/workflow-recipes/tests/unit/workflow/regressionGuard.test.ts
index a99fa849b..6ede45c54 100644
--- a/workflow-recipes/tests/unit/workflow/regressionGuard.test.ts
+++ b/workflow-recipes/tests/unit/workflow/regressionGuard.test.ts
@@ -350,13 +350,18 @@ describe('REG-13: Internal tools in StepMcpRouter', () => {
expect(content).toMatch(/resolveInternalTools|INTERNAL_TOOLS/)
})
- it('internalTools.ts is not empty', () => {
+ it('internalTools.ts lists the document tools, whose schemas live in toolSchemas/', () => {
const content = readMcpHostSource('workflow/internalTools.ts')
expect(content.length).toBeGreaterThan(100)
- expect(content).toContain('clerum__generate_pdf')
- expect(content).toContain('clerum__generate_docx')
- expect(content).toContain('clerum__generate_xlsx')
- expect(content).toContain('clerum__generate_markdown')
+ for (const [file, name] of [
+ ['pdf', 'clerum__generate_pdf'],
+ ['docx', 'clerum__generate_docx'],
+ ['xlsx', 'clerum__generate_xlsx'],
+ ['markdown', 'clerum__generate_markdown'],
+ ]) {
+ expect(content).toContain(`from './toolSchemas/${file}'`)
+ expect(readMcpHostSource(`workflow/toolSchemas/${file}.ts`)).toContain(name)
+ }
})
})
@@ -781,7 +786,7 @@ describe('REG-26: Parent PVC + subPath output storage', () => {
})
it('internalTools uses /output in workflow mode', () => {
- const content = readMcpHostSource('workflow/internalTools.ts')
+ const content = readMcpHostSource('workflow/outputDirectory.ts')
expect(content).toMatch(/['"]\/output['"]/)
expect(content).toContain('CLERUM_WORKFLOW_ENABLED')
// Fallback for non-workflow mode