@pascal-app/core 1.0.3 → 1.0.4

package/dist/agent-tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-tools/index.ts"],"names":[],"mappings":"AA4BA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAClC,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA;AACvB,cAAc,gBAAgB,CAAA;AAE9B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BgB,CAAA"}

package/dist/agent-tools/index.js

@@ -0,0 +1,82 @@
+import { addObjectTool, getSourceTool } from './add-object.js';
+import { searchAssetsTool } from './assets.js';
+import { clearSceneTool } from './clear-scene.js';
+import { editCollectionTool, listCollectionsTool } from './collections.js';
+import { addColumnTool } from './columns.js';
+import { createRoomTool } from './create-room.js';
+import { findByTypeTool } from './find-by-type.js';
+import { furnishRoomTool } from './furnish-room.js';
+import { addLevelTool, duplicateLevelTool, getLevelSummaryTool, getWallsTool, getZonesTool, listLevelsTool, } from './levels.js';
+import { deleteNodeTool, getNodeTool } from './nodes.js';
+import { paintTool } from './paint.js';
+import { placeItemsTool } from './place-items.js';
+import { ROOM_TOOL_CONTRACTS } from './room-structure.js';
+import { searchMaterialsTool } from './search-materials.js';
+import { createStairTool, fitStairTool, measureStairTool } from './stairs.js';
+import { verifySceneTool } from './verify-scene.js';
+import { viewSceneTool } from './view-scene.js';
+import { addDoorTool, addWindowTool } from './wall-openings.js';
+import { addWallTool } from './walls.js';
+export * from './achieved.js';
+export * from './add-object.js';
+export * from './assets.js';
+export * from './clear-scene.js';
+export * from './collections.js';
+export * from './columns.js';
+export * from './contract.js';
+export * from './create-room.js';
+export * from './find-by-type.js';
+export * from './furnish-room.js';
+export * from './hosted-services.js';
+export * from './levels.js';
+export * from './measurement.js';
+export { NodeId } from './node-id.js';
+export * from './nodes.js';
+export * from './paint.js';
+export * from './place-items.js';
+export * from './refusal.js';
+export * from './room-structure.js';
+export * from './search-materials.js';
+export * from './stairs.js';
+export * from './verify-scene.js';
+export * from './view-scene.js';
+export * from './wall-openings.js';
+export * from './walls.js';
+export * from './write-target.js';
+/**
+ * Tools defined once for every agent surface — the MCP server and the hosted AI chat register
+ * each from this contract (name, description, input schema), and a parity test fails when a
+ * surface drifts. See wiki/architecture/agent-surfaces.md.
+ */
+export const AGENT_TOOL_CONTRACTS = [
+    addColumnTool,
+    measureStairTool,
+    fitStairTool,
+    viewSceneTool,
+    addDoorTool,
+    addWindowTool,
+    listLevelsTool,
+    getNodeTool,
+    getLevelSummaryTool,
+    getWallsTool,
+    getZonesTool,
+    duplicateLevelTool,
+    verifySceneTool,
+    addWallTool,
+    addLevelTool,
+    placeItemsTool,
+    createStairTool,
+    deleteNodeTool,
+    addObjectTool,
+    getSourceTool,
+    findByTypeTool,
+    editCollectionTool,
+    listCollectionsTool,
+    clearSceneTool,
+    createRoomTool,
+    furnishRoomTool,
+    searchAssetsTool,
+    paintTool,
+    searchMaterialsTool,
+    ...ROOM_TOOL_CONTRACTS,
+];

package/dist/agent-tools/levels.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+export declare const listLevelsTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {};
+};
+export declare const levelTarget: {
+    levelId: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodString>;
+};
+export declare const getLevelSummaryTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        levelId: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+    };
+};
+export declare const getWallsTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        levelId: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+    };
+};
+export declare const getZonesTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        levelId: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+    };
+};
+export declare const addLevelTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        buildingId: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        height: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>>;
+    };
+};
+export declare const duplicateLevelTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        levelId: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodEnum<{
+            above: "above";
+            below: "below";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            structure: "structure";
+            everything: "everything";
+            "structure-materials": "structure-materials";
+            "structure-furniture": "structure-furniture";
+        }>>;
+    };
+};
+//# sourceMappingURL=levels.d.ts.map

