@pinepaper.studio/mcp-server 1.6.24 → 1.6.25

package/dist/tools/handlers.js

@@ -13,7 +13,7 @@ import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, Ad
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
-AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
+AgentStartJobInputSchema, AgentEndJobInputSchema, AgentResetInputSchema, AgentBatchExecuteInputSchema, AgentBatchOperationSchema, AgentExportInputSchema, ExportStoreInputSchema, AgentAnalyzeInputSchema, 
 // Letter collage schemas
 CreateLetterCollageInputSchema, AnimateLetterCollageInputSchema, 
 // Map schemas
@@ -34,11 +34,10 @@ SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInput
 import { ZodError, z } from 'zod';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { effectClass } from './effect-class.js';
-import { exportFileReceipt } from './export-file-receipt.js';
+import { exportFileReceiptOrReason, receiptErrorLine } from './export-file-receipt.js';
 import { ExportStepError, errorText, verifySavedFile, writeStep, bytesForSave } from './export-file-check.js';
 import { EFFECT_BEFORE_JS, effectAfterJs, namedItemIds, idMayBeGone, NO_CHANGE_NOTE } from './effect-check.js';
 import { writeFile, mkdir, appendFile, unlink, readFile, stat } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
 import { join, extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
@@ -59,12 +58,15 @@ import { exportHandlers } from './handlers/export.js';
 import { generateHandlers } from './handlers/generate.js';
 import { beatHandlers } from './handlers/beats.js';
 import { planCharacter, generateCharacterCode } from './handlers/character.js';
+import { jsLiteral } from '../utils/js-literal.js';
 import { buildZip } from '../utils/zip.js';
 import { buildScc } from '../utils/scc.js';
 import { checkContrast, checkFlashes, parseCssColor } from '../utils/a11y.js';
 import { buildHtml5Ad, buildPlayable, externalRequests, pinSceneBackground } from '../utils/ad-package.js';
 import { safeFetch, checkUrl, UnsafeUrlError } from '../utils/safe-fetch.js';
 import { confineAssetPath } from '../utils/asset-paths.js';
+import { env } from '../utils/env.js';
+import { getExportDir, exportFileLink } from '../utils/export-dir.js';
 /**
  * Registry of per-domain handler maps. Tools listed here short-circuit the
  * main switch at dispatch time (see handleToolCallInner). New domains are
@@ -87,7 +89,7 @@ function getDomainHandlers() {
  * Defaults to 'on_request' for optimal performance.
  */
 export function getScreenshotMode() {
-    const mode = process.env.PINEPAPER_SCREENSHOT_MODE?.toLowerCase();
+    const mode = env('PINEPAPER_SCREENSHOT_MODE')?.toLowerCase();
     if (mode === 'always' || mode === 'never' || mode === 'on_request') {
         return mode;
     }
@@ -97,9 +99,8 @@ export function getScreenshotMode() {
 // =============================================================================
 // EXPORT FILE SAVE HELPERS
 // =============================================================================
-export function getExportDir() {
-    return process.env.PINEPAPER_EXPORT_DIR || join(tmpdir(), 'pinepaper-exports');
-}
+// The export folder, one definition for the writers and for path confinement (utils/export-dir.ts).
+export { getExportDir };
 // wav joins them: a minute of 48kHz 16-bit is ~5.8 MB of base64 and the ten
 // minutes the schema allows is ~77 MB. Deliverable across the bridge, useless
 // pasted into a response.
@@ -135,10 +136,10 @@ const SAVE_THRESHOLD_BYTES = 180_000; // ~180KB base64 ≈ 135KB decoded
  */
 const EXPORT_GOVERNOR_DEFAULT_MS = 300_000;
 function exportGovernorTimeoutMs() {
-    const raw = Number(process.env.PINEPAPER_EXPORT_TIMEOUT);
+    const raw = Number(env('PINEPAPER_EXPORT_TIMEOUT'));
     if (!Number.isFinite(raw) || raw <= 0)
         return EXPORT_GOVERNOR_DEFAULT_MS;
-    const protocolFloor = Math.max(Number(process.env.PINEPAPER_TIMEOUT) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
+    const protocolFloor = Math.max(Number(env('PINEPAPER_TIMEOUT')) || 0, EXPORT_GOVERNOR_DEFAULT_MS);
     if (raw > protocolFloor) {
         console.error(`[PinePaper] PINEPAPER_EXPORT_TIMEOUT=${raw}ms is above the browser's protocol timeout (${protocolFloor}ms) — ` +
             'raise PINEPAPER_TIMEOUT to match, or an export past that point fails as a protocol error rather than a governor timeout.');
@@ -420,7 +421,7 @@ async function saveAdExport(r, input, platform) {
         content: [{
                 type: 'text',
                 text: `Ad saved:\n\n${Object.entries(files).map(([k, v]) => `${k}: ${v}`).join('\n')}\nFormat: ${r.format}\nSize: ${r.adSize.width}x${r.adSize.height}, upload ${(uploadBytes / 1024).toFixed(1)} KB\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-            }],
+            }, ...Object.values(files).filter((f) => typeof f === 'string').map((f) => exportFileLink(f))],
     };
 }
 async function saveExportToFile(data, format, platform) {
@@ -601,7 +602,7 @@ async function streamRetainedExportToFile(controller, retained, platform) {
  * Defaults to 'puppeteer' for live execution.
  */
 export function getExecutionMode() {
-    const mode = process.env.PINEPAPER_EXECUTION_MODE?.toLowerCase();
+    const mode = env('PINEPAPER_EXECUTION_MODE')?.toLowerCase();
     if (mode === 'puppeteer' || mode === 'code') {
         return mode;
     }
@@ -792,7 +793,7 @@ function executedResult(code, result, screenshot, description, report) {
     const content = [
         { type: 'text', text: JSON.stringify(resultObj, null, 2) },
     ];
-    if (process.env.PINEPAPER_ECHO_CODE === '1') {
+    if (env('PINEPAPER_ECHO_CODE') === '1') {
         content.push({ type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` });
     }
     if (screenshot) {
@@ -822,7 +823,7 @@ function screenshotResult(screenshot) {
  * error code, not a program, and stripping those would take information away.
  */
 function redactGeneratedCode(details) {
-    if (process.env.PINEPAPER_ECHO_CODE === '1')
+    if (env('PINEPAPER_ECHO_CODE') === '1')
         return details;
     if (!details || typeof details !== 'object' || Array.isArray(details))
         return details;
@@ -1085,9 +1086,7 @@ export async function customCodeRollback(controller, error) {
         removed = v.removed ?? 0;
         left = typeof v.left === 'number' ? v.left : -1;
     }
-    catch {
-        rolledBack = false;
-    }
+    catch { /* rolledBack stays false: nothing was confirmed removed */ }
     const scene = rolledBack
         ? (removed > 0
             ? `The ${removed} item(s) this call created before it stopped were removed. Changes it made to items that already existed are not reverted.`
@@ -1189,7 +1188,7 @@ async function writeResultDataToFile(out, ext) {
         const { data: _d, ...rest } = r;
         void _d;
         obj.result = { ...rest, filePath, bytes: bytes.length };
-        return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1)] };
+        return { ...out, content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }, ...out.content.slice(1), exportFileLink(filePath, bytes.length)] };
     }
     catch (e) {
         const err = e instanceof ExportStepError ? new ExportStepError(e.step, e.path ?? filePath, e.reason)
@@ -1569,7 +1568,7 @@ export function unwrapLint(run) {
     if (!r || typeof r !== 'object' || Array.isArray(r) || !('__ppLint' in r))
         return [];
     const lint = Array.isArray(r.__ppLint) ? r.__ppLint : [];
-    if ('__ppValue' in r)
+    if ('__ppValue' in r || r.__ppWrapped === true)
         run.result = r.__ppValue;
     else {
         const { __ppLint: _l, ...rest } = r;
@@ -1847,7 +1846,46 @@ async function nestedIgnoredFor(toolName, args) {
     if (!tool)
         return [];
     const hidden = new Set(NESTED_HIDDEN[toolName] ?? []);
-    return nestedIgnoredPaths(tool.inputSchema, args).filter((p) => !hidden.has(p.replace(/\[\d+\]/g, '[]')));
+    const paths = nestedIgnoredPaths(tool.inputSchema, args).filter((p) => !hidden.has(p.replace(/\[\d+\]/g, '[]')));
+    return toolName === 'pinepaper_agent_batch_execute' ? [...paths, ...batchOpIgnoredPaths(args)] : paths;
+}
+/**
+ * Batch op keys the batch reads that AgentBatchOperationSchema does not list. The op schema is passthrough (a create
+ * takes shape properties flat), so these arrive intact; batch-op-keys.test.ts fails when the batch code reads a key
+ * that is in neither list, so a working key is never reported. Shrink-only.
+ */
+export const BATCH_OP_HIDDEN = {
+    '*': ['_step', 'id'],
+    keyframe_animate: ['params', 'timeUnits', 'timeOffset', 'clipInPoint', 'clipOutPoint'],
+    timeline: ['repeat', 'yoyo', 'anchor'],
+};
+/** Hints for the slips that land on a key another op type reads. */
+const BATCH_OP_HINTS = {
+    'relation.params': 'a relation op takes its parameters as relationOptions',
+    'modify.x': 'a modify op takes changes inside properties', 'modify.y': 'a modify op takes changes inside properties',
+};
+/**
+ * A key on a batch op that nothing reads (the passthrough schema let it in, so the nested walk cannot see it). A
+ * `create` folds every op-level key into its properties, which create_item's own property report covers, so only the
+ * other op types are checked here.
+ */
+export function batchOpIgnoredPaths(args) {
+    const ops = Array.isArray(args.operations) ? args.operations : [];
+    const shape = Object.keys(AgentBatchOperationSchema.shape);
+    const out = [];
+    ops.forEach((op, i) => {
+        const type = op && typeof op === 'object' && !Array.isArray(op) ? String(op.type) : 'create';
+        if (type === 'create')
+            return;
+        const known = new Set([...shape, ...BATCH_OP_HIDDEN['*'], ...(BATCH_OP_HIDDEN[type] ?? [])]);
+        for (const k of Object.keys(op)) {
+            if (known.has(k))
+                continue;
+            const hint = BATCH_OP_HINTS[`${type}.${k}`];
+            out.push(`operations[${i}].${k}${hint ? ` (${hint})` : ''}`);
+        }
+    });
+    return out.slice(0, 50);
 }
 export const IGNORED_ARGUMENTS_META_KEY = 'pinepaper.studio/ignoredArguments';
 export async function handleToolCall(toolName, args, options = {}) {
@@ -2591,7 +2629,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                             const controller = options.browserController || getBrowserController();
                             if (!controller.connected)
                                 await controller.connect();
-                            const r = await controller.executeCode(`(function() { const ids = ${JSON.stringify(itemIds)}; return ids.filter(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return !(e && e.item); }); })();`, false);
+                            const r = await controller.executeCode(`(function() { const ids = ${jsLiteral(itemIds)}; return ids.filter(function(id) { const e = app.itemRegistry && app.itemRegistry.get(id); return !(e && e.item); }); })();`, false);
                             if (r.success && Array.isArray(r.result))
                                 missingItems = r.result;
                         }
@@ -3035,7 +3073,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 // Falls back to the PINEPAPER_STUDIO_URL env var, else PuppeteerController's
                 // built-in prod default. "/editor" + agent params are appended by the controller.
                 const rawUrl = typeof args.url === 'string' ? args.url.trim() : '';
-                const studioUrl = (rawUrl || (process.env.PINEPAPER_STUDIO_URL || '').trim()) || undefined;
+                const studioUrl = (rawUrl || (env('PINEPAPER_STUDIO_URL') || '').trim()) || undefined;
                 // Only http(s) is supported — reject file://, data://, javascript:, etc.
                 if (studioUrl) {
                     const v = validateStudioUrl(studioUrl);
@@ -3188,7 +3226,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     version: SERVER_VERSION,
                     toolkit: detectToolkit(),
                     verbosity: detectVerbosity(),
-                    locale: process.env.PINEPAPER_LOCALE || 'en',
+                    locale: env('PINEPAPER_LOCALE') || 'en',
                     executionMode: options.executionMode || getExecutionMode(),
                     screenshotMode: options.screenshotMode || getScreenshotMode(),
                 };
@@ -3290,6 +3328,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         })),
                         profiles: {
                             'full+verbose': fullTokens,
+                            'core+compact': Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity('compact'), 'core')), 'utf-8') / 4),
                             'agent+compact': agentCompactTokens,
                             'agent+minimal': agentMinimalTokens,
                         },
@@ -3302,7 +3341,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     const recs = toolDefsSection.recommendations;
                     const alternatives = [];
                     for (const v of ['compact', 'minimal']) {
-                        for (const k of ['full', 'agent', 'minimal']) {
+                        for (const k of ['full', 'agent', 'core', 'minimal']) {
                             if (k === toolkit && v === verbosity)
                                 continue;
                             const t = Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity(v), k)), 'utf-8') / 4);
