@pinepaper.studio/mcp-server 1.6.18 → 1.6.20

package/dist/tools/handlers.js

@@ -6,7 +6,7 @@
  * Supports browser execution via Puppeteer.
  */
 import { codeGenerator, generateQueryMutationsCode, SHEET_RUBRIC } from '../types/code-generator.js';
-import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
+import { CreateItemInputSchema, ModifyItemInputSchema, DeleteItemInputSchema, AddRelationInputSchema, RemoveRelationInputSchema, QueryRelationsInputSchema, AnimateItemInputSchema, ImportMotionCaptureInputSchema, KeyframeAnimateInputSchema, ExecuteGeneratorInputSchema, ApplyEffectInputSchema, GetItemsInputSchema, PlayTimelineInputSchema, SetBackgroundColorInputSchema, SetCanvasSizeInputSchema, ImportSVGInputSchema, ImportMermaidInputSchema, AddFilterInputSchema, CreateGlossySphereInputSchema, CreateDiagonalStripesInputSchema, BatchCreateInputSchema, BatchModifyInputSchema, CreateGridInputSchema, GeometryInputSchema, EquationPathInputSchema, EventInputSchema, ConstructionSequenceInputSchema, ValidateSceneInputSchema, CaptureFramesInputSchema, InstantiateOntologyInputSchema, LintSceneInputSchema, MediaInputSchema, TextStyleInputSchema, TextEffectInputSchema, DesignMediumInputSchema, RelightInputSchema, ChoreographInputSchema, EmitterInputSchema, MorphSequenceInputSchema, OriginalCharacterInputSchema, LookInputSchema, RenderHookInputSchema, ShaderGraphInputSchema, ShatterImageInputSchema, ImportLayeredCharacterInputSchema, CharacterInputSchema, GameInputSchema, World3DInputSchema, BrandKitInputSchema, ComponentInputSchema, ArtboardInputSchema, CommentInputSchema, ProvenanceInputSchema, SceneDiffInputSchema, AudioBeatsInputSchema, TemplateParamsInputSchema, RenderBatchInputSchema, AccessibilityCheckInputSchema, QueryMutationsInputSchema, ComposeInputSchema, CropImageInputSchema, PathOpInputSchema, MotionInputSchema, SoundInputSchema, InterchangeInputSchema, StickInputSchema, DesignSystemInputSchema, StoryInputSchema, ChromaKeyInputSchema, RiggingInputSchema, GroupInputSchema, CameraDirectorInputSchema, DetectObjectsInputSchema, ExtractObjectInputSchema, ArrangeInputSchema, CreateSceneInputSchema, GetPerformanceMetricsInputSchema, DiagnosticReportInputSchema, SearchAssetsInputSchema, ImportAssetInputSchema, P5DrawInputSchema, 
 // Diagram schemas
 CreateDiagramShapeInputSchema, ConnectInputSchema, ConnectPortsInputSchema, AddPortsInputSchema, AutoLayoutInputSchema, GetDiagramShapesInputSchema, UpdateConnectorInputSchema, RemoveConnectorInputSchema, DiagramModeInputSchema, 
 // Agent flow mode schemas
@@ -27,8 +27,11 @@ ImportImageInputSchema,
 // Scene management schemas
 ManageScenesInputSchema, ScenePlaybackInputSchema, SceneGraphInputSchema, SequenceInputSchema, StaggerInputSchema, FlipInputSchema, 
 // New consolidated tool schemas
-SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, ErrorCodes, } from '../types/schemas.js';
+SelectionInputSchema, TransformInputSchema, HistoryInputSchema, ImageFilterInputSchema, LassoInputSchema, CutoutStyleInputSchema, PrecompInputSchema, BackgroundInputSchema, QueryInputSchema, QueryCapabilitiesInputSchema, DeformInputSchema, SpriteSheetInputSchema, InteractionInputSchema, ExportWidgetInputSchema, ExportWidgetHtmlInputSchema, CreateChartInputSchema, MagicInputSchema, PhysicsInputSchema, MeasurementInputSchema, PlaceOnSurfaceInputSchema, StyledSceneInputSchema, ErrorCodes, } from '../types/schemas.js';
 import { ZodError, z } from 'zod';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { effectClass } from './effect-class.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';
@@ -37,6 +40,7 @@ import { getBrowserController, resetBrowserController, } from '../browser/puppet
 import { sameStudioTarget, validateStudioUrl } from '../browser/url-target.js';
 import { getPerformanceTracker } from '../metrics/index.js';
 import { formatErrorContext, captureCanvasState } from '../execution/index.js';
+import { FILTER_PARAM_RANGES } from './engine-lists.js';
 import { getSessionManager } from '../agent/session-manager.js';
 import { vocabularyHintForPath, validateBatchVocabulary, detectBatchPropertyTypos } from '../ontology/hints.js';
 import { cameraHandlers } from './handlers/camera.js';
