@pinepaper.studio/mcp-server 1.5.0 → 1.5.3

package/dist/tools/handlers.js

@@ -6,7 +6,7 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator } from '../types/code-generator.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ExportTrainingDataInputSchema, ImportSVGInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ExportTrainingDataInputSchema, ImportSVGInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
@@ -28,12 +28,20 @@ ApplyAnimatedMaskInputSchema, ApplyCustomMaskInputSchema, RemoveMaskInputSchema,
 // Template schemas
 ApplyTemplateInputSchema, 
 // Image import schemas
-ImportImageInputSchema, ErrorCodes, } from '../types/schemas.js';
+ImportImageInputSchema, 
+// Tool guide schema
+ToolGuideInputSchema, 
+// Ontology schemas
+AnalyzeDesignInputSchema, ValidateDesignInputSchema, QueryOntologyInputSchema, 
+// Scene management schemas
+ManageScenesInputSchema, ScenePlaybackInputSchema, 
+// New consolidated tool schemas
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, ViewInputSchema, BackgroundInputSchema, QueryInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError } from 'zod';
 import { writeFile, mkdir } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { getBrowserController, } from '../browser/puppeteer-controller.js';
+import { getBrowserController, resetBrowserController, } from '../browser/puppeteer-controller.js';
 import { getPerformanceTracker } from '../metrics/index.js';
 import { formatErrorContext, captureCanvasState } from '../execution/index.js';
 import { getSessionManager } from '../agent/session-manager.js';
