fix(agent): bound spreadsheet and media generation (#273)

## Why

Routine spreadsheet requests were falling into a multi-step
Python/LibreOffice path because the native XLSX generator could not
represent formulas. Image requests also shared one strict schema with
video-only fields, causing model adapters to materialize incompatible
placeholders and enter validation retry loops.

## What changed

- add typed workbook-local formula cells with cached values and standard
number formats to the bounded XLSX generator
- route routine workbooks through one native publishing call while
retaining the custom Office path for complex work
- replace the mixed media tool with separate strict image and video
capabilities
- align capability policy, activity copy, system guidance, skill
bundles, and architecture documentation
- remove all legacy mixed-media tool references; no compatibility shim

## Architecture and migration effects

- tool capability contract changes from one mixed media capability to
two mode-specific capabilities
- no database migration or environment change
- Google AI keys remain request-scoped and lazily resolved

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode` (existing Knip configuration hint only)
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- parsed a representative bakery workbook with total and percentage
formula cells
- verified an external-network spreadsheet formula is rejected
- production acceptance will repeat the same ordinary-user spreadsheet
and image prompts after the exact merge commit is deployed

Author: iamjr15

apps/web/src/components/chat/message-activity-model.ts

@@ -64,6 +64,8 @@ const TOOL_VERBS: Record<string, ToolVerbSpec> = {
   docs_generate_pdf: { verb: "Generated a PDF" },
   docs_generate_slides: { verb: "Generated slides" },
   docs_generate_xlsx: { verb: "Generated a spreadsheet" },
+  generate_or_edit_image: { verb: "Generated or edited an image" },
+  generate_or_extend_video: { verb: "Generated or extended a video" },
   search_scrape: { verb: "Scraped", argKeys: ["url"] },
   search_web_content: { verb: "Searched the web", argKeys: ["query", "q"] },
   search_extract: { verb: "Extracted", argKeys: ["url"] },

packages/agent-core/README.md

@@ -27,8 +27,11 @@ Sandbox and artifact capabilities cross tool-domain boundaries only through
 Single-consumer data, document, and media implementations live under
 `src/tools/`. Data tools profile and normalize bounded tabular inputs and render
 deterministic SVG/Recharts output. Document tools generate sandbox-side PPTX,
-DOCX, XLSX, and PDF source against `/opt/cheatcode-doc-runtime`. Media and Google-backed
-browser tools resolve the user's Google AI BYOK key lazily when invoked. All three receive
+DOCX, XLSX, and PDF source against `/opt/cheatcode-doc-runtime`; routine XLSX generation
+supports bounded scalar and workbook-local formula cells with cached results and standard number
+formats, while complex models remain on the custom Office path. Image and video generation use
+separate strict contracts so one mode cannot acquire the other mode's arguments. Media and
+Google-backed browser tools resolve the user's Google AI BYOK key lazily when invoked. All three receive
 sandbox and R2 artifact capabilities through request-scoped contracts; they do
 not read environment variables, persist credentials, or log keys.
 Published media is rendered automatically in the chat artifact card and is available in Files;

packages/agent-core/src/mastra/agent-tool-policy.ts

@@ -54,7 +54,10 @@ const DOCUMENT_TOOLS = [
   "docs_generate_xlsx",
 ] as const satisfies readonly ToolCapabilityName[];
 
-const MEDIA_TOOLS = ["generate_or_edit_media"] as const satisfies readonly ToolCapabilityName[];
+const MEDIA_TOOLS = [
+  "generate_or_edit_image",
+  "generate_or_extend_video",
+] as const satisfies readonly ToolCapabilityName[];
 
 const RESEARCH_TOOLS = [
   "search_extract",

packages/agent-core/src/mastra/system-prompt.ts

@@ -322,15 +322,15 @@ This project is scaffolded at the workspace root and its dev server + live previ
 
 const DOCS_MODULE = `## Building documents & slides
 
-Build decks and docs from scratch with the preinstalled libraries — pptxgenjs for .pptx, docx, @react-pdf/renderer, exceljs — when the request needs custom layout control, or use docs_generate_slides / docs_generate_docx / docs_generate_pdf / docs_generate_xlsx for a fast structured deliverable. Preserve exact requested counts and scope. The structured generators validate their bounded layouts, publish the file, return its canonical read-only project path, and report the authoritative slide, section, or sheet count. For routine structured output, confirm that returned count and finish; do not search for the file, convert it, start a local server, or take screenshots. Use the custom path and inspect real renders when the user explicitly requests visual QA, the layout is custom or template-driven, or the document is high-stakes. In that path, check for faint text, overflow, placeholder text, and unfilled sections; re-render only affected pages after a fix. The file lands in the Deliverables automatically — refer to it naturally ("your deck is ready below"), don't paste a download link.`;
+Build decks and docs from scratch with the preinstalled libraries — pptxgenjs for .pptx, docx, @react-pdf/renderer, exceljs — when the request needs custom layout control, or use docs_generate_slides / docs_generate_docx / docs_generate_pdf / docs_generate_xlsx for a fast structured deliverable. Preserve exact requested counts and scope. The XLSX generator accepts scalar cells plus typed formula cells with cached results and number formats. The structured generators validate their bounded layouts, publish the file, return its canonical read-only project path, and report the authoritative slide, section, or sheet count. For routine structured output, confirm that returned count and finish; do not search for the file, convert it, start a local server, or take screenshots. Use the custom path and inspect real renders when the user explicitly requests visual QA, the layout is custom or template-driven, or the document is high-stakes. In that path, check for faint text, overflow, placeholder text, and unfilled sections; re-render only affected pages after a fix. The file lands in the Deliverables automatically — refer to it naturally ("your deck is ready below"), don't paste a download link.`;
 
 const DATA_MODULE = `## Data & analysis
 
 For a quick question, compute the answer and just tell the user — a small code_run or data_analyze_csv is enough; don't build a chart or open a browser unless asked. For a real analysis, profile the data (data_analyze_csv, or pandas / Node in the sandbox), surface the key findings, and build charts (data_chart) only when they add insight. Verify: open the produced file, confirm the numbers reconcile and formulas evaluate (no #REF! / #DIV/0!), and sanity-check every chart against the data.`;
 
 const MEDIA_MODULE = `## Images & video
 
-Load the generate-media skill before creating or editing an image or generating or extending a video. Use generate_or_edit_media for the final asset, choose the requested aspect ratio intentionally, preserve stated invariants when editing, and refer to the resulting Deliverable naturally without pasting its download URL. A successful result is rendered automatically in the chat and can be opened in Files; do not open its sandbox path in the browser or claim that the user cannot preview it.`;
+Load the generate-media skill before creating or editing an image or generating or extending a video. Use generate_or_edit_image for an image and generate_or_extend_video for a video. Call the selected tool once, choose the requested aspect ratio intentionally, preserve stated invariants when editing, and refer to the resulting Deliverable naturally without pasting its download URL. A successful result is rendered automatically in the chat and can be opened in Files; do not open its sandbox path in the browser or claim that the user cannot preview it. If the provider rejects or fails the request, report that failure instead of retrying the same request or substituting a hand-authored asset.`;
 
 const RESEARCH_MODULE = `## Research
 
@@ -343,7 +343,7 @@ Pick the path that fits and load the matching skill (skill_invoke) for its full
 - Web or mobile app → build it in the sandbox (React / Next.js, or Expo for mobile), start the dev server, and verify it in the browser; the running app shows in the Computer panel.
 - Slides or documents → use the fast structured generator when it fits, or the document libraries for custom control; preserve exact counts and verify proportionately before finishing. The file lands in the Deliverables.
 - Data → profile it (data_analyze_csv, or pandas / Node) and chart it (data_chart) when it adds insight; verify the numbers.
-- Image or video → load generate-media, then use generate_or_edit_media; the asset lands in the project and Deliverables and renders automatically in chat and Files.
+- Image or video → load generate-media, then use generate_or_edit_image for an image or generate_or_extend_video for a video; the asset lands in the project and Deliverables and renders automatically in chat and Files.
 - Research → gather and cross-check real sources (search_web / firecrawl_* / research_deep); cite everything, and use the deep-research workflow when the user asks for a report so its PDF is delivered automatically.
 - Acting in the user's connected apps → composio_list_tools then composio_execute, only when they ask.`;
 

packages/agent-core/src/mastra/tool-defs/document-tools.ts

@@ -45,7 +45,7 @@ export const mastraDocsGenerateDocx = createTool({
 export const mastraDocsGenerateXlsx = createTool({
   id: "docs_generate_xlsx",
   description:
-    "Generate an XLSX workbook from sheets, columns, and rows. Publishes it as a Deliverable and returns its exact project filePath.",
+    "Generate an XLSX workbook from sheets, columns, scalar cells, and typed formula cells with cached results and number formats. Publishes it as a Deliverable and returns its exact project filePath; routine workbooks need no custom script or recalculation pass.",
   inputSchema: GenerateSpreadsheetInputSchema,
   outputSchema: GenerateXlsxOutputSchema,
   execute: async (input, context) =>

packages/agent-core/src/mastra/tool-defs/media-tools.ts

@@ -1,24 +1,47 @@
 import { createTool } from "@mastra/core/tools";
-import { executeGenerateOrEditMedia } from "../../tools/media/execute";
 import {
-  GenerateOrEditMediaInputSchema,
-  GenerateOrEditMediaOutputSchema,
+  executeGenerateOrEditImage,
+  executeGenerateOrExtendVideo,
+} from "../../tools/media/execute";
+import {
+  GenerateImageOutputSchema,
+  GenerateOrEditImageInputSchema,
+  GenerateOrExtendVideoInputSchema,
+  GenerateVideoOutputSchema,
 } from "../../tools/media/schemas";
 import { resolveGoogleToolApiKey } from "./request-context";
 import { requestContextFromToolContext, workspaceRuntimeFromContext } from "./tool-runtime-context";
 
-/** Generates or edits media after lazily resolving the user's Google AI tool key. */
-export const mastraGenerateOrEditMedia = createTool({
-  id: "generate_or_edit_media",
+/** Generates or edits one image through a contract that cannot accept video-only fields. */
+export const mastraGenerateOrEditImage = createTool({
+  id: "generate_or_edit_image",
+  description:
+    "Generate a new image or edit/reference provided images with Google AI. Publishes the result to the project and Deliverables in one bounded call.",
+  inputSchema: GenerateOrEditImageInputSchema,
+  outputSchema: GenerateImageOutputSchema,
+  execute: async (input, context) => {
+    const requestContext = requestContextFromToolContext(context);
+    const googleApiKey = await resolveGoogleToolApiKey(requestContext);
+    return executeGenerateOrEditImage(
+      GenerateOrEditImageInputSchema.parse(input),
+      await workspaceRuntimeFromContext(context),
+      googleApiKey ?? "",
+    );
+  },
+});
+
+/** Generates or extends one video through a contract that cannot accept image-edit fields. */
+export const mastraGenerateOrExtendVideo = createTool({
+  id: "generate_or_extend_video",
   description:
-    "Generate or edit an image, or generate/extend a video, using Google media models. Stores the result in the project and Deliverables.",
-  inputSchema: GenerateOrEditMediaInputSchema,
-  outputSchema: GenerateOrEditMediaOutputSchema,
+    "Generate a new video or extend a provided video with Google AI. Publishes the result to the project and Deliverables in one bounded call.",
+  inputSchema: GenerateOrExtendVideoInputSchema,
+  outputSchema: GenerateVideoOutputSchema,
   execute: async (input, context) => {
     const requestContext = requestContextFromToolContext(context);
     const googleApiKey = await resolveGoogleToolApiKey(requestContext);
-    return executeGenerateOrEditMedia(
-      GenerateOrEditMediaInputSchema.parse(input),
+    return executeGenerateOrExtendVideo(
+      GenerateOrExtendVideoInputSchema.parse(input),
       await workspaceRuntimeFromContext(context),
       googleApiKey ?? "",
     );

packages/agent-core/src/mastra/tool-defs/registry.ts

@@ -32,7 +32,7 @@ export {
   mastraDocsGenerateSlides,
   mastraDocsGenerateXlsx,
 } from "./document-tools";
-export { mastraGenerateOrEditMedia } from "./media-tools";
+export { mastraGenerateOrEditImage, mastraGenerateOrExtendVideo } from "./media-tools";
 export {
   mastraDeepResearch,
   mastraFirecrawlExtract,

packages/agent-core/src/mastra/tool-defs/tool-set.ts

@@ -24,7 +24,8 @@ import {
   mastraFsRead,
   mastraFsSearch,
   mastraFsWrite,
-  mastraGenerateOrEditMedia,
+  mastraGenerateOrEditImage,
+  mastraGenerateOrExtendVideo,
   mastraGitClone,
   mastraGitCommit,
   mastraGitPush,
@@ -74,7 +75,8 @@ export const cheatcodeTools = {
   fs_read: mastraFsRead,
   fs_search: mastraFsSearch,
   fs_write: mastraFsWrite,
-  generate_or_edit_media: mastraGenerateOrEditMedia,
+  generate_or_edit_image: mastraGenerateOrEditImage,
+  generate_or_extend_video: mastraGenerateOrExtendVideo,
   git_clone: mastraGitClone,
   git_commit: mastraGitCommit,
   git_push: mastraGitPush,

packages/agent-core/src/tools/docs/schemas.ts

@@ -53,7 +53,26 @@ export const GenerateMarkdownPdfInputSchema = z.strictObject({
   title: TextValueSchema.optional(),
 });
 
-const SpreadsheetCellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+const SpreadsheetScalarSchema = z.union([
+  z.string().max(10_000),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+const SpreadsheetFormulaSchema = z.strictObject({
+  formula: z
+    .string()
+    .trim()
+    .min(1)
+    .max(1_000)
+    .refine(isSafeSpreadsheetFormula, "Formula must use workbook-local values and functions."),
+  numberFormat: z.enum(["general", "integer", "decimal", "percent", "currency"]).optional(),
+  result: z.union([z.string().max(10_000), z.number(), z.boolean()]),
+  type: z.literal("formula"),
+});
+
+const SpreadsheetCellSchema = z.union([SpreadsheetScalarSchema, SpreadsheetFormulaSchema]);
 const SpreadsheetRowSchema = z.record(z.string().min(1).max(80), SpreadsheetCellSchema);
 
 const SpreadsheetSheetSchema = z.strictObject({
@@ -107,3 +126,9 @@ export type GenerateSlidesInput = z.input<typeof GenerateSlidesInputSchema>;
 export type GenerateSlidesOutput = z.output<typeof GenerateSlidesOutputSchema>;
 export type GenerateSpreadsheetInput = z.input<typeof GenerateSpreadsheetInputSchema>;
 export type GenerateXlsxOutput = z.output<typeof GenerateXlsxOutputSchema>;
+
+function isSafeSpreadsheetFormula(value: string): boolean {
+  const formula = value.startsWith("=") ? value.slice(1) : value;
+  const blockedFunction = /\b(?:CALL|DDE|EXEC|FILTERXML|HYPERLINK|RTD|WEBSERVICE)\s*\(/i;
+  return formula.length > 0 && !/[[\]"'|@]/.test(formula) && !blockedFunction.test(formula);
+}

packages/agent-core/src/tools/docs/scripts.ts

@@ -107,14 +107,34 @@ export function buildXlsxScript(inputPath: string, outputPath: string, filename:
     'workbook.creator = "Cheatcode";',
     "workbook.created = new Date();",
     "workbook.title = input.title;",
+    "const numberFormats = {",
+    '  general: "General",',
+    '  integer: "#,##0",',
+    '  decimal: "#,##0.00",',
+    '  percent: "0.0%",',
+    '  currency: "$#,##0.00;($#,##0.00);-",',
+    "};",
+    "function cellValue(value) {",
+    '  if (!value || typeof value !== "object" || value.type !== "formula") return value;',
+    '  return { formula: value.formula.replace(/^=/, ""), result: value.result };',
+    "}",
     "for (const sheet of input.sheets) {",
     "  const worksheet = workbook.addWorksheet(sheet.name);",
     "  worksheet.columns = sheet.columns.map((column) => ({",
     "    header: column,",
     "    key: column,",
     "    width: Math.max(12, Math.min(36, column.length + 8)),",
     "  }));",
-    "  worksheet.addRows(sheet.rows);",
+    "  for (const inputRow of sheet.rows) {",
+    "    const values = Object.fromEntries(sheet.columns.map((column) => [column, cellValue(inputRow[column])]));",
+    "    const row = worksheet.addRow(values);",
+    "    sheet.columns.forEach((column, columnIndex) => {",
+    "      const value = inputRow[column];",
+    '      if (value && typeof value === "object" && value.type === "formula" && value.numberFormat) {',
+    "        row.getCell(columnIndex + 1).numFmt = numberFormats[value.numberFormat];",
+    "      }",
+    "    });",
+    "  }",
     "  worksheet.getRow(1).font = { bold: true };",
     "  worksheet.views = [{ state: 'frozen', ySplit: 1 }];",
     "}",