@@ -560,10 +564,37 @@ export function getExecutionMode() {
     // Default to 'puppeteer' for live browser execution
     return 'puppeteer';
 }
+/** Where a generated script travels for a host to record, beside the agent-visible text. */
+/** Relation types registered with register_custom_relation in this server session (gate D2). */
+export const CUSTOM_RELATION_NAMES = new Set();
+/**
+ * Tools whose browser work legitimately outlasts the governor's 10 s default.
+ * The first detection call downloads and initialises a model, which on a cold
+ * page took longer than 10 s and died as a timeout (gate C10, 1.6.19).
+ */
+const LONG_GOVERNOR_BUDGET_MS = {
+    pinepaper_detect_objects: 120_000,
+    pinepaper_extract_object: 120_000,
+};
+export const CODE_META_KEY = 'pinepaper.studio/code';
 // =============================================================================
 // RESULT HELPERS
 // =============================================================================
-function successResult(code, description) {
+function successResult(code, description, deferred = false) {
+    if (deferred) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        status: 'recorded',
+                        step: description || 'canvas step',
+                        note: 'Recorded on the scene. It runs in the studio when the scene renders or exports, not now; keep building, then render.',
+                    }, null, 2),
+                }],
+            _meta: { [CODE_META_KEY]: code },
+        };
+    }
     const content = [
         {
             type: 'text',
@@ -576,7 +607,7 @@ function successResult(code, description) {
             text: `\n${description}`,
         });
     }
-    return { content };
+    return { content, _meta: { [CODE_META_KEY]: code } };
 }
 /**
  * A plain data answer.
@@ -589,6 +620,29 @@ function successResult(code, description) {
 function dataResult(value) {
     return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
 }
+/**
+ * Where a call's time went (O1, per-request trace). In the result's _meta, the
+ * spec's slot for metadata, under one namespaced key, so it adds nothing to
+ * the text a model reads. browserMs includes the screenshot when one was taken.
+ * index.ts adds toolMs, the whole call, for every tool.
+ */
+export const TIMING_META_KEY = 'pinepaper.studio/timing';
+export const EFFECT_META_KEY = 'pinepaper.studio/effect';
+/** The tool and action of the call in flight, for executeOrGenerate's effect check. */
+const callContext = new AsyncLocalStorage();
+let READ_ONLY_TOOLS = null;
+async function readOnlyTools() {
+    if (!READ_ONLY_TOOLS) {
+        const { PINEPAPER_TOOLS } = await import('./definitions.js');
+        READ_ONLY_TOOLS = new Set(PINEPAPER_TOOLS.filter((t) => t.annotations?.readOnlyHint).map((t) => t.name));
+    }
+    return READ_ONLY_TOOLS;
+}
+export function withTiming(out, t) {
+    const meta = (out._meta ?? {});
+    const prev = (meta[TIMING_META_KEY] ?? {});
+    return { ...out, _meta: { ...meta, [TIMING_META_KEY]: { ...prev, ...t } } };
+}
 /**
  * A call that only succeeded after the browser session was recovered says so,
  * in the result: the controller has reported `recovered` / `canvasReset` for
@@ -601,7 +655,7 @@ function withSessionNote(out, r) {
     const note = r.relaunched
         ? `The browser session had been lost; the browser was relaunched and this call ran on an EMPTY canvas${r.canvasSizeRestored ? ` (size restored to ${r.canvasSizeRestored.width}x${r.canvasSizeRestored.height})` : ' at the default size'}. Item ids from before are gone: rebuild the scene.`
         : r.canvasReset
-            ? 'The page had reloaded and the canvas came back EMPTY. Item ids from before are gone: rebuild the scene.'
+            ? 'The studio page had reloaded or navigated away, and the canvas came back EMPTY. Item ids from before are gone: rebuild the scene.'
             : 'The page connection was re-established; the scene survived.';
     const first = out.content[0];
     if (first && first.type === 'text') {
@@ -804,6 +858,80 @@ const REMOVE_ITEMS_CREATED_SINCE_MARK = `(function () {
  * false when the page could not be marked (the rollback is then skipped and
  * the failure note says nothing about the scene it cannot vouch for).
  */