package/dist/agent-tools/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../../src/agent-tools/levels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,cAAc;;;;;CAM1B,CAAA;AAGD,eAAO,MAAM,WAAW;;;CAKvB,CAAA;AAED,eAAO,MAAM,mBAAmB;;;;;;;;CAM/B,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;CAMxB,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;CAMxB,CAAA;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;CAwBxB,CAAA;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;CA4B9B,CAAA"}

package/dist/agent-tools/levels.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import { measurement } from './measurement.js';
+import { NodeId } from './node-id.js';
+export const listLevelsTool = {
+    name: 'list_levels',
+    title: 'List levels',
+    description: 'List every level of every building in floor order: id, name, floorIndex, building (parentId), role (occupied storey, roof-only level or support level), child count, and which one the person is viewing (isActive). A roof-only level is the roof, not a storey.',
+    input: {},
+};
+// `level` is the chat's older name for the same parameter; threads and habits still use it.
+export const levelTarget = {
+    levelId: NodeId.optional().describe('The level, by an id list_levels returned; an id made up from a name ("level_1", "level_ground") does not exist. Default: the floor the person is viewing, else the lowest floor.'),
+    level: NodeId.optional().describe('Same as levelId.'),
+};
+export const getLevelSummaryTool = {
+    name: 'get_level_summary',
+    title: 'Get level summary',
+    description: "Summarise one level so nothing on it goes unseen: its role and counts, then walls (length, heights, doors and windows), zones (name, area, size, floor_choices), slabs, ceilings, items (floor, wall and ceiling), floor openings, stairs, roofs, and anything else by type. Zone polygons: get_zones; a node's full data: get_node.",
+    input: levelTarget,
+};
+export const getWallsTool = {
+    name: 'get_walls',
+    title: 'Get walls',
+    description: 'Get the walls of a level: start and end in metres, length, stored and resolved height, thickness, and their doors and windows.',
+    input: levelTarget,
+};
+export const getZonesTool = {
+    name: 'get_zones',
+    title: 'Get zones',
+    description: 'Get the zones (rooms) of a level: name, colour, polygon and holes in metres, area in m² (holes taken out), bounding size, and floor_choices: the floor plates the room can take (key, plateId, name, current; drawn and mezzanine flags). A room shares its floor plate with the rooms next to it unless detached.',
+    input: levelTarget,
+};
+export const addLevelTool = {
+    name: 'add_level',
+    title: 'Add level',
+    description: 'Add an empty level to a building, as the editor does: above its highest level, or below its lowest for a basement. On a scene with no building (a new or cleared scene), it starts the scene as the editor does: a site, a building and its ground level. To copy a floor with its content, use duplicate_level.',
+    input: {
+        buildingId: NodeId.optional().describe("The building. Default: the building of the floor the person is viewing, else the scene's only building."),
+        position: z
+            .enum(['above', 'below'])
+            .optional()
+            .describe('above (default): over the highest level; below: under the lowest, a basement.'),
+        name: z
+            .string()
+            .min(1)
+            .max(120)
+            .optional()
+            .describe('Name of the level, e.g. "Basement", "Attic".'),
+        height: measurement('length', 'm', {
+            positive: true,
+            description: 'Floor-to-floor storey height (default 2.5 m).',
+        }).optional(),
+    },
+};
+export const duplicateLevelTool = {
+    name: 'duplicate_level',
+    title: 'Duplicate level',
+    description: 'Copy a level with everything on it, as the editor does: fresh ids, internal links kept, and units whose rooms are all on that level copied too; plan references, scans and spawn points stay behind. The copy goes above the original (or below it) and the floors past it move up one.',
+    input: {
+        levelId: NodeId.optional().describe('The level to copy, by an id list_levels returned. Default: the floor the person is viewing.'),
+        position: z
+            .enum(['above', 'below'])
+            .optional()
+            .describe('Where the copy goes: above the original (default) or below it.'),
+        name: z
+            .string()
+            .min(1)
+            .max(120)
+            .optional()
+            .describe('Name of the copy. Default: none, so it reads by its floor like a new level (Floor 1, Ground floor…).'),
+        preset: z
+            .enum(['everything', 'structure', 'structure-materials', 'structure-furniture'])
+            .optional()
+            .describe('What to copy, as in the editor: everything (default); structure (walls, zones, slabs, ceilings, roofs, stairs, doors, windows) without materials; structure with its materials; or structure and furniture.'),
+    },
+};

