feat(mcp): place_design creates a validated design on today's hosts (AK-02 2/3)

[Aymericr]

Merge as one unit (coordinator ruling on the Codex R8 finding): #948, #953 and the private AK-02 3/3 PR (chat tools and scene programs) merge the same day, so there is no window where MCP has design tools that chat and programs lack. The owner's AD-6 exception covers today's surfaces.

Stacked on #948 (AK-02 1/3). Until #948 merges, this diff also shows its commit; the change here is commits dde17bf, 2036305 and 30de136 (rebased onto editor main with #938 merged, 5e7e128), plus the review fixes.

What

Agents can now create a design they validated on today's hosts, with typed refusals.

• Core: planDesignPlacement(nodes, request).
  1. It validates the design with validateDesign, the same authority as validate_design. The design can be an object or a JSON string.
  2. It picks the host from the design's mounting, using today's hosting fields only:
     • floor designs go on a level, or on a slab or zone of it (the level becomes the parent). They can also go on a named surface of a placed design (attachments[childId] = surfaceId);
     • wall-side designs go on a straight wall face (wallId/side, with position = along, height and offset of the reference);
     • ceiling designs go under a ceiling (plan x/z).
  3. It builds the node and runs validateProceduralRelations directly. The mount checks therefore hold without the node registry: before this, the trial saw ceiling and wall designs accepted as level children when builtinPlugin was not loaded.
  4. It returns { node, parentId, hostUpdate? } or throws DesignPlacementError. The codes are invalid_design (with diagnostics), invalid_placement, host_not_found, wrong_host, unknown_surface and does_not_fit, plus the apply_patch guard codes. A wall misfit says where the reference fits, for example "fits along 0.317–3.683 m and at height 0.47–2.23 m on this wall".
• MCP: place_design wraps it and only creates.
  • The node, plus the host's attachment update for a surface, goes through applyPatch.
  • A refusal is a tool error whose JSON text is { code, message, diagnostics? }; the message starts with the code.
  • It adds one line to the agent guide and one README row. The annotation inventory goes from 50 to 51 tools (additive).