+/**
+ * The studio's job gate (FxTool D92). PinePaperAgent.startJob is the one place
+ * a stale studio reloads, and only when the job is about to clear the canvas:
+ * it resolves {reloading: true, fromBuild, toBuild} and the PAGE reloads, so
+ * nothing running in it survives — the wait has to happen here. Poll the new
+ * page through waitForReady, open the job again, then let start_job's own
+ * setup (clear, canvas size) run on the fresh page.
+ */
+export async function studioJobGate(input, options, wait = (ms) => new Promise((r) => setTimeout(r, ms))) {
+    const mode = options.executionMode ?? getExecutionMode();
+    if (mode === 'code' || !options.executeInBrowser || options.deferred)
+        return {};
+    const controller = options.browserController || getBrowserController();
+    if (!controller.connected) {
+        try {
+            await controller.connect();
+        }
+        catch {
+            return {};
+        }
+    }
+    const args = JSON.stringify({ ...(input.name ? { name: input.name } : {}), clearCanvas: input.clearCanvas !== false });
+    const START = `(async function () {
+  const A = typeof window !== 'undefined' ? window.PinePaperAgent : null;
+  if (!A || !A.startJob) return { legacy: true };
+  return await A.startJob(${args});
+})();`;
+    const call = async (code) => {
+        try {
+            const r = await controller.executeCode(code, false, { bypassGovernor: true });
+            return r.success ? r.result : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const first = await call(START);
+    if (!first || first.legacy || (first.jobOpen === undefined && first.reloading === undefined))
+        return {};
+    const build = (j) => ({ buildId: j.buildId, liveBuildId: j.liveBuildId, stale: !!j.stale });
+    if (first.reloading) {
+        const READY = `(async function () {
+  const A = typeof window !== 'undefined' ? window.PinePaperAgent : null;
+  if (!A || !A.waitForReady) return { ready: false };
+  await A.waitForReady();
+  return { ready: true };
+})();`;
+        let ready = false;
+        for (let i = 0; i < 60 && !ready; i++) { // ~30 s: a reload is ~100 ms plus a fresh boot
+            await wait(500);
+            const r = await call(READY);
+            ready = !!(r && r.ready);
+        }
+        if (!ready)
+            return { warning: `the studio was reloading from build ${first.fromBuild} to ${first.toBuild} and did not come back within 30 s; this job may run on the old page.`, build: build(first) };
+        const second = await call(START);
+        if (!second)
+            return { warning: 'the studio reloaded but did not open the job again.', build: build(first) };
+        return {
+            note: `Studio was on build ${first.fromBuild}, reloaded to ${first.toBuild} before this job.`,
+            ...(second.stale ? { warning: `the studio is still on an old build after reloading (${second.buildId}; live ${second.liveBuildId})${second.reason ? ': ' + second.reason : ''}.` } : {}),
+            build: build(second),
+        };
+    }
+    if (first.stale) {
+        return {
+            warning: input.clearCanvas === false
+                ? `studio is on old build ${first.buildId} (live: ${first.liveBuildId}); finish, then start a new job to update.`
+                : `studio is on old build ${first.buildId} (live: ${first.liveBuildId}) and was not reloaded${first.reason ? ': ' + first.reason : ''}.`,
+            build: build(first),
+        };
+    }
+    return { build: build(first) };
+}
 async function markItemsBeforeRun(controller) {
     try {
         const r = await controller.executeCode(MARK_ITEMS_BEFORE_RUN, false, { bypassGovernor: true });
@@ -894,6 +1022,40 @@ async function brandFromUrl(url, shots, options) {
         return errorResult(ErrorCodes.EXECUTION_ERROR, `could not read ${url}: ${e instanceof Error ? e.message : String(e)}`, {}, { toolName: 'pinepaper_brand_kit' });
     }
 }
+/**
+ * If an executed result carries `data` (a data URL, or JSON/text), write it to
+ * a file in the export dir and replace it with filePath + bytes.
+ */
+async function writeResultDataToFile(out, ext) {
+    const first = out.content?.[0];
+    if (out.isError || !first || first.type !== 'text')
+        return out;
+    let obj;
+    try {
+        obj = JSON.parse(first.text);
+    }
+    catch {
+        return out;
+    }
+    const r = obj.result;
+    if (!r || r.data === undefined || r.data === null)
+        return out;
+    let bytes;
+    if (typeof r.data === 'string' && r.data.startsWith('data:'))
+        bytes = Buffer.from(r.data.slice(r.data.indexOf(',') + 1), 'base64');
+    else if (typeof r.data === 'string')
+        bytes = Buffer.from(r.data, 'utf-8');
+    else
+        bytes = Buffer.from(JSON.stringify(r.data), 'utf-8');
+    const dir = getExportDir();
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, `pinepaper_${String(r.format ?? 'export').replace(/[^a-z0-9-]/gi, '')}_${Date.now()}.${ext}`);
+    await writeFile(filePath, bytes);
+    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)] };
+}
 /**
  * pinepaper_capture_frames with `sheet`: one tiled image of the film, saved
  * to a file (an image is never useful inline, see ALWAYS_SAVE_FORMATS), with
@@ -998,7 +1160,7 @@ The code is ready to use. Each subsequent tool call will also generate code you
             timestamp: Date.now(),
             success: true,
         });
-        return successResult(code, description);
+        return successResult(code, description, options.deferred === true);
     }
     const controller = browserController || getBrowserController();
     // Auto-connect in agent mode if not connected
@@ -1081,18 +1243,46 @@ ${code}
     // emitter is not (its verdict already describes what it left behind).
     const rollbackOnFailure = toolName === 'pinepaper_execute_custom_code'
         && await markItemsBeforeRun(controller);
-    const result = await controller.executeCode(code, shouldTakeScreenshot, stage ? { stage } : {});
+    const governorTimeoutMs = LONG_GOVERNOR_BUDGET_MS[toolName];
+    // NO SILENT SUCCESS (effect-class.ts / effect-check.ts): fingerprint a
+    // mutating call before and after it runs.
+    const ctx = callContext.getStore();
+    const action = ctx && ctx.toolName === toolName ? ctx.action : undefined;
+    const effect = effectClass(toolName, action, (await readOnlyTools()).has(toolName));
+    const checkEffect = effect === 'mutates' && !rollbackOnFailure;
+    let effectCheckMs = 0;
+    let effectArmed = false;
+    if (checkEffect) {
+        const t0 = Date.now();
+        try {
+            const r = await controller.executeCode(EFFECT_BEFORE_JS, false, { bypassGovernor: true });
+            effectArmed = !!(r.success && r.result?.ok);
+        }
+        catch { /* unchecked this time */ }
+        effectCheckMs += Date.now() - t0;
+    }
+    const result = await controller.executeCode(code, shouldTakeScreenshot, {
+        ...(stage ? { stage } : {}),
+        ...(governorTimeoutMs ? { governorTimeoutMs } : {}),
+    });
     const browserDuration = tracker.endTimer(`${timerId}_browser_execution`);
