@pascal-app/core 1.0.4 → 1.0.5

package/dist/agent-operations/apply-changes.js

@@ -1,10 +1,21 @@
 const childrenOf = (node) => node && 'children' in node && Array.isArray(node.children) ? node.children : null;
 /**
- * The scene after an operation's changes, without a store: for checks and previews. Same order as
- * the store's applyNodeChanges — updates, creates, then deletes — so an opening moved off a wall
- * being replaced is no longer among that wall's children when it goes.
+ * A node with a patch applied. A field the patch sets to `undefined` is removed, as the store's
+ * updateNode removes it: optional fields encode a mode by their absence.
  */
-export function applySceneChanges(nodes, changes) {
+function patched(node, data) {
+    const merged = { ...node, ...data };
+    for (const [key, value] of Object.entries(data))
+        if (value === undefined)
+            delete merged[key];
+    return merged;
+}
+/**
+ * The scene after a write's operations in their order, without a store: each create attached to its
+ * parent, each reparent moved between both parents' `children`, each delete taking everything under
+ * it. A create is written as given; parse it first for its schema's defaults.
+ */
+export function applySceneWrites(nodes, writes) {
     const next = { ...nodes };
     const setChildren = (parentId, edit) => {
         const parent = parentId ? next[parentId] : undefined;
@@ -14,32 +25,52 @@ export function applySceneChanges(nodes, changes) {
     };
     const detach = (parentId, id) => setChildren(parentId, (ids) => ids.filter((child) => child !== id));
     const attach = (parentId, id) => setChildren(parentId, (ids) => (ids.includes(id) ? ids : [...ids, id]));
-    for (const { id, data } of changes?.update ?? []) {
-        const current = next[id];
-        if (!current)
-            continue;
-        if (data.parentId !== undefined && data.parentId !== current.parentId) {
-            detach(current.parentId, id);
-            attach(data.parentId, id);
-        }
-        next[id] = { ...current, ...data };
-    }
-    for (const { node, parentId } of changes?.create ?? []) {
-        next[node.id] = parentId ? { ...node, parentId } : node;
-        attach(parentId ?? node.parentId, node.id);
-    }
     const remove = (id) => {
         const node = next[id];
         delete next[id];
         for (const child of childrenOf(node) ?? [])
             remove(child);
     };
-    for (const id of changes?.delete ?? []) {
-        detach(next[id]?.parentId, id);
-        remove(id);
+    for (const write of writes) {
+        if (write.op === 'create') {
+            const { node, parentId } = write;
+            next[node.id] = parentId ? { ...node, parentId } : node;
+            attach(parentId ?? node.parentId, node.id);
+        }
+        else if (write.op === 'update') {
+            const current = next[write.id];
+            if (!current)
+                continue;
+            const data = write.data;
+            if (data.parentId !== undefined && data.parentId !== current.parentId) {
+                detach(current.parentId, write.id);
+                attach(data.parentId, write.id);
+            }
+            next[write.id] = patched(current, data);
+        }
+        else if (write.op === 'delete') {
+            detach(next[write.id]?.parentId, write.id);
+            remove(write.id);
+        }
     }
     return next;
 }
+/**
+ * The scene after an operation's changes, without a store: for checks and previews. Same order as
+ * the store's applyNodeChanges — updates, creates, then deletes — so an opening moved off a wall
+ * being replaced is no longer among that wall's children when it goes.
+ */
+export function applySceneChanges(nodes, changes) {
+    return applySceneWrites(nodes, [
+        ...(changes?.update ?? []).map(({ id, data }) => ({ op: 'update', id, data })),
+        ...(changes?.create ?? []).map(({ node, parentId }) => ({
+            op: 'create',
+            node,
+            parentId,
+        })),
+        ...(changes?.delete ?? []).map((id) => ({ op: 'delete', id })),
+    ]);
+}
 /**
  * Several operations' changes, in order, as one set that lands the scene where applying them one
  * by one does — whether a surface applies creates, updates or deletes first: a batch is one undo
@@ -66,7 +97,7 @@ export function mergeSceneChanges(sets) {
             const entry = created.get(id);
             if (entry)
                 created.set(id, {
-                    node: { ...entry.node, ...data },
+                    node: patched(entry.node, data),
                     parentId: data.parentId ?? entry.parentId,
                 });
             else
@@ -89,5 +120,6 @@ export function mergeSceneChanges(sets) {
         update: [...updated].map(([id, data]) => ({ id, data })),
         delete: [...deleted],
         collections,
+        ...(materials.size ? { materials: [...materials.values()] } : {}),
     };
 }

package/dist/agent-operations/apply-outcome.d.ts

@@ -1,3 +1,4 @@
+import { type SessionKeep } from './scene-checkpoint.js';
 import type { AgentOperationOutcome, SceneChanges, SceneNodes } from './types.js';
 /** What a surface lends an operation's outcome: its scene, its writes and its reconciler. */
 export type AgentHostRuntime = {
@@ -5,6 +6,11 @@ export type AgentHostRuntime = {
     applyChanges: (changes: SceneChanges) => void;
     /** Derive construction from the scene as it now is: rooms, auto ceilings, floor plates. */
     reconcile: () => void;
+    /**
+     * Keeps what the agent's session should remember: the checkpoint an operation took and the nodes
+     * a write created. The host stores it where its sessions live, never in the scene.
+     */
+    keep?: (keep: SessionKeep) => void;
 };
 /**
  * Applies an operation's outcome through a host and returns the answer: its changes, then for an

package/dist/agent-operations/apply-outcome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-outcome.d.ts","sourceRoot":"","sources":["../../src/agent-operations/apply-outcome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAE9E,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,UAAU,CAAA;IAC1B,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;IAC7C,2FAA2F;IAC3F,SAAS,EAAE,MAAM,IAAI,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB"}
+{"version":3,"file":"apply-outcome.d.ts","sourceRoot":"","sources":["../../src/agent-operations/apply-outcome.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAE9E,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,UAAU,CAAA;IAC1B,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;IAC7C,2FAA2F;IAC3F,SAAS,EAAE,MAAM,IAAI,CAAA;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;CACnC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB"}

package/dist/agent-operations/apply-outcome.js

@@ -1,18 +1,33 @@
+import { madeEntries } from './scene-checkpoint.js';
 /**
  * Applies an operation's outcome through a host and returns the answer: its changes, then for an
  * outcome that reads derived construction, the reconcile, its follow-up changes and a second
  * reconcile. The host frames the call as one undo step.
  */
 export function applyAgentOutcome(outcome, runtime) {
-    if (outcome.changes)
+    const written = [];
+    if (outcome.changes) {
         runtime.applyChanges(outcome.changes);
-    if (!outcome.afterReconcile)
-        return outcome.result;
-    runtime.reconcile();
-    const settled = outcome.afterReconcile(runtime.getNodes());
-    if (settled.changes) {
-        runtime.applyChanges(settled.changes);
+        written.push(outcome.changes);
+    }
+    let result = outcome.result;
+    if (outcome.afterReconcile) {
         runtime.reconcile();
+        const settled = outcome.afterReconcile(runtime.getNodes());
+        if (settled.changes) {
+            runtime.applyChanges(settled.changes);
+            written.push(settled.changes);
+            runtime.reconcile();
+        }
+        result = settled.result;
+    }
+    if (runtime.keep) {
+        const made = madeEntries(runtime.getNodes(), written);
+        if (outcome.keep?.checkpoint ||
+            outcome.keep?.designBrief !== undefined ||
+            outcome.keep?.viewed !== undefined ||
+            made.length)
+            runtime.keep({ ...outcome.keep, ...(made.length ? { made } : {}) });
     }
-    return settled.result;
+    return result;
 }

package/dist/agent-operations/asset-views.d.ts

@@ -0,0 +1,75 @@
+import type { AssetInput } from '../schema/index.js';
+import type { AgentContext, AgentOperation, SceneNodes } from './types.js';
+/**
+ * What a host read about one catalog item before the call, as the operations are sync: its
+ * picture (a data URL, at most 512 px), and the names of its paintable surfaces, the `slot_<id>`
+ * materials in its model. A fact the host could not read is left out, never guessed.
+ */
+export type AssetViewFacts = {
+    picture?: string;
+    surfaces?: readonly string[];
+    /** Why a picture or the surfaces are missing, in the host's words. */
+    unavailable?: string;
+};
+type ViewAssetsInput = {
+    ids: string[];
+};
+/** The item a host reads: `id` keys its facts, `src` is its model, `thumbnail` its picture. */
+export type AssetViewSubject = Pick<AssetInput, 'id' | 'src'> & {
+    thumbnail?: string;
+};
+/**
+ * The names of a GLB's paintable surfaces (its `slot_<id>` materials, as the renderer and the
+ * editor's Paint read them), from the container's JSON chunk alone: `read` is asked for the
+ * 20-byte header, then for the JSON chunk. A file with no slot materials gives `[]`.
+ */
+export declare function readGlbSurfaces(read: (start: number, end: number) => Promise<Uint8Array>): Promise<string[]>;
+/** How a host reaches a library's files: a byte range of a model, a thumbnail as a data URL. */
+export type AssetViewIO = {
+    range: (url: string, start: number, end: number) => Promise<Uint8Array>;
+    picture: (url: string) => Promise<string>;
+};
+/**
+ * The library's files over `fetch`: a model by two small `Range` requests, a thumbnail whole, then
+ * `resizePicture` (the host's own: a canvas in the browser, sharp on a server) to at most 512 px.
+ * Without one the thumbnail goes as it is. A path with no host (a standalone server's built-in
+ * list) is refused by `fetch`, which the loader reports as the picture's absence.
+ */
+export declare function createFetchAssetViewIO({ fetchImpl, resolveUrl, resizePicture, }?: {
+    fetchImpl?: typeof fetch;
+    resolveUrl?: (url: string) => Promise<string | null>;
+    resizePicture?: (bytes: Uint8Array, mediaType: string) => Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+    }>;
+}): AssetViewIO;
+/** Reads the facts of catalog items; `pictures: false` reads the surfaces only. */
+export type AssetViewLoader = (subjects: readonly AssetViewSubject[], options?: {
+    pictures?: boolean;
+}) => Promise<Record<string, AssetViewFacts>>;
+/**
+ * The loader a host builds once: its surface names are cached per model for the session (a model
+ * is read by two small range requests, never twice), its pictures are fetched when asked for.
+ */
+export declare function createAssetViewLoader(io: AssetViewIO): AssetViewLoader;
+/** Whether `assetViewNeeds` looks items up in the catalog for this call, so the host must hand it over. */
+export declare const assetViewsReadCatalog: (tool: string, input: unknown) => boolean;
+/**
+ * What a host reads before a call, as the catalog is fetched: the items `view_assets` names (with
+ * their pictures), and the catalog items `paint` is asked to finish without a role, alone or in a
+ * batch (only their surfaces: paint then lists them). Every subject is the catalog's entry, never
+ * the scene's: a node's `asset.src` is data a person or a script writes, so it is not a place the
+ * host may fetch from. An item whose id the catalog does not hold is not read.
+ */
+export declare function assetViewNeeds(nodes: SceneNodes, tool: string, input: unknown, context: Pick<AgentContext, 'catalog'>): {
+    subjects: AssetViewSubject[];
+    pictures: boolean;
+};
+/**
+ * `view_assets`: a picture of each catalog item, with its size, category and the names of its
+ * paintable surfaces. The pictures and surfaces are the host's, read before the call; a host that
+ * cannot fetch them answers the facts it has, and says so.
+ */
+export declare const viewAssets: AgentOperation<ViewAssetsInput>;
+export {};
+//# sourceMappingURL=asset-views.d.ts.map

package/dist/agent-operations/asset-views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-views.d.ts","sourceRoot":"","sources":["../../src/agent-operations/asset-views.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,KAAK,eAAe,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAExC,+FAA+F;AAC/F,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAStF;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB;AAED,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACvE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC1C,CAAA;AAkCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,SAAiB,EACjB,UAAuC,EACvC,aAAa,GACd,GAAE;IACD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACpD,aAAa,CAAC,EAAE,CACd,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClD,GAAG,WAAW,CAyBnB;AAED,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,CAC5B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,KAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;AAI5C;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,eAAe,CAyCtE;AAkBD,2GAA2G;AAC3G,eAAO,MAAM,qBAAqB,SAAU,MAAM,SAAS,OAAO,KAAG,OACH,CAAA;AAElE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GACrC;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAgBrD;AAWD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,eAAe,CAyCtD,CAAA"}

package/dist/agent-operations/asset-views.js

@@ -0,0 +1,234 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { deriveSlotId } from '../lib/slots.js';
+const round = (value) => Math.round(value * 100) / 100;
+/** A GLB's JSON chunk is read whole; one past this is not a model's description. */
+const MAX_JSON_CHUNK = 8 * 1024 * 1024;
+const GLB_MAGIC = 0x46_54_6c_67;
+const GLB_JSON_CHUNK = 0x4e_4f_53_4a;
+/**
+ * The names of a GLB's paintable surfaces (its `slot_<id>` materials, as the renderer and the
+ * editor's Paint read them), from the container's JSON chunk alone: `read` is asked for the
+ * 20-byte header, then for the JSON chunk. A file with no slot materials gives `[]`.
+ */
+export async function readGlbSurfaces(read) {
+    const head = await read(0, 20);
+    if (head.byteLength < 20)
+        throw new Error('Not a GLB: the file is shorter than its header.');
+    const view = new DataView(head.buffer, head.byteOffset, head.byteLength);
+    if (view.getUint32(0, true) !== GLB_MAGIC)
+        throw new Error('Not a GLB: bad magic.');
+    if (view.getUint32(16, true) !== GLB_JSON_CHUNK)
+        throw new Error('Not a GLB: no JSON chunk first.');
+    const length = view.getUint32(12, true);
+    if (length > MAX_JSON_CHUNK)
+        throw new Error('The GLB description is too large to read.');
+    const json = await read(20, 20 + length);
+    if (json.byteLength < length)
+        throw new Error('The GLB description is truncated.');
+    const parsed = JSON.parse(new TextDecoder().decode(json).trim());
+    const ids = (parsed.materials ?? []).flatMap((material) => typeof material?.name === 'string' ? [deriveSlotId(material.name)] : []);
+    return [...new Set(ids.filter((id) => id !== null))];
+}
+/** A thumbnail is fetched whole; one past this is not a thumbnail. */
+const MAX_PICTURE_BYTES = 4 * 1024 * 1024;
+/** The first `end` bytes of a body, then the rest is dropped: a server that ignores `Range`. */
+async function readPrefix(response, end) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return new Uint8Array(await response.arrayBuffer()).subarray(0, end);
+    const chunks = [];
+    let length = 0;
+    while (length < end) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+        length += value.byteLength;
+    }
+    await reader.cancel().catch(() => undefined);
+    const bytes = new Uint8Array(length);
+    let at = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return bytes.subarray(0, end);
+}
+function base64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x80_00)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x80_00));
+    return btoa(binary);
+}
+/**
+ * The library's files over `fetch`: a model by two small `Range` requests, a thumbnail whole, then
+ * `resizePicture` (the host's own: a canvas in the browser, sharp on a server) to at most 512 px.
+ * Without one the thumbnail goes as it is. A path with no host (a standalone server's built-in
+ * list) is refused by `fetch`, which the loader reports as the picture's absence.
+ */
+export function createFetchAssetViewIO({ fetchImpl = fetch, resolveUrl = async (url) => url, resizePicture, } = {}) {
+    const open = async (url, init) => {
+        const resolved = await resolveUrl(url);
+        if (!resolved)
+            throw new Error('the file is not available');
+        const response = await fetchImpl(resolved, init);
+        if (!response.ok)
+            throw new Error(`the file answered ${response.status}`);
+        return response;
+    };
+    return {
+        range: async (url, start, end) => {
+            const response = await open(url, { headers: { Range: `bytes=${start}-${end - 1}` } });
+            return response.status === 206
+                ? new Uint8Array(await response.arrayBuffer())
+                : (await readPrefix(response, end)).subarray(start);
+        },
+        picture: async (url) => {
+            const response = await open(url);
+            const mediaType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? '';
+            if (!mediaType.startsWith('image/'))
+                throw new Error('the file is not an image');
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            if (bytes.byteLength > MAX_PICTURE_BYTES)
+                throw new Error('the picture is too large');
+            const shown = resizePicture ? await resizePicture(bytes, mediaType) : { bytes, mediaType };
+            return `data:${shown.mediaType};base64,${base64(shown.bytes)}`;
+        },
+    };
+}
+const failure = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * The loader a host builds once: its surface names are cached per model for the session (a model
+ * is read by two small range requests, never twice), its pictures are fetched when asked for.
+ */
+export function createAssetViewLoader(io) {
+    const surfaces = new Map();
+    const surfacesOf = (src) => {
+        let known = surfaces.get(src);
+        if (!known) {
+            known = readGlbSurfaces((start, end) => io.range(src, start, end));
+            surfaces.set(src, known);
+            // A model that could not be read is read again next time.
+            known.catch(() => surfaces.delete(src));
+        }
+        return known;
+    };
+    return async (subjects, { pictures = true } = {}) => {
+        const entries = await Promise.all(subjects.map(async (subject) => {
+            const [surface, picture] = await Promise.allSettled([
+                subject.src ? surfacesOf(subject.src) : Promise.reject(new Error('it has no model')),
+                pictures && subject.thumbnail
+                    ? io.picture(subject.thumbnail)
+                    : Promise.reject(new Error(pictures ? 'it has no picture' : 'not asked')),
+            ]);
+            const missing = [
+                ...(surface.status === 'rejected'
+                    ? [`its surfaces could not be read (${failure(surface.reason)})`]
+                    : []),
+                ...(pictures && picture.status === 'rejected'
+                    ? [`its picture could not be fetched (${failure(picture.reason)})`]
+                    : []),
+            ];
+            return [
+                subject.id,
+                {
+                    ...(surface.status === 'fulfilled' ? { surfaces: surface.value } : {}),
+                    ...(picture.status === 'fulfilled' ? { picture: picture.value } : {}),
+                    ...(missing.length ? { unavailable: missing.join('; ') } : {}),
+                },
+            ];
+        }));
+        return Object.fromEntries(entries);
+    };
+}
+/** The `paint` inputs of a call, alone or in a batch, that name no role: they list the surfaces. */
+function roleLessPaints(tool, input) {
+    const calls = tool === 'run_batch'
+        ? (input?.calls ?? []).flatMap((call) => (call?.tool === 'paint' ? [call.input] : []))
+        : tool === 'paint'
+            ? [input]
+            : [];
+    return calls.flatMap((call) => {
+        const { targets, role } = (call ?? {});
+        return !role && Array.isArray(targets) ? [{ targets }] : [];
+    });
+}
+/** Whether `assetViewNeeds` looks items up in the catalog for this call, so the host must hand it over. */
+export const assetViewsReadCatalog = (tool, input) => tool === 'view_assets' || roleLessPaints(tool, input).length > 0;
+/**
+ * What a host reads before a call, as the catalog is fetched: the items `view_assets` names (with
+ * their pictures), and the catalog items `paint` is asked to finish without a role, alone or in a
+ * batch (only their surfaces: paint then lists them). Every subject is the catalog's entry, never
+ * the scene's: a node's `asset.src` is data a person or a script writes, so it is not a place the
+ * host may fetch from. An item whose id the catalog does not hold is not read.
+ */
+export function assetViewNeeds(nodes, tool, input, context) {
+    const catalog = context.catalog ?? [];
+    if (tool === 'view_assets') {
+        const ids = input?.ids;
+        const wanted = new Set(Array.isArray(ids) ? ids : []);
+        return { subjects: catalog.filter((item) => wanted.has(item.id)), pictures: true };
+    }
+    const subjects = new Map();
+    for (const { targets } of roleLessPaints(tool, input))
+        for (const id of targets) {
+            const node = typeof id === 'string' ? nodes[id] : undefined;
+            if (node?.type !== 'item' || !node.asset?.id)
+                continue;
+            const entry = catalog.find((item) => item.id === node.asset.id);
+            if (entry?.src)
+                subjects.set(entry.id, { id: entry.id, src: entry.src });
+        }
+    return { subjects: [...subjects.values()], pictures: false };
+}
+const dimensionsOf = (item) => (item.dimensions ?? [1, 1, 1]).map(round).join(' × ');
+function surfacesText(facts) {
+    if (!facts?.surfaces)
+        return 'surfaces unknown here (its model could not be read)';
+    return facts.surfaces.length
+        ? `surfaces: ${facts.surfaces.join(', ')}`
+        : 'no named surfaces: paint has no part of it to finish';
+}
+/**
+ * `view_assets`: a picture of each catalog item, with its size, category and the names of its
+ * paintable surfaces. The pictures and surfaces are the host's, read before the call; a host that
+ * cannot fetch them answers the facts it has, and says so.
+ */
+export const viewAssets = (_nodes, { ids }, context) => {
+    const catalog = context.catalog;
+    if (!catalog)
+        refuse('no_catalog', 'This host has no item library to look in; no item has a picture here.');
+    const wanted = [...new Set(ids)];
+    const found = wanted.map((id) => catalog.find((item) => item.id === id));
+    const unknown = wanted.filter((_, i) => !found[i]);
+    if (unknown.length)
+        refuse('unknown_asset', `${unknown.map((id) => `"${id}"`).join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not in the item library, so no picture exists. Use ids search_assets returned. Nothing was shown.`, { ids: unknown });
+    const items = found.map((item) => {
+        const facts = context.assetViews?.[item.id];
+        return {
+            id: item.id,
+            name: item.name,
+            category: item.category,
+            dimensions: item.dimensions ?? [1, 1, 1],
+            surfaces: facts?.surfaces ?? null,
+            picture: Boolean(facts?.picture),
+            label: `${item.name} (${item.id}): ${item.category}, ${dimensionsOf(item)} m; ${surfacesText(facts)}.`,
+            ...(facts?.unavailable ? { unavailable: facts.unavailable } : {}),
+        };
+    });
+    const previews = items.flatMap(({ id, label }) => {
+        const image = context.assetViews?.[id]?.picture;
+        return image ? [{ label, image }] : [];
+    });
+    return {
+        result: {
+            items: items.map(({ label: _label, ...item }) => item),
+            shown: previews.length,
+            ...(previews.length < items.length && {
+                note: `${items.length - previews.length} of ${items.length} items show no picture here: this host could not fetch ${items.length - previews.length === 1 ? 'it' : 'them'} (each item's unavailable says why). Sizes and surfaces are as read.`,
+            }),
+            previews,
+        },
+        keep: { viewed: items.map((item) => item.id) },
+    };
+};

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

