@compilr-dev/sdk 0.29.8 → 0.31.0

package/dist/platform/tools/scene-tools.js

@@ -0,0 +1,511 @@
+/**
+ * Scene Tools — agents build 3D scenes as validated JSON (3d-canvas-spec §6).
+ *
+ * 7 tools: scene_create, scene_get, scene_add_object, scene_update_object,
+ * scene_remove_object, scene_set_camera, scene_screenshot.
+ *
+ * Every edit goes through the scene writer (`platform/scene-writer.ts`) — the same instance the
+ * host's inspector uses — so user and agent edits serialise and the agent is TOLD about the
+ * user's changes: a successful result starts with "The user edited this scene since your last
+ * call: …" when there are any.
+ *
+ * Names carry the `scene_` prefix: generic names (`add_object`) collide with MCP servers, and
+ * hosts refresh views on tool-name prefixes.
+ */
+import { defineTool, createErrorResult } from '@compilr-dev/agents';
+import { createSceneWriter } from '../scene-writer.js';
+import { SCENE_MAX_BATCH, SCENE_OBJECT_TYPES, describeScene, serializeScene, } from '../../canvas/scene.js';
+import { formatUserEditNotice, } from '../../canvas/scene-ops.js';
+export const SCENE_TOOL_NAMES = [
+    'scene_create',
+    'scene_get',
+    'scene_add_object',
+    'scene_update_object',
+    'scene_remove_object',
+    'scene_set_camera',
+    'scene_screenshot',
+];
+const DEFAULT_SHOT = { width: 1280, height: 800 };
+const SHOT_MIN = 320;
+const SHOT_MAX = 2048;
+/** "sofa · box · Sofa" rows, indented under their group parent. */
+export function sceneOutline(scene) {
+    if (scene.objects.length === 0)
+        return '(no objects yet)';
+    const byParent = new Map();
+    const ids = new Set(scene.objects.map((o) => o.id));
+    for (const o of scene.objects) {
+        const key = o.group !== undefined && ids.has(o.group) ? o.group : undefined;
+        const list = byParent.get(key) ?? [];
+        list.push(o);
+        byParent.set(key, list);
+    }
+    /** The type column, with what changes its shape: "group (3 inside)", "cone (4 sides)", … */
+    const typeOf = (o) => {
+        switch (o.type) {
+            case 'group': {
+                const n = byParent.get(o.id)?.length ?? 0;
+                return n === 0 ? 'group (empty)' : `group (${String(n)} inside)`;
+            }
+            case 'cone':
+            case 'cylinder':
+                return o.segments !== undefined ? `${o.type} (${String(o.segments)} sides)` : o.type;
+            case 'extrude':
+                return o.axis !== undefined && o.axis !== 'y' ? `extrude (along ${o.axis})` : o.type;
+            case 'wedge':
+                return o.ridge !== undefined && o.ridge !== 0.5
+                    ? `wedge (ridge ${String(o.ridge)})`
+                    : o.type;
+            default:
+                return o.type;
+        }
+    };
+    const rows = [];
+    const walk = (parent, depth) => {
+        for (const o of byParent.get(parent) ?? []) {
+            const lock = o.locked ? ' · locked' : '';
+            rows.push(`${'  '.repeat(depth)}${o.id} · ${typeOf(o)}${o.name ? ` · ${o.name}` : ''}${lock}`);
+            if (depth < 8)
+                walk(o.id, depth + 1);
+        }
+    };
+    walk(undefined, 0);
+    return rows.join('\n');
+}
+function clampShot(v, fallback) {
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return fallback;
+    return Math.round(Math.max(SHOT_MIN, Math.min(SHOT_MAX, v)));
+}
+/**
+ * Render a scene through the host's `renderSceneToImage` — shared by scene_screenshot and
+ * canvas_screenshot (either tool works on a scene).
+ */
+export async function screenshotScene(ctx, args) {
+    const render = ctx.canvasRenderer?.renderSceneToImage?.bind(ctx.canvasRenderer);
+    if (!render) {
+        return {
+            available: false,
+            text: '3D scene rendering is not available in this environment — open the scene in compilr.dev ' +
+                `Desktop to see it. Rely on scene_get instead: "${args.title}" has ${describeScene(args.scene)}.`,
+        };
+    }
+    const width = clampShot(args.width, DEFAULT_SHOT.width);
+    const height = clampShot(args.height, DEFAULT_SHOT.height);
+    const img = await render({ scene: args.scene, width, height });
+    const view = args.scene.camera ? 'its camera' : 'the fitted view';
+    return {
+        available: true,
+        text: `Rendered scene "${args.title}" (${describeScene(args.scene)}) at ${String(width)}×${String(height)} from ${view}. ` +
+            'Check proportions, gaps, overlaps and floating objects (position.y is the BOTTOM); fix with ' +
+            'scene_update_object and screenshot again.',
+        image: { data: img.data, mediaType: img.mediaType, width: img.width, height: img.height },
+    };
+}
+const VEC3 = { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3 };
+/** The per-object fields, shared by the single-object form and each entry of `objects`. */
+const OBJECT_PROPERTIES = {
+    type: {
+        type: 'string',
+        enum: SCENE_OBJECT_TYPES,
+        description: 'box (size [w,h,d]) · sphere (radius) · cylinder / cone (radius, height, optional segments) · torus (radius, tube; lies flat) · ' +
+            'extrude (points + height, optional axis) for walls, floors and profiles · wedge (size [w,h,d], optional ridge) — a ' +
+            'triangular prism for roofs · group — a container with no geometry: give it your own id and put parts in it with ' +
+            'group: "<id>". There is no "wall" type — use extrude.',
+    },
+    position: {
+        ...VEC3,
+        description: "Metres [x, y, z]. y is the object's BOTTOM: y = 0 sits on the floor.",
+    },
+    id: {
+        type: 'string',
+        description: 'Your own id (lowercase letters, digits, - or _; ≤ 48), e.g. "house", "roof-left". Choose ids for ' +
+            'groups so later objects — even in the same batch — can say group: "<id>". Must be new: an id already ' +
+            'in the scene is an error (never renamed). Omit to generate one from name.',
+    },
+    name: { type: 'string', description: 'Display name (≤ 80 chars), e.g. "Sofa".' },
+    size: {
+        ...VEC3,
+        description: 'box / wedge: [width (x), height (y), depth (z)] in metres (0.01–500).',
+    },
+    radius: {
+        type: 'number',
+        description: 'sphere/cylinder/cone/torus: radius in metres. With segments it is the corner (circum-) radius.',
+    },
+    height: {
+        type: 'number',
+        description: 'cylinder/cone: height in metres. extrude: how far it extends along its axis.',
+    },
+    tube: { type: 'number', description: 'torus only: tube radius (≤ radius).' },
+    segments: {
+        type: 'integer',
+        minimum: 3,
+        maximum: 64,
+        description: 'cone/cylinder only: number of flat sides (3–64); omit for smooth. cone + 4 = a pyramid (hip roof) — ' +
+            'its corners point along ±x/±z, so add rotation [0, 45, 0] for sides parallel to the axes (side = radius·√2).',
+    },
+    points: {
+        type: 'array',
+        items: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 },
+        description: 'extrude only: outline [[a, b], …] local to position, 3–256 points, not self-intersecting. ' +
+            'axis "y" (default): [x, z] plan points, rising 0 → height. axis "z": [x, y] side profile ' +
+            '(b is up), pushed 0 → height along +z. axis "x": [z, y] side profile (b is up), pushed 0 → height along +x. ' +
+            "The profile's lowest point sits at position.y.",
+    },
+    axis: {
+        type: 'string',
+        enum: ['x', 'y', 'z'],
+        description: 'extrude only: the direction it extends. "y" (default) = a plan outline rising vertically (walls, floors); ' +
+            '"x" / "z" = a side profile (a gable, a roof section) extended horizontally — see points.',
+    },
+    ridge: {
+        type: 'number',
+        description: 'wedge only: where the apex sits across the width, 0–1 (default 0.5 = centred; 0 or 1 = a lean-to). ' +
+            'The triangle is in the x–y plane; the ridge runs along z (the depth). Rotate [0, 90, 0] for a ridge along x.',
+    },
+    rotation: {
+        ...VEC3,
+        description: 'Degrees [x, y, z]. Rotate about Y; x/z tilt breaks the floor rule.',
+    },
+    color: {
+        type: 'string',
+        description: '"#RRGGBB". Omit for the neutral palette — keep neutral colours unless asked. Not on a group.',
+    },
+    group: {
+        type: 'string',
+        description: 'Parent id — normally a type "group" container, created earlier or in the same batch. position/rotation ' +
+            "become relative to the parent (y = 0 is the group's y); moving the group moves its children.",
+    },
+    material: {
+        type: 'object',
+        description: '{ roughness 0–1, metalness 0–1, opacity 0.05–1 }. Not on a group.',
+        properties: {
+            roughness: { type: 'number' },
+            metalness: { type: 'number' },
+            opacity: { type: 'number' },
+        },
+    },
+    locked: {
+        type: 'boolean',
+        description: 'Lock against USER edits in the inspector (agents can still edit it).',
+    },
+};
+const OBJECT_FIELD_NAMES = Object.keys(OBJECT_PROPERTIES);
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createSceneTools(config, options) {
+    const ctx = config.context;
+    const canvases = ctx.canvases;
+    if (!canvases)
+        throw new Error('canvases repository required');
+    const writer = options?.writer ?? ctx.sceneWriter ?? createSceneWriter(canvases);
+    /** The calling agent (keys the "told about user edits" mark per agent). */
+    const agentKey = () => config.hooks?.resolveOwner?.('self') ?? '';
+    const agentSource = () => ({ kind: 'agent', agentId: agentKey() || undefined });
+    /** Prepend the user-edit notice (successful results only) and mark it delivered. */
+    const withNotice = (canvasId, body) => {
+        const notice = formatUserEditNotice(writer.consumeUserEdits(canvasId, agentKey()));
+        return notice ? `${notice}\n\n${body}` : body;
+    };
+    const errorMessage = (verb, error) => `Failed to ${verb}: ${error instanceof Error ? error.message : String(error)}`;
+    /** Apply ops as the agent and shape the tool result. */
+    const applyAsAgent = async (canvasId, ops, idLine) => {
+        const r = await writer.apply(canvasId, ops, agentSource());
+        if (!r.ok)
+            return createErrorResult(r.error);
+        const lines = [...r.summaries];
+        const ids = idLine(r.ids);
+        if (ids)
+            lines.push(ids);
+        lines.push(`Scene "${r.title}": ${describeScene(r.scene)} · rev ${String(r.rev)}`);
+        if (r.warnings.length)
+            lines.push('', ...r.warnings);
+        return {
+            success: true,
+            result: withNotice(canvasId, lines.join('\n')),
+            // Structured sibling for hosts (view refresh / P2 grow-in) — prose stays for the model.
+            scene: { canvasId, rev: r.rev, ids: r.ids, action: ops[0]?.op },
+        };
+    };
+    // ---------------------------------------------------------------------------
+    const sceneCreateTool = defineTool({
+        name: 'scene_create',
+        description: 'Create a 3D SCENE canvas — objects in metres the user can orbit, select, edit and export. ' +
+            'Scenes are JSON data, not HTML/code (never use canvas_write for 3D). Pass only a title for an ' +
+            'empty scene, then build it with scene_add_object (up to 50 objects per call), or pass a whole ' +
+            'scene { objects: [...], camera?, lights? }. Returns the canvas ID used by every scene_* tool.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Scene title (shown in the library and tab).' },
+                scene: {
+                    type: 'object',
+                    description: 'Optional initial scene: { objects: [...], camera?: { position, target }, lights?: [...] }. ' +
+                        'version/units/name default from the title. Each object is { id, type, position, … } as in scene_add_object.',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Optional project id. Defaults to the current project.',
+                },
+            },
+            required: ['title'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No active project. Provide project_id or select a project.');
+                }
+                const r = await writer.create({ projectId, title: input.title, scene: input.scene });
+                if (!r.ok)
+                    return createErrorResult(r.error);
+                // Mark first contact so later user edits are announced to this agent.
+                writer.consumeUserEdits(r.canvas.id, agentKey());
+                /*
+                  ⚠️ Same prose + `canvas` sibling as canvas_write: Desktop reveals/auto-splits new
+                  canvases from this exact shape (`renderer/src/lib/canvas-authored.ts`).
+                */
+                return {
+                    success: true,
+                    result: `Created canvas "${r.canvas.title}" (scene)\nID: ${String(r.canvas.id)}\n` +
+                        `${describeScene(r.scene)}. Add objects with scene_add_object; check it with scene_screenshot.`,
+                    canvas: {
+                        id: r.canvas.id,
+                        title: r.canvas.title,
+                        type: r.canvas.type,
+                        action: 'created',
+                    },
+                };
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('create scene', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneGetTool = defineTool({
+        name: 'scene_get',
+        description: 'Read a 3D scene: the full JSON (pretty-printed) plus a one-line summary. Always read before ' +
+            'editing — the user edits scenes too, and object ids come from here.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const r = await writer.read(input.canvas_id);
+                if (!r.ok)
+                    return createErrorResult(r.error);
+                const body = `Scene "${r.title}" (canvas ${String(r.canvasId)}): ${describeScene(r.scene)} · rev ${String(r.rev)}\n\n` +
+                    serializeScene(r.scene);
+                return { success: true, result: withNotice(r.canvasId, body) };
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('read scene', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneAddObjectTool = defineTool({
+        name: 'scene_add_object',
+        description: 'Add one object to a 3D scene, or up to 50 at once with objects: [...] (atomic: all or none). ' +
+            "Units are metres; position.y is the object's BOTTOM (0 = on the floor); rotation in degrees about Y. " +
+            'Build hierarchically: a type "group" with your own id (e.g. "house", then "walls", "roof" inside it), ' +
+            'and its parts with group: "<id>" — a batch may name a group it creates itself. ' +
+            'Returns the new id(s) — yours, or generated from name when id is omitted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                ...OBJECT_PROPERTIES,
+                objects: {
+                    type: 'array',
+                    maxItems: SCENE_MAX_BATCH,
+                    description: `Batch form: up to ${String(SCENE_MAX_BATCH)} objects, each with the same fields as the single form (type, position, …). Use instead of the top-level fields.`,
+                    items: { type: 'object', properties: OBJECT_PROPERTIES, required: ['type', 'position'] },
+                },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const single = {};
+                for (const k of OBJECT_FIELD_NAMES)
+                    if (input[k] !== undefined)
+                        single[k] = input[k];
+                const hasSingle = Object.keys(single).length > 0;
+                let op;
+                if (input.objects !== undefined) {
+                    if (hasSingle) {
+                        return createErrorResult("Pass either one object's fields (type, position, …) or objects: [...], not both.");
+                    }
+                    if (!Array.isArray(input.objects)) {
+                        return createErrorResult('objects must be an array of objects.');
+                    }
+                    op = { op: 'add', objects: input.objects };
+                }
+                else {
+                    if (!hasSingle) {
+                        return createErrorResult('Nothing to add. Pass type + position (+ size/radius/height/…), or objects: [...].');
+                    }
+                    op = { op: 'add', object: single };
+                }
+                return await applyAsAgent(input.canvas_id, [op], (ids) => ids.length === 1 ? `ID: ${ids[0]}` : `IDs: ${ids.join(', ')}`);
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('add object', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneUpdateObjectTool = defineTool({
+        name: 'scene_update_object',
+        description: 'Change fields of one object in a 3D scene. patch is a SHALLOW merge — arrays (position, size, ' +
+            'points, rotation) and material are replaced whole; null clears an optional field (e.g. group). ' +
+            'id and type cannot change: remove the object and add it again. Read ids with scene_get first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                id: { type: 'string', description: 'The object id to change.' },
+                patch: {
+                    type: 'object',
+                    description: 'Fields to set, e.g. { "position": [1.2, 0, -0.4], "color": "#8FA3B0" }. Same fields as scene_add_object: ' +
+                        'size, radius, height, tube, points, segments (cone/cylinder), axis (extrude), ridge (wedge), group ' +
+                        '(move it into a group; null = back to the root), name, rotation, color/material (not on a group), locked.',
+                },
+            },
+            required: ['canvas_id', 'id', 'patch'],
+        },
+        execute: async (input) => {
+            try {
+                return await applyAsAgent(input.canvas_id, [{ op: 'update', id: input.id, patch: input.patch }], () => null);
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('update object', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneRemoveObjectTool = defineTool({
+        name: 'scene_remove_object',
+        description: 'Remove an object from a 3D scene. Objects grouped under it (its children) are removed too, ' +
+            'and the result lists them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                id: { type: 'string', description: 'The object id to remove.' },
+            },
+            required: ['canvas_id', 'id'],
+        },
+        execute: async (input) => {
+            try {
+                return await applyAsAgent(input.canvas_id, [{ op: 'remove', id: input.id }], () => null);
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('remove object', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneSetCameraTool = defineTool({
+        name: 'scene_set_camera',
+        description: 'Set the default view of a 3D scene: position + target in metres, or fit: true to clear it ' +
+            "(the viewer then frames all objects). The user's own orbiting never changes this.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                position: { ...VEC3, description: 'Camera position [x, y, z] in metres.' },
+                target: { ...VEC3, description: 'The point the camera looks at [x, y, z].' },
+                fit: {
+                    type: 'boolean',
+                    description: 'true = remove the stored camera and frame all objects.',
+                },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                let op;
+                if (input.fit === true) {
+                    if (input.position !== undefined || input.target !== undefined) {
+                        return createErrorResult('Pass position + target, or fit: true — not both.');
+                    }
+                    op = { op: 'camera', camera: { fit: true } };
+                }
+                else {
+                    if (input.position === undefined || input.target === undefined) {
+                        return createErrorResult('Pass both position and target ([x, y, z] in metres), or fit: true to frame all objects.');
+                    }
+                    op = {
+                        op: 'camera',
+                        camera: { position: input.position, target: input.target },
+                    };
+                }
+                return await applyAsAgent(input.canvas_id, [op], () => null);
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('set camera', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    const sceneScreenshotTool = defineTool({
+        name: 'scene_screenshot',
+        description: 'RENDER a 3D scene and SEE it — check proportions, overlaps, gaps and floating objects after ' +
+            'building. Uses the scene camera, or frames all objects when it has none. Only useful on a ' +
+            'vision-capable model; unavailable in hosts without a 3D viewer (e.g. the terminal).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                width: {
+                    type: 'number',
+                    description: `Image width in px (default ${String(DEFAULT_SHOT.width)}).`,
+                },
+                height: {
+                    type: 'number',
+                    description: `Image height in px (default ${String(DEFAULT_SHOT.height)}).`,
+                },
+            },
+            required: ['canvas_id'],
+        },
+        execute: async (input) => {
+            try {
+                const r = await writer.read(input.canvas_id);
+                if (!r.ok)
+                    return createErrorResult(r.error);
+                const shot = await screenshotScene(ctx, {
+                    canvasId: r.canvasId,
+                    title: r.title,
+                    scene: r.scene,
+                    width: input.width,
+                    height: input.height,
+                });
+                if (!shot.available)
+                    return { success: true, result: withNotice(r.canvasId, shot.text) };
+                return {
+                    success: true,
+                    result: withNotice(r.canvasId, shot.text),
+                    imageBlocks: [{ ...shot.image, filename: `scene-${String(r.canvasId)}.png` }],
+                };
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('screenshot scene', error));
+            }
+        },
+    });
+    return [
+        sceneCreateTool,
+        sceneGetTool,
+        sceneAddObjectTool,
+        sceneUpdateObjectTool,
+        sceneRemoveObjectTool,
+        sceneSetCameraTool,
+        sceneScreenshotTool,
+    ];
+}

package/dist/team/tool-config.js

@@ -304,6 +304,21 @@ export const TOOL_GROUPS = {
         readOnly: false,
         tier: 'meta',
     },
+    scene: {
+        label: '3D Scene',
+        // Defined in @compilr-dev/sdk (createSceneTools) — literal names, like canvas.
+        tools: [
+            'scene_create',
+            'scene_get',
+            'scene_add_object',
+            'scene_update_object',
+            'scene_remove_object',
+            'scene_set_camera',
+            'scene_screenshot',
+        ],
+        readOnly: false,
+        tier: 'meta',
+    },
     plans: {
         label: 'Planning',
         tools: [
@@ -535,6 +550,7 @@ export const TOOL_PROFILES = {
         'backlog_write',
         'documents',
         'canvas',
+        'scene',
         'plans',
         'artifacts',
         'anchors',
@@ -575,6 +591,7 @@ export const TOOL_PROFILES = {
         'search',
         'documents',
         'canvas',
+        'scene',
         'web',
         'factory_models',
     ],
@@ -631,6 +648,7 @@ export const TOOL_PROFILES = {
         'backlog_read',
         'documents',
         'canvas',
+        'scene',
         'plans',
         'artifacts',
         'anchors',
@@ -655,6 +673,7 @@ export const TOOL_PROFILES = {
         'backlog_write',
         'documents',
         'canvas',
+        'scene',
         'plans',
         'artifacts',
         'anchors',
@@ -677,6 +696,7 @@ export const TOOL_PROFILES = {
         'backlog_write',
         'documents',
         'canvas',
+        'scene',
         'artifacts',
         'anchors',
         'web',
@@ -696,6 +716,7 @@ export const TOOL_PROFILES = {
         'search',
         'documents',
         'canvas',
+        'scene',
         'artifacts',
         'anchors',
         'web',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.29.8",
+  "version": "0.31.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",