+    // THE METRIC RECORDS THE CALL'S VERDICT, NOT THE TRANSPORT'S (gate H2,
+    // 1.6.19). result.success only says the code RAN; an emitter that ran and
+    // returned { success: false } is a failed call, and get_performance_metrics
+    // reported "Success Rate: 100.0%" over exactly such a failure.
+    const innerVerdict = result.success ? innerFailure(result.result) : null;
     tracker.recordMetric({
         toolName,
         phase: 'browser_execution',
         duration: browserDuration,
         timestamp: Date.now(),
-        success: result.success,
-        error: result.error,
+        success: result.success && !innerVerdict,
+        error: result.error || innerVerdict || undefined,
     });
+    let screenshotMs;
     if (shouldTakeScreenshot) {
         const screenshotDuration = tracker.endTimer(`${timerId}_screenshot`);
+        screenshotMs = screenshotDuration;
         tracker.recordMetric({
             toolName,
             phase: 'screenshot',
@@ -1108,13 +1298,14 @@ ${code}
         phase: 'total',
         duration: totalDuration,
         timestamp: Date.now(),
-        success: result.success,
-        error: result.error,
+        success: result.success && !innerVerdict,
+        error: result.error || innerVerdict || undefined,
     });
+    const timing = { browserMs: Math.round(browserDuration), ...(screenshotMs !== undefined ? { screenshotMs: Math.round(screenshotMs) } : {}) };
     if (!result.success) {
         // Capture canvas state for error context
         const canvasState = await captureCanvasState(controller);
-        return errorResult(ErrorCodes.EXECUTION_ERROR, result.error || 'Failed to execute code in browser', 
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, result.error || 'Failed to execute code in browser', 
         // errorCode surfaces the governor's structured code (PP_ITEM_BUDGET,
         // PP_LOOP_BUDGET, PP_TIMEOUT) so the model can correct on the next turn.
         {
@@ -1123,7 +1314,7 @@ ${code}
         }, {
             toolName,
             canvasState: canvasState || undefined,
-        });
+        }), timing);
     }
     // TWO VERDICTS. `result.success` says the CODE RAN. The emitted code has its
     // own verdict, and almost every emitter in this repo returns
@@ -1137,15 +1328,57 @@ ${code}
     // outer success and the agent kept building on a rig that did not exist.
     // pinepaper_agent_export got this check in 1.6.9; it belongs HERE, where
     // every tool inherits it.