package/dist/agent-tools/measurement.d.ts

@@ -0,0 +1,37 @@
+import { type Kind } from '@pascal-app/lingo';
+import { z } from 'zod';
+/**
+ * A zod field for a measurement tool argument that a model may emit as a bare
+ * number OR as natural language. `measurement('length', 'm')` accepts `0.15`,
+ * `"6 in"`, `"180cm"`, `"2 ft 3 in"`; `measurement('angle', 'deg')` accepts
+ * `45`, `"45°"`, `"1.57rad"`, `"0.25 turn"`. The value is canonicalized (via
+ * `@pascal-app/lingo`) to a number in `unit` — the exact unit the tool handler
+ * already expects — so no handler change is needed. `min`/`max` (in `unit`)
+ * reject out-of-range values with a model-readable message.
+ *
+ * The emitted JSON Schema is `number | string`, so the model is free to answer
+ * in whatever unit it is thinking in; AI SDK v6 applies the transform and
+ * forwards the canonical number to the tool executor.
+ *
+ * Tool-boundary safety: genuinely ambiguous separators (`"1,234"`, which could
+ * mean 1234 or 1.234) are rejected rather than silently absorbed, so a European
+ * decimal never becomes a 1000× value.
+ *
+ * NOTE: intentionally duplicated as `editor/packages/mcp/src/tools/measurement.ts`
+ * (MCP tools) and `packages/ai/src/tools/scene/measurement.ts` (AI-chat tools).
+ * The two tool stacks live in different packages — one inside the `editor`
+ * submodule — so they can't share a module. Keep the two copies identical; the
+ * clean long-term dedup is a zod-field adapter exported from `@pascal-app/lingo`.
+ */
+export interface MeasurementOptions {
+    /** Semantic description (e.g. "Wall thickness"). The natural-language note is appended. */
+    description?: string;
+    /** Upper bound, in `unit`. */
+    max?: number;
+    /** Inclusive lower bound, in `unit`. */
+    min?: number;
+    /** Require the value to be strictly greater than 0 (for non-zero dimensions). */
+    positive?: boolean;
+}
+export declare function measurement(kind: Kind, unit: string, opts?: MeasurementOptions): z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>;
+//# sourceMappingURL=measurement.d.ts.map

package/dist/agent-tools/measurement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurement.d.ts","sourceRoot":"","sources":["../../src/agent-tools/measurement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAiB,MAAM,mBAAmB,CAAA;AAC5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,kBAAkB;IACjC,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AA6CD,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,uGAoDlF"}

package/dist/agent-tools/measurement.js

