@pascal-app/mcp 1.0.4 → 1.0.6

package/dist/tools/set-zone.js

@@ -1,7 +1,8 @@
-import { newZone } from '@pascal-app/core';
+import { isAllocatedRoomName, newZone, walledRoomAt } from '@pascal-app/core';
+import { roofLevelRefusal } from '@pascal-app/core/agent-operations';
 import { z } from 'zod';
 import { ADDITIVE_TOOL_ANNOTATIONS } from './annotations.js';
-import { ErrorCode, throwMcpError } from './errors.js';
+import { ProtocolErrorCode, refusalResult, throwMcpError } from './errors.js';
 import { liveSyncOutput, persistencePayload, publishLiveSceneSnapshot } from './live-sync.js';
 import { NodeIdSchema, Vec2Schema } from './schemas.js';
 export const setZoneInput = {
@@ -17,30 +18,41 @@ export const setZoneOutput = {
 export function registerSetZone(server, bridge) {
     server.registerTool('set_zone', {
         title: 'Set zone',
-        description: 'Create a polygonal zone on the given level. label is stored as the zone name and properties are merged into metadata.',
-        inputSchema: setZoneInput,
-        outputSchema: setZoneOutput,
+        description: 'Create a polygonal zone on the given level. label is stored as the zone name and properties are merged into metadata. A polygon along walls that already enclose a room is that room, never a second zone: a room still named "Room N", or already named label, takes the label and properties; a room a person named otherwise is refused (rename it with update_node only when the person asked).',
+        inputSchema: z.object(setZoneInput),
+        outputSchema: z.object(setZoneOutput),
         annotations: ADDITIVE_TOOL_ANNOTATIONS,
     }, async ({ levelId, polygon, label, properties }) => {
         const parent = bridge.getNode(levelId);
         if (!parent) {
-            throwMcpError(ErrorCode.InvalidParams, `Level not found: ${levelId}`);
+            throwMcpError(ProtocolErrorCode.InvalidParams, `Level not found: ${levelId}`);
         }
         if (parent.type !== 'level') {
-            throwMcpError(ErrorCode.InvalidParams, `Node ${levelId} is a ${parent.type}, expected level`);
+            throwMcpError(ProtocolErrorCode.InvalidParams, `Node ${levelId} is a ${parent.type}, expected level`);
         }
-        if (typeof parent.metadata === 'object' &&
-            parent.metadata !== null &&
-            'role' in parent.metadata &&
-            parent.metadata.role === 'roof') {
-            throwMcpError(ErrorCode.InvalidParams, `Roof support level ${levelId} is not an occupied story; create zones on an occupied level instead`);
+        const onRoofLevel = roofLevelRefusal(bridge.getNodes(), levelId, 'a zone');
+        if (onRoofLevel)
+            return refusalResult(onRoofLevel);
+        const walled = walledRoomAt(bridge.getNodes(), levelId, polygon);
+        if (walled && !isAllocatedRoomName(walled.name) && walled.name !== label) {
+            throwMcpError(ProtocolErrorCode.InvalidParams, `The walls here already enclose the room "${walled.name}" (${walled.id}), which a person named; a zone "${label}" would stack a second room on it. Rename it with update_node only if the person asked; otherwise leave it.`);
+        }
+        let id;
+        if (walled) {
+            id = walled.id;
+            bridge.updateNode(id, {
+                name: label,
+                metadata: { ...walled.metadata, ...properties },
+            });
+        }
+        else {
+            const zone = newZone({
+                name: label,
+                polygon: polygon,
+                metadata: properties ?? {},
+            });
+            id = bridge.createNode(zone, levelId);
         }
-        const zone = newZone({
-            name: label,
-            polygon: polygon,
-            metadata: properties ?? {},
-        });
-        const id = bridge.createNode(zone, levelId);
         const persistence = await publishLiveSceneSnapshot(bridge, 'set_zone');
         const payload = { zoneId: id, ...persistencePayload(persistence) };
         return {

package/dist/tools/shared-tools.d.ts

@@ -1,6 +1,7 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type AgentOperation, type SceneChanges } from '@pascal-app/core/agent-operations';
-import { type AgentToolAnnotations, type AgentToolContract } from '@pascal-app/core/agent-tools';
+import type { McpServer } from '@modelcontextprotocol/server';
+import { type AddObjectInput, type AgentHostRuntime, type AgentOperation, type AssetViewLoader, type SceneChanges } from '@pascal-app/core/agent-operations';
+import { type AgentToolAnnotations, type AgentToolContract, type DesignBrief } from '@pascal-app/core/agent-tools';
+import { type CompiledGeometryScript } from '@pascal-app/core/schema';
 import { z } from 'zod';
 import type { Patch } from '../bridge/scene-bridge.js';
 import type { SceneOperations } from '../operations/index.js';
@@ -20,11 +21,20 @@ export type OperationTool = {
     /** Reads the host's item library: only these calls wait for it (the hosted one is a query). */
     catalog?: true;
 };
+export type PlanReadingHosts = {
+    /** Reads catalog pictures and surfaces before view_assets and paint. */
+    assetViews?: AssetViewLoader;
+    /** Compiles one add_object module for a batch before the synchronous operations run. */
+    buildObject?: (input: Omit<AddObjectInput, 'compiled'>) => Promise<CompiledGeometryScript>;
+};
 export declare function toPatches(changes: SceneChanges): Patch[];
-export declare function registerSharedTools(server: McpServer, bridge: SceneOperations, catalog?: AssetCatalog): void;
+/** How an outcome reaches this bridge: its patches, its derived construction, its session record. */
+export declare function agentRuntime(bridge: SceneOperations): AgentHostRuntime;
+export declare function briefInForce(bridge: SceneOperations): DesignBrief | null | undefined;
+export declare function registerSharedTools(server: McpServer, bridge: SceneOperations, catalog?: AssetCatalog, hosts?: PlanReadingHosts): void;
 /**
  * Registers one operation tool, as the shared tools are: a host adds a plugin's `'operation'`
  * tools with it, from the plugin's `./agent-tools` contract and `./agent-operations` operation.
  */
-export declare function registerOperationTool(server: McpServer, bridge: SceneOperations, tool: OperationTool, catalog?: AssetCatalog): void;
+export declare function registerOperationTool(server: McpServer, bridge: SceneOperations, tool: OperationTool, catalog?: AssetCatalog, hosts?: PlanReadingHosts): void;
 //# sourceMappingURL=shared-tools.d.ts.map

package/dist/tools/shared-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-tools.d.ts","sourceRoot":"","sources":["../../src/tools/shared-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,EAGL,KAAK,cAAc,EAGnB,KAAK,YAAY,EAElB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAsBvB,MAAM,8BAA8B,CAAA;AAOrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAMpD,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,iBAAiB,CAAA;AASnE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,SAAS,EAAE,cAAc,CAAA;IACzB,WAAW,EAAE,oBAAoB,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/D,+FAA+F;IAC/F,OAAO,CAAC,EAAE,IAAI,CAAA;CACf,CAAA;AAmRD,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,EAAE,CAmBxD;AAUD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,YAA6B,GACrC,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,YAA6B,GACrC,IAAI,CAkEN"}
+{"version":3,"file":"shared-tools.d.ts","sourceRoot":"","sources":["../../src/tools/shared-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EAUpB,KAAK,YAAY,EAGlB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAStB,KAAK,WAAW,EA+BjB,MAAM,8BAA8B,CAAA;AAErC,OAAO,EAGL,KAAK,sBAAsB,EAG5B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAMpD,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,iBAAiB,CAAA;AASnE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,SAAS,EAAE,cAAc,CAAA;IACzB,WAAW,EAAE,oBAAoB,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/D,+FAA+F;IAC/F,OAAO,CAAC,EAAE,IAAI,CAAA;CACf,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wEAAwE;IACxE,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B,wFAAwF;IACxF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAA;CAC3F,CAAA;AAmaD,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,EAAE,CAmBxD;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAsBtE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,GAAG,SAAS,CAIpF;AAUD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,YAA6B,EACtC,KAAK,GAAE,gBAAqB,GAC3B,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,YAA6B,EACtC,KAAK,GAAE,gBAAqB,GAC3B,IAAI,CAuHN"}

package/dist/tools/shared-tools.js

@@ -1,5 +1,6 @@
-import { AGENT_OPERATIONS, achievedChanges, applyAgentOutcome, writeCollections, } from '@pascal-app/core/agent-operations';
-import { addLevelTool, addWallTool, createRoomTool, createStairTool, deleteNodeTool, duplicateLevelTool, findByTypeTool, fitStairTool, furnishRoomTool, getLevelSummaryTool, getNodeTool, getWallsTool, getZonesTool, listLevelsTool, measureStairTool, paintTool, placeItemsTool, ROOM_TOOL_CONTRACTS, searchAssetsTool, searchMaterialsTool, verifySceneTool, } from '@pascal-app/core/agent-tools';
+import { AGENT_OPERATIONS, achievedChanges, applyAgentOutcome, assetViewNeeds, assetViewsReadCatalog, briefReadsCatalog, buildBatchObjects, createAssetViewLoader, createFetchAssetViewIO, furnishingRefusal, startOfSession, writeCollections, } from '@pascal-app/core/agent-operations';
+import { addCornerWindowTool, addFenceTool, addLevelTool, addObjectTool, addWallTool, createRoofTool, createRoomTool, createStairTool, deleteNodeTool, designBriefTool, duplicateLevelTool, findByTypeTool, fitStairTool, furnishRoomTool, getLevelSummaryTool, getNodeTool, getSiteTool, getWallsTool, getZonesTool, listLevelsTool, measureStairTool, mergeWindowsTool, moveRoofsToRoofLevelTool, paintTool, placeBuildingTool, placeDesignTool, placeInRoomTool, placeItemsTool, ROOM_TOOL_CONTRACTS, refuse, runBatchTool, searchAssetsTool, searchMaterialsTool, setCheckpointTool, setGroundLevelTool, validateDesignTool, verifySceneTool, viewAssetsTool, } from '@pascal-app/core/agent-tools';
+import { DesignValidationSchema } from '@pascal-app/core/procedural-items';
 import { MaterialSchema, SceneMaterial, } from '@pascal-app/core/schema';
 import { z } from 'zod';
 import { ADDITIVE_TOOL_ANNOTATIONS, DESTRUCTIVE_TOOL_ANNOTATIONS, READ_ONLY_TOOL_ANNOTATIONS, } from './annotations.js';
@@ -8,7 +9,11 @@ import { registerCollectionTools } from './collections.js';
 import { refusalResult } from './errors.js';
 import { liveSyncOutput, persistencePayload, publishLiveSceneSnapshot } from './live-sync.js';
 import { ROOM_TOOL_ANNOTATIONS, structureOutput } from './structure-tools.js';
+const defaultAssetViews = createAssetViewLoader(createFetchAssetViewIO());
 const jsonObject = z.record(z.string(), z.unknown());
+function refuseScripts() {
+    refuse('scripts_unavailable', 'This Pascal server cannot run geometry scripts.');
+}
 /** What the scene holds after a mutating call (core achievedChanges). */
 const achievedOutput = {
     achieved: z
@@ -31,6 +36,23 @@ const levelRoleOutput = {
     referenceLevelId: z.string().nullable(),
 };
 const SHARED_TOOLS = [
+    {
+        contract: validateDesignTool,
+        operation: AGENT_OPERATIONS.validate_design,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        outputSchema: DesignValidationSchema.shape,
+    },
+    {
+        contract: placeDesignTool,
+        operation: AGENT_OPERATIONS.place_design,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+        outputSchema: {
+            designId: z.string(),
+            parentId: z.string(),
+            surfaceId: z.string().nullable(),
+            ...liveSyncOutput,
+        },
+    },
     {
         contract: measureStairTool,
         operation: AGENT_OPERATIONS.measure_stair,
@@ -67,7 +89,12 @@ const SHARED_TOOLS = [
         contract: getNodeTool,
         operation: AGENT_OPERATIONS.get_node,
         annotations: READ_ONLY_TOOL_ANNOTATIONS,
-        outputSchema: { node: jsonObject, materials: z.record(z.string(), SceneMaterial).optional() },
+        outputSchema: {
+            node: jsonObject,
+            ancestorIds: z.array(z.string()),
+            missingChildIds: z.array(z.string()).optional(),
+            materials: z.record(z.string(), SceneMaterial).optional(),
+        },
     },
     {
         contract: getLevelSummaryTool,
@@ -117,6 +144,24 @@ const SHARED_TOOLS = [
             ...liveSyncOutput,
         },
     },
+    {
+        contract: setGroundLevelTool,
+        operation: AGENT_OPERATIONS.set_ground_level,
+        annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+        outputSchema: {
+            ok: z.boolean(),
+            levelId: z.string(),
+            buildingId: z.string(),
+            floorElevation: z.number(),
+            gradeElevation: z.number().optional(),
+            movedBuildingBy: z.number().optional(),
+            renumbered: z.boolean().optional(),
+            unchanged: z.boolean().optional(),
+            message: z.string(),
+            ...achievedOutput,
+            ...liveSyncOutput,
+        },
+    },
     {
         contract: verifySceneTool,
         operation: AGENT_OPERATIONS.verify_scene,
@@ -132,17 +177,33 @@ const SHARED_TOOLS = [
             activeLevelId: z.string().nullable(),
             levels: z.array(jsonObject),
             emptyLevelIds: z.array(z.string()),
-            issues: z.array(z.object({
+            // Typed by `type`; a check registered with verify_scene may add fields of its own.
+            issues: z.array(z.looseObject({
                 type: z.string(),
                 message: z.string(),
                 severity: z.literal('info').optional(),
+                nodeId: z.string().optional(),
+                path: z.string().optional(),
+                zoneId: z.string().optional(),
+                wallIds: z.array(z.string()).optional(),
+                area: z.number().optional(),
+                at: z.tuple([z.number(), z.number()]).optional(),
                 wallId: z.string().optional(),
+                slabId: z.string().optional(),
+                levelId: z.string().optional(),
+                wallTop: z.number().optional(),
+                slabUnderside: z.number().optional(),
+                slabTop: z.number().optional(),
+                penetration: z.number().optional(),
+                coplanar: z.boolean().optional(),
                 end: z.enum(['start', 'end']).optional(),
                 reason: z.enum(['gap', 'crosses', 'parallel', 'rejected']).optional(),
                 gap: z.number().optional(),
                 nearestWallId: z.string().optional(),
             })),
             hasIssues: z.boolean(),
+            checkpoints: z.array(z.string()).optional(),
+            since: jsonObject.optional(),
             authoredObjects: z
                 .array(z.object({
                 id: z.string(),
@@ -154,11 +215,36 @@ const SHARED_TOOLS = [
         },
         envelope: (bridge) => ({ activeSceneId: bridge.getActiveScene()?.id ?? null }),
     },
+    {
+        contract: setCheckpointTool,
+        operation: AGENT_OPERATIONS.set_checkpoint,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+    },
+    {
+        contract: designBriefTool,
+        operation: AGENT_OPERATIONS.design_brief,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+    },
     {
         contract: addWallTool,
         operation: AGENT_OPERATIONS.add_wall,
         annotations: ADDITIVE_TOOL_ANNOTATIONS,
     },
+    {
+        contract: addFenceTool,
+        operation: AGENT_OPERATIONS.add_fence,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+    },
+    {
+        contract: addCornerWindowTool,
+        operation: AGENT_OPERATIONS.add_corner_window,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+    },
+    {
+        contract: mergeWindowsTool,
+        operation: AGENT_OPERATIONS.merge_windows,
+        annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+    },
     {
         contract: addLevelTool,
         operation: AGENT_OPERATIONS.add_level,
@@ -169,6 +255,16 @@ const SHARED_TOOLS = [
         operation: AGENT_OPERATIONS.create_stair,
         annotations: ADDITIVE_TOOL_ANNOTATIONS,
     },
+    {
+        contract: createRoofTool,
+        operation: AGENT_OPERATIONS.create_roof,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+    },
+    {
+        contract: moveRoofsToRoofLevelTool,
+        operation: AGENT_OPERATIONS.move_roofs_to_roof_level,
+        annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+    },
     {
         contract: placeItemsTool,
         operation: AGENT_OPERATIONS.place_items,
@@ -227,12 +323,6 @@ const SHARED_TOOLS = [
             ...liveSyncOutput,
         },
     },
-    {
-        contract: searchAssetsTool,
-        operation: AGENT_OPERATIONS.search_assets,
-        annotations: READ_ONLY_TOOL_ANNOTATIONS,
-        catalog: true,
-    },
     {
         contract: paintTool,
         operation: AGENT_OPERATIONS.paint,
@@ -249,6 +339,54 @@ const SHARED_TOOLS = [
             ...liveSyncOutput,
         },
     },
+    {
+        contract: placeInRoomTool,
+        operation: AGENT_OPERATIONS.place_in_room,
+        annotations: ADDITIVE_TOOL_ANNOTATIONS,
+        catalog: true,
+        outputSchema: {
+            ok: z.literal(true),
+            itemId: z.string(),
+            kind: z.string(),
+            placed: z.object({ position: z.array(z.number()), rotationDeg: z.number() }),
+            against: z.object({ edge: z.number(), wall: z.string() }).optional(),
+            around: z.string().optional(),
+            facing: z.string().optional(),
+            message: z.string(),
+            ...achievedOutput,
+            ...liveSyncOutput,
+        },
+    },
+    {
+        contract: getSiteTool,
+        operation: AGENT_OPERATIONS.get_site,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    },
+    {
+        contract: placeBuildingTool,
+        operation: AGENT_OPERATIONS.place_building,
+        annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+        outputSchema: {
+            buildingId: z.string(),
+            moved: z.boolean(),
+            fit: z.enum(['buildable', 'lot', 'outside']),
+            message: z.string(),
+            ...achievedOutput,
+            ...liveSyncOutput,
+        },
+    },
+    {
+        contract: searchAssetsTool,
+        operation: AGENT_OPERATIONS.search_assets,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        catalog: true,
+    },
+    {
+        contract: viewAssetsTool,
+        operation: AGENT_OPERATIONS.view_assets,
+        annotations: READ_ONLY_TOOL_ANNOTATIONS,
+        catalog: true,
+    },
     {
         contract: searchMaterialsTool,
         operation: AGENT_OPERATIONS.search_materials,
@@ -263,6 +401,11 @@ const SHARED_TOOLS = [
             outputSchema: { ...structureOutput, ...achievedOutput },
         };
     }),
+    {
+        contract: runBatchTool,
+        operation: AGENT_OPERATIONS.run_batch,
+        annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
+    },
 ];
 export function toPatches(changes) {
     return [
@@ -284,25 +427,51 @@ export function toPatches(changes) {
         })),
     ];
 }
+/** How an outcome reaches this bridge: its patches, its derived construction, its session record. */
+export function agentRuntime(bridge) {
+    return {
+        getNodes: () => bridge.getNodes(),
+        applyChanges: (changes) => {
+            if (changes.materials?.length &&
+                (bridge.supportsMaterialUpserts !== true || bridge.getMaterials?.() === undefined))
+                refuse('materials_unavailable', 'This host cannot atomically persist native materials; nothing was painted.');
+            const next = toPatches(changes);
+            if (next.length)
+                bridge.applyPatch(next);
+            if (changes.collections && Object.keys(changes.collections).length)
+                bridge.setCollections(writeCollections(bridge.getCollections(), changes.collections));
+        },
+        reconcile: () => {
+            bridge.deriveStructure();
+        },
+        keep: (keep) => bridge.agentSession?.keep(keep),
+    };
+}
+export function briefInForce(bridge) {
+    if (bridge.designBriefRequired === false)
+        return undefined;
+    const session = bridge.agentSession;
+    return session ? (session.read().designBrief ?? null) : undefined;
+}
 function writesScene(changes) {
     return Boolean(changes &&
         (toPatches(changes).length ||
             (changes.collections && Object.keys(changes.collections).length)));
 }
-export function registerSharedTools(server, bridge, catalog = builtInCatalog) {
+export function registerSharedTools(server, bridge, catalog = builtInCatalog, hosts = {}) {
     for (const tool of SHARED_TOOLS)
-        registerOperationTool(server, bridge, tool, catalog);
+        registerOperationTool(server, bridge, tool, catalog, hosts);
     registerCollectionTools(server, bridge);
 }
 /**
  * Registers one operation tool, as the shared tools are: a host adds a plugin's `'operation'`
  * tools with it, from the plugin's `./agent-tools` contract and `./agent-operations` operation.
  */
-export function registerOperationTool(server, bridge, tool, catalog = builtInCatalog) {
+export function registerOperationTool(server, bridge, tool, catalog = builtInCatalog, hosts = {}) {
     server.registerTool(tool.contract.name, {
         title: tool.contract.title,
         description: tool.contract.description,
-        inputSchema: tool.contract.input,
+        inputSchema: z.object(tool.contract.input),
         // Loose: a client that listed the tools rejects any field the schema leaves out, and the
         // operations in core grow fields (verify_scene's guesses) that this list would miss.
         ...(tool.outputSchema ? { outputSchema: z.looseObject(tool.outputSchema) } : {}),
@@ -312,13 +481,50 @@ export function registerOperationTool(server, bridge, tool, catalog = builtInCat
         // A copy of the map: a host may write its own in place (the hosted bridge does), and a
         // "before" that grows with the call reads every creation as unchanged.
         const before = { ...bridge.getNodes() };
+        // The agent's session begins with its first call, before anything is written.
+        const first = bridge.agentSession && startOfSession(bridge.agentSession.read(), before);
+        if (first)
+            bridge.agentSession?.keep(first);
+        // Gate before catalog I/O or module compilation.
+        const designBrief = briefInForce(bridge);
+        if (designBrief !== undefined) {
+            const refusal = furnishingRefusal(tool.contract.name, input, designBrief);
+            if (refusal)
+                return refusalResult(refusal);
+        }
+        const batchPlacesInRoom = tool.contract.name === runBatchTool.name &&
+            Array.isArray(input.calls) &&
+            input.calls.some((call) => typeof call === 'object' &&
+                call !== null &&
+                'tool' in call &&
+                call.tool === placeInRoomTool.name);
+        const batchesObjects = tool.contract.name === runBatchTool.name &&
+            Array.isArray(input.calls) &&
+            input.calls.some((call) => typeof call === 'object' &&
+                call !== null &&
+                'tool' in call &&
+                call.tool === addObjectTool.name);
         const context = {
-            activeLevelId: null,
-            ...(tool.catalog && { catalog: await catalog() }),
+            activeLevelId: bridge.activeLevelId?.() ?? null,
             ...(bridge.supportsMaterialUpserts && bridge.getMaterials
                 ? { materials: bridge.getMaterials() }
                 : {}),
+            ...(bridge.nodeSchema && { nodeSchema: (kind) => bridge.nodeSchema(kind) }),
+            session: bridge.agentSession?.read(),
+            ...(designBrief !== undefined && { designBrief }),
+            ...((tool.catalog ||
+                batchPlacesInRoom ||
+                assetViewsReadCatalog(tool.contract.name, input) ||
+                briefReadsCatalog(tool.contract.name, input)) && { catalog: await catalog() }),
+            ...(batchesObjects && {
+                batchObjects: await buildBatchObjects(input.calls, hosts.buildObject ?? refuseScripts),
+            }),
         };
+        const needs = assetViewNeeds(before, tool.contract.name, input, context);
+        if (needs.subjects.length)
+            context.assetViews = await (hosts.assetViews ?? defaultAssetViews)(needs.subjects, {
+                pictures: needs.pictures,
+            });
         try {
             outcome = tool.operation(before, input, context);
         }
@@ -330,21 +536,13 @@ export function registerOperationTool(server, bridge, tool, catalog = builtInCat
         // An outcome edits the scene through its node changes, its collection writes, or the
         // follow-up it plans once the host has reconciled; any of them is one history step.
         if (writesScene(outcome.changes) || outcome.afterReconcile) {
-            result = bridge.runAsSingleHistoryStep(() => applyAgentOutcome(outcome, {
-                getNodes: () => bridge.getNodes(),
-                applyChanges: (changes) => {
-                    const next = toPatches(changes);
-                    if (next.length)
-                        bridge.applyPatch(next);
-                    if (changes.collections && Object.keys(changes.collections).length)
-                        bridge.setCollections(writeCollections(bridge.getCollections(), changes.collections));
-                },
-                reconcile: () => {
-                    bridge.deriveStructure();
-                },
-            }));
+            result = bridge.runAsSingleHistoryStep(() => applyAgentOutcome(outcome, agentRuntime(bridge)));
             persistence = persistencePayload(await publishLiveSceneSnapshot(bridge, tool.contract.name));
         }
+        else if (outcome.keep) {
+            // A checkpoint: kept with the session, nothing in the scene to save.
+            result = applyAgentOutcome(outcome, agentRuntime(bridge));
+        }
         // What the scene holds after the call, not only what the call says it built.
         const achieved = outcome.changes ? achievedChanges(before, outcome.changes) : null;
         const payload = {
@@ -353,6 +551,21 @@ export function registerOperationTool(server, bridge, tool, catalog = builtInCat
             ...(tool.envelope?.(bridge) ?? {}),
             ...persistence,
         };
+        const { previews, ...shown } = payload;
+        const pictures = (Array.isArray(previews) ? previews : []).flatMap(({ label, image }) => {
+            const [, mimeType, data] = /^data:(image\/[\w.+-]+);base64,(.+)$/.exec(image) ?? [];
+            return mimeType && data
+                ? [
+                    { type: 'text', text: label },
+                    { type: 'image', data, mimeType },
+                ]
+                : [];
+        });
+        if (pictures.length)
+            return {
+                content: [{ type: 'text', text: JSON.stringify(shown) }, ...pictures],
+                structuredContent: shown,
+            };
         return {
             content: [{ type: 'text', text: JSON.stringify(payload) }],
             structuredContent: payload,

package/dist/tools/structure-tools.d.ts

@@ -8,8 +8,8 @@ export declare const structureOutput: {
     unsaved: z.ZodOptional<z.ZodString>;
     persistence: z.ZodOptional<z.ZodObject<{
         status: z.ZodEnum<{
-            unbound: "unbound";
             events_unsupported: "events_unsupported";
+            unbound: "unbound";
         }>;
         warning: z.ZodString;
     }, z.core.$strip>>;
@@ -31,9 +31,9 @@ export declare const structureOutput: {
         zoneId: z.ZodString;
         name: z.ZodString;
         mode: z.ZodEnum<{
-            merge: "merge";
-            delete: "delete";
             blocked: "blocked";
+            delete: "delete";
+            merge: "merge";
         }>;
         mergedIntoZoneId: z.ZodOptional<z.ZodString>;
         contents: z.ZodEnum<{

package/dist/tools/templates/create-from-template.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import type { SceneOperations } from '../../operations/index.js';
 export declare const createFromTemplateInput: {
@@ -36,8 +36,8 @@ export declare const createFromTemplateOutput: {
         published: z.ZodBoolean;
         isDraft: z.ZodBoolean;
         saveMode: z.ZodEnum<{
-            draft: "draft";
             checkpoint: "checkpoint";
+            draft: "draft";
         }>;
         graphHash: z.ZodOptional<z.ZodString>;
         levelIds: z.ZodArray<z.ZodString>;

package/dist/tools/templates/create-from-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-from-template.d.ts","sourceRoot":"","sources":["../../../src/tools/templates/create-from-template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOvD,eAAO,MAAM,uBAAuB;;;IAYlC;;;;;OAKG;;;CAGJ,CAAA;AAED,eAAO,MAAM,wBAAwB;;;;IAInC,yEAAyE;;IAEzE,6DAA6D;;;;;;;;;;;;;;;;;;;;;;;;CAuB9D,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA+F3F"}
+{"version":3,"file":"create-from-template.d.ts","sourceRoot":"","sources":["../../../src/tools/templates/create-from-template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAG7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOvD,eAAO,MAAM,uBAAuB;IAClC,EAAE;IAKF,IAAI;IAMJ;;;;;OAKG;IACH,IAAI;IACJ,SAAS;CACV,CAAA;AAED,eAAO,MAAM,wBAAwB;IACnC,UAAU;IACV,WAAW;IACX,SAAS;IACT,yEAAyE;IACzE,WAAW;IACX,6DAA6D;IAC7D,KAAK;;;;;;;;;;;;;;;;;;;;;;;CAsBN,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA+F3F"}

package/dist/tools/templates/create-from-template.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { rehydrateSiteChildren } from '../../lib/rehydrate-site-children.js';
 import { isTemplateId, TEMPLATES } from '../../templates/index.js';
 import { DESTRUCTIVE_TOOL_ANNOTATIONS } from '../annotations.js';
-import { ErrorCode, throwMcpError } from '../errors.js';
+import { ProtocolErrorCode, throwMcpError } from '../errors.js';
 import { appendLiveSceneEvent } from '../live-sync.js';
 import { currentLevelContext, sceneMetaPayload } from '../scene-lifecycle/metadata.js';
 export const createFromTemplateInput = {
@@ -67,12 +67,12 @@ export function registerCreateFromTemplate(server, bridge) {
     server.registerTool('create_from_template', {
         title: 'Create scene from template',
         description: 'Instantiate a seed Pascal scene template into the bridge. Regenerates all ids before applying. When `save: true` and a SceneStore is wired, also persists the new scene and returns the SceneMeta.',
-        inputSchema: createFromTemplateInput,
-        outputSchema: createFromTemplateOutput,
+        inputSchema: z.object(createFromTemplateInput),
+        outputSchema: z.object(createFromTemplateOutput),
         annotations: DESTRUCTIVE_TOOL_ANNOTATIONS,
     }, async ({ id, name, save, projectId }) => {
         if (!isTemplateId(id)) {
-            throwMcpError(ErrorCode.InvalidParams, `unknown_template: ${id}. Call list_templates for the set of valid ids.`);
+            throwMcpError(ProtocolErrorCode.InvalidParams, `unknown_template: ${id}. Call list_templates for the set of valid ids.`);
         }
         const entry = TEMPLATES[id];
         // Clone: regenerate ids so each instantiation is independent.
@@ -87,7 +87,7 @@ export function registerCreateFromTemplate(server, bridge) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            throwMcpError(ErrorCode.InternalError, `apply_failed: ${msg}`);
+            throwMcpError(ProtocolErrorCode.InternalError, `apply_failed: ${msg}`);
         }
         const basePayload = {
             templateId: entry.id,
@@ -143,7 +143,7 @@ export function registerCreateFromTemplate(server, bridge) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            throwMcpError(ErrorCode.InternalError, `save_failed: ${msg}`);
+            throwMcpError(ProtocolErrorCode.InternalError, `save_failed: ${msg}`);
         }
     });
 }

package/dist/tools/templates/create-house-from-brief.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import type { SceneOperations } from '../../operations/index.js';
 export declare const createHouseFromBriefInput: {

package/dist/tools/templates/create-house-from-brief.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-house-from-brief.d.ts","sourceRoot":"","sources":["../../../src/tools/templates/create-house-from-brief.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOvD,eAAO,MAAM,yBAAyB;;;;;;;;;CASrC,CAAA;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;CAmBtC,CAAA;AAmCD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAsI7F"}
+{"version":3,"file":"create-house-from-brief.d.ts","sourceRoot":"","sources":["../../../src/tools/templates/create-house-from-brief.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAG7D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOvD,eAAO,MAAM,yBAAyB;IACpC,KAAK;IACL,SAAS;IACT,WAAW;IACX,YAAY;IACZ,KAAK;IACL,KAAK;IACL,WAAW;IACX,WAAW;CACZ,CAAA;AAED,eAAO,MAAM,0BAA0B;IACrC,SAAS;IACT,SAAS;IACT,GAAG;IACH,OAAO;IACP,SAAS;IACT,OAAO;IACP,UAAU;IACV,SAAS;IACT,SAAS;IACT,QAAQ;IACR,cAAc;IACd,UAAU;;;;IAIV,OAAO;IACP,WAAW;IACX,QAAQ;CACT,CAAA;AAmCD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAsI7F"}