@pascal-app/mcp 1.0.3 → 1.0.5

package/dist/lib/safe-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../src/lib/safe-fetch.ts"],"names":[],"mappings":"AAkHA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA6F1B"}
+{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../../src/lib/safe-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAExE,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AA2GpD,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAYzD;AAkDD,MAAM,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;AA2BrE,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,cAAc,CAcvE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAA;AAqBvF,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAA;AAOrE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAOD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAAqB,EAC3B,IAAI,GAAE,aAA2B,GAChC,OAAO,CAAC,eAAe,CAAC,CAwE1B"}

package/dist/lib/safe-fetch.js

@@ -1,83 +1,150 @@
-import { isIPv4, isIPv6 } from 'node:net';
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { ProtocolError, ProtocolErrorCode } from '@modelcontextprotocol/server';
 /**
  * SSRF-safe fetch for user-supplied URLs (image URLs in vision tools).
  *
- * Blocks the usual server-side-request-forgery attack surface:
- * - loopback (127.0.0.0/8, ::1)
- * - link-local (169.254.0.0/16 — includes cloud metadata at 169.254.169.254)
- * - private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7)
- * - non-http(s) schemes
- * - manual-redirect with the same allowlist applied to each hop
- * - max body size (default 20 MB)
- * - request timeout (default 10 s)
+ * Every hop (the initial URL and each redirect target) is checked the same way:
+ * - only http(s) schemes
+ * - well-known local hostnames are refused outright
+ * - the host is resolved once and *every* resolved address must be public;
+ *   IPv6 forms that embed an IPv4 address (mapped, compatible, 6to4) are
+ *   judged by the embedded address
+ * - the socket connects only to the addresses that were checked, so a DNS
+ *   answer that changes between check and connect cannot reach a private host
+ * - optional origin allowlist via `PASCAL_ALLOWED_ASSET_ORIGINS` (comma-separated)
+ * - max body size (default 20 MB) and request timeout (default 10 s)
  *
- * Optional allowlist via `PASCAL_ALLOWED_ASSET_ORIGINS` env var (comma-separated).
- *
- * Phase 10 A2 found that photo_to_scene / analyze_floorplan_image /
- * analyze_room_photo all called raw `fetch(url)` with no protection, giving
- * a direct `169.254.169.254` exfil primitive on any host.
+ * Used by photo_to_scene / analyze_floorplan_image / analyze_room_photo.
  */
 const DEFAULT_MAX_BYTES = 20 * 1024 * 1024; // 20 MB
 const DEFAULT_TIMEOUT_MS = 10_000;
 const MAX_REDIRECTS = 3;
-function isPrivateOrLoopbackV4(addr) {
-    const parts = addr.split('.').map(Number);
-    if (parts.length !== 4 || parts.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
-        return true; // malformed → treat as unsafe
-    const [a, b] = parts;
-    if (a === 127)
-        return true; // 127.0.0.0/8 loopback
+function parseIPv4(addr) {
+    const parts = addr.split('.');
+    if (parts.length !== 4 || parts.some((p) => !/^\d{1,3}$/.test(p)))
+        return null;
+    const octets = parts.map(Number);
+    return octets.every((n) => n <= 255) ? octets : null;
+}
+/** Expands any valid IPv6 text form (incl. `::` and a dotted IPv4 tail) to 8 groups. */
+function parseIPv6(addr) {
+    let s = addr.toLowerCase();
+    const zone = s.indexOf('%');
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    let tail = [];
+    const lastColon = s.lastIndexOf(':');
+    if (lastColon < 0)
+        return null;
+    if (s.slice(lastColon + 1).includes('.')) {
+        const v4 = parseIPv4(s.slice(lastColon + 1));
+        if (!v4)
+            return null;
+        tail = [(v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]];
+        const prefix = s.slice(0, lastColon + 1);
+        s = prefix.endsWith('::') ? prefix : prefix.slice(0, -1);
+    }
+    const halves = s.split('::');
+    if (halves.length > 2)
+        return null;
+    const groups = (part) => part === ''
+        ? []
+        : part.split(':').map((h) => (/^[0-9a-f]{1,4}$/.test(h) ? parseInt(h, 16) : NaN));
+    const head = groups(halves[0]);
+    const rest = halves.length === 2 ? groups(halves[1]) : [];
+    const explicit = head.length + rest.length + tail.length;
+    if ([...head, ...rest].some(Number.isNaN))
+        return null;
+    if (halves.length === 1)
+        return explicit === 8 ? [...head, ...tail] : null;
+    if (explicit > 7)
+        return null;
+    return [...head, ...new Array(8 - explicit).fill(0), ...rest, ...tail];
+}
+function isBlockedV4([a, b]) {
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network"
     if (a === 10)
         return true; // 10.0.0.0/8 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT (incl. Alibaba metadata)
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (cloud metadata)
     if (a === 172 && b >= 16 && b <= 31)
         return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 0)
+        return true; // 192.0.0.0/24 IETF protocol assignments
     if (a === 192 && b === 168)
         return true; // 192.168.0.0/16 private
-    if (a === 169 && b === 254)
-        return true; // link-local incl. cloud metadata
-    if (a === 0)
-        return true; // current-network
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmarking
     if (a >= 224)
-        return true; // multicast / reserved
+        return true; // multicast, reserved, broadcast
     return false;
 }
-function isPrivateOrLoopbackV6(addr) {
-    const lower = addr.toLowerCase();
-    if (lower === '::1' || lower === '::')
-        return true;
-    if (lower.startsWith('fe80:') ||
-        lower.startsWith('fe90:') ||
-        lower.startsWith('fea0:') ||
-        lower.startsWith('feb0:'))
-        return true; // link-local
-    if (lower.startsWith('fc') || lower.startsWith('fd'))
-        return true; // ULA fc00::/7
-    if (lower.startsWith('::ffff:')) {
-        // v4-mapped
-        const v4 = lower.slice(7);
-        if (isIPv4(v4))
-            return isPrivateOrLoopbackV4(v4);
+function embeddedV4(hi, lo) {
+    return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
+}
+function isBlockedV6(g) {
+    const [g0, g1, g2, g3, g4, g5, g6, g7] = g;
+    const first4Zero = g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0;
+    // ::/96 (unspecified, loopback, IPv4-compatible), ::ffff:0:0/96 (mapped),
+    // ::ffff:0:0:0/96 (translated) — judge by the embedded IPv4 address.
+    if (first4Zero && ((g4 === 0 && (g5 === 0 || g5 === 0xffff)) || (g4 === 0xffff && g5 === 0))) {
+        return isBlockedV4(embeddedV4(g6, g7));
     }
+    if (g0 === 0x64 && g1 === 0xff9b)
+        return true; // 64:ff9b::/96 and 64:ff9b:1::/48 NAT64
+    if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0)
+        return true; // 100::/64 discard
+    if (g0 === 0x2001 && g1 === 0)
+        return true; // 2001::/32 Teredo
+    if (g0 === 0x2002)
+        return isBlockedV4(embeddedV4(g1, g2)); // 2002::/16 6to4
+    if ((g0 & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 ULA (incl. fd00:ec2::254 metadata)
+    if ((g0 & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((g0 & 0xffc0) === 0xfec0)
+        return true; // fec0::/10 site-local
+    if ((g0 & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
     return false;
 }
-function isUnsafeHost(hostname) {
-    const host = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets if any
-    if (isIPv4(host))
-        return isPrivateOrLoopbackV4(host);
-    if (isIPv6(host))
-        return isPrivateOrLoopbackV6(host);
-    // Hostname (not IP) — block well-known local names.
-    const lower = host.toLowerCase();
-    if (lower === 'localhost' ||
+/** True for any address a server-side fetch must not reach. Unparseable input is blocked. */
+export function isBlockedAddress(address) {
+    const literal = address.replace(/^\[|\]$/g, '');
+    const family = isIP(literal);
+    if (family === 4) {
+        const v4 = parseIPv4(literal);
+        return v4 ? isBlockedV4(v4) : true;
+    }
+    if (family === 6) {
+        const v6 = parseIPv6(literal);
+        return v6 ? isBlockedV6(v6) : true;
+    }
+    return true;
+}
+function isLocalHostname(hostname) {
+    const lower = hostname.toLowerCase().replace(/\.+$/, '');
+    return (lower === 'localhost' ||
         lower.endsWith('.localhost') ||
         lower === 'broadcasthost' ||
         lower.endsWith('.local') ||
         lower.endsWith('.internal') ||
-        lower.endsWith('.corp')) {
-        return true;
-    }
-    return false;
+        lower.endsWith('.corp'));
+}
+function blocked(reason, details, log = {}) {
+    console.error(`[pascal-mcp] safe_fetch_blocked ${JSON.stringify({ reason, ...details, ...log })}`);
+    return protocolError(reason, details);
+}
+function protocolError(reason, details) {
+    throw new ProtocolError(ProtocolErrorCode.InvalidParams, reason, details);
 }
 function assertAllowedUrl(url) {
     let parsed;
@@ -85,21 +152,11 @@ function assertAllowedUrl(url) {
         parsed = new URL(url);
     }
     catch {
-        throw new McpError(ErrorCode.InvalidParams, 'invalid_url', { url });
+        return protocolError('invalid_url', { url });
     }
     if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-        throw new McpError(ErrorCode.InvalidParams, 'url_scheme_not_allowed', {
-            url,
-            protocol: parsed.protocol,
-        });
+        blocked('url_scheme_not_allowed', { url, protocol: parsed.protocol });
     }
-    if (isUnsafeHost(parsed.hostname)) {
-        throw new McpError(ErrorCode.InvalidParams, 'url_host_blocked', {
-            url,
-            hostname: parsed.hostname,
-        });
-    }
-    // Optional env-allowlist narrowing.
     const allowEnv = process.env.PASCAL_ALLOWED_ASSET_ORIGINS;
     if (allowEnv) {
         const origins = allowEnv
@@ -107,20 +164,85 @@ function assertAllowedUrl(url) {
             .map((s) => s.trim())
             .filter(Boolean);
         if (!origins.includes(parsed.origin)) {
-            throw new McpError(ErrorCode.InvalidParams, 'url_origin_not_allowlisted', {
-                url,
-                origin: parsed.origin,
-            });
+            blocked('url_origin_not_allowlisted', { url, origin: parsed.origin });
         }
     }
     return parsed;
 }
+/** Resolves `url`'s host and returns its addresses only if every one of them is public. */
+async function resolveCheckedAddresses(url, resolve) {
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    const details = { url: url.toString(), hostname: url.hostname };
+    const literalFamily = isIP(host);
+    let addresses;
+    if (literalFamily) {
+        addresses = [{ address: host, family: literalFamily }];
+    }
+    else {
+        if (isLocalHostname(host))
+            blocked('url_host_blocked', details);
+        try {
+            addresses = await resolve(host);
+        }
+        catch (err) {
+            return protocolError('dns_lookup_failed', {
+                ...details,
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (addresses.length === 0)
+        protocolError('dns_lookup_failed', details);
+    const unsafe = addresses.find((a) => isBlockedAddress(a.address));
+    if (unsafe)
+        blocked('url_host_blocked', details, { address: unsafe.address });
+    return addresses;
+}
+/** A socket `lookup` that only ever answers with the given, already-checked addresses. */
+export function pinnedLookup(addresses) {
+    return (_hostname, options, callback) => {
+        const family = options.family === 'IPv4' ? 4 : options.family === 'IPv6' ? 6 : options.family;
+        const matching = family === 4 || family === 6 ? addresses.filter((a) => a.family === family) : addresses;
+        const first = matching[0];
+        if (!first) {
+            callback(Object.assign(new Error('no checked address for family'), { code: 'ENOTFOUND' }), '');
+        }
+        else if (options.all) {
+            callback(null, matching);
+        }
+        else {
+            callback(null, first.address, first.family);
+        }
+    };
+}
+function requestPinned(url, init) {
+    const send = url.protocol === 'https:' ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const req = send(url, {
+            method: 'GET',
+            agent: false,
+            headers: init.headers,
+            lookup: init.lookup,
+            signal: init.signal,
+        }, resolve);
+        req.on('error', reject);
+        req.end();
+    });
+}
+const defaultDeps = {
+    resolve: (hostname) => dnsLookup(hostname, { all: true, verbatim: true }),
+    request: requestPinned,
+};
+function header(res, name) {
+    const value = res.headers[name];
+    return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+}
 /**
- * SSRF-safe fetch that follows redirects manually, revalidating the host
- * allowlist + private-IP check on every hop. Throws `McpError` for blocked
- * URLs, non-2xx responses, oversize bodies, or timeouts.
+ * SSRF-safe fetch that follows redirects manually, re-resolving and rechecking
+ * the host on every hop and connecting only to the checked addresses. Throws
+ * `ProtocolError` for blocked URLs, non-2xx responses, oversize bodies, or timeouts.
  */
-export async function safeFetch(urlStr, opts = {}) {
+export async function safeFetch(urlStr, opts = {}, deps = defaultDeps) {
     const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const hops = [];
@@ -131,89 +253,66 @@ export async function safeFetch(urlStr, opts = {}) {
         for (let i = 0; i <= MAX_REDIRECTS; i++) {
             const parsed = assertAllowedUrl(current);
             hops.push(parsed.toString());
-            const res = await fetch(parsed, {
-                redirect: 'manual',
+            const addresses = await resolveCheckedAddresses(parsed, deps.resolve);
+            const res = await deps.request(parsed, {
+                headers: opts.accept ? { Accept: opts.accept } : {},
+                lookup: pinnedLookup(addresses),
                 signal: controller.signal,
-                headers: opts.accept ? { Accept: opts.accept } : undefined,
             });
-            // Manual redirect handling
-            if (res.status >= 300 && res.status < 400) {
-                const location = res.headers.get('location');
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                res.resume();
+                const location = header(res, 'location');
                 if (!location) {
-                    throw new McpError(ErrorCode.InvalidParams, 'redirect_without_location', {
-                        url: parsed.toString(),
-                        status: res.status,
-                    });
+                    protocolError('redirect_without_location', { url: parsed.toString(), status });
                 }
                 current = new URL(location, parsed).toString();
                 continue;
             }
-            if (!res.ok) {
-                throw new McpError(ErrorCode.InvalidParams, 'fetch_failed', {
+            if (status < 200 || status >= 300) {
+                res.resume();
+                protocolError('fetch_failed', {
                     url: parsed.toString(),
-                    status: res.status,
-                    statusText: res.statusText,
+                    status,
+                    statusText: res.statusMessage ?? '',
                 });
             }
-            // Enforce Content-Length up front if present.
-            const declared = Number(res.headers.get('content-length'));
+            const declared = Number(header(res, 'content-length') ?? Number.NaN);
             if (Number.isFinite(declared) && declared > maxBytes) {
-                throw new McpError(ErrorCode.InvalidParams, 'response_too_large', {
-                    url: parsed.toString(),
-                    declared,
-                    maxBytes,
-                });
-            }
-            // Stream with a running cap so servers that lie about length still get bounded.
-            const reader = res.body?.getReader();
-            if (!reader) {
-                throw new McpError(ErrorCode.InvalidParams, 'empty_response', {
-                    url: parsed.toString(),
-                });
+                res.destroy();
+                protocolError('response_too_large', { url: parsed.toString(), declared, maxBytes });
             }
+            // Running cap so servers that lie about length still get bounded.
             const chunks = [];
             let total = 0;
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                if (value) {
-                    total += value.byteLength;
-                    if (total > maxBytes) {
-                        try {
-                            await reader.cancel();
-                        }
-                        catch {
-                            // ignore
-                        }
-                        throw new McpError(ErrorCode.InvalidParams, 'response_too_large', {
-                            url: parsed.toString(),
-                            received: total,
-                            maxBytes,
-                        });
-                    }
-                    chunks.push(value);
+            for await (const chunk of res) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                total += buf.byteLength;
+                if (total > maxBytes) {
+                    res.destroy();
+                    protocolError('response_too_large', { url: parsed.toString(), received: total, maxBytes });
                 }
+                chunks.push(buf);
             }
             return {
-                buffer: Buffer.concat(chunks.map((c) => Buffer.from(c))),
-                contentType: res.headers.get('content-type'),
+                buffer: Buffer.concat(chunks),
+                contentType: header(res, 'content-type'),
                 finalUrl: parsed.toString(),
                 hops,
             };
         }
-        throw new McpError(ErrorCode.InvalidParams, 'too_many_redirects', {
-            hops: hops.slice(0, MAX_REDIRECTS + 1),
-        });
+        return protocolError('too_many_redirects', { hops: hops.slice(0, MAX_REDIRECTS + 1) });
     }
     catch (err) {
-        if (err instanceof McpError)
+        if (err instanceof ProtocolError)
             throw err;
-        if (err.name === 'AbortError') {
-            throw new McpError(ErrorCode.InvalidParams, 'fetch_timeout', { url: urlStr, timeoutMs });
+        if (controller.signal.aborted || err.name === 'AbortError') {
+            return protocolError('fetch_timeout', { url: urlStr, timeoutMs });
         }
-        const message = err instanceof Error ? err.message : String(err);
-        throw new McpError(ErrorCode.InvalidParams, 'fetch_error', { url: urlStr, message });
+        return protocolError('fetch_error', {
+            url: urlStr,
+            message: err instanceof Error ? err.message : String(err),
+        });
     }
     finally {
         clearTimeout(timer);

package/dist/operations/scene-operations.d.ts

@@ -1,12 +1,22 @@
+import type { NodeDeletionPlan, NodeDeletionScene } from '@pascal-app/core';
 import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
-import type { AnyNode, AnyNodeId, AnyNodeType } from '@pascal-app/core/schema';
+import type { AnyNode, AnyNodeId, AnyNodeType, Collection, CollectionId, SceneMaterial, SceneMaterialId } from '@pascal-app/core/schema';
+import type { ZodType } from 'zod';
+import type { AgentSession } from '../bridge/agent-session.js';
 import type { ActiveSceneMeta, Patch, SceneBridge, ValidationResult } from '../bridge/scene-bridge.js';
-import type { ProjectCreateOptions, ProjectStatus, SceneEvent, SceneEventAppendOptions, SceneEventListOptions, SceneListOptions, SceneMeta, SceneMutateOptions, SceneSaveOptions, SceneStore, SceneWithGraph } from '../storage/types.js';
+import type { ProjectCreateOptions, ProjectStatus, SceneDeleteResult, SceneEvent, SceneEventAppendOptions, SceneEventListOptions, SceneListOptions, SceneMeta, SceneMutateOptions, SceneSaveOptions, SceneStore, SceneWithGraph } from '../storage/types.js';
 export type CreateSceneOperationsOptions = {
     bridge?: SceneBridge;
     store?: SceneStore;
+    /**
+     * The floor the host's person is viewing, which an operation that names no level defaults to,
+     * as the chat's does. A host with no view (the remote MCP) leaves it out: the lowest storey.
+     */
+    activeLevelId?: () => string | null;
 };
 export interface SceneOperations {
+    /** A host with an evidence-led design workflow owns its brief policy. */
+    designBriefRequired?: boolean;
     readonly hasBridge: boolean;
     readonly hasStore: boolean;
     readonly hasSceneEvents: boolean;
@@ -15,6 +25,15 @@ export interface SceneOperations {
     readonly canCreateProject: boolean;
     readonly canGetProjectStatus: boolean;
     readonly storeBackend: SceneStore['backend'] | null;
+    /** What the agent's session has kept (named moments, what it made); absent on a host with none. */
+    readonly agentSession?: AgentSession;
+    /**
+     * Whether `applyPatch` takes `upsert_material` patches with the nodes that use them, in one
+     * history step. A host that does lends `getMaterials`, and paint keeps native materials there.
+     */
+    readonly supportsMaterialUpserts?: boolean;
+    /** The floor the host's person is viewing, when the host has a view. */
+    readonly activeLevelId?: () => string | null;
     setActiveScene(meta: ActiveSceneMeta): void;
     getActiveScene(): ActiveSceneMeta | null;
     clearActiveScene(): void;
@@ -27,6 +46,10 @@ export interface SceneOperations {
     loadJSON(json: string | SceneGraph): void;
     getNode(id: AnyNodeId): AnyNode | null;
     getNodes(): Record<AnyNodeId, AnyNode>;
+    getCollections(): Record<CollectionId, Collection>;
+    getMaterials?(): Readonly<Record<SceneMaterialId, SceneMaterial>>;
+    /** Replace the scene's collections (one undo step, like any edit). */
+    setCollections(collections: Record<CollectionId, Collection>): void;
     getRootNodeIds(): AnyNodeId[];
     getChildren(parentId: AnyNodeId): AnyNode[];
     getAncestry(id: AnyNodeId): AnyNode[];
@@ -44,6 +67,20 @@ export interface SceneOperations {
         deletedIds: AnyNodeId[];
         createdIds: AnyNodeId[];
     };
+    /**
+     * The active bridge's deletion preview, when it has one. Absent for bridges
+     * that cannot preview their own deletes; the apply_patch guard is then stricter.
+     */
+    readonly planDeletion?: (scene: NodeDeletionScene, ids: AnyNodeId[]) => NodeDeletionPlan;
+    /**
+     * The schema the active bridge checks a stored node of a kind by, for each kind it checks: a host
+     * that validates its plugins' nodes at its own write boundary lends it (verify_scene reads it).
+     */
+    readonly nodeSchema?: (kind: string) => ZodType | undefined;
+    deriveStructure(levelIds?: AnyNodeId[]): {
+        createdIds: AnyNodeId[];
+        deletedIds: AnyNodeId[];
+    };
     undo(steps?: number): number;
     redo(steps?: number): number;
     validateScene(): ValidationResult;
@@ -53,12 +90,13 @@ export interface SceneOperations {
         futureCount: number;
     };
     clearHistory(): void;
+    runAsSingleHistoryStep<T>(run: () => T): T;
     createProject(options: ProjectCreateOptions): Promise<ProjectStatus>;
     getProjectStatus(id: string): Promise<ProjectStatus | null>;
     saveScene(options: SceneSaveOptions): Promise<SceneMeta>;
     loadStoredScene(id: string): Promise<SceneWithGraph | null>;
     listScenes(options?: SceneListOptions): Promise<SceneMeta[]>;
-    deleteStoredScene(id: string, options?: SceneMutateOptions): Promise<boolean>;
+    deleteStoredScene(id: string, options?: SceneMutateOptions): Promise<SceneDeleteResult>;
     renameStoredScene(id: string, newName: string, options?: SceneMutateOptions): Promise<SceneMeta>;
     appendSceneEvent(options: SceneEventAppendOptions): Promise<SceneEvent | null>;
     listSceneEvents(id: string, options?: SceneEventListOptions): Promise<SceneEvent[]>;

package/dist/operations/scene-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-operations.d.ts","sourceRoot":"","sources":["../../src/operations/scene-operations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene-operations.d.ts","sourceRoot":"","sources":["../../src/operations/scene-operations.ts"],"names":[],"mappings":"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"}

package/dist/operations/scene-operations.js

@@ -4,13 +4,30 @@ export function createSceneOperations(options) {
 class SceneOperationsFacade {
     #bridge;
     #store;
+    planDeletion;
+    nodeSchema;
+    activeLevelId;
     constructor(options) {
         this.#bridge = options.bridge;
         this.#store = options.store;
+        if (options.activeLevelId)
+            this.activeLevelId = options.activeLevelId;
+        const bridge = options.bridge;
+        if (typeof bridge?.planDeletion === 'function') {
+            this.planDeletion = (scene, ids) => bridge.planDeletion(scene, ids);
+        }
+        if (typeof bridge?.nodeSchema === 'function')
+            this.nodeSchema = (kind) => bridge.nodeSchema(kind);
     }
     get hasBridge() {
         return this.#bridge !== undefined;
     }
+    get supportsMaterialUpserts() {
+        return this.#bridge?.supportsMaterialUpserts === true;
+    }
+    get agentSession() {
+        return this.#bridge?.agentSession;
+    }
     get hasStore() {
         return this.#store !== undefined;
     }
@@ -61,7 +78,9 @@ class SceneOperationsFacade {
         };
     }
     loadJSON(json) {
-        this.requireBridge().loadJSON(json);
+        const bridge = this.requireBridge();
+        bridge.loadJSON(json);
+        bridge.clearHistory();
     }
     getNode(id) {
         return this.requireBridge().getNode(id);
@@ -69,6 +88,15 @@ class SceneOperationsFacade {
     getNodes() {
         return this.requireBridge().getNodes();
     }
+    getCollections() {
+        return this.requireBridge().getCollections();
+    }
+    getMaterials() {
+        return this.requireBridge().getMaterials();
+    }
+    setCollections(collections) {
+        this.requireBridge().setCollections(collections);
+    }
     getRootNodeIds() {
         return this.requireBridge().getRootNodeIds();
     }
@@ -94,8 +122,18 @@ class SceneOperationsFacade {
         return this.requireBridge().deleteNode(id, cascade);
     }
     applyPatch(patches) {
+        if (patches.some((patch) => patch.op === 'upsert_material') && !this.supportsMaterialUpserts)
+            throw new Error('materials_unavailable');
         return this.requireBridge().applyPatch(patches);
     }
+    /**
+     * Derive construction from the intent the tools just wrote. The hosted
+     * bridge reconciles inside every mutation and exposes no hook, so the call
+     * is optional: there it is already done by the time a tool builds its result.
+     */
+    deriveStructure(levelIds) {
+        return this.requireBridge().deriveStructure?.(levelIds) ?? { createdIds: [], deletedIds: [] };
+    }
     undo(steps) {
         return this.requireBridge().undo(steps);
     }
@@ -114,6 +152,9 @@ class SceneOperationsFacade {
     clearHistory() {
         this.requireBridge().clearHistory();
     }
+    runAsSingleHistoryStep(run) {
+        return this.requireBridge().runAsSingleHistoryStep(run);
+    }
     async createProject(options) {
         const store = this.requireStore();
         if (!store.createProject) {

package/dist/prompts/from-brief.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from '@modelcontextprotocol/server';
 import type { SceneOperations } from '../operations/index.js';
 /**
  * Build the user-facing prompt text for `from_brief`. Pure function for testability.