@womp/spark-agent 5.6.1 → 5.7.0

package/dist/agent-run.d.ts

@@ -43,7 +43,7 @@ export declare function runAgent(options: RunOptions): Promise<{
     } | undefined;
     conversationId: string | null;
     runId: string | null;
-    status: "queued" | "running" | "requires_action" | "completed" | "failed" | "cancelled" | "incomplete";
+    status: "completed" | "queued" | "running" | "requires_action" | "failed" | "cancelled" | "incomplete";
     finalAnswer: string;
     durationMs: number | null;
     steps: number;

package/dist/agent-tools.js

@@ -79,10 +79,18 @@ export function createSparkTools(options) {
     return {
         read_skill: tool({
             ...inputLabels("name"),
-            description: "Read the skills listed in names. Returns instructions, TypeScript API declarations, and JavaScript examples from the available directory.",
+            description: "Read required skills together with names, or one skill with name. Returns instructions, TypeScript API declarations, and JavaScript examples from the available directory.",
             inputSchema: z.object({
-                names: z.array(z.string().min(1).max(160)).min(1),
-            }).strict(),
+                name: z.string().min(1).max(160).optional(),
+                names: z.array(z.string().min(1).max(160)).min(1).optional(),
+            }).strict().transform((input, context) => {
+                if (input.name !== undefined && input.names === undefined)
+                    return { name: input.name };
+                if (input.names !== undefined && input.name === undefined)
+                    return { names: input.names };
+                context.addIssue({ code: "custom", message: "Provide exactly one of name or names." });
+                return z.NEVER;
+            }),
             execute: (input, { toolCallId }) => execute({ id: toolCallId, name: "read_skill", input }, async () => {
                 const read = (requested) => {
                     const skill = options.capabilities.skills.find(({ name }) => name === requested);
@@ -95,6 +103,8 @@ export function createSparkTools(options) {
                     }
                     return { ok: true, ...skill };
                 };
+                if (input.name !== undefined)
+                    return read(input.name);
                 const skills = [...new Set(input.names)].map(read);
                 return { ok: skills.every(skill => skill.ok), skills };
             }),

package/dist/agent.d.ts

@@ -26,6 +26,8 @@ export type SparkAgentOptions = {
     instructions?: string;
     maxSteps?: number;
     maxOutputTokens?: number;
+    /** Stops after the completed step that reaches the total-token limit. */
+    tokenBudget?: number;
     executionTimeoutMs?: number;
     persistence?: SparkPersistence;
     prepareMessages?(messages: ModelMessage[]): Promise<ModelMessage[]>;

package/dist/agent.js

@@ -3,6 +3,7 @@ import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 import { createSparkTools } from "./agent-tools.js";
 import { SPARK_AGENT_PROMPT } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
+import { goalTokenCount } from "./goals.js";
 import { contextWindowFor, fitMessagesToContext } from "./context-budget.js";
 function errorMessage(error) {
     return sparkErrorDiagnostics(error).message;
@@ -138,7 +139,8 @@ export function runSparkAgent(options) {
                     tools,
                     toolChoice: "auto",
                     abortSignal: controller.signal,
-                    stopWhen: stepCountIs(maxSteps),
+                    stopWhen: [stepCountIs(maxSteps), ({ steps }) => options.tokenBudget !== undefined &&
+                            steps.reduce((total, step) => total + goalTokenCount(step.usage), 0) >= options.tokenBudget],
                     maxOutputTokens: options.maxOutputTokens,
                     providerOptions: options.providerOptions,
                     prepareStep: async ({ messages }) => {

package/dist/capabilities/geometry.js

@@ -14,20 +14,20 @@ export function createGeometryCapability(host, reference) {
                 name: "geometry-nodes",
                 version: "5",
                 description: "Create and edit visual Geometry Nodes graphs with adjustable parameters and animation.",
-                instructions: `Use womp.geometry for requested Geometry Nodes, parametric organic/procedural geometry, or animation.
-Keep follow-up edits to an existing Geometry Nodes object in its graph, preserving its adjustable parameters and instances.
-Read the target after any scene edit this build needs. read(0) reads the scene root as a creation container.
-write updates an existing shared graph, attaches a new graph to an Area without one, or creates a new Area beneath the root/Group target. Use the returned objectId for follow-up edits.
-Read geometry-nodes-reference before writing source. Supply the complete FlowIR text after inspecting the target. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
-Inspect the current target before replacing its graph; preserve unrelated geometry and parameter overrides.
-If source is null and diagnostics are present, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
-Preserve unrelated statements, parameter names, and FlowIR node IDs from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
-Use min/max/step for naturally bounded parameters and omit ranges for free-form positions/rotations. Meaningful parameter names become editor labels. Do not invent label fields.
-SetMaterial assigns one scene material to every primitive it receives. Its Material input is a scene material ID, not a color; 0 selects the scene default material.
-Obtain that ID from the scene-editing skill inside one scene.access, where those lookups live: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
-Create or import the material inside scene.access before writing the geometry target, all within one JavaScript call. Each call has a fresh scope and cannot read an earlier call's variables.
-Positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
-On compiler errors, repair the source in this same conversation and retry with a fresh read. A rejected write made no change. Committed/unknown effects remain in execution receipts even if a later call fails; inspect before retrying.
+                instructions: `Use womp.geometry for requested Geometry Nodes, parametric organic/procedural geometry, or animation.
+Keep follow-up edits to an existing Geometry Nodes object in its graph, preserving its adjustable parameters and instances.
+Read the target after any scene edit this build needs. read(0) reads the scene root as a creation container.
+write updates an existing shared graph, attaches a new graph to an Area without one, or creates a new Area beneath the root/Group target. Use the returned objectId for follow-up edits.
+Read geometry-nodes-reference before writing source. Supply the complete FlowIR text after inspecting the target. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
+Inspect the current target before replacing its graph; preserve unrelated geometry and parameter overrides.
+If source is null and diagnostics are present, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
+Preserve unrelated statements, parameter names, and FlowIR node IDs from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
+Use min/max/step for naturally bounded parameters and omit ranges for free-form positions/rotations. Meaningful parameter names become editor labels. Do not invent label fields.
+SetMaterial assigns one scene material to every primitive it receives. Its Material input is a scene material ID, not a color; 0 selects the scene default material.
+Obtain that ID from the scene-editing skill inside one scene.access, where those lookups live: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
+Create or import the material inside scene.access before writing the geometry target, all within one JavaScript call. Each call has a fresh scope and cannot read an earlier call's variables.
+Positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
+On compiler errors, repair the source in this same conversation and retry with a fresh read. A rejected write made no change. Committed/unknown effects remain in execution receipts even if a later call fails; inspect before retrying.
 After applying, read the returned object and use the scene screenshot API with emitImage to inspect the applied result.`,
                 declarations: WOMP_GEOMETRY_DECLARATIONS,
                 examples: [

package/dist/capabilities/materials.js

@@ -14,20 +14,20 @@ export function createMaterialsCapability(host, captures) {
                 name: "procedural-materials",
                 version: "15",
                 description: "Discover live texture resources, build procedural shader layers, edit material constants, clone and assign materials.",
-                instructions: `Use womp.materials for procedural surface appearance.
-recipe() builds editable grid, noise, grain and woven starting graphs and resolves live operation selectors internally. Use it directly for these patterns; no preliminary descriptor dump is needed. It does not write or assign a material. featureSize is in object-coordinate units for coordinateSpace:'object', or physical millimeters for 'world'; vector components use graph axes. Object mapping follows the owning carrier and its transforms; world mapping stays fixed in the scene. Grid includes major cells at featureSize and minor cells at one tenth of it, with lower minor contrast. colorA is the base and colorB the grid-line color. Use shallow relief for probes.
-field() builds terminal-free noise, grain, woven, grid or cellular structures. It shares the recipe coordinate/feature-size convention; rotation is in degrees. cellMode selects a cellular pattern or boundary mask; remap controls contrast and can invert a mask. compose() merges these fields or arbitrary custom {graph,source:{node,slot}} fields, wiring independent color, roughness and combined height/bump weights. Color/roughness weights are nonnegative and sum to at most 1; fields must be normalized to 0..1. Relief weights may be signed. This is generic construction, not a finished material preset. Keep broad variation, defining shapes and fine roughness/relief separate. Independent feature colors use shape palette and blend; compose preserves their RGB with color low zero, high one, and weight one. Scalar channels consume X.
-Coordinate axes are known: scene.access public X corresponds to negative renderer Z, public Y to renderer Y, public Z to negative renderer X. World-space featureSize uses renderer axes in physical mm: for grain running along public X, make Z the largest feature-size component, such as {x:1,y:1,z:40}; public Z uses the largest X component. These are orientation examples; choose sizes from the target. Object-space coordinates additionally follow carrier transforms and primitive/mesh mapping. A symmetric grid measures spacing/stretch but cannot establish axis identity. Use the known basis plus carrier transforms, or physical world mapping when local axis identity is uncertain; world mapping remains scene anchored.
-${MATERIALS_STRUCTURE_GUIDANCE}
-Composed controls are named Constants. Palette colors, roughness endpoints, metalness and overall relief are exposed for editing; structural weights and centering stay internal. SDK write results include parameters with current referenceId, value and color; print only the controls relevant to refinement. Change those through constants without rebuilding the graph, preserving the counterpart value/color. Use the new handles after resets/replacements; when a host omits parameters, recover them from read().
-${MATERIAL_RECIPE_RELIEF_GUIDANCE}
-${MATERIALS_QUALITY_GUIDANCE}
-For custom operations, use exact names from catalog().operations; request catalog({operations:[...]}) only for descriptors not already known in this conversation. Request includeTextures:true when you need texture resource names. Request refreshTextures:true after adding/replacing texture resources or switching resource context. Never infer availability from files on the agent's machine or persist catalogue indices as texture identity.
-read() lists materials and direct users; read(id) returns native base data and graph layers. Existing material edits affect every reference, including Geometry Nodes/OpenSCAD references not listed as direct users. To isolate an edit, use cloneFrom with objectIds. Shader storage shared with another material is copied automatically.
-Use node() to construct literals and encode ramps, texture names and option payloads. For custom nodes, discover unfamiliar descriptors before connecting output slots to input slots. OutputMaterial needs connections; its unconnected ports inherit the incoming material.
-write replaces the full layers array when supplied. Preserve unrelated layers, nodes and references from read. Omit layers for assignment/constant-only edits. When rebuilding an existing graph, carry forward intended Constant overrides; omitted overrides reset with replacement nodes, including finish controls. constants entries require both value and color; preserve the counterpart when editing one. A null entry resets a Constant and returns its new reference ID: read again before further edits.
-Base properties and names remain available through scene.access; material names have a 63-character limit. Procedural colors, including recipe palettes, Constant colors and ramp stops, are linear RGB in 0..1. Decode display RGB before supplying it; for this renderer's gamma-2.2 base colors use (channel/255)**2.2. Do not apply this conversion to roughness, metalness, height or normals, or to colors already linear. Graph coordinates use native conventions, not scene.access's mm convenience API.
-Writes use the host's protected scene access, persistence, permissions and receipts. Read current layers before replacing them. After an uncertain commit/save, inspect receipts and scene state; do not replay blindly.
+                instructions: `Use womp.materials for procedural surface appearance.
+recipe() builds editable grid, noise, grain and woven starting graphs and resolves live operation selectors internally. Use it directly for these patterns; no preliminary descriptor dump is needed. It does not write or assign a material. featureSize is in object-coordinate units for coordinateSpace:'object', or physical millimeters for 'world'; vector components use graph axes. Object mapping follows the owning carrier and its transforms; world mapping stays fixed in the scene. Grid includes major cells at featureSize and minor cells at one tenth of it, with lower minor contrast. colorA is the base and colorB the grid-line color. Use shallow relief for probes.
+field() builds terminal-free noise, grain, woven, grid or cellular structures. It shares the recipe coordinate/feature-size convention; rotation is in degrees. cellMode selects a cellular pattern or boundary mask; remap controls contrast and can invert a mask. compose() merges these fields or arbitrary custom {graph,source:{node,slot}} fields, wiring independent color, roughness and combined height/bump weights. Color/roughness weights are nonnegative and sum to at most 1; fields must be normalized to 0..1. Relief weights may be signed. This is generic construction, not a finished material preset. Keep broad variation, defining shapes and fine roughness/relief separate. Independent feature colors use shape palette and blend; compose preserves their RGB with color low zero, high one, and weight one. Scalar channels consume X.
+Coordinate axes are known: scene.access public X corresponds to negative renderer Z, public Y to renderer Y, public Z to negative renderer X. World-space featureSize uses renderer axes in physical mm: for grain running along public X, make Z the largest feature-size component, such as {x:1,y:1,z:40}; public Z uses the largest X component. These are orientation examples; choose sizes from the target. Object-space coordinates additionally follow carrier transforms and primitive/mesh mapping. A symmetric grid measures spacing/stretch but cannot establish axis identity. Use the known basis plus carrier transforms, or physical world mapping when local axis identity is uncertain; world mapping remains scene anchored.
+${MATERIALS_STRUCTURE_GUIDANCE}
+Composed controls are named Constants. Palette colors, roughness endpoints, metalness and overall relief are exposed for editing; structural weights and centering stay internal. SDK write results include parameters with current referenceId, value and color; print only the controls relevant to refinement. Change those through constants without rebuilding the graph, preserving the counterpart value/color. Use the new handles after resets/replacements; when a host omits parameters, recover them from read().
+${MATERIAL_RECIPE_RELIEF_GUIDANCE}
+${MATERIALS_QUALITY_GUIDANCE}
+For custom operations, use exact names from catalog().operations; request catalog({operations:[...]}) only for descriptors not already known in this conversation. Request includeTextures:true when you need texture resource names. Request refreshTextures:true after adding/replacing texture resources or switching resource context. Never infer availability from files on the agent's machine or persist catalogue indices as texture identity.
+read() lists materials and direct users; read(id) returns native base data and graph layers. Existing material edits affect every reference, including Geometry Nodes/OpenSCAD references not listed as direct users. To isolate an edit, use cloneFrom with objectIds. Shader storage shared with another material is copied automatically.
+Use node() to construct literals and encode ramps, texture names and option payloads. For custom nodes, discover unfamiliar descriptors before connecting output slots to input slots. OutputMaterial needs connections; its unconnected ports inherit the incoming material.
+write replaces the full layers array when supplied. Preserve unrelated layers, nodes and references from read. Omit layers for assignment/constant-only edits. When rebuilding an existing graph, carry forward intended Constant overrides; omitted overrides reset with replacement nodes, including finish controls. constants entries require both value and color; preserve the counterpart when editing one. A null entry resets a Constant and returns its new reference ID: read again before further edits.
+Base properties and names remain available through scene.access; material names have a 63-character limit. Procedural colors, including recipe palettes, Constant colors and ramp stops, are linear RGB in 0..1. Decode display RGB before supplying it; for this renderer's gamma-2.2 base colors use (channel/255)**2.2. Do not apply this conversion to roughness, metalness, height or normals, or to colors already linear. Graph coordinates use native conventions, not scene.access's mm convenience API.
+Writes use the host's protected scene access, persistence, permissions and receipts. Read current layers before replacing them. After an uncertain commit/save, inspect receipts and scene state; do not replay blindly.
 status() reports independent global compiler-queue and pending-resource observations. A null field means its query failed; errors identifies the source. Per-shader diagnostics are unavailable. Catalogue names do not establish texture channels, color space or normal convention; choose decoding only when the resource encoding is known. Applied means committed. When inspect is available, use inspect({views:[...]}) after writes; it primes registration once, polls status without screenshot loops and captures the angles sequentially. Emit every returned frame within the same execution for joint comparison. queueSettled describes observations, not visual correctness; Report pending/unavailable observations honestly; fewer frames than requested means inspection is incomplete. When inspect is unavailable, prime with a screenshot, then observe status and capture the needed angles.`,
                 declarations: WOMP_MATERIALS_DECLARATIONS,
                 examples: [

package/dist/capabilities/openscad-instructions.js

@@ -1,81 +1,81 @@
-export const OPENSCAD_INSTRUCTIONS = `Use womp.openscad to create or update one adjustable CAD part. Read an existing part before editing it.
-Keep follow-up edits to an existing CAD part in that part unless the user asks to change representation.
+export const OPENSCAD_INSTRUCTIONS = `Use womp.openscad to create or update one adjustable CAD part. Read an existing part before editing it.
+Keep follow-up edits to an existing CAD part in that part unless the user asks to change representation.
 read(0) returns the root container for creation. read(id) returns an existing
-part or container. Use the scene-editing skill when available to discover other scene objects.
-create requires a parentId (0 means the scene root); update requires the existing objectId.
-Both methods compile the effective source and parameters, apply one undoable change, and check wall thickness.
+part or container. Use the scene-editing skill when available to discover other scene objects.
+create requires a parentId (0 means the scene root); update requires the existing objectId.
+Both methods compile the effective source and parameters, apply one undoable change, and check wall thickness.
 Preserve intervening user changes. Ask the user when the intended edits conflict or remain ambiguous.
 Existing overrides are preserved for parameters still present;
-params supplies overrides to merge into the current values. Keep top-level parameter names stable.
-Return complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.
-Compile errors return status rejected without applying. Creation requires validated placement bounds.
-An update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.
-An applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.
-When thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.
-At most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;
-do not bypass it by recreating the part. Unavailable thickness is not a pass. Report unresolved issues honestly.
-Build connected geometry and avoid features below 1.4 mm. OpenSCAD source dimensions use millimetres,
-independently of the scene display unit. New parts are centered and grounded from compiled bounds.
-OpenSCAD is Z-up; the scene-editing API is Y-up. For an unrotated part at its creation-time scale and an identity parent transform,
-a source point [x,y,z] mm maps to scene {x:y, y:z, z:-x} times the scene.unitMultiplier inside the access callback, plus nodeGetPos(partId).
-Account for the part and parent transforms when they are not identity; source coordinates are not scene coordinates.
-After a major change, use the scene screenshot API and emitImage to inspect the applied result.
-A committed effect can survive later failure. Inspect receipts and the existing part before retrying.
-Do not print source in the final answer unless requested; describe the result and any unresolved diagnostics.
-
-RUNTIME
-- Produce a single OpenSCAD file.
-- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.
-- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.
-- Do not use $fn, $fa, or $fs; tessellation controls are ignored.
-- Build faceted geometry by combining supported primitives with CSG operations and transforms.
-- Do not use scale(); size primitives directly instead.
-- Use color("#rrggbb") around distinct visible parts.
-- Keep the model centered near the origin and use millimeter-like units consistently.
-- For organic blending, use goop(radius_mm) { ... }. The radius is in millimetres before parent scaling, matching scene-editing; do not multiply by project unitMultiplier. It is ordered: the first child seeds with blend 0, and each later child uses radius_mm.
-- Put core primitives first. Avoid wrapping goop children in union() when they should blend individually.
-
-SCREWS AND THREADS
-- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. It joins spheres with cylinders; never use stacked rings or disconnected spheres.
-- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).
-- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.
-- Embed the ridge in the shaft/neck (e.g. radius = shaft_radius). Hollow fittings: subtract the bore from body + thread. Internal threads: subtract the helix from the socket wall with mating clearance. Mating parts need matching pitch and handedness.
-- Expose diameter, pitch, thread length, and thickness in Customizer; derive sampling. Keep 2 * tube_radius < pitch and allow tube_radius beyond both path endpoints for rounded ends. This is a rounded profile, not ISO/metric V-thread; never claim standards compliance.
-- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.
-
-module helical_ridge(radius, pitch, turns, tube_radius, handedness) {
-  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {
-    // Limit chord error to 0.03 mm or 3% of the ridge radius.
-    chord_error = min(0.03, tube_radius * 0.03);
-    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));
-    steps = ceil(turns * steps_per_turn);
-    for (i = [0:steps]) {
-      angle = handedness * 360 * turns * i / steps;
-      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];
-      translate(p) sphere(r = tube_radius);
-      if (i < steps) {
-        next_angle = handedness * 360 * turns * (i + 1) / steps;
-        dx = radius * cos(next_angle) - p[0];
-        dy = radius * sin(next_angle) - p[1];
-        dz = pitch * turns / steps;
-        segment_length = sqrt(dx * dx + dy * dy + dz * dz);
-        translate(p)
-          rotate([0, acos(dz / segment_length), atan2(dy, dx)])
-            cylinder(h = segment_length, r = tube_radius);
-      }
-    }
-  }
-}
-
-PARAMETERS
-- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:
-  - Numbers with ranges: body_radius = 12; // [4:0.5:40]
-  - Counts: leg_count = 4; // [2:8]
-  - Booleans: show_base = true;
-  - Options: style = "round"; // [round, sharp, chunky]
-- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.
-
-SUPPORTED SUBSET
-- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.
-- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.
+params supplies overrides to merge into the current values. Keep top-level parameter names stable.
+Return complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.
+Compile errors return status rejected without applying. Creation requires validated placement bounds.
+An update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.
+An applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.
+When thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.
+At most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;
+do not bypass it by recreating the part. Unavailable thickness is not a pass. Report unresolved issues honestly.
+Build connected geometry and avoid features below 1.4 mm. OpenSCAD source dimensions use millimetres,
+independently of the scene display unit. New parts are centered and grounded from compiled bounds.
+OpenSCAD is Z-up; the scene-editing API is Y-up. For an unrotated part at its creation-time scale and an identity parent transform,
+a source point [x,y,z] mm maps to scene {x:y, y:z, z:-x} times the scene.unitMultiplier inside the access callback, plus nodeGetPos(partId).
+Account for the part and parent transforms when they are not identity; source coordinates are not scene coordinates.
+After a major change, use the scene screenshot API and emitImage to inspect the applied result.
+A committed effect can survive later failure. Inspect receipts and the existing part before retrying.
+Do not print source in the final answer unless requested; describe the result and any unresolved diagnostics.
+
+RUNTIME
+- Produce a single OpenSCAD file.
+- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.
+- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.
+- Do not use $fn, $fa, or $fs; tessellation controls are ignored.
+- Build faceted geometry by combining supported primitives with CSG operations and transforms.
+- Do not use scale(); size primitives directly instead.
+- Use color("#rrggbb") around distinct visible parts.
+- Keep the model centered near the origin and use millimeter-like units consistently.
+- For organic blending, use goop(radius_mm) { ... }. The radius is in millimetres before parent scaling, matching scene-editing; do not multiply by project unitMultiplier. It is ordered: the first child seeds with blend 0, and each later child uses radius_mm.
+- Put core primitives first. Avoid wrapping goop children in union() when they should blend individually.
+
+SCREWS AND THREADS
+- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. It joins spheres with cylinders; never use stacked rings or disconnected spheres.
+- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).
+- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.
+- Embed the ridge in the shaft/neck (e.g. radius = shaft_radius). Hollow fittings: subtract the bore from body + thread. Internal threads: subtract the helix from the socket wall with mating clearance. Mating parts need matching pitch and handedness.
+- Expose diameter, pitch, thread length, and thickness in Customizer; derive sampling. Keep 2 * tube_radius < pitch and allow tube_radius beyond both path endpoints for rounded ends. This is a rounded profile, not ISO/metric V-thread; never claim standards compliance.
+- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.
+
+module helical_ridge(radius, pitch, turns, tube_radius, handedness) {
+  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {
+    // Limit chord error to 0.03 mm or 3% of the ridge radius.
+    chord_error = min(0.03, tube_radius * 0.03);
+    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));
+    steps = ceil(turns * steps_per_turn);
+    for (i = [0:steps]) {
+      angle = handedness * 360 * turns * i / steps;
+      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];
+      translate(p) sphere(r = tube_radius);
+      if (i < steps) {
+        next_angle = handedness * 360 * turns * (i + 1) / steps;
+        dx = radius * cos(next_angle) - p[0];
+        dy = radius * sin(next_angle) - p[1];
+        dz = pitch * turns / steps;
+        segment_length = sqrt(dx * dx + dy * dy + dz * dz);
+        translate(p)
+          rotate([0, acos(dz / segment_length), atan2(dy, dx)])
+            cylinder(h = segment_length, r = tube_radius);
+      }
+    }
+  }
+}
+
+PARAMETERS
+- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:
+  - Numbers with ranges: body_radius = 12; // [4:0.5:40]
+  - Counts: leg_count = 4; // [2:8]
+  - Booleans: show_base = true;
+  - Options: style = "round"; // [round, sharp, chunky]
+- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.
+
+SUPPORTED SUBSET
+- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.
+- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.
 - Unsupported OpenSCAD may validate but can warn or skip during export; prefer the supported subset above.`;

package/dist/capabilities/operations.js

@@ -79,39 +79,39 @@ export function createOperationsCapability(host) {
                 name: "generation",
                 version: "7",
                 description: "Generate or edit images and meshes, inspect jobs, and wait for their outputs.",
-                instructions: `Read operations.catalog() for the currently available models and selected defaults.
+                instructions: `Read operations.catalog() for the currently available models and selected defaults.
 Use generation for requested inline image/mesh results, not unsolicited previews of scene creations.
 For generation explicitly requested through Flow/nodes or continued edits to that Flow workflow, use flow-graphs
 unless the user asks for an inline result. If Flow is unavailable or closed, explain the prerequisite; do not substitute inline generation.
-Use generate() for image/mesh generation, image editing, upscaling, or background removal. Model IDs must
-come from the catalog and support the requested operation. An unavailable or restricted explicit choice
-is an error; do not silently substitute another model. Omit model IDs to use the user's defaults.
-For text-to-mesh, imageParams configures the image step and params configures the mesh step. For
-image-to-mesh, an optional prompt requests an image-editing step first. Advanced params are JSON
-values passed to the existing service; use documented options and do not invent provider settings.
-Author the full text-to-mesh image prompt yourself, preserving the user's requested subject and details.
-For a standalone object, describe a clear three-quarter view with a plain background and even lighting
-unless the user requests otherwise. Do not rely on another model to expand or rewrite this prompt.
-Inputs are image references returned by the available assets API or a previous completed operation.
-Do not fabricate references, replace a missing input with another image, or pass arbitrary URLs.
-Assign a short, distinct key to each intended job. Reuse that key when checking the same submission;
-never choose a new key merely to retry a timeout or unknown outcome. A key cannot identify two
-different requests. Host receipts and saved message IDs record submitted effects.
-generate() waits for cost confirmation and then for completion, failure, or cancellation.
-Use exactly one generation per execute_javascript call and print its result. Put follow-up work in
-another call. Do not poll, start background work, use Promise.all, or report success before completion.
-The host waits without consuming model steps. Stop ends agent execution; the host handles cancellation of its accepted jobs.
-Refresh recovery reconnects the same job. It never resumes the interrupted JavaScript stack.
-Read the recovered status and artifact references, then continue any requested remaining work in a new call; do not repeat generation.
-generate() returns the terminal status and job.outputs artifact references directly, including after recovery.
-Completed generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.
+Use generate() for image/mesh generation, image editing, upscaling, or background removal. Model IDs must
+come from the catalog and support the requested operation. An unavailable or restricted explicit choice
+is an error; do not silently substitute another model. Omit model IDs to use the user's defaults.
+For text-to-mesh, imageParams configures the image step and params configures the mesh step. For
+image-to-mesh, an optional prompt requests an image-editing step first. Advanced params are JSON
+values passed to the existing service; use documented options and do not invent provider settings.
+Author the full text-to-mesh image prompt yourself, preserving the user's requested subject and details.
+For a standalone object, describe a clear three-quarter view with a plain background and even lighting
+unless the user requests otherwise. Do not rely on another model to expand or rewrite this prompt.
+Inputs are image references returned by the available assets API or a previous completed operation.
+Do not fabricate references, replace a missing input with another image, or pass arbitrary URLs.
+Assign a short, distinct key to each intended job. Reuse that key when checking the same submission;
+never choose a new key merely to retry a timeout or unknown outcome. A key cannot identify two
+different requests. Host receipts and saved message IDs record submitted effects.
+generate() waits for cost confirmation and then for completion, failure, or cancellation.
+Use exactly one generation per execute_javascript call and print its result. Put follow-up work in
+another call. Do not poll, start background work, use Promise.all, or report success before completion.
+The host waits without consuming model steps. Stop ends agent execution; the host handles cancellation of its accepted jobs.
+Refresh recovery reconnects the same job. It never resumes the interrupted JavaScript stack.
+Read the recovered status and artifact references, then continue any requested remaining work in a new call; do not repeat generation.
+generate() returns the terminal status and job.outputs artifact references directly, including after recovery.
+Completed generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.
 A brief, relevant follow-up suggestion is optional after completion. Offer only available actions; wait for a clear choice
 and required confirmations before acting. Clarify ambiguous acceptance of multiple options. Reuse returned artifacts for the chosen follow-up.
-Inspect images deliberately when needed for verification or reference comparisons; never claim visual verification without inspecting the image.
-Omitted image bytes are expected; missing artifact references are not. If a completed job has no outputs, recover the references or report the missing result.
-Reserve list() for older jobs or missing references. Follow nextFrom even when a page has no jobs.
-Verify an uncertain submission's job status, never issue a replacement request.
-Only returned outputs exist. Generating a mesh does not import it into the scene. Use the assets skill for requested imports.
+Inspect images deliberately when needed for verification or reference comparisons; never claim visual verification without inspecting the image.
+Omitted image bytes are expected; missing artifact references are not. If a completed job has no outputs, recover the references or report the missing result.
+Reserve list() for older jobs or missing references. Follow nextFrom even when a page has no jobs.
+Verify an uncertain submission's job status, never issue a replacement request.
+Only returned outputs exist. Generating a mesh does not import it into the scene. Use the assets skill for requested imports.
 Never resume stopped work or resubmit a job because cancellation or submission is uncertain.`,
                 declarations: WOMP_OPERATIONS_DECLARATIONS,
                 examples: [