feat(mcp): add --output-max-size with post-response disk eviction (draft)

Alternative to #41021 implementing Pavel's suggestion: instead of
intercepting writes in code with an OutputFile/OutputDir layer, let
tools write whatever and prune the outputDir from disk after each
tool call.

After Response.serialize() builds its sections, _enforceOutputBudget
recursively lists outputDir, sorts by mtime ascending, and unlinks
oldest files until total <= outputMaxSize. Files written by the
current Response are tracked in _writtenFiles and never evicted, so
artifacts referenced in the response stay readable.

Config: same outputMaxSize field, --output-max-size CLI flag, and
PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE env var as #41021.

Trade-offs vs #41021:
- ~74 lines added vs ~390; no new types or evictable plumbing.
- Trace/sessionLog need no special-casing — their mtime bumps keep
  them young, naturally last to evict.
- Sees externally-written files (downloads, trace bundles) — they
  count against the budget and evict by age.
- Self-healing on external fs changes.
- Cap can briefly exceed during a single tool call that writes a
  large artifact; #41021 pre-evicts so the cap is hard.
- Weaker pin guarantee for session.md (recency-based, not flag-based).

Author: Skn0tt

packages/playwright-core/src/tools/backend/context.ts

@@ -45,6 +45,7 @@ export type ContextConfig = {
     blockedOrigins?: string[];
   };
   outputDir?: string;
+  outputMaxSize?: number;
   outputMode?: 'file' | 'stdout';
   saveSession?: boolean;
   saveTrace?: boolean;

packages/playwright-core/src/tools/backend/response.ts

@@ -21,6 +21,8 @@ import debug from 'debug';
 import { renderModalStates } from './tab';
 import { scaleImageToFitMessage } from './screenshot';
 
+import { outputDir as resolveOutputDir } from './context';
+
 import type * as playwright from '../../..';
 import type { TabHeader } from './tab';
 import type { CallToolResult, ImageContent, TextContent } from '@modelcontextprotocol/sdk/types.js';
