@compilr-dev/sdk 0.33.0 → 0.33.1

package/dist/platform/tools/scene-tools.d.ts

@@ -18,6 +18,37 @@ import { type SceneFile } from '../../canvas/scene.js';
 export declare const SCENE_TOOL_NAMES: readonly ["scene_create", "scene_get", "scene_add_object", "scene_update_object", "scene_remove_object", "scene_set_camera", "scene_screenshot"];
 /** "sofa · box · Sofa" rows, indented under their group parent. */
 export declare function sceneOutline(scene: SceneFile): string;
+/**
+ * The most JSON one `scene_get` may return.
+ *
+ * ⚠️ Sized to stay UNDER the context manager's 8,000-token delegation threshold
+ * (`delegationThreshold`, agents lib). A read that crosses it gets auto-summarised — and a
+ * summary of a scene loses the exact object ids, which is the one thing the agent reads a scene
+ * for. So an oversized read must be refused with instructions, never silently shortened.
+ */
+export declare const SCENE_READ_MAX_CHARS = 20000;
+/**
+ * What `scene_get` returns: the outline, named objects in full, or the whole scene.
+ *
+ * ⚠️ THE OUTLINE IS THE DEFAULT ON PURPOSE. This tool used to return
+ * `serializeScene(scene)` every time, and its own description told the agent to call it before
+ * every edit — about 4,500 tokens for a 51-object house, 11x the outline, on every read of a
+ * build loop. It also taught the model to answer in the same register: having just read a page
+ * of fully-specified pretty-printed JSON, it would emit one enormous `scene_add_object` and get
+ * cut off at the output limit mid-arguments.
+ *
+ * The outline carries ids, types, names and hierarchy — enough to address anything. Numbers come
+ * from `ids`, which is the common case for an edit (the roof, not the house).
+ *
+ * See 3d-canvas-spec §6.4 for the measurements. Exported for its tests.
+ */
+export declare function sceneReadBody(scene: SceneFile, head: string, ids: unknown, full: unknown): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Render a scene through the host's `renderSceneToImage` — shared by scene_screenshot and
  * canvas_screenshot (either tool works on a scene).