@@ -111,18 +119,13 @@ function successResult(code, description) {
     return { content };
 }
 function executedResult(code, result, screenshot, description) {
+    const resultObj = { success: true, result };
+    if (description)
+        resultObj.description = description;
     const content = [
-        {
-            type: 'text',
-            text: `Executed PinePaper code:\n\n\`\`\`javascript\n${code}\n\`\`\`\n\nResult: ${JSON.stringify(result, null, 2)}`,
-        },
+        { type: 'text', text: JSON.stringify(resultObj, null, 2) },
+        { type: 'text', text: `Generated code:\n\`\`\`javascript\n${code}\n\`\`\`` },
     ];
-    if (description) {
-        content.push({
-            type: 'text',
-            text: `\n${description}`,
-        });
-    }
     if (screenshot) {
         content.push({
             type: 'image',
@@ -412,10 +415,43 @@ async function executeToolWithTracking(toolName, args, options, validator, codeG
 // =============================================================================
 // TOOL HANDLERS
 // =============================================================================
+/**
+ * Measure the approximate byte size of a CallToolResult payload.
+ * Text content is measured directly; image content estimates base64 overhead.
+ */
+function measureResponseBytes(result) {
+    let bytes = 0;
+    if (result.content) {
+        for (const item of result.content) {
+            if (item.type === 'text') {
+                bytes += Buffer.byteLength(item.text, 'utf-8');
+            }
+            else if (item.type === 'image') {
+                // Base64 image data
+                bytes += (item.data?.length ?? 0);
+            }
+        }
+    }
+    return bytes;
+}
 export async function handleToolCall(toolName, args, options = {}) {
-    const { i18n } = options;
     const tracker = getPerformanceTracker();
     const baseTimerId = `${toolName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    const result = await handleToolCallInner(toolName, args, options, tracker, baseTimerId);
+    // Record response payload size for token estimation
+    const responseBytes = measureResponseBytes(result);
+    tracker.recordMetric({
+        toolName,
+        phase: 'response_size',
+        duration: 0,
+        timestamp: Date.now(),
+        success: !result.isError,
+        responseBytes,
+    });
+    return result;
+}
+async function handleToolCallInner(toolName, args, options, tracker, baseTimerId) {
+    const { i18n } = options;
     try {
         switch (toolName) {
             // -----------------------------------------------------------------------
@@ -499,6 +535,78 @@ export async function handleToolCall(toolName, args, options = {}) {
                 const description = `Creates complete scene with ${itemCount} items, ${relationCount} relations, ${animationCount} animations`;
                 return executeOrGenerate(code, description, options, 'pinepaper_create_scene');
             }
+            case 'pinepaper_manage_scenes': {
+                const input = ManageScenesInputSchema.parse(args);
+                const code = codeGenerator.generateManageScenes(input);
+                return executeOrGenerate(code, `Scene: ${input.action}`, options, 'pinepaper_manage_scenes');
+            }
+            case 'pinepaper_scene_playback': {
+                const input = ScenePlaybackInputSchema.parse(args);
+                const code = codeGenerator.generateScenePlayback(input);
+                return executeOrGenerate(code, `Scene playback: ${input.action}`, options, 'pinepaper_scene_playback');
+            }
+            // -----------------------------------------------------------------------
+            // SELECTION, TRANSFORM & HISTORY TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_selection': {
+                const input = SelectionInputSchema.parse(args);
+                const code = codeGenerator.generateSelection(input);
+                return executeOrGenerate(code, `Selection: ${input.action}`, options, 'pinepaper_selection');
+            }
+            case 'pinepaper_transform': {
+                const input = TransformInputSchema.parse(args);
+                const code = codeGenerator.generateTransform(input);
+                return executeOrGenerate(code, `Transform: ${input.action}`, options, 'pinepaper_transform');
+            }
+            case 'pinepaper_history': {
+                const input = HistoryInputSchema.parse(args);
+                const code = codeGenerator.generateHistory(input);
+                return executeOrGenerate(code, `History: ${input.action}`, options, 'pinepaper_history');
+            }
+            // -----------------------------------------------------------------------
+            // IMAGE PROCESSING TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_image_filter': {
+                const input = ImageFilterInputSchema.parse(args);
+                const code = codeGenerator.generateImageFilter(input);
+                return executeOrGenerate(code, `Image filter: ${input.action}`, options, 'pinepaper_image_filter');
+            }
+            case 'pinepaper_lasso': {
+                const input = LassoInputSchema.parse(args);
+                const code = codeGenerator.generateLasso(input);
+                return executeOrGenerate(code, `Lasso: ${input.action}`, options, 'pinepaper_lasso');
+            }
+            case 'pinepaper_cutout_style': {
+                const input = CutoutStyleInputSchema.parse(args);
+                const code = codeGenerator.generateCutoutStyle(input);
+                return executeOrGenerate(code, `Cutout style: ${input.action}`, options, 'pinepaper_cutout_style');
+            }
+            // -----------------------------------------------------------------------
+            // COMPOSITION & VIEW TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_precomp': {
+                const input = PrecompInputSchema.parse(args);
+                const code = codeGenerator.generatePrecomp(input);
+                return executeOrGenerate(code, `Precomp: ${input.action}`, options, 'pinepaper_precomp');
+            }
+            case 'pinepaper_view': {
+                const input = ViewInputSchema.parse(args);
+                const code = codeGenerator.generateView(input);
+                return executeOrGenerate(code, `View: ${input.action}`, options, 'pinepaper_view');
+            }
+            case 'pinepaper_background': {
+                const input = BackgroundInputSchema.parse(args);
+                const code = codeGenerator.generateBackground(input);
+                return executeOrGenerate(code, `Background: ${input.action}`, options, 'pinepaper_background');
+            }
+            // -----------------------------------------------------------------------
+            // CANVAS QUERY TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_query': {
+                const input = QueryInputSchema.parse(args);
+                const code = codeGenerator.generateQuery(input);
+                return executeOrGenerate(code, `Query: ${input.action}`, options, 'pinepaper_query');
+            }
             // -----------------------------------------------------------------------
             // BATCH OPERATION TOOLS
             // -----------------------------------------------------------------------
@@ -924,86 +1032,35 @@ You can now start creating new items on a clean canvas.`,
             // BROWSER CONTROL TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_browser_connect': {
-                const url = args.url || 'https://pinepaper.studio';
-                // Default to headless: true for enforced agent mode
-                const headless = args.headless ?? true;
-                const controller = getBrowserController({ studioUrl: url, headless });
-                if (controller.connected) {
+                // Default to headless: false — if you explicitly call browser_connect, you likely want to see it
+                const headless = args.headless ?? false;
+                const controller = getBrowserController({ headless });
+                // Already connected with same headless mode → nothing to do
+                if (controller.connected && controller.isHeadless === headless) {
                     return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `Already connected to PinePaper Studio at ${controller.actualUrl}. Do NOT call this tool again — proceed directly with pinepaper_agent_start_job.`,
-                            },
-                        ],
+                        content: [{ type: 'text', text: `Already connected to PinePaper Studio (headless: ${headless}).` }],
                     };
                 }
+                // Already connected but different headless mode → reconnect
+                if (controller.connected && controller.isHeadless !== headless) {
+                    await resetBrowserController();
+                }
                 try {
-                    await controller.connect();
-                    // Get canvas size info to help agent understand the workspace
-                    const canvasSizeResult = await controller.executeCode(`const size = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 }; ({ width: size.width || 800, height: size.height || 600 });`, false);
+                    const newController = controller.connected ? controller : getBrowserController({ headless });
+                    if (!newController.connected)
+                        await newController.connect();
+                    const canvasSizeResult = await newController.executeCode(`const size = app.getCanvasSize ? app.getCanvasSize() : { width: 800, height: 600 }; ({ width: size.width || 800, height: size.height || 600 });`, false);
                     const canvasSize = canvasSizeResult.success
                         ? canvasSizeResult.result
                         : { width: 800, height: 600 };
-                    const screenshot = await controller.takeScreenshot();
-                    const content = [
-                        {
-                            type: 'text',
-                            text: `✅ Connected to PinePaper Studio at ${controller.actualUrl}
-
-**Agent mode enabled** (agent=1&mode=agent parameters added automatically)
-**Current canvas size: ${canvasSize.width}x${canvasSize.height}**
-
-⚠️ IMPORTANT NOTES:
-1. **Welcome Template**: First-time visitors see a welcome template with example items. Use \`pinepaper_clear_canvas\` or \`pinepaper_refresh_page\` to start with an empty canvas.
-2. **Canvas Size**: For complex designs (cards, invitations, detailed graphics), call \`pinepaper_set_canvas_size\` FIRST to set an appropriate size like 1080x1080 or larger. The default 800x600 may be too small.
-3. **Verify with Screenshots**: After making changes, use \`pinepaper_browser_screenshot\` to confirm your work.
-
-Browser is ready. You can now use other pinepaper tools to create and animate graphics.`,
-                        },
-                    ];
-                    if (screenshot) {
-                        content.push({
-                            type: 'image',
-                            data: screenshot,
-                            mimeType: 'image/png',
-                        });
-                    }
-                    return { content };
+                    return {
+                        content: [{ type: 'text', text: `Connected to PinePaper Studio (headless: ${headless}, canvas: ${canvasSize.width}x${canvasSize.height}).` }],
+                    };
                 }
                 catch (error) {
-                    const errorMessage = error instanceof Error ? error.message : 'Failed to connect to browser';
-                    // Provide helpful fallback instructions instead of just failing
+                    const errorMessage = error instanceof Error ? error.message : 'Failed to connect';
                     return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `⚠️ **Browser Connection Failed**
-
-**Error:** ${errorMessage}
-
-## Don't worry! You can still use PinePaper manually:
-
-### Option 1: Manual Browser Mode
-1. Open **PinePaper Studio** in your browser: https://pinepaper.studio/editor?agent=1&mode=agent
-2. Continue using PinePaper tools - the MCP server will generate code for each action
-3. Copy the generated code and paste it into the **Code Console** (</> icon in toolbar)
-
-### Option 2: Troubleshoot Browser Connection
-- **Check Chrome/Chromium**: Puppeteer requires Chrome or Chromium installed
-- **Try headless: false**: Call \`pinepaper_browser_connect\` with \`headless: false\` to see the browser window
-- **Check permissions**: Ensure the process has permission to launch browsers
-- **Firewall**: Check if firewall is blocking browser launch
-
-### What happens now?
-All PinePaper tools will work in **code-only mode**:
-- Each tool generates JavaScript code
-- You copy the code and paste it in PinePaper's Code Console
-- The code executes and creates your graphics
-
-**The MCP server is fully functional** - just without automatic browser control.`,
-                            },
-                        ],
+                        content: [{ type: 'text', text: `Browser connection failed: ${errorMessage}` }],
                     };
                 }
             }