@@ -3744,7 +3783,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                 type: 'text',
                                 // The script is not part of the answer here either — same reason
                                 // errors no longer carry it. PINEPAPER_ECHO_CODE=1 brings it back.
-                                text: (process.env.PINEPAPER_ECHO_CODE === '1'
+                                text: (env('PINEPAPER_ECHO_CODE') === '1'
                                     ? `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\n`
                                     : '')
                                     + `Full screenshot saved to: ${filePath} (${(fileSize / 1024).toFixed(1)} KB)\n\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
@@ -4017,13 +4056,13 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                             format,
                             chunkBytes: Number(exportResult.chunkBytes) || undefined,
                         }, input.platform || 'auto');
-                        const receipt = await exportFileReceipt(filePath, exportResult);
+                        const receipt = await exportFileReceiptOrReason(filePath, exportResult);
                         const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, chunks, file: receipt };
                         return withEngineReport({
                             content: [{
                                     type: 'text',
-                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n${probeLines(receipt)}${lintLines(exportResult)}\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-                                }],
+                                    text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\nPaged out of the studio's export store in ${chunks} chunk${chunks === 1 ? '' : 's'}\n${receiptErrorLine(receipt)}${'receiptError' in receipt ? '' : probeLines(receipt)}${lintLines(exportResult)}\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
+                                }, exportFileLink(filePath, fileSize)],
                         }, exportBrowserResult.report);
                     }
                     catch (streamError) {
@@ -4056,7 +4095,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                     const { sccCues: _c, ...rest } = exportResult;
                     void _c;
                     const cleanResult = { ...rest, filePath, fileSize, frameRate: '29.97 drop-frame', fidelity: { warnings } };
-                    return withEngineReport({ content: [{ type: 'text', text: `Export saved to file:\n\nFile: ${filePath}\nFormat: scc (CEA-608, CC1, pop-on)\nSize: ${fileSize} bytes\n\nResult: ${JSON.stringify(cleanResult, null, 2)}` }] }, exportBrowserResult.report);
+                    return withEngineReport({ content: [{ type: 'text', text: `Export saved to file:\n\nFile: ${filePath}\nFormat: scc (CEA-608, CC1, pop-on)\nSize: ${fileSize} bytes\n\nResult: ${JSON.stringify(cleanResult, null, 2)}` }, exportFileLink(filePath, fileSize)] }, exportBrowserResult.report);
                 }
                 if ((format === 'html5-ad' || format === 'playable') && typeof exportResult?.adPage === 'string') {
                     try {
@@ -4079,7 +4118,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 if (shouldSaveToFile) {
                     try {
                         const { filePath, fileSize } = await saveExportToFile(data, format, input.platform || 'auto');
-                        const receipt = await exportFileReceipt(filePath, exportResult);
+                        const receipt = await exportFileReceiptOrReason(filePath, exportResult);
                         const cleanResult = { ...exportResult, data: undefined, filePath, fileSize, file: receipt };
                         // A mix that dropped sounds wrote a perfectly good file that is
                         // missing tracks. It rides the SUCCESS path, which is exactly why
@@ -4090,10 +4129,11 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                     type: 'text',
                                     text: `Export saved to file:\n\nFile: ${filePath}\nFormat: ${format}\nSize: ${(fileSize / 1024).toFixed(1)} KB\nPlatform: ${input.platform}\n`
                                         + (dropNote ? `DROPPED: ${dropNote}\n` : '')
-                                        + probeLines(receipt)
+                                        + receiptErrorLine(receipt)
+                                        + ('receiptError' in receipt ? '' : probeLines(receipt))
                                         + lintLines(exportResult)
                                         + `\nResult: ${JSON.stringify(cleanResult, null, 2)}`,
-                                }],
+                                }, exportFileLink(filePath, fileSize)],
                         }, exportBrowserResult.report);
                     }
                     catch (saveError) {