@@ -0,0 +1,157 @@
+import type { AuthorScenePayload } from '../agent-tools/author-scene.js';
+import { type AnyNode, type CompiledGeometryScript, type GeometryArtifactManifest, type SceneMaterial, type WallFace } from '../schema/index.js';
+import type { AgentContext, AgentOperationOutcome, SceneNodes } from './types.js';
+/**
+ * `author_scene`: a whole design, read by its author from the three.js module it wrote, handed
+ * over as a payload and written as native Pascal nodes in one step. Not in AGENT_OPERATIONS: the
+ * host compiles every module first (the MCP on its server, the chat in its worker) and passes the
+ * results as `compiled`, keyed by the payload's item ids and, for an opening with code, by
+ * `<wallId>/<index>`. Candidate ceiling points use `light/<level>/<index>` from
+ * `authorSceneCeilingPoints`; a module whose compile failed is absent and comes back in the report
+ * with the host's reason.
+ *
+ * The policy, decided with the owner: accept and report. Everything valid is written; every
+ * defect comes back by the payload's own id with a reason; what Pascal fills in or drops is a
+ * sentence in `defaults`; what it writes but doubts is a `warning`. Its join rule snaps a wall
+ * end within reach of another wall's centerline onto it, reported per wall. Ids are derived from the payload, so the same payload writes the same
+ * scene.
+ */
+export type AuthorSceneInput = {
+    payload: AuthorScenePayload;
+    compiled: Record<string, CompiledGeometryScript>;
+    /** Why a module did not compile, keyed like `compiled`, for the report. */
+    compileErrors?: Record<string, string>;
+    replace?: boolean;
+    buildingId?: string;
+    /** Hosts compile finishes against the candidate before making one scene commit. */
+    prepareOnly?: boolean;
+};
+export type AuthorSceneState = {
+    version: 1;
+    buildingId: string;
+    seed: string;
+    ids: Record<string, string>;
+    nodes: Record<string, AnyNode>;
+};
+export type AuthorSceneDefect = {
+    id: string;
+    code: string;
+    message: string;
+};
+export type AuthorSceneReport = {
+    levels: number;
+    walls: number;
+    doors: number;
+    windows: number;
+    rooms: number;
+    roomsNamed: number;
+    slabs: number;
+    columns: number;
+    items: number;
+    lights: number;
+    /** Rooms whose floor finish is their module, counted by the host that compiles them after the write. */
+    floorScripts: number;
+    /** Wall faces whose finish is a module, counted by the host that compiles them after the write. */
+    faceScripts: number;
+    /** The join rule applied: wall ends moved onto a centerline, with how far. */
+    snapped: {
+        id: string;
+        end: 'start' | 'end';
+        movedM: number;
+    }[];
+    /** What Pascal filled in or dropped, one sentence per fact. */
+    defaults: string[];
+    /** Written, but doubtful: by the payload's id, with a code. */
+    warnings: AuthorSceneDefect[];
+    defects: AuthorSceneDefect[];
+    notes: string[];
+    /** Payload ids, `wall/i` openings, `room/level/i`, and `light/level/i` ceiling points to nodes. */
+    ids: Record<string, string>;
+};
+/** Candidate modules, compiled by the host before room derivation decides which points are used. */
+export declare function authorSceneCeilingPoints(payload: AuthorScenePayload): {
+    id: string;
+    code: string;
+}[];
+/**
+ * The rooms whose floor finish is a module, by their zone once the write made it: the host reads
+ * each room's floor (`floorScriptInputs`), compiles the module for it and writes it with
+ * `setRoomFloorScript`, which core cannot do without a three.js runtime. A room whose seed found
+ * no enclosure has no zone and is already a defect.
+ */
+export declare function authorSceneFloorScripts(payload: AuthorScenePayload, report: Pick<AuthorSceneReport, 'ids'>): {
+    roomId: string;
+    zoneId: string;
+    code: string;
+}[];
+/** A wall face whose finish is a module, for the host to compile once the write is applied. */
+export type AuthorSceneFaceScript = {
+    /** The payload's wall id. */
+    wallId: string;
+    face: WallFace;
+    nodeId: string;
+    code: string;
+    toHeight?: number;
+};
+/** Where a floor or face script's build was compiled: the room's floor outline, or the wall's face. */
+export type AuthorSceneFinishHost = {
+    room: string;
+    polygon: [number, number][];
+} | {
+    wall: string;
+    face: WallFace;
+};
+/**
+ * The `finish_gaps` warning for a floor or face script whose build leaves part of its host bare:
+ * its `coverage` under FINISH_COVERED with at least one bare patch, each named by where it lies.
+ * Joints make no patch, so a tiled finish is never warned for its joints alone. Null otherwise.
+ */
+export declare function authorSceneFinishGaps(id: string, manifest: GeometryArtifactManifest, host: AuthorSceneFinishHost): AuthorSceneDefect | null;
+/**
+ * The wall faces whose finish is a module, once the write made the walls and the rooms: the host
+ * reads each face (`wallFaceScriptInputs`), compiles the module for it and writes it with
+ * `setWallFaceScript`, which core cannot do without a three.js runtime. The faces that cannot take
+ * one are already `no_face` defects in the operation's report.
+ */
+export declare function authorSceneFaceScripts(payload: AuthorScenePayload, report: Pick<AuthorSceneReport, 'ids'>, nodes: SceneNodes): AuthorSceneFaceScript[];
+export declare function authorScene(scene: SceneNodes, input: AuthorSceneInput, context: AgentContext): AgentOperationOutcome & {
+    result: AuthorSceneReport;
+    candidate: AuthorSceneState;
+    buildingId: string;
+};
+/** Commit the complete candidate after the host has compiled all of its finishes. */
+export declare function finalizeAuthorScene(scene: SceneNodes, outcome: AgentOperationOutcome & {
+    result: AuthorSceneReport;
+    candidate: AuthorSceneState;
+    buildingId: string;
+}): {
+    result: Record<string, unknown> & AuthorSceneReport;
+    keep?: import("./scene-checkpoint.js").SessionKeep;
+    afterReconcile?: (nodes: SceneNodes) => {
+        result: Record<string, unknown>;
+        changes?: import("./types.js").SceneChanges;
+    };
+    candidate: AuthorSceneState;
+    buildingId: string;
+    changes: {
+        materials?: readonly SceneMaterial[];
+        create?: {
+            node: AnyNode;
+            parentId?: string;
+        }[];
+        delete?: string[];
+        collections?: Record<string, import("../index.js").Collection | null>;
+        update: ({
+            id: string;
+            data: Partial<AnyNode>;
+        } | {
+            id: `building_${string}`;
+            data: {
+                metadata: {
+                    authorSceneState: AuthorSceneState;
+                };
+            };
+        })[];
+    };
+};
+//# sourceMappingURL=author-scene.d.ts.map

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

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