@@ -1094,6 +1151,286 @@ All PinePaper tools will work in **code-only mode**:
                 };
             }
             // -----------------------------------------------------------------------
+            // DIAGNOSTIC REPORT
+            // -----------------------------------------------------------------------
+            case 'pinepaper_diagnostic_report': {
+                const input = DiagnosticReportInputSchema.parse(args);
+                const includeMetrics = input.includeMetrics !== false;
+                const includeCanvas = input.includeCanvas !== false;
+                const metricsLimit = input.metricsLimit ?? 100;
+                // --- Server info ---
+                const { detectToolkitFromEnvironment: detectToolkit, detectVerbosityFromEnvironment: detectVerbosity } = await import('./toolkits.js');
+                const serverSection = {
+                    version: '1.5.1',
+                    toolkit: detectToolkit(),
+                    verbosity: detectVerbosity(),
+                    locale: process.env.PINEPAPER_LOCALE || 'en',
+                    executionMode: options.executionMode || getExecutionMode(),
+                    screenshotMode: options.screenshotMode || getScreenshotMode(),
+                };
+                // --- Browser state ---
+                let browserSection = { connected: false };
+                try {
+                    const ctrl = options.browserController || getBrowserController();
+                    browserSection = {
+                        connected: ctrl.connected,
+                        agentMode: ctrl.agentMode,
+                        studioUrl: ctrl.studioUrl,
+                    };
+                }
+                catch { /* browser not initialized */ }
+                // --- Session state ---
+                let sessionSection = {};
+                try {
+                    const session = getSessionManager();
+                    sessionSection = session.getStats();
+                }
+                catch { /* session not initialized */ }
+                // --- Canvas state ---
+                let canvasSection = null;
+                if (includeCanvas) {
+                    try {
+                        const ctrl = options.browserController || getBrowserController();
+                        if (ctrl.connected) {
+                            canvasSection = await captureCanvasState(ctrl);
+                        }
+                    }
+                    catch { /* canvas capture failed */ }
+                }
+                // --- Performance metrics ---
+                let metricsSection = null;
+                if (includeMetrics) {
+                    try {
+                        const perfTracker = getPerformanceTracker();
+                        const recentMetrics = perfTracker.exportMetrics('json', { limit: metricsLimit });
+                        const stats = perfTracker.getStats();
+                        metricsSection = { entries: recentMetrics, stats };
+                    }
+                    catch { /* metrics not available */ }
+                }
+                // --- Tool definitions overhead (fixed cost per API turn) ---
+                let toolDefsSection = null;
+                try {
+                    const { PINEPAPER_TOOLS, getToolsForVerbosity } = await import('./definitions.js');
+                    const { getToolsForToolkit } = await import('./toolkits.js');
+                    const toolkit = detectToolkit();
+                    const verbosity = detectVerbosity();
+                    // Measure what actually gets sent to the LLM
+                    const activeTools = getToolsForToolkit(getToolsForVerbosity(verbosity), toolkit);
+                    const activeJson = JSON.stringify(activeTools);
+                    const activeBytes = Buffer.byteLength(activeJson, 'utf-8');
+                    const activeTokens = Math.ceil(activeBytes / 4);
+                    // Also measure full set for comparison
+                    const fullJson = JSON.stringify(PINEPAPER_TOOLS);
+                    const fullBytes = Buffer.byteLength(fullJson, 'utf-8');
+                    const fullTokens = Math.ceil(fullBytes / 4);
+                    // Measure other profiles for comparison recommendations
+                    const agentCompactTools = getToolsForToolkit(getToolsForVerbosity('compact'), 'agent');
+                    const agentCompactTokens = Math.ceil(Buffer.byteLength(JSON.stringify(agentCompactTools), 'utf-8') / 4);
+                    const agentMinimalTools = getToolsForToolkit(getToolsForVerbosity('minimal'), 'agent');
+                    const agentMinimalTokens = Math.ceil(Buffer.byteLength(JSON.stringify(agentMinimalTools), 'utf-8') / 4);
+                    // Per-tool breakdown of active set (top 10 heaviest)
+                    const perToolDef = activeTools.map((t) => ({
+                        tool: t.name,
+                        bytes: Buffer.byteLength(JSON.stringify(t), 'utf-8'),
+                        descBytes: Buffer.byteLength(t.description || '', 'utf-8'),
+                    })).sort((a, b) => b.bytes - a.bytes);
+                    const totalDescBytes = perToolDef.reduce((s, t) => s + t.descBytes, 0);
+                    toolDefsSection = {
+                        toolkit,
+                        verbosity,
+                        activeToolCount: activeTools.length,
+                        activeBytes,
+                        activeTokens,
+                        fullToolCount: PINEPAPER_TOOLS.length,
+                        fullBytes,
+                        fullTokens,
+                        descriptionBytes: totalDescBytes,
+                        descriptionPct: ((totalDescBytes / activeBytes) * 100).toFixed(1) + '%',
+                        top10: perToolDef.slice(0, 10).map((t) => ({
+                            tool: t.tool,
+                            bytes: t.bytes,
+                            tokens: Math.ceil(t.bytes / 4),
+                        })),
+                        profiles: {
+                            'full+verbose': fullTokens,
+                            'agent+compact': agentCompactTokens,
+                            'agent+minimal': agentMinimalTokens,
+                        },
+                        recommendations: [],
+                    };
+                    // Add actionable recommendations
+                    const recs = toolDefsSection.recommendations;
+                    if (toolkit === 'full') {
+                        recs.push(`Switch to PINEPAPER_TOOLKIT=agent to reduce to ~${agentCompactTokens.toLocaleString()} tokens/turn (agent+compact)`);
+                    }
+                    if (verbosity === 'verbose') {
+                        recs.push(`Set PINEPAPER_VERBOSITY=compact to reduce tool definitions overhead`);
+                    }
+                    if (verbosity !== 'minimal') {
+                        recs.push(`Set PINEPAPER_VERBOSITY=minimal for maximum savings (~${agentMinimalTokens.toLocaleString()} tokens with agent toolkit) — use pinepaper_tool_guide for on-demand docs`);
+                    }
+                    if (activeTokens > 20000) {
+                        recs.push(`Tool definitions alone consume ~${activeTokens.toLocaleString()} tokens per API turn — this is a major context budget item`);
+                    }
+                }
+                catch { /* definitions not available */ }
+                // --- Token usage estimate (response payloads) ---
+                let tokenSection = null;
+                try {
+                    const perfTracker = getPerformanceTracker();
+                    const responseSizeMetrics = perfTracker.getMetrics({ phase: 'response_size' });
+                    // Aggregate per-tool response sizes
+                    const perTool = new Map();
+                    let totalResponseBytes = 0;
+                    for (const m of responseSizeMetrics) {
+                        const bytes = m.responseBytes ?? 0;
+                        totalResponseBytes += bytes;
+                        const entry = perTool.get(m.toolName) ?? { calls: 0, totalBytes: 0 };
+                        entry.calls++;
+                        entry.totalBytes += bytes;
+                        perTool.set(m.toolName, entry);
+                    }
+                    // ~4 chars per token is a common estimate for English text
+                    const estimatedTokens = Math.ceil(totalResponseBytes / 4);
+                    // Sort by totalBytes descending
+                    const perToolSorted = [...perTool.entries()]
+                        .sort((a, b) => b[1].totalBytes - a[1].totalBytes)
+                        .map(([tool, data]) => ({
+                        tool,
+                        calls: data.calls,
+                        totalBytes: data.totalBytes,
+                        estimatedTokens: Math.ceil(data.totalBytes / 4),
+                        avgBytesPerCall: Math.round(data.totalBytes / data.calls),
+                    }));
+                    tokenSection = {
+                        totalToolCalls: responseSizeMetrics.length,
+                        totalResponseBytes,
+                        estimatedResponseTokens: estimatedTokens,
+                        perTool: perToolSorted,
+                    };
+                }
+                catch { /* metrics not available */ }
+                // --- Assemble report ---
+                const report = {
+                    timestamp: new Date().toISOString(),
+                    server: serverSection,
+                    browser: browserSection,
+                    session: sessionSection,
+                    canvas: canvasSection,
+                    metrics: metricsSection,
+                    toolDefinitions: toolDefsSection,
+                    tokenUsage: tokenSection,
+                };
+                // --- Save to disk ---
+                const exportDir = getExportDir();
+                await mkdir(exportDir, { recursive: true });
+                const fileName = `pinepaper_diagnostic_${Date.now()}.json`;
+                const filePath = join(exportDir, fileName);
+                const jsonContent = JSON.stringify(report, null, 2);
+                await writeFile(filePath, jsonContent, 'utf-8');
+                // --- Build summary (token budget first — it's what matters most) ---
+                const lines = [
+                    `Diagnostic report saved to: ${filePath}`,
+                    ``,
+                ];
+                // Token budget section — prominent at top
+                if (toolDefsSection) {
+                    const td = toolDefsSection;
+                    lines.push(`TOKEN BUDGET`);
+                    lines.push(`  Tool definitions: ~${td.activeTokens.toLocaleString()} tokens/turn (${td.activeToolCount} tools, ${(td.activeBytes / 1024).toFixed(0)} KB)`);
+                    lines.push(`  Descriptions are ${td.descriptionPct} of that overhead`);
+                    lines.push(`  Config: toolkit=${td.toolkit}, verbosity=${td.verbosity}`);
+                    if (tokenSection) {
+                        const tk = tokenSection;
+                        lines.push(`  Response payloads: ~${tk.estimatedResponseTokens.toLocaleString()} tokens across ${tk.totalToolCalls} tool calls (${(tk.totalResponseBytes / 1024).toFixed(1)} KB)`);
+                        const totalPerTurn = td.activeTokens + Math.ceil(tk.estimatedResponseTokens / Math.max(tk.totalToolCalls, 1));
+                        lines.push(`  Estimated per-turn cost: ~${totalPerTurn.toLocaleString()} tokens (definitions + avg response)`);
+                    }
+                    // Top 3 heaviest tool definitions
+                    const topDefs = td.top10.slice(0, 3);
+                    if (topDefs.length > 0) {
+                        lines.push(`  Heaviest definitions: ${topDefs.map(t => `${t.tool} (~${t.tokens.toLocaleString()}t)`).join(', ')}`);
+                    }
+                    // Top 3 heaviest response consumers
+                    if (tokenSection) {
+                        const tk = tokenSection;
+                        const topResp = tk.perTool.slice(0, 3);
+                        if (topResp.length > 0) {
+                            lines.push(`  Heaviest responses: ${topResp.map(t => `${t.tool} (${t.calls}x, ~${t.estimatedTokens.toLocaleString()}t)`).join(', ')}`);
+                        }
+                    }
+                    if (td.recommendations.length > 0) {
+                        lines.push(``);
+                        lines.push(`RECOMMENDATIONS`);
+                        for (const rec of td.recommendations) {
+                            lines.push(`  - ${rec}`);
+                        }
+                    }
+                    lines.push(``);
+                }
+                // Brief state summary
+                lines.push(`Server: v${serverSection.version} | toolkit=${serverSection.toolkit} | mode=${serverSection.executionMode}`);
+                lines.push(`Browser: ${browserSection.connected ? 'connected' : 'disconnected'}`);
+                lines.push(`Session: ${sessionSection.activeJob ? `active job (${sessionSection.currentJobId})` : 'no active job'} | ${sessionSection.completedJobs ?? 0} completed | ${sessionSection.totalItemsCreated ?? 0} items total`);
+                if (canvasSection) {
+                    const cs = canvasSection;
+                    lines.push(`Canvas: ${cs.itemCount ?? 0} items | ${JSON.stringify(cs.canvasSize ?? {})}`);
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            }
+            // -----------------------------------------------------------------------
+            // TOOL GUIDE (on-demand documentation)
+            // -----------------------------------------------------------------------
+            case 'pinepaper_tool_guide': {
+                const input = ToolGuideInputSchema.parse(args);
+                const { PINEPAPER_TOOLS, AI_AGENT_GUIDE } = await import('./definitions.js');
+                const { TOOL_TAGS } = await import('./toolkits.js');
+                // No args → full AI Agent Guide
+                if (!input.tool && !input.category) {
+                    return {
+                        content: [{ type: 'text', text: AI_AGENT_GUIDE }],
+                    };
+                }
+                // Specific tool → full verbose description
+                if (input.tool) {
+                    const tool = PINEPAPER_TOOLS.find((t) => t.name === input.tool);
+                    if (!tool) {
+                        return {
+                            content: [{ type: 'text', text: `Unknown tool: ${input.tool}. Use pinepaper_tool_guide with no args to see the AI Agent Guide.` }],
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: [{ type: 'text', text: `# ${tool.name}\n\n${tool.description}` }],
+                    };
+                }
+                // Category → all tools in that tag with descriptions
+                if (input.category) {
+                    const toolNames = TOOL_TAGS[input.category];
+                    if (!toolNames) {
+                        const available = Object.keys(TOOL_TAGS).join(', ');
+                        return {
+                            content: [{ type: 'text', text: `Unknown category: ${input.category}. Available: ${available}` }],
+                            isError: true,
+                        };
+                    }
+                    const lines = [`# Category: ${input.category}\n`];
+                    for (const name of toolNames) {
+                        const tool = PINEPAPER_TOOLS.find((t) => t.name === name);
+                        if (tool) {
+                            lines.push(`## ${tool.name}\n${tool.description}\n`);
+                        }
+                    }
+                    return {
+                        content: [{ type: 'text', text: lines.join('\n') }],
+                    };
+                }
+                return { content: [{ type: 'text', text: AI_AGENT_GUIDE }] };
+            }
+            // -----------------------------------------------------------------------
             // ASSET TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_search_assets': {
@@ -1306,8 +1643,13 @@ All PinePaper tools will work in **code-only mode**:
                     }
                 }
                 const code = codeGenerator.generateAgentStartJob(input);