-    const inner = innerFailure(result.result);
+    const inner = innerVerdict;
     if (inner) {
         const canvasState = await captureCanvasState(controller);
-        return errorResult(ErrorCodes.EXECUTION_ERROR, inner, {
+        // THE ENGINE'S OWN REASON, when it gave one. An emitter's refusal is often
+        // generic ("the studio refused the time_expression relation") while the
+        // engine said exactly why in a warning the governor captured ("unknown
+        // property 'opacty' — did you mean 'opacity'?"; D78). Production strips
+        // console.warn, so this is the only place the model can read it.
+        const said = (Array.isArray(result.report?.warnings) ? result.report.warnings : [])
+            .filter((w) => typeof w === 'string' && w.length > 0 && !inner.includes(w))
+            .slice(0, 3);
+        return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, said.length ? `${inner} The studio said: ${said.join(' | ')}` : inner, {
             code, result: result.result, governorReport: result.report,
             ...(rollbackOnFailure ? await customCodeRollback(controller, inner) : {}),
-        }, { toolName, canvasState: canvasState || undefined });
+        }, { toolName, canvasState: canvasState || undefined }), timing);
+    }
+    // Session item counts come from the governor's own count of what this call
+    // created (gate H3: the session stats read 0 with items on the canvas).
+    const created = result.report?.items?.created;
+    if (typeof created === 'number' && created > 0) {
+        try {
+            getSessionManager().noteItemsCreated(created);
+        }
+        catch { /* no session */ }
+    }
+    let noChangeNote = null;
+    let effectMeta = null;
+    if (checkEffect && effectArmed) {
+        const t0 = Date.now();
+        const ids = idMayBeGone(toolName, action) ? [] : namedItemIds(result.result);
+        const verdict = await controller.executeCode(effectAfterJs(ids), false, { bypassGovernor: true })
+            .then((r) => (r.success ? r.result : null))
+            .catch(() => null);
+        effectCheckMs += Date.now() - t0;
+        if (verdict && verdict.ok) {
+            // A CONTRADICTION, not idempotence: the call names an item that is not there.
+            if (verdict.missing && verdict.missing.length) {
+                return withTiming(errorResult(ErrorCodes.EXECUTION_ERROR, `the call reported ${verdict.missing.join(', ')}, which ${verdict.missing.length === 1 ? 'is' : 'are'} not on the canvas: it did not make what it said it made.`, { result: result.result }, { toolName }), { ...timing, effectCheckMs });
+            }
+            const changed = verdict.changed ?? [];
+            effectMeta = { class: effect, changed: changed.length > 0, signals: changed, checked: verdict.checked ?? [] };
+            if (!changed.length)
+                noChangeNote = NO_CHANGE_NOTE(verdict.checked ?? []);
+        }
     }