@@ -59,6 +61,7 @@ export class Response {
   private _imageResults: { data: Buffer, imageType: 'png' | 'jpeg' }[] = [];
   private _raw: boolean;
   private _json: boolean;
+  private _writtenFiles = new Set<string>();
 
   constructor(context: Context, toolName: string, toolArgs: Record<string, any>, options?: { relativeTo?: string, raw?: boolean, json?: boolean }) {
     this._context = context;
@@ -111,6 +114,7 @@ export class Response {
       await fs.promises.writeFile(resolvedFile.fileName, this._redactSecrets(data), 'utf-8');
     else if (data)
       await fs.promises.writeFile(resolvedFile.fileName, data);
+    this._writtenFiles.add(path.resolve(resolvedFile.fileName));
   }
 
   async addFileResult(resolvedFile: ResolvedFile, data: Buffer | string | null) {
@@ -163,6 +167,7 @@ export class Response {
 
   async serialize(): Promise<CallToolResult> {
     const allSections = await this._build();
+    await this._enforceOutputBudget();
     const rawSections = ['Error', 'Result', 'Snapshot'] as const;
     const sections = this._raw ? allSections.filter(section => rawSections.includes(section.title as typeof rawSections[number])) : allSections;
 
@@ -225,6 +230,37 @@ export class Response {
     };
   }
 
+  private async _enforceOutputBudget(): Promise<void> {
+    const maxSize = this._context.config.outputMaxSize;
+    if (!maxSize)
+      return;
+    const dir = resolveOutputDir(this._context.options);
+    let entries: { path: string, size: number, mtimeMs: number }[];
+    try {
+      entries = await listFilesRecursive(dir);
+    } catch {
+      return;
+    }
+    let total = 0;
+    for (const e of entries)
+      total += e.size;
+    if (total <= maxSize)
+      return;
+    entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const entry of entries) {
+      if (total <= maxSize)
+        break;
+      if (this._writtenFiles.has(entry.path))
+        continue;
+      try {
+        await fs.promises.unlink(entry.path);
+        total -= entry.size;
+      } catch (error) {
+        requestDebug('output-budget unlink failed %s: %s', entry.path, error);
+      }
+    }
+  }
+
   private async _build(): Promise<Section[]> {
     const sections: Section[] = [];
     const addSection = (title: string, content: string[], codeframe?: 'yaml' | 'js') => {
@@ -329,6 +365,32 @@ function sanitizeUnicode(text: string): string {
   return text.toWellFormed?.() ?? text;
 }
 
+async function listFilesRecursive(dir: string): Promise<{ path: string, size: number, mtimeMs: number }[]> {
+  const result: { path: string, size: number, mtimeMs: number }[] = [];
+  async function walk(current: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        try {
+          const stat = await fs.promises.stat(full);
+          result.push({ path: full, size: stat.size, mtimeMs: stat.mtimeMs });
+        } catch {
+        }
+      }
+    }
+  }
+  await walk(dir);
+  return result;
+}
+
 function parseSections(text: string): Map<string, string> {
   const sections = new Map<string, string>();
   const sectionHeaders = text.split(/^### /m).slice(1); // Remove empty first element

packages/playwright-core/src/tools/mcp/config.d.ts

@@ -154,6 +154,11 @@ export type Config = {
    */
   outputDir?: string;
 
+  /**
+   * Threshold for evicting old output files, in bytes.
+   */
+  outputMaxSize?: number;
+
   console?: {
     /**
      * The level of console messages to return. Each level includes the messages of more severe levels. Defaults to "info".

packages/playwright-core/src/tools/mcp/config.ts

@@ -60,6 +60,7 @@ export type CLIOptions = {
   imageResponses?: 'allow' | 'omit';
   sandbox?: boolean;
   outputDir?: string;
+  outputMaxSize?: number;
   port?: number;
   proxyBypass?: string;
   proxyServer?: string;
@@ -354,6 +355,7 @@ function configFromCLIOptions(cliOptions: CLIOptions): Config & { configFile?: s
     sharedBrowserContext: cliOptions.sharedBrowserContext,
     snapshot: cliOptions.snapshotMode ? { mode: cliOptions.snapshotMode } : undefined,
     outputDir: cliOptions.outputDir,
+    outputMaxSize: cliOptions.outputMaxSize,
     imageResponses: cliOptions.imageResponses,
     testIdAttribute: cliOptions.testIdAttribute,
     timeouts: {
@@ -399,6 +401,7 @@ export function configFromEnv(env?: NodeJS.ProcessEnv): Config & { configFile?:
     options.imageResponses = enumParser<'allow' | 'omit'>('--image-responses', ['allow', 'omit'], e.PLAYWRIGHT_MCP_IMAGE_RESPONSES);
   options.sandbox = envToBoolean(e.PLAYWRIGHT_MCP_SANDBOX);
   options.outputDir = envToString(e.PLAYWRIGHT_MCP_OUTPUT_DIR);
+  options.outputMaxSize = numberParser(e.PLAYWRIGHT_MCP_OUTPUT_MAX_SIZE);
   options.port = numberParser(e.PLAYWRIGHT_MCP_PORT);
   options.proxyBypass = envToString(e.PLAYWRIGHT_MCP_PROXY_BYPASS);
   options.proxyServer = envToString(e.PLAYWRIGHT_MCP_PROXY_SERVER);

packages/playwright-core/src/tools/mcp/configIni.ts

@@ -161,6 +161,7 @@ const longhandTypes: Record<string, LonghandType> = {
   'saveVideo': 'size',
   'sharedBrowserContext': 'boolean',
   'outputDir': 'string',
+  'outputMaxSize': 'number',
   'imageResponses': 'string',
   'allowUnrestrictedFileAccess': 'boolean',
   'codegen': 'string',

packages/playwright-core/src/tools/mcp/program.ts

@@ -59,6 +59,7 @@ export function decorateMCPCommand(command: Command) {
       .option('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".', enumParser.bind(null, '--image-responses', ['allow', 'omit']))
       .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
       .option('--output-dir <path>', 'path to the directory for output files.')
+      .option('--output-max-size <bytes>', 'Threshold for evicting old output files, in bytes.', numberParser)
       .option('--output-mode <mode>', 'whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout".', enumParser.bind(null, '--output-mode', ['file', 'stdout']))
       .option('--port <port>', 'port to listen on for SSE transport.')
       .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')