-                const description = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
-                return executeOrGenerate(code, description, options, 'pinepaper_agent_start_job');
+                const descriptionText = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
+                const result = await executeOrGenerate(code, descriptionText, options, 'pinepaper_agent_start_job');
+                // Append a 1-line workflow hint
+                if (result.content && result.content.length > 0 && result.content[0].type === 'text') {
+                    result.content[0].text += `\n\nNEXT: Call batch_execute with all operations, then end_job.`;
+                }
+                return result;
             }
             case 'pinepaper_agent_end_job': {
                 const input = AgentEndJobInputSchema.parse(args);
@@ -1704,6 +2046,170 @@ All PinePaper tools will work in **code-only mode**:
                 return executeOrGenerate(code, 'Imports image', options, 'pinepaper_import_image');
             }
             // -----------------------------------------------------------------------
+            // ONTOLOGY TOOLS
+            // -----------------------------------------------------------------------
+            case 'pinepaper_analyze_design': {
+                const input = AnalyzeDesignInputSchema.parse(args);
+                const { DesignGraph } = await import('../ontology/index.js');
+                const dg = new DesignGraph();
+                const graph = dg.extractFromDefinition(input.definition);
+                const jsonLd = dg.toJsonLd(graph);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                templateId: graph.templateId,
+                                templateName: graph.templateName,
+                                category: graph.category,
+                                dimensions: graph.dimensions,
+                                duration: graph.duration,
+                                nodeCount: graph.nodes.length,
+                                edgeCount: graph.edges.length,
+                                nodeTypes: Object.fromEntries(Object.entries(graph.fingerprint?.nodeTypeCounts || {}).sort((a, b) => b[1] - a[1])),
+                                edgeTypes: Object.fromEntries(Object.entries(graph.fingerprint?.edgeTypeCounts || {}).sort((a, b) => b[1] - a[1])),
+                                patterns: graph.patterns,
+                                mathFunctions: graph.mathFunctions,
+                                generator: graph.generator,
+                                semantics: graph.semantics,
+                                fingerprint: graph.fingerprint,
+                                jsonLd,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case 'pinepaper_validate_design': {
+                const input = ValidateDesignInputSchema.parse(args);
+                const { DesignGraph, KnowledgeGraphValidator } = await import('../ontology/index.js');
+                const dg = new DesignGraph();
+                const validator = new KnowledgeGraphValidator();
+                const definition = input.definition;
+                const validation = validator.validateTemplate(definition);
+                let quality = null;
+                if (validation.valid) {
+                    const graph = dg.extractFromDefinition(definition);
+                    quality = validator.scoreQuality(definition, graph);
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                validation,
+                                quality,
+                            }, null, 2),
+                        }],
+                };
+            }
+            // -----------------------------------------------------------------------
+            // ONTOLOGY QUERY (read-only graph navigation)
+            // -----------------------------------------------------------------------
+            case 'pinepaper_query_ontology': {
+                const input = QueryOntologyInputSchema.parse(args);
+                const { PP_VOCABULARY, ITEM_TYPE_MAP, RELATION_TYPE_MAP } = await import('../ontology/vocabulary.js');
+                const { DesignGraph } = await import('../ontology/design-graph.js');
+                const dg = new DesignGraph();
+                let result;
+                switch (input.query) {
+                    case 'list_types': {
+                        const entries = Object.entries(PP_VOCABULARY.types);
+                        const filtered = entries.filter(([key, def]) => {
+                            if (input.category && def.category !== input.category)
+                                return false;
+                            if (!input.includeAbstract && def.abstract)
+                                return false;
+                            return true;
+                        });
+                        result = Object.fromEntries(filtered);
+                        break;
+                    }
+                    case 'list_edges': {
+                        const entries = Object.entries(PP_VOCABULARY.edges);
+                        const filtered = input.category
+                            ? entries.filter(([, def]) => def.category === input.category)
+                            : entries;
+                        result = Object.fromEntries(filtered);
+                        break;
+                    }
+                    case 'list_generators': {
+                        const entries = Object.entries(PP_VOCABULARY.generators);
+                        const filtered = input.category
+                            ? entries.filter(([, def]) => def.category === input.category)
+                            : entries;
+                        result = Object.fromEntries(filtered);
+                        break;
+                    }
+                    case 'list_effects': {
+                        result = ['sparkle', 'blast', 'smoke', 'fire', 'rain', 'snow', 'confetti', 'ripple', 'glow', 'electric'];
+                        break;
+                    }
+                    case 'list_patterns': {
+                        result = PP_VOCABULARY.patterns;
+                        break;
+                    }
+                    case 'list_math_functions': {
+                        result = PP_VOCABULARY.mathFunctions;
+                        break;
+                    }
+                    case 'type_hierarchy': {
+                        if (!input.ppType)
+                            return errorResult('INVALID_INPUT', 'ppType is required for type_hierarchy');
+                        result = dg.getTypeHierarchy(input.ppType);
+                        break;
+                    }
+                    case 'type_children': {
+                        if (!input.ppType)
+                            return errorResult('INVALID_INPUT', 'ppType is required for type_children');
+                        result = dg.getTypeChildren(input.ppType);
+                        break;
+                    }
+                    case 'type_properties': {
+                        if (!input.ppType)
+                            return errorResult('INVALID_INPUT', 'ppType is required for type_properties');
+                        result = dg.getPropertiesFor(input.ppType);
+                        break;
+                    }
+                    case 'animatable_properties': {
+                        if (!input.ppType)
+                            return errorResult('INVALID_INPUT', 'ppType is required for animatable_properties');
+                        result = dg.getAnimatableProperties(input.ppType);
+                        break;
+                    }
+                    case 'is_subtype': {
+                        if (!input.typeA || !input.typeB)
+                            return errorResult('INVALID_INPUT', 'typeA and typeB are required for is_subtype');
+                        result = { isSubtype: dg.isSubtypeOf(input.typeA, input.typeB) };
+                        break;
+                    }
+                    case 'edge_info': {
+                        const edgeName = input.relationName || input.ppType;
+                        if (!edgeName)
+                            return errorResult('INVALID_INPUT', 'relationName or ppType is required for edge_info');
+                        const ppEdge = PP_VOCABULARY.edges[edgeName] || PP_VOCABULARY.edges[RELATION_TYPE_MAP[edgeName] || ''];
+                        result = ppEdge || { error: `Unknown edge: ${edgeName}` };
+                        break;
+                    }
+                    case 'node_type': {
+                        if (!input.itemType)
+                            return errorResult('INVALID_INPUT', 'itemType is required for node_type');
+                        result = { ppType: dg.getNodeType(input.itemType) };
+                        break;
+                    }
+                    case 'edge_type': {
+                        if (!input.relationName)
+                            return errorResult('INVALID_INPUT', 'relationName is required for edge_type');
+                        result = { ppEdge: dg.getEdgeType(input.relationName) };
+                        break;
+                    }
+                    default:
+                        return errorResult('INVALID_INPUT', `Unknown query: ${input.query}`);
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        }],
+                };
+            }
+            // -----------------------------------------------------------------------
             // UNKNOWN TOOL
             // -----------------------------------------------------------------------
             default: {
@@ -1762,6 +2268,7 @@ All PinePaper tools will work in **code-only mode**:
                         'pinepaper_browser_screenshot',
                         'pinepaper_browser_status',
                         'pinepaper_get_performance_metrics',
+                        'pinepaper_diagnostic_report',
                         'pinepaper_search_assets',
                         'pinepaper_import_asset',
                         'pinepaper_p5_draw',
@@ -1777,6 +2284,8 @@ All PinePaper tools will work in **code-only mode**:
                         'pinepaper_diagram_mode',
                         // Scene tools
                         'pinepaper_create_scene',
+                        'pinepaper_manage_scenes',
+                        'pinepaper_scene_playback',
                         // Agent flow mode tools
                         'pinepaper_agent_start_job',
                         'pinepaper_agent_end_job',
@@ -1846,6 +2355,27 @@ All PinePaper tools will work in **code-only mode**:
                         'pinepaper_import_image',
                         // Paper.js direct access tools
                         'pinepaper_register_item',
+                        // On-demand guide & runtime config
+                        'pinepaper_tool_guide',
+                        'pinepaper_set_toolkit',
+                        // Ontology tools
+                        'pinepaper_analyze_design',
+                        'pinepaper_validate_design',
+                        'pinepaper_query_ontology',
+                        // Selection, transform & history tools
+                        'pinepaper_selection',
+                        'pinepaper_transform',
+                        'pinepaper_history',
+                        // Image processing tools
+                        'pinepaper_image_filter',
+                        'pinepaper_lasso',
+                        'pinepaper_cutout_style',
+                        // Composition & view tools
+                        'pinepaper_precomp',
+                        'pinepaper_view',
+                        'pinepaper_background',
+                        // Canvas query tools
+                        'pinepaper_query',
                     ],
                 });
             }