@@ -47,6 +78,10 @@ export declare function createSceneTools(config: PlatformToolsConfig, options?:
     title: string;
     scene?: unknown;
     project_id?: number;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    ids?: unknown;
+    full?: unknown;
 }> | import("@compilr-dev/agents").Tool<Record<string, unknown> & {
     canvas_id: number;
 }> | import("@compilr-dev/agents").Tool<{

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

@@ -72,6 +72,75 @@ export function sceneOutline(scene) {
     walk(undefined, 0);
     return rows.join('\n');
 }
+/**
+ * The most JSON one `scene_get` may return.
+ *
+ * ⚠️ Sized to stay UNDER the context manager's 8,000-token delegation threshold
+ * (`delegationThreshold`, agents lib). A read that crosses it gets auto-summarised — and a
+ * summary of a scene loses the exact object ids, which is the one thing the agent reads a scene
+ * for. So an oversized read must be refused with instructions, never silently shortened.
+ */
+export const SCENE_READ_MAX_CHARS = 20_000;
+/** "roof, walls" — the first few of a list, for an error that has to name what is available. */
+function someIds(ids, limit = 12) {
+    return ids.length <= limit
+        ? ids.join(', ')
+        : `${ids.slice(0, limit).join(', ')}, … (${String(ids.length)} in all)`;
+}
+/**
+ * What `scene_get` returns: the outline, named objects in full, or the whole scene.
+ *
+ * ⚠️ THE OUTLINE IS THE DEFAULT ON PURPOSE. This tool used to return
+ * `serializeScene(scene)` every time, and its own description told the agent to call it before
+ * every edit — about 4,500 tokens for a 51-object house, 11x the outline, on every read of a
+ * build loop. It also taught the model to answer in the same register: having just read a page
+ * of fully-specified pretty-printed JSON, it would emit one enormous `scene_add_object` and get
+ * cut off at the output limit mid-arguments.
+ *
+ * The outline carries ids, types, names and hierarchy — enough to address anything. Numbers come
+ * from `ids`, which is the common case for an edit (the roof, not the house).
+ *
+ * See 3d-canvas-spec §6.4 for the measurements. Exported for its tests.
+ */
+export function sceneReadBody(scene, head, ids, full) {
+    const known = scene.objects.map((o) => o.id);
+    const guard = (json, over) => json.length > SCENE_READ_MAX_CHARS
+        ? { ok: false, error: over }
+        : { ok: true, text: `${head}\n\n${json}` };
+    if (ids !== undefined) {
+        if (!Array.isArray(ids) || ids.some((i) => typeof i !== 'string')) {
+            return { ok: false, error: 'ids must be an array of object id strings.' };
+        }
+        const wanted = ids;
+        if (wanted.length === 0)
+            return {
+                ok: false,
+                error: 'ids was empty. Omit it for the outline, or name the objects you need.',
+            };
+        const found = scene.objects.filter((o) => wanted.includes(o.id));
+        const missing = wanted.filter((i) => !known.includes(i));
+        if (found.length === 0) {
+            return {
+                ok: false,
+                error: `No object in this scene has ${missing.length === 1 ? 'that id' : 'those ids'} (${someIds(missing)}). The scene has: ${someIds(known)}. Call scene_get without ids for the outline.`,
+            };
+        }
+        const body = guard(JSON.stringify(found, null, 2), `Those ${String(wanted.length)} objects come to more than ${String(SCENE_READ_MAX_CHARS)} characters. Ask for fewer ids at a time.`);
+        // A partial hit still answers, but says what was not there — a silently short list reads as
+        // "those objects do not exist".
+        if (body.ok && missing.length > 0) {
+            return { ok: true, text: `${body.text}\n\nNot in this scene: ${someIds(missing)}.` };
+        }
+        return body;
+    }
+    if (full === true) {
+        return guard(serializeScene(scene), `This scene's JSON is over ${String(SCENE_READ_MAX_CHARS)} characters, which would be summarised before you saw it and you would lose the ids. Call scene_get without full for the outline, then with ids: [...] for the objects you need.`);
+    }
+    return {
+        ok: true,
+        text: `${head}\n\n--- objects (id · type · name) ---\n${sceneOutline(scene)}`,
+    };
+}
 function clampShot(v, fallback) {
     if (typeof v !== 'number' || !Number.isFinite(v))
         return fallback;
@@ -231,7 +300,8 @@ export function createSceneTools(config, options) {
         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 ' +
+            'empty scene, then build it with scene_add_object (up to 50 per call, but see its note on ' +
+            'batch size), or pass a whole ' +
             'scene { objects: [...], camera?, lights? }. Returns the canvas ID used by every scene_* tool.',
         inputSchema: {
             type: 'object',
@@ -284,12 +354,26 @@ export function createSceneTools(config, options) {
     // ---------------------------------------------------------------------------
     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.',
+        description: 'Read a 3D scene. By default returns a one-line summary and the OUTLINE — every object as ' +
+            '"id · type · name", indented by group — which is what you need to address objects. ' +
+            'Always read before editing: the user edits scenes too, and object ids come from here. ' +
+            'For an object\'s numbers (position, size, rotation, colour) pass ids: ["roof", "walls"] ' +
+            'and you get those objects in full. full: true dumps the entire scene JSON and is rarely ' +
+            'worth it — it costs about 11x the outline and is refused on a large scene.',
         inputSchema: {
             type: 'object',
             properties: {
                 canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                ids: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Return these objects IN FULL (all their fields) instead of the outline. The ids come ' +
+                        'from a previous outline. This is the right way to read detail before an edit.',
+                },
+                full: {
+                    type: 'boolean',
+                    description: 'Return the whole scene as JSON. Only for a wholesale rewrite or an export; prefer ids.',
+                },
             },
             required: ['canvas_id'],
         },
@@ -298,9 +382,11 @@ export function createSceneTools(config, options) {
                 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) };
+                const head = `Scene "${r.title}" (canvas ${String(r.canvasId)}): ${describeScene(r.scene)} · rev ${String(r.rev)}`;
+                const body = sceneReadBody(r.scene, head, input.ids, input.full);
+                if (!body.ok)
+                    return createErrorResult(body.error);
+                return { success: true, result: withNotice(r.canvasId, body.text) };
             }
             catch (error) {
                 return createErrorResult(errorMessage('read scene', error));
@@ -314,7 +400,11 @@ export function createSceneTools(config, options) {
             "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.',
+            'Returns the new id(s) — yours, or generated from name when id is omitted. ' +
+            'BATCH SIZE: about 15-20 per call once objects carry names, colours, groups and rotations. ' +
+            'Fifty of those is roughly 3,000 tokens of arguments, your reasoning is drawn from the same ' +
+            'output budget, and a call cut off at that limit adds NOTHING and has to be redone — so two ' +
+            'moderate calls finish sooner than one oversized one.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

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