@@ -0,0 +1,94 @@
+import { parseQuantity } from '@pascal-app/lingo';
+import { z } from 'zod';
+function unitNoun(unit) {
+    switch (unit) {
+        case 'm':
+            return 'meters';
+        case 'deg':
+            return 'degrees';
+        case 'rad':
+            return 'radians';
+        default:
+            return unit;
+    }
+}
+function naturalLanguageNote(kind, unit) {
+    let examples;
+    if (kind === 'angle') {
+        // Lead with an example in the field's own unit so a bare number is read
+        // the way the model intends (a bare "45" in a radians field is 45 rad).
+        examples =
+            unit === 'rad' ? '1.5708, "90°", "1.57rad", "0.25 turn"' : '45, "45°", "1.57rad", "0.25 turn"';
+    }
+    else {
+        examples = '0.9, "6 ft", "180cm", "2 ft 3 in"';
+    }
+    return `Accepts a number (${unitNoun(unit)}) or a natural-language string; other units are converted. e.g. ${examples}.`;
+}
+function boundsNote(unit, min, max, positive) {
+    if (positive) {
+        return max === undefined
+            ? ` Must be greater than 0 ${unit}.`
+            : ` Greater than 0, up to ${max} ${unit}.`;
+    }
+    if (min !== undefined && max !== undefined)
+        return ` Range ${min}–${max} ${unit}.`;
+    if (min !== undefined)
+        return ` Minimum ${min} ${unit}.`;
+    if (max !== undefined)
+        return ` Maximum ${max} ${unit}.`;
+    return '';
+}
+export function measurement(kind, unit, opts = {}) {
+    const { min, max, positive = false } = opts;
+    const description = [
+        opts.description,
+        naturalLanguageNote(kind, unit) + boundsNote(unit, min, max, positive),
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return z
+        .union([z.number(), z.string()])
+        .transform((val, ctx) => {
+        let value;
+        if (typeof val === 'number') {
+            value = val;
+        }
+        else {
+            const result = parseQuantity(val, {
+                kind,
+                unit,
+                strictness: 'forgiving',
+                // A genuinely ambiguous separator ("1,234") must not silently become
+                // a 1000× value at a tool boundary — fail so the model self-corrects.
+                escalate: { AMBIGUOUS_NUMBER: 'error' },
+            });
+            if (!result.ok) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: result.issues[0]?.message ?? `Could not read "${val}" as a ${kind}.`,
+                });
+                return z.NEVER;
+            }
+            value = result.quantity.to(unit).value;
+        }
+        if (!Number.isFinite(value)) {
+            ctx.addIssue({ code: 'custom', message: `Value must be a finite ${kind} in ${unit}.` });
+            return z.NEVER;
+        }
+        if (positive && value <= 0) {
+            ctx.addIssue({ code: 'custom', message: `Must be greater than 0 ${unit} (got ${value}).` });
+            return z.NEVER;
+        }
+        if (min !== undefined && value < min) {
+            ctx.addIssue({ code: 'custom', message: `Must be at least ${min} ${unit} (got ${value}).` });
+            return z.NEVER;
+        }
+        if (max !== undefined && value > max) {
+            ctx.addIssue({ code: 'custom', message: `Must be at most ${max} ${unit} (got ${value}).` });
+            return z.NEVER;
+        }
+        return value;
+    })
+        .describe(description);
+}

package/dist/agent-tools/node-id.d.ts

@@ -0,0 +1,3 @@
+import { z } from 'zod';
+export declare const NodeId: z.ZodString;
+//# sourceMappingURL=node-id.d.ts.map

package/dist/agent-tools/node-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-id.d.ts","sourceRoot":"","sources":["../../src/agent-tools/node-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,MAAM,aAAoB,CAAA"}

package/dist/agent-tools/node-id.js

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export const NodeId = z.string().min(1);

package/dist/agent-tools/nodes.d.ts

@@ -0,0 +1,17 @@
+export declare const getNodeTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        id: import("zod").ZodString;
+    };
+};
+export declare const deleteNodeTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        id: import("zod").ZodString;
+    };
+};
+//# sourceMappingURL=nodes.d.ts.map

package/dist/agent-tools/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/agent-tools/nodes.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW;;;;;;;CAMvB,CAAA;AAED,eAAO,MAAM,cAAc;;;;;;;CAM1B,CAAA"}

package/dist/agent-tools/nodes.js

@@ -0,0 +1,13 @@
+import { NodeId } from './node-id.js';
+export const getNodeTool = {
+    name: 'get_node',
+    title: 'Get node',
+    description: 'Get the full data of any node by its id, and the scene materials (scene:<id>) its finishes use.',
+    input: { id: NodeId.describe('The node id.') },
+};
+export const deleteNodeTool = {
+    name: 'delete_node',
+    title: 'Delete node',
+    description: "Delete a node with everything under it, as the editor's Delete does: a wall goes with its doors and windows, a level with everything on it. The floors above a deleted level keep their index.",
+    input: { id: NodeId.describe('The node id.') },
+};

