@sealab/mcp-server 1.0.3 → 1.0.4

package/dist/tools/cart-cross-check.js

@@ -0,0 +1,182 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Cart-manifest cross-check for placement projection.
+//
+// Ground-truth fix for under-segmentation: a placement may only exist for a
+// real AI cart item, and its real-world size must match that item's catalog
+// dimensions. This anchors the drawing to the manifest — you cannot stretch one
+// 18" cabinet's box to cover a 36" run, and you cannot invent boxes for
+// cabinets that were never configured. Combined with one-placement-per-item, a
+// run can only hold as many cabinets as there are real items of the right size.
+//
+// Pure (no IO): the handler fetches session/cart state and passes the items in.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCartLookup = buildCartLookup;
+exports.crossCheckPlacementsAgainstCart = crossCheckPlacementsAgainstCart;
+const DEFAULT_WIDTH_TOLERANCE = 1.0;
+const DEFAULT_HEIGHT_TOLERANCE = 1.5;
+const DEFAULT_DEPTH_TOLERANCE = 1.5;
+function stringifyId(value) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    const text = String(value).trim();
+    return text.length > 0 ? text : undefined;
+}
+function toFiniteNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Read a cabinet dimension from the item itself or any of its payloads. */
+function extractCartItemDimension(item, key) {
+    const direct = toFiniteNumber(item[key]);
+    if (direct !== undefined) {
+        return direct;
+    }
+    for (const payload of [item.orderReadyPayload, item.itemPayload, item.originalItemPayload]) {
+        if (isRecord(payload)) {
+            const value = toFiniteNumber(payload[key]);
+            if (value !== undefined) {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+function buildCartLookup(cartItems) {
+    const byId = new Map();
+    const byPositionName = new Map();
+    for (const item of cartItems) {
+        const itemId = stringifyId(item.id ?? item.aiCartItemId);
+        const positionName = stringifyId(item.positionName);
+        if (itemId) {
+            byId.set(itemId, item);
+        }
+        if (positionName) {
+            byPositionName.set(positionName, item);
+        }
+    }
+    return { byId, byPositionName };
+}
+function findMatchingCartItem(spec, lookup) {
+    return ((spec.aiCartItemId ? lookup.byId.get(spec.aiCartItemId) : undefined) ??
+        lookup.byPositionName.get(spec.positionName));
+}
+function cartItemKey(item) {
+    return stringifyId(item.id ?? item.aiCartItemId) ?? stringifyId(item.positionName) ?? '';
+}
+/**
+ * Cross-check projected placement specs against the real AI cart manifest.
+ * Returns blocking issues (refuse the write) and soft warnings.
+ */
+function crossCheckPlacementsAgainstCart(specs, cartItems, options = {}) {
+    const widthTol = options.widthToleranceInches ?? DEFAULT_WIDTH_TOLERANCE;
+    const heightTol = options.heightToleranceInches ?? DEFAULT_HEIGHT_TOLERANCE;
+    const depthTol = options.depthToleranceInches ?? DEFAULT_DEPTH_TOLERANCE;
+    const lookup = buildCartLookup(cartItems);
+    const blocking = [];
+    const warnings = [];
+    const usedItemKeys = new Map(); // cart item key -> first positionName that used it
+    let matchedCount = 0;
+    for (const spec of specs) {
+        const item = findMatchingCartItem(spec, lookup);
+        if (!item) {
+            blocking.push({
+                positionName: spec.positionName,
+                code: 'no_matching_cart_item',
+                message: `Placement "${spec.positionName}" does not match any active AI cart item by aiCartItemId or positionName. ` +
+                    'Create the AI cart item first (one physical cabinet = one cart item) and reference its backend id/positionName. ' +
+                    'Do not place cabinets that are not in the manifest.',
+            });
+            continue;
+        }
+        matchedCount += 1;
+        const key = cartItemKey(item);
+        const priorPositionName = usedItemKeys.get(key);
+        if (priorPositionName !== undefined && priorPositionName !== spec.positionName) {
+            blocking.push({
+                positionName: spec.positionName,
+                code: 'duplicate_cart_item_reference',
+                message: `Placements "${priorPositionName}" and "${spec.positionName}" both resolve to the same AI cart item. ` +
+                    'One physical cabinet can have only one placement per canvas. If this is really two cabinets, create a ' +
+                    'second AI cart item; if it is one cabinet, use a single placement.',
+            });
+        }
+        else if (priorPositionName === undefined) {
+            usedItemKeys.set(key, spec.positionName);
+        }
+        const cartWidth = extractCartItemDimension(item, 'width');
+        if (cartWidth === undefined) {
+            warnings.push({
+                positionName: spec.positionName,
+                code: 'cart_item_dimensions_unknown',
+                message: `AI cart item for "${spec.positionName}" has no readable width; could not verify the placement width ` +
+                    'against the manifest. Confirm the cart item is configured with real catalog dimensions.',
+            });
+        }
+        else if (Math.abs(cartWidth - spec.widthInches) > widthTol) {
+            blocking.push({
+                positionName: spec.positionName,
+                code: 'width_mismatch',
+                message: `Placement "${spec.positionName}" width ${spec.widthInches}" does not match the AI cart item width ` +
+                    `${cartWidth}" (tolerance ${widthTol}"). A box wider than its real cabinet usually means a run was lumped ` +
+                    'into one box; split it into one cabinet per item, or correct the cart item width.',
+            });
+        }
+        if (spec.heightInches !== undefined) {
+            const cartHeight = extractCartItemDimension(item, 'height');
+            if (cartHeight !== undefined && Math.abs(cartHeight - spec.heightInches) > heightTol) {
+                blocking.push({
+                    positionName: spec.positionName,
+                    code: 'height_mismatch',
+                    message: `Placement "${spec.positionName}" height ${spec.heightInches}" does not match the AI cart item height ` +
+                        `${cartHeight}" (tolerance ${heightTol}"). For base cabinets use the body height (excluding toekick and ` +
+                        'countertop) and make the cart item height match.',
+                });
+            }
+        }
+        if (spec.depthInches !== undefined) {
+            const cartDepth = extractCartItemDimension(item, 'depth');
+            if (cartDepth !== undefined && Math.abs(cartDepth - spec.depthInches) > depthTol) {
+                blocking.push({
+                    positionName: spec.positionName,
+                    code: 'depth_mismatch',
+                    message: `Plan footprint "${spec.positionName}" depth ${spec.depthInches}" does not match the AI cart item depth ` +
+                        `${cartDepth}" (tolerance ${depthTol}").`,
+                });
+            }
+        }
+    }
+    if (options.reportCoverage) {
+        const referencedKeys = new Set();
+        for (const spec of specs) {
+            const item = findMatchingCartItem(spec, lookup);
+            if (item) {
+                referencedKeys.add(cartItemKey(item));
+            }
+        }
+        for (const item of cartItems) {
+            const key = cartItemKey(item);
+            if (key && !referencedKeys.has(key)) {
+                const positionName = stringifyId(item.positionName) ?? key;
+                warnings.push({
+                    positionName,
+                    code: 'cart_item_without_placement',
+                    message: `Active AI cart item "${positionName}" has no placement in this write. If it belongs on this canvas, ` +
+                        'add it; if it only appears on another view, this is expected.',
+                });
+            }
+        }
+    }
+    return { matchedCount, blocking, warnings };
+}

package/dist/tools/elevation-run-segmentation.js

@@ -0,0 +1,99 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Elevation run segmentation.
+//
+// Second root cause of bad placement (after raw pixel-guessing): the agent
+// does not reliably decide HOW MANY physical cabinets a dimensioned run holds,
+// or WHAT front type each is. It draws one rectangle around a whole run — e.g.
+// a 3'-0" "EQ A | EQ A" upper run that is actually two double-door cabinets gets
+// treated as a single cabinet.
+//
+// This module makes segmentation explicit and checkable. The agent enumerates
+// each module of a run with its real width and declared front type; this code
+// tiles them contiguously (computing each module's along-wall start so there is
+// exactly one box per cabinet) and emits warnings when the declared layout is
+// implausible or contradicts the dimension chain the agent says it read. The
+// act of filling in per-module front types + widths forces the single-vs-double
+// and one-vs-many reasoning the model was skipping.
+//
+// Pure (no IO) so it can be unit-tested directly.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.segmentElevationRun = segmentElevationRun;
+const DEFAULT_MAX_SINGLE_CABINET_WIDTH = 48;
+const DEFAULT_REVEAL = 0;
+// Industry-typical door sizing used only to raise warnings, never hard errors.
+const SINGLE_DOOR_MAX_WIDTH = 24;
+const DOUBLE_DOOR_MIN_WIDTH = 12;
+const RUN_TOTAL_TOLERANCE = 0.51;
+/**
+ * Tile a run's modules left-to-right and collect segmentation warnings.
+ * This never throws; structural requirements (non-empty modules, positive
+ * widths, required frontType) are enforced by the Zod schema at the tool layer.
+ */
+function segmentElevationRun(run) {
+    const reveal = run.revealBetweenModulesInches ?? DEFAULT_REVEAL;
+    const maxSingle = run.maxSingleCabinetWidthInches ?? DEFAULT_MAX_SINGLE_CABINET_WIDTH;
+    const modules = [];
+    let cursor = run.runStartInches;
+    for (let i = 0; i < run.modules.length; i += 1) {
+        const moduleSpec = run.modules[i];
+        const start = cursor;
+        const end = start + moduleSpec.widthInches;
+        modules.push({ ...moduleSpec, horizontalStartInches: start, horizontalEndInches: end });
+        cursor = end + reveal;
+    }
+    const modulesWidthInches = run.modules.reduce((sum, m) => sum + m.widthInches, 0);
+    const occupiedSpanInches = modules.length > 0
+        ? modules[modules.length - 1].horizontalEndInches - modules[0].horizontalStartInches
+        : 0;
+    const warnings = collectSegmentationWarnings(run, modules, modulesWidthInches, maxSingle);
+    return { modules, modulesWidthInches, occupiedSpanInches, warnings };
+}
+function collectSegmentationWarnings(run, modules, modulesWidthInches, maxSingle) {
+    const warnings = [];
+    // Under-segmentation: a single very wide module is the classic "one box for
+    // multiple cabinets" failure.
+    for (const m of modules) {
+        if (m.widthInches > maxSingle) {
+            warnings.push(`Module "${m.positionName}" is ${m.widthInches}" wide, above the ${maxSingle}" single-cabinet threshold. ` +
+                'Verify this is one physical cabinet and not several lumped into one box; if the dimension chain subdivides ' +
+                'this span, split it into separate cabinets with their own cart items and placements.');
+        }
+    }
+    // Front-type vs width plausibility.
+    for (const m of modules) {
+        if (m.frontType === 'single_door' && m.widthInches > SINGLE_DOOR_MAX_WIDTH) {
+            warnings.push(`Module "${m.positionName}" is declared single_door but is ${m.widthInches}" wide (> ${SINGLE_DOOR_MAX_WIDTH}"). ` +
+                'A single door this wide is unusual; confirm it is not a double_door cabinet or two separate cabinets.');
+        }
+        if ((m.frontType === 'double_door' || m.frontType === 'pair_of_doors') && m.widthInches < DOUBLE_DOOR_MIN_WIDTH) {
+            warnings.push(`Module "${m.positionName}" is declared ${m.frontType} but is only ${m.widthInches}" wide (< ${DOUBLE_DOOR_MIN_WIDTH}"). ` +
+                'Two doors in a span this narrow is unusual; confirm the front type.');
+        }
+    }
+    // Declared subdivisions vs module count: the secondary dimension chain
+    // ("EQ A | EQ A") is explicit segmentation evidence in the drawing.
+    if (run.declaredSubdivisionCount !== undefined && run.declaredSubdivisionCount > modules.length) {
+        warnings.push(`You read ${run.declaredSubdivisionCount} equal subdivisions in the dimension chain but provided only ` +
+            `${modules.length} module(s). Confirm whether each subdivision is a separate cabinet (split it) or just ` +
+            'multiple doors within one cabinet (keep one module and set the front type accordingly).');
+    }
+    // Tiled width vs the run's primary dimension string.
+    if (run.expectedRunTotalInches !== undefined) {
+        const reveal = run.revealBetweenModulesInches ?? DEFAULT_REVEAL;
+        const totalWithReveals = modulesWidthInches + reveal * Math.max(0, modules.length - 1);
+        const delta = run.expectedRunTotalInches - totalWithReveals;
+        if (Math.abs(delta) > RUN_TOTAL_TOLERANCE) {
+            warnings.push(`Module widths${reveal ? ' plus reveals' : ''} total ${round2(totalWithReveals)}" but the run dimension is ` +
+                `${run.expectedRunTotalInches}" (off by ${round2(delta)}"). Re-check module count, widths, or reveal: ` +
+                (delta > 0
+                    ? 'the run has unaccounted width — a cabinet or filler may be missing.'
+                    : 'the modules overflow the run — a width is too large or there are too many cabinets.'));
+        }
+    }
+    return warnings;
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}

package/dist/tools/orders.js

@@ -412,6 +412,8 @@ const DeleteSavedCartArticlesSchema = zod_1.z.object({
 });
 const CreateOrderSchema = zod_1.z.object({
     articles: flexArray(exports.ArticleItemSchema).describe('Line items to order.'),
+    projectId: zod_1.z.number().int().positive().optional().describe('Optional existing project ID to place this order into. Use list_projects or create_project first. ' +
+        'When provided, the backend copies that project name/address and pricing snapshot to the order.'),
     projectName: zod_1.z.string().describe('Project name for this order'),
     purchaseOrder: zod_1.z.string().describe('Purchase order number'),
     projectAddress: ProjectAddressSchema.optional().describe('Project address (where cabinets will be installed)'),

package/dist/tools/placement-projection.js

@@ -0,0 +1,119 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Deterministic AIDrawingTool placement projection.
+//
+// Root cause of inaccurate cabinet placement: the agent was asked to eyeball
+// raw centerX/centerY/width/height pixel rectangles directly from a drawing.
+// Vision-language models are unreliable at precise pixel localization, so boxes
+// drifted, overlapped, doubled, and overshot — especially across rows of
+// near-identical modules where per-box error accumulates.
+//
+// This module removes that guesswork. The agent establishes ONE pixels-per-inch
+// calibration per canvas (from a visible dimension string + the floor/Z0 line +
+// one origin reference) and supplies each cabinet's REAL inch dimensions and
+// position. Every placement rectangle is then computed from the same scale, so
+// the entire layout is internally consistent and free of cumulative drift.
+//
+// These functions are pure (no IO) so they can be unit-tested directly.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectElevationPlacement = projectElevationPlacement;
+exports.projectPlanPlacement = projectPlanPlacement;
+exports.projectPlanWallAnchoredPlacement = projectPlanWallAnchoredPlacement;
+exports.isProjectedPlacementOutsideImage = isProjectedPlacementOutsideImage;
+const PIXEL_PRECISION = 2;
+function roundPx(value) {
+    const factor = 10 ** PIXEL_PRECISION;
+    return Math.round(value * factor) / factor;
+}
+function horizontalSign(direction) {
+    return direction === 'right' ? 1 : -1;
+}
+function elevationVerticalSign(direction) {
+    // Height-above-floor grows upward; screen Y grows downward.
+    // 'up' positive => increasing height moves toward smaller pixel Y.
+    return direction === 'up' ? -1 : 1;
+}
+function planVerticalSign(direction) {
+    return direction === 'down' ? 1 : -1;
+}
+function elevationPixelX(horizontalInches, cal) {
+    return (cal.horizontalOriginPx.x +
+        horizontalSign(cal.horizontalAxisPositiveDirection) *
+            (horizontalInches - cal.horizontalOriginCoordinateInches) *
+            cal.horizontalPixelsPerInch);
+}
+function elevationPixelY(heightAboveFloorInches, cal) {
+    return (cal.floorZ0Px +
+        elevationVerticalSign(cal.verticalAxisPositiveDirection) *
+            heightAboveFloorInches *
+            cal.verticalPixelsPerInch);
+}
+/** Project one elevation cabinet face spec into an image-pixel rectangle. */
+function projectElevationPlacement(spec, cal) {
+    const bottomFromFloor = spec.bottomFromFloorInches ?? 0;
+    const leftPx = elevationPixelX(spec.horizontalStartInches, cal);
+    const rightPx = elevationPixelX(spec.horizontalStartInches + spec.widthInches, cal);
+    const bottomPx = elevationPixelY(bottomFromFloor, cal);
+    const topPx = elevationPixelY(bottomFromFloor + spec.heightInches, cal);
+    return {
+        centerX: roundPx((leftPx + rightPx) / 2),
+        centerY: roundPx((topPx + bottomPx) / 2),
+        width: roundPx(Math.abs(rightPx - leftPx)),
+        height: roundPx(Math.abs(bottomPx - topPx)),
+        rotation: 0,
+    };
+}
+function planPixelX(xInches, cal) {
+    return cal.roomOriginPx.x + horizontalSign(cal.xPositiveDirection) * xInches * cal.pixelsPerInch;
+}
+function planPixelY(yInches, cal) {
+    return cal.roomOriginPx.y + planVerticalSign(cal.yPositiveDirection) * yInches * cal.pixelsPerInch;
+}
+/** Project one plan cabinet footprint spec into an image-pixel rectangle. */
+function projectPlanPlacement(spec, cal) {
+    const rotation = ((spec.rotation ?? 0) % 360 + 360) % 360;
+    const rotatedQuarterTurn = rotation === 90 || rotation === 270;
+    const inchesAlongX = rotatedQuarterTurn ? spec.depthInches : spec.widthInches;
+    const inchesAlongY = rotatedQuarterTurn ? spec.widthInches : spec.depthInches;
+    return {
+        centerX: roundPx(planPixelX(spec.centerXInches, cal)),
+        centerY: roundPx(planPixelY(spec.centerYInches, cal)),
+        width: roundPx(inchesAlongX * cal.pixelsPerInch),
+        height: roundPx(inchesAlongY * cal.pixelsPerInch),
+        // The rectangle is axis-aligned to the room/image; orientation is captured
+        // by the dimension swap above, so the rendered box rotation stays 0.
+        rotation: 0,
+    };
+}
+/**
+ * Project a wall-anchored plan footprint. The back edge lands exactly on
+ * wallBackEdgeInches; the box extends widthInches along the wall and depthInches
+ * into the room. The rendered rectangle is axis-aligned (rotation 0).
+ */
+function projectPlanWallAnchoredPlacement(spec, cal) {
+    const sign = spec.depthDirection === 'positive' ? 1 : -1;
+    const alongCenter = spec.alongWallStartInches + spec.widthInches / 2;
+    const depthCenter = spec.wallBackEdgeInches + sign * (spec.depthInches / 2);
+    const centerXInches = spec.depthAxis === 'x' ? depthCenter : alongCenter;
+    const centerYInches = spec.depthAxis === 'y' ? depthCenter : alongCenter;
+    const inchesAlongX = spec.depthAxis === 'x' ? spec.depthInches : spec.widthInches;
+    const inchesAlongY = spec.depthAxis === 'y' ? spec.depthInches : spec.widthInches;
+    return {
+        centerX: roundPx(planPixelX(centerXInches, cal)),
+        centerY: roundPx(planPixelY(centerYInches, cal)),
+        width: roundPx(inchesAlongX * cal.pixelsPerInch),
+        height: roundPx(inchesAlongY * cal.pixelsPerInch),
+        rotation: 0,
+    };
+}
+/** True when any part of the rectangle falls outside the calibration image. */
+function isProjectedPlacementOutsideImage(placement, imageSizePx) {
+    const halfWidth = placement.width / 2;
+    const halfHeight = placement.height / 2;
+    const minX = placement.centerX - halfWidth;
+    const maxX = placement.centerX + halfWidth;
+    const minY = placement.centerY - halfHeight;
+    const maxY = placement.centerY + halfHeight;
+    return minX < 0 || minY < 0 || maxX > imageSizePx.width || maxY > imageSizePx.height;
+}