-    return withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result);
+    let out = withSessionNote(executedResult(code, result.result, result.screenshot, description, result.report), result);
+    if (noChangeNote)
+        out = { ...out, content: [...(out.content ?? []), { type: 'text', text: noChangeNote }] };
+    if (effectMeta)
+        out = { ...out, _meta: { ...(out._meta ?? {}), [EFFECT_META_KEY]: effectMeta } };
+    return withTiming(out, checkEffect ? { ...timing, effectCheckMs } : timing);
 }
 /**
  * The emitted code's own verdict, when it reported one and it was a failure.
@@ -1334,7 +1567,7 @@ export function ignoredArgumentsNote(toolName, args) {
 export async function handleToolCall(toolName, args, 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);
+    const result = await callContext.run({ toolName, action: typeof args.action === 'string' ? args.action : undefined }, () => handleToolCallInner(toolName, args, options, tracker, baseTimerId));
     const ignoredNote = ignoredArgumentsNote(toolName, args);
     if (ignoredNote)
         result.content = [...(result.content ?? []), { type: 'text', text: ignoredNote }];
@@ -1703,6 +1936,28 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_validate_scene': {
                 const input = ValidateSceneInputSchema.parse(args);
+                // The validator reads { from, to, relation } on an addRelation op; the
+                // add_relation tool's own names (source, target, relationType) are what
+                // an agent reaches for, and the tool's example used them, so every
+                // example op failed SOURCE_NOT_FOUND "undefined" (gate D8, 1.6.19).
+                if (Array.isArray(input.ops)) {
+                    input.ops = input.ops.map((op) => {
+                        const o = { ...op };
+                        if (o.from === undefined && o.source !== undefined) {
+                            o.from = o.source;
+                            delete o.source;
+                        }
+                        if (o.to === undefined && o.target !== undefined) {
+                            o.to = o.target;
+                            delete o.target;
+                        }
+                        if (o.relation === undefined && o.relationType !== undefined) {
+                            o.relation = o.relationType;
+                            delete o.relationType;
+                        }
+                        return o;
+                    });
+                }
                 const code = codeGenerator.generateValidateScene(input);
                 const description = input.ops ? `Pre-validate ${input.ops.length} proposed op(s)` : 'Audit the live scene';
                 return executeOrGenerate(code, description, options, 'pinepaper_validate_scene');
@@ -1770,6 +2025,47 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
                 return executeOrGenerate(code, `Text effect: ${input.action}`, options, 'pinepaper_text_effect');
             }
             // ─── 1.6.4: agent surface for the Tier-2 engine features ───
+            case 'pinepaper_look': {
+                const input = LookInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateLook(input), `Look: ${input.action}`, options, 'pinepaper_look');
+            }
+            case 'pinepaper_original_character': {
+                const input = OriginalCharacterInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateOriginalCharacter(input), `Original character: ${input.action}`, options, 'pinepaper_original_character');
+            }
+            case 'pinepaper_morph_sequence': {
+                const input = MorphSequenceInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateMorphSequence(input), `Morph sequence: ${input.states.length} states`, options, 'pinepaper_morph_sequence');
+            }
+            case 'pinepaper_emitter': {
+                const input = EmitterInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateEmitter(input), `Emitter: ${input.action}`, options, 'pinepaper_emitter');
+            }
+            case 'pinepaper_render_hook': {
+                const input = RenderHookInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateRenderHook(input), `Render hook: ${input.action}`, options, 'pinepaper_render_hook');
+            }
+            case 'pinepaper_choreograph': {
+                const input = ChoreographInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateChoreograph(input), `Choreograph: ${input.beats.map((b) => b.verb).join(' → ')}`, options, 'pinepaper_choreograph');
+            }
+            case 'pinepaper_relight': {
+                const input = RelightInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateRelight(input), `Relight: ${input.action}`, options, 'pinepaper_relight');
+            }
+            case 'pinepaper_shader_graph': {
+                const input = ShaderGraphInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateShaderGraph(input), `Shader graph: ${input.action}`, options, 'pinepaper_shader_graph');
+            }
+            case 'pinepaper_styled_scene': {
+                const input = StyledSceneInputSchema.parse(args);
+                return executeOrGenerate(codeGenerator.generateStyledScene(input), `Styled scene${input.style ? `: ${input.style}` : ''}`, options, 'pinepaper_styled_scene');
+            }
+            case 'pinepaper_place_on_surface': {
+                const input = PlaceOnSurfaceInputSchema.parse(args);
+                const code = codeGenerator.generatePlaceOnSurface(input);
+                return executeOrGenerate(code, 'Place a UI onto a screen in a photo', options, 'pinepaper_place_on_surface');
+            }
             case 'pinepaper_brand_kit': {
                 const input = BrandKitInputSchema.parse(args);
                 if (input.action === 'from_url')
@@ -2031,12 +2327,21 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             // RELATION TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_add_relation': {
-                const input = AddRelationInputSchema.parse(args);
-                const code = codeGenerator.generateAddRelation(input);
+                // A relation registered with register_custom_relation this session is
+                // a valid type here (gate D2, 1.6.19: the enum refused the name just
+                // registered). Only those names; an unknown one is still refused.
+                const rt = args.relationType;
+                // The schema's refinements check presence, not which type, so a custom
+                // name is validated with a built-in stand-in and then put back.
+                const isCustom = typeof rt === 'string' && CUSTOM_RELATION_NAMES.has(rt);
+                const input = AddRelationInputSchema.parse(isCustom ? { ...args, relationType: 'orbits' } : args);
+                if (isCustom)
+                    input.relationType = rt;
+                const code = codeGenerator.generateAddRelation(input, isCustom);
                 const description = getLocalizedSuccessMessage(i18n, 'relationAdded', {
                     relationType: input.relationType ?? `preset:${input.presetId}`,
                     sourceId: input.sourceId,
-                    targetId: input.targetId || 'self',
+                    targetId: input.targetId || '(no target)',
                 });
                 return executeOrGenerate(code, description, options, 'pinepaper_add_relation');
             }
@@ -2056,6 +2361,7 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             }
             case 'pinepaper_register_custom_relation': {
                 const input = RegisterCustomRelationInputSchema.parse(args);
+                CUSTOM_RELATION_NAMES.add(input.name);
                 const code = codeGenerator.generateRegisterCustomRelation(input);
                 return executeOrGenerate(code, `Registers custom relation type: ${input.name}`, options, 'pinepaper_register_custom_relation');
             }
@@ -2197,10 +2503,9 @@ async function handleToolCallInner(toolName, args, options, tracker, baseTimerId
             case 'pinepaper_set_canvas_size': {
                 const input = SetCanvasSizeInputSchema.parse(args);
                 const code = codeGenerator.generateSetCanvasSize(input);
-                const description = getLocalizedSuccessMessage(i18n, 'canvasSizeSet', {
-                    width: input.width,
-                    height: input.height,
-                });
+                const description = input.preset && input.width === undefined
+                    ? `Set canvas size to preset ${input.preset}`
+                    : getLocalizedSuccessMessage(i18n, 'canvasSizeSet', { width: input.width ?? '', height: input.height ?? '' });
                 return executeOrGenerate(code, description, options, 'pinepaper_set_canvas_size');
             }
             case 'pinepaper_get_canvas_size': {
@@ -2306,6 +2611,15 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             // -----------------------------------------------------------------------
             case 'pinepaper_add_filter': {
                 const input = AddFilterInputSchema.parse(args);
+                // Out-of-range parameters are refused with the engine's own range
+                // (gate A, 1.6.19: dither levels 99 was accepted and quietly clamped).
+                const ranges = FILTER_PARAM_RANGES[input.filterType] ?? {};
+                for (const [k, v] of Object.entries((input.params ?? {}))) {
+                    const r = ranges[k];
+                    if (r && typeof v === 'number' && (v < r[0] || v > r[1])) {
+                        return errorResult(ErrorCodes.VALIDATION_ERROR, `${input.filterType} ${k} must be ${r[0]}..${r[1]} (got ${v}).`, { filterType: input.filterType, param: k, range: r });
+                    }
+                }
                 const code = codeGenerator.generateAddFilter(input.filterType, input.params);
                 const description = `Adds ${input.filterType} filter to the canvas`;
                 return executeOrGenerate(code, description, options, 'pinepaper_add_filter');
@@ -2516,7 +2830,19 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         const perfTracker = getPerformanceTracker();
                         const recentMetrics = perfTracker.exportMetrics('json', { limit: metricsLimit });
                         const stats = perfTracker.getStats();
-                        metricsSection = { entries: recentMetrics, stats };
+                        // exportMetrics('json') returns a JSON STRING; embedded as-is it reached
+                        // the report as one escaped string, not an array (gate H3).
+                        let entries = recentMetrics;
+                        if (typeof recentMetrics === 'string') {
+                            try {
+                                entries = JSON.parse(recentMetrics);
+                            }
+                            catch { /* keep the string */ }
+                        }
+                        if (entries && typeof entries === 'object' && !Array.isArray(entries) && Array.isArray(entries.metrics)) {
+                            entries = entries.metrics;
+                        }
+                        metricsSection = { entries, stats };
                     }
                     catch { /* metrics not available */ }
                 }