package/dist/agent-tools/paint.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export declare const paintTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        targets: z.ZodArray<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        material: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            preset: z.ZodOptional<z.ZodCatch<z.ZodEnum<{
+                custom: "custom";
+                white: "white";
+                brick: "brick";
+                concrete: "concrete";
+                wood: "wood";
+                glass: "glass";
+                metal: "metal";
+                plaster: "plaster";
+                tile: "tile";
+                marble: "marble";
+            }>>>;
+            properties: z.ZodOptional<z.ZodObject<{
+                color: z.ZodDefault<z.ZodString>;
+                roughness: z.ZodDefault<z.ZodNumber>;
+                metalness: z.ZodDefault<z.ZodNumber>;
+                opacity: z.ZodDefault<z.ZodNumber>;
+                transparent: z.ZodDefault<z.ZodBoolean>;
+                side: z.ZodDefault<z.ZodEnum<{
+                    front: "front";
+                    back: "back";
+                    double: "double";
+                }>>;
+            }, z.core.$strip>>;
+            texture: z.ZodOptional<z.ZodObject<{
+                url: z.ZodString;
+                repeat: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                scale: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>]>>;
+        materialName: z.ZodOptional<z.ZodString>;
+        erase: z.ZodOptional<z.ZodLiteral<true>>;
+    };
+};
+//# sourceMappingURL=paint.d.ts.map

package/dist/agent-tools/paint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paint.d.ts","sourceRoot":"","sources":["../../src/agent-tools/paint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BrB,CAAA"}

package/dist/agent-tools/paint.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { MaterialSchema } from '../schema/material.js';
+import { NodeId } from './node-id.js';
+export const paintTool = {
+    name: 'paint',
+    title: 'Paint',
+    description: "Give walls, columns, slabs, ceilings, fences, doors, windows or roofs a finish in one call, as the editor's Paint does. Give one finish: color (#rrggbb, painted with the nearest of the library's flat colours, said with how near); material, a library:<id> (find it with search_materials) or scene:<id> ref, or a native material {properties: {color, roughness, metalness}} for an exact finish, kept as a scene material (materialName names a new one) and reused when the scene holds an equal one; or erase: true, back to the surface's default. role picks the surface: a wall's face a or b (or exterior, interior: the face turned out or into its room), its trims aSkirting, bSkirting, aCrown, bCrown, aChairRail, bChairRail, a curtain wall's curtain-frame, curtain-glass, curtain-solid; a column's shaft, base, capital or frame; a slab's surface, side, edge, riser, underside or foundation; a ceiling's surface; a fence's posts, infill, base or rail; a door's panel, frame, glass or hardware; a window's frame or glass; a roof's top, edge or wall. Without a role: both faces of a wall, a column's shaft, a slab's or a ceiling's surface, a whole fence, a door's panel and frame, a window's frame, a roof's top. A wall face is painted whole, over the wall finish of the room it faces; its painted parts keep their own, named in the note. A ceiling shows its finish's colour, not its texture. The result says the finish written, and the scene material when there is one. A target that is not in the scene, a role it lacks or an unknown material refuses the whole call: nothing is painted.",
+    input: {
+        targets: z.array(NodeId).min(1).max(200).describe('The nodes to paint.'),
+        role: z.string().min(1).optional().describe('The surface: see the description.'),
+        color: z
+            .string()
+            .regex(/^#[0-9a-fA-F]{6}$/)
+            .optional()
+            .describe('A colour, #rrggbb: painted with the nearest library colour.'),
+        material: z
+            .union([z.string().min(1), MaterialSchema])
+            .optional()
+            .describe('A library:<id> or scene:<id> ref, or a native material (properties color, roughness, metalness, and an existing texture) kept as a scene material.'),
+        materialName: z
+            .string()
+            .trim()
+            .min(1)
+            .max(120)
+            .optional()
+            .describe('The name of a new native material; an equal one already in the scene keeps its own.'),
+        erase: z.literal(true).optional().describe("Back to the surface's default."),
+    },
+};

package/dist/agent-tools/place-items.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const placeItemsTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        levelId: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodString>;
+        items: z.ZodArray<z.ZodObject<{
+            assetId: z.ZodString;
+            x: z.ZodNumber;
+            z: z.ZodNumber;
+            y: z.ZodOptional<z.ZodNumber>;
+            targetNodeId: z.ZodOptional<z.ZodString>;
+            rotation: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>>;
+        }, z.core.$strip>>;
+    };
+};
+//# sourceMappingURL=place-items.d.ts.map

package/dist/agent-tools/place-items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place-items.d.ts","sourceRoot":"","sources":["../../src/agent-tools/place-items.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAKvB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CA+B1B,CAAA"}