Codex review fixes (failing cases in the commit before 96b80a3): SceneBridge.applyPatch commits a whole patch as one history step, so a design-surface placement undoes in one step; designs above 24 KiB are refused with design_too_large (R7, as #947); an explicit existing id is refused with node_exists before the surface host's shadow graph is built. The known limit about two undo steps no longer applies.

Why

Owner decision AD-6: agent design tools ship now on today's surfaces. This is an explicit, owner-approved exception to charter R8, which otherwise waits for the P-04 tool kernel. It is kernel-shaped: one core function, and the MCP adapter adds only transport. Following the CHALLENGE correction, it uses v1 inline recipes and today's hosting fields; pin and Mount arguments wait for AK-01/P-05 and the Mount decision.

Create-only goes through #938's patch guards. place_design runs assertPatchKeepsIdentity over its create (and a surface host's attachment update) before applyPatch, so an explicit existing id is refused with apply_patch's own node_exists code and message; planDesignPlacement no longer carries its own check (30de136). Refusals are tool errors with JSON { code, message, diagnostics? }, like apply_patch's, because an McpError keeps only its message.

Failing case before this PR: no tool placed a design.

• tools/call place_design returns "tool not found".
• Through apply_patch, an agent had to hand-write the node, and without builtinPlugin a wall-side or ceiling design was accepted as a level child (trial.md, "mount relations are enforced only when the process has loaded builtinPlugin").

Proof

Command	Result
bun test src/procedural-items/design-placement.test.ts (core)	18 pass, 0 fail
bun test src (core)	3012 pass, 0 fail
bun test (mcp)	388 pass, 0 fail
bun test scripts/openai-tool-annotation-policy.test.ts, bun run skills:validate	5 pass; 69 pass
bun run check, core check-types, mcp tsgo --noEmit	clean (6 pre-existing infos)

The tests use the trial fixtures:

• the E5 louver on both faces of a wall, and refused when too high, with the fit range;
• the E2 air handler under a ceiling, and refused outside its polygon;
• the example table on a level and on a slab, then a vase on its support surface: the attachment is written, an overlapping second vase is refused, and an unknown surface lists the valid ones;
• 11 refusal cases, each asserting the code prefix, plus node refusals that name the field (invalid_placement: node: Unknown slot paint);
• through MCP: the scene is unchanged after every refusal, and validate_scene stays valid after placements.

House effect: no change. This is an agent-facing tool, and the converter, viewer and bake never call it.

Eval (AK-02 3/3, cap-design-louver)

Latest run (2026-09-28, on the review-fix heads #948 eaf8c7cec / #953 96b80a3b6, prompt with "place exactly one vent", MCP lane with read_resource and prompt mcp-lane-v2; records bench/ai-chat/runs/eval-2026-09-28T04-35-16-586Z direct, …T04-44-47-852Z mcp):

Lane	Valid wall-side louver of the right size	Exactly one placed	Notes
direct	3/3	0/3 (+6, +7, +2)	The no-duplicate line did not help: agents re-place after each re-validation. Two runs hit the 40-segment ceiling; 21–30 validate_design calls
mcp	0/3	2/3	Every run read pascal://schema/design first and placed within 27–87 s, but both placed louvers are 0.45–0.48 m deep instead of ~0.08 m; the third run never placed

Net: the design tools work end to end on both lanes. Duplicate placement in chat and depth control via MCP are prompt and task findings for a follow-up, not tool defects.

R1–R9

Rule	Check
R1	API v1 and node schemas unchanged; additive exports
R3	The one writer path validates the final graph for the new node and its surface host (validateProceduralRelations) before applyPatch; no new reference kinds
R5	Agents can place designs on MCP; chat and scene programs follow in AK-02 3/3 over the same function
R7	Inline v1 recipes; pins wait for AK-01/P-05
R8	AD-6 exception (above): typed input, coded refusals, annotation inventory. The eval and the second adapter come in AK-02 3/3
R2, R4, R6, R9	Unaffected

For Wassim to review

design-placement.ts reuses validateProceduralRelations and proceduralLocalPose and mirrors prepareProceduralPlacement. It also adds slab and zone resolution and design-surface attachments. Check that the wall position semantics (reference along, height and offset) match how the move tool writes them.

Known limits

• Hosted collaboration projects still refuse MCP whole-scene writes (P-05/P-08). Inline designs above the 64 KiB operation cap wait for AK-01.
• Floor designs get no floor-fit or collision check, the same as place_item; check_collisions reports them.

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds a new agent-driven scene mutation path and placement rules (wall/ceiling hosts, attachments) that must stay consistent with existing procedural relations; patch history grouping changes undo behavior for mixed batches.

Overview
Agents get a design validation and placement pipeline for procedural-item recipes: core validateDesign / describeDesignSchema (schema, sweeps, measurements, coded diagnostics) and planDesignPlacement, which validates the recipe, resolves hosts from mounting (floor/slab/zone/design surface, wall-side, ceiling), runs validateProceduralRelations without relying on the node registry, and returns create plans or DesignPlacementError codes (including wall fit ranges and a 24 KiB inline cap).

MCP exposes read-only validate_design, create-only place_design (via applyPatch + patch identity guards), and resource pascal://schema/design, with agent-guide/README updates. Trial HVAC/louver/stair-guard fixtures back core and MCP tests.

Renderer alignment: shared PRIMITIVE_TESSELLATION, shapeTriangles, and shapeBounds so validation counts match buildProceduralGeometry. apply_patch is wrapped in runAsSingleSceneHistoryStep so a create plus surface attachment update undo together. OpenAI tool annotation inventory bumps 49 → 51.

^{Reviewed by Cursor Bugbot for commit 96b80a3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: 045136d6-d42f-4d3c-a6d1-0051f452ef15