@@ -2571,17 +2897,25 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         },
                         recommendations: [],
                     };
-                    // Add actionable recommendations
+                    // RECOMMEND ONLY WHAT SAVES (gate H4, 1.6.19). This said "switch to
+                    // agent" on full, which saves under 1% (agent omits three small
+                    // tools). Each alternative is measured against the active set and
+                    // offered only when it saves at least 10%, with the saving stated.
                     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`);
+                    const alternatives = [];
+                    for (const v of ['compact', 'minimal']) {
+                        for (const k of ['full', 'agent', 'minimal']) {
+                            if (k === toolkit && v === verbosity)
+                                continue;
+                            const t = Math.ceil(Buffer.byteLength(JSON.stringify(getToolsForToolkit(getToolsForVerbosity(v), k)), 'utf-8') / 4);
+                            alternatives.push({ label: `${k}+${v}`, how: `PINEPAPER_TOOLKIT=${k} PINEPAPER_VERBOSITY=${v}`, tokens: t });
+                        }
                     }
+                    alternatives
+                        .filter((alt) => alt.tokens <= activeTokens * 0.9)
+                        .sort((x, y) => x.tokens - y.tokens)
+                        .slice(0, 3)
+                        .forEach((alt) => recs.push(`${alt.how}: ~${alt.tokens.toLocaleString()} tokens/turn (${Math.round((1 - alt.tokens / activeTokens) * 100)}% less)${alt.label.startsWith('minimal+') ? ' — a small core set; switch profiles at runtime with pinepaper_set_toolkit' : ''}`));
                     if (activeTokens > 20000) {
                         recs.push(`Tool definitions alone consume ~${activeTokens.toLocaleString()} tokens per API turn — this is a major context budget item`);
                     }
@@ -2700,11 +3034,19 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             // ASSET TOOLS
             // -----------------------------------------------------------------------
             case 'pinepaper_search_assets': {
+                // Asked for by name, a removed repository says why rather than failing
+                // the enum check with a bare "invalid option".
+                {
+                    const { REMOVED_REPOSITORIES, REMOVED_REPOSITORY_REASON } = await import('../assets/index.js');
+                    if (typeof args.repository === 'string' && REMOVED_REPOSITORIES.includes(args.repository)) {
+                        return errorResult(ErrorCodes.INVALID_PARAMS, `${REMOVED_REPOSITORY_REASON} Search repository 'all', 'iconify' or 'fontawesome'.`, { repository: args.repository }, { toolName: 'pinepaper_search_assets' });
+                    }
+                }
                 const input = SearchAssetsInputSchema.parse(args);
                 const { getAssetManager } = await import('../assets/index.js');
                 const assetManager = getAssetManager();
                 try {
-                    const results = await assetManager.search(input.query, input.repository || 'all', input.limit || 10);
+                    const { results, sources } = await assetManager.searchWithStatus(input.query, input.repository || 'all', input.limit || 10);
                     // If includeSvgContent is true, fetch SVG content for each result
                     let resultsWithContent = [];
                     if (input.includeSvgContent) {
@@ -2776,6 +3118,7 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                     query: input.query,
                                     repository: input.repository || 'all',
                                     count: resultsWithContent.length,
+                                    sources,
                                     includeSvgContent: input.includeSvgContent || false,
                                     attributionRequired: requiresAttribution.length > 0,
                                     attributionNotice,
@@ -2836,6 +3179,15 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                         svg = body;
                         metadata = { source: 'url', url: input.url };
                     }
+                    // `color` was accepted and never applied, so a recoloured icon
+                    // rendered black (gate D15, 1.6.19). A monochrome icon draws in
+                    // currentColor (stroke sets) or in the default fill (fill sets):
+                    // both take the colour.
+                    if (input.color) {
+                        const c = input.color.replace(/"/g, '');
+                        svg = svg.replace(/currentColor/g, c);
+                        svg = svg.replace(/<svg\b([^>]*)>/i, (m, attrs) => (/\sfill\s*=/.test(attrs) ? m : `<svg${attrs} fill="${c}">`));
+                    }
                     // Import the SVG onto canvas using existing import_svg tool
                     const code = codeGenerator.generateImportSVG(svg, undefined, input.position, input.scale);
                     // A URL import has no catalogue metadata (no title, no licence): this
@@ -2940,11 +3292,20 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                 }
                 const code = codeGenerator.generateAgentStartJob(input);
                 const descriptionText = `Started agent job${input.name ? ` "${input.name}"` : ''} with ${input.screenshotPolicy || 'on_complete'} screenshot policy`;
+                // A STALE STUDIO IS RELOADED HERE, AND ONLY HERE (D92): the canvas is
+                // about to be cleared anyway. The setup below runs on the new page.
+                const gate = await studioJobGate(input, options);
                 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.`;