package/dist/agent-tools/place-items.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { levelTarget } from './levels.js';
+import { measurement } from './measurement.js';
+import { NodeId } from './node-id.js';
+export const placeItemsTool = {
+    name: 'place_items',
+    title: 'Place items',
+    description: 'Place one or more catalog items (furniture, fixtures, plants, art, lights) in one call; batch them rather than calling once per item. Each assetId comes from search_assets, never guessed. Positions are level (x, z) metres. An item stands on the floor of the level, or on the host it names (targetNodeId): a wall (art, a sconce: y is the height of its bottom above the floor, required; it goes on the side of the wall the point is on), a ceiling (a pendant, a downlight: it hangs flush under it), or an item standing on the floor (a lamp on a nightstand: it rests on its top; on an object built with add_object it rests on the real surface under the point, such as a porch landing, or a ceiling item hangs from the underside above it, such as a sloped vault, and the result names it in restingOn). A room, a slab or a level as the target means its floor. Each item is placed or refused on its own (asset_not_found; outside_rooms: an indoor item on the floor outside every room of a level that has rooms — garden and outdoor items may stand outside; height_required, item_too_tall, unsupported_host, host_not_found, host_not_on_level; blocks_door: a floor item standing where a door needs space, with a spot in its room that clears every door; too_large_for_room: a floor item its room cannot hold in any turn).',
+    input: {
+        items: z
+            .array(z.object({
+            assetId: z.string().min(1).describe('A catalog id from search_assets.'),
+            x: z.number().describe('X in level coordinates (metres).'),
+            z: z.number().describe('Z in level coordinates (metres).'),
+            y: z
+                .number()
+                .optional()
+                .describe("Height above the floor (metres): on a wall, of the item's bottom (required: art centred at eye level is 1.5 − its height / 2, a sconce about 1.5); on an item, a resting height you set rather than its top. Not used on a floor or a ceiling."),
+            targetNodeId: NodeId.optional().describe("The host: a wall, a ceiling or an item standing on the floor; a room, a slab or a level means its floor. Default: the level's floor."),
+            rotation: measurement('angle', 'deg', {
+                description: 'Turn about the vertical (default 0).',
+            }).optional(),
+        }))
+            .min(1)
+            .max(64)
+            .describe('The items to place.'),
+        ...levelTarget,
+    },
+};

package/dist/agent-tools/refusal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A sane, expected failure of an agent operation: the request cannot be done as asked, and the
+ * message says why and what would work ("Wall wall_a is 0.80 m long, too short for a 0.90 m
+ * door."). Every surface answers it the same way, `{ error, code, ...details }`, and counts it by
+ * `code` — a refusal is information for the model, not a crash.
+ */
+export declare class AgentRefusal extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    readonly name = "AgentRefusal";
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function isAgentRefusal(error: unknown): error is AgentRefusal;
+export declare function refuse(code: string, message: string, details?: Record<string, unknown>): never;
+/** The answer both surfaces return for a refusal. */
+export declare function refusalPayload(error: AgentRefusal): {
+    error: string;
+    code: string;
+};
+//# sourceMappingURL=refusal.d.ts.map

package/dist/agent-tools/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/agent-tools/refusal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAJ3C,SAAkB,IAAI,kBAAiB;gBAE5B,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAIjD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAOpE;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAE9F;AAED,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY;;;EAEjD"}

package/dist/agent-tools/refusal.js

@@ -0,0 +1,29 @@
+/**
+ * A sane, expected failure of an agent operation: the request cannot be done as asked, and the
+ * message says why and what would work ("Wall wall_a is 0.80 m long, too short for a 0.90 m
+ * door."). Every surface answers it the same way, `{ error, code, ...details }`, and counts it by
+ * `code` — a refusal is information for the model, not a crash.
+ */
+export class AgentRefusal extends Error {
+    code;
+    details;
+    name = 'AgentRefusal';
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export function isAgentRefusal(error) {
+    return (error instanceof AgentRefusal ||
+        (error instanceof Error &&
+            error.name === 'AgentRefusal' &&
+            typeof error.code === 'string'));
+}
+export function refuse(code, message, details) {
+    throw new AgentRefusal(code, message, details);
+}
+/** The answer both surfaces return for a refusal. */
+export function refusalPayload(error) {
+    return { error: error.message, code: error.code, ...error.details };
+}