+                    if (gate.note)
+                        result.content[0].text = `${gate.note}\n\n${result.content[0].text}`;
+                    if (gate.warning)
+                        result.content[0].text = `⚠️ ${gate.warning}\n\n${result.content[0].text}`;
                 }
+                if (gate.build)
+                    result._meta = { ...(result._meta ?? {}), 'pinepaper.studio/build': gate.build };
                 return result;
             }
             case 'pinepaper_agent_end_job': {
@@ -3366,10 +3727,18 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
                                 `Call action 'list_styles' and use one marked composable.`, { style: input.style }, { toolName: 'pinepaper_design_system' });
                         }
                         const ops = designSystems.sceneToOps(scene);
+                        // Some vendored styles lay out at their OWN fixed size and ignore
+                        // width/height (swiss_typographic is always 1280x720), so a caller
+                        // asking for 1080x1080 got a resized canvas (gate run 3). Say so.
+                        const sizeIgnored = (input.width !== undefined && input.width !== scene.width)
+                            || (input.height !== undefined && input.height !== scene.height);
+                        const sizeWarning = sizeIgnored
+                            ? `"${scene.style}" lays out at its own size, ${scene.width}x${scene.height}; the requested ${input.width ?? '?'}x${input.height ?? '?'} was not used`
+                            : undefined;
                         if (input.draw === false) {
-                            return dataResult({ scene, ops, drawn: false });
+                            return dataResult({ scene, ops, drawn: false, ...(sizeWarning ? { warning: sizeWarning } : {}) });
                         }
-                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style);
+                        const code = codeGenerator.generateDesignCompose(scene, ops, scene.style, sizeWarning);
                         return executeOrGenerate(code, `Composed a ${scene.style} scene (${ops.length} items)`, options, 'pinepaper_design_system');
                     }
                 }
@@ -3387,7 +3756,12 @@ You can now start creating new items on a clean canvas.${sizeNote}`,
             case 'pinepaper_interchange': {
                 const input = InterchangeInputSchema.parse(args);
                 const code = codeGenerator.generateInterchange(input);
-                return executeOrGenerate(code, `Interchange: ${input.action}`, options, 'pinepaper_interchange');
+                const out = await executeOrGenerate(code, `Interchange: ${input.action}`, options, 'pinepaper_interchange');
+                // AN EXPORT IS A FILE (gate D7, 1.6.19): .lottie, GLB and the PNG-sequence
+                // zip came back as byte-index objects or inline data URLs, and a Lottie
+                // JSON can be large. Written out; the result names the path.
+                const ext = { export_lottie: 'json', export_dotlottie: 'lottie', export_glb: 'glb', export_png_sequence: 'zip', export_bvh: 'bvh' };
+                return ext[input.action] ? await writeResultDataToFile(out, ext[input.action]) : out;
             }
             case 'pinepaper_sound': {
                 const input = SoundInputSchema.parse(args);