@womp/spark-agent 5.6.1 → 5.7.1

package/dist/materials/reference.js

@@ -1,97 +1,97 @@
 // A one-layer graph with procedural bump feeding the surface normal.
-export const MATERIALS_NOISE_BUMP_RECIPE = `const graph = {
-  nodes: [
-    womp.materials.node({op:'Constant',inputs:{2:0.5}}),
-    womp.materials.node({op:'Passthrough',inputs:{0:0.3}}),
-    womp.materials.node({op:'OutputMaterial'}),
-    womp.materials.node({op:'InputPosition'}),
-    womp.materials.node({op:'Mapping',inputs:{1:0,2:0,3:1}}),
-    womp.materials.node({op:'NoiseFBM',inputs:{1:4,2:3,3:1,4:0}}),
-    womp.materials.node({op:'Bump',inputs:{1:0.03}}),
-    womp.materials.node({op:'OutputSurfaceNormal'})
-  ],
-  connections: [
-    {input_node:0,input_slot:2,output_node:2,output_slot:0,flags:0},
-    {input_node:1,input_slot:0,output_node:2,output_slot:3,flags:0},
-    {input_node:1,input_slot:0,output_node:2,output_slot:4,flags:0},
-    {input_node:3,input_slot:0,output_node:4,output_slot:0,flags:0},
-    {input_node:4,input_slot:0,output_node:5,output_slot:0,flags:0},
-    {input_node:5,input_slot:0,output_node:6,output_slot:0,flags:0},
-    {input_node:6,input_slot:0,output_node:7,output_slot:0,flags:0}
-  ]
+export const MATERIALS_NOISE_BUMP_RECIPE = `const graph = {
+  nodes: [
+    womp.materials.node({op:'Constant',inputs:{2:0.5}}),
+    womp.materials.node({op:'Passthrough',inputs:{0:0.3}}),
+    womp.materials.node({op:'OutputMaterial'}),
+    womp.materials.node({op:'InputPosition'}),
+    womp.materials.node({op:'Mapping',inputs:{1:0,2:0,3:1}}),
+    womp.materials.node({op:'NoiseFBM',inputs:{1:4,2:3,3:1,4:0}}),
+    womp.materials.node({op:'Bump',inputs:{1:0.03}}),
+    womp.materials.node({op:'OutputSurfaceNormal'})
+  ],
+  connections: [
+    {input_node:0,input_slot:2,output_node:2,output_slot:0,flags:0},
+    {input_node:1,input_slot:0,output_node:2,output_slot:3,flags:0},
+    {input_node:1,input_slot:0,output_node:2,output_slot:4,flags:0},
+    {input_node:3,input_slot:0,output_node:4,output_slot:0,flags:0},
+    {input_node:4,input_slot:0,output_node:5,output_slot:0,flags:0},
+    {input_node:5,input_slot:0,output_node:6,output_slot:0,flags:0},
+    {input_node:6,input_slot:0,output_node:7,output_slot:0,flags:0}
+  ]
 };`;
-export const MATERIALS_REFERENCE = `
-Procedural shaders are material graphs, separate from Geometry Nodes and Workbench Flow. recipe() builds the standard grid, noise, grain and woven graphs with live selectors internally; their controls are already defined. Use catalog() for unfamiliar custom operations or includeTextures:true for resource names. get_node_types is a different graph system.
-
-Storage and sharing
-- Material IDs and shader IDs occupy separate positive 16-bit namespaces; material 0 remains the scene default. There are eight ordered shader slots, where null/0 is empty. write always pads trailing slots to eight to clear the native layer cache.
-- write without materialId creates a material. cloneFrom copies base properties, layers and metadata. Existing materialId edits affect every user of that material. Graph edits copy shared shader storage automatically.
-- Graph nodes have op, optional name/location/editor_flags/reference_id, in0..in19 vectors, and optional external_data bytes. Read preserves native data. Keep unrelated metadata; node() constructs new nodes with scalar broadcasting and payload encoding.
-- Connections use zero-based ARRAY INDICES: input_node/source node, input_slot/source OUTPUT; output_node/destination node, output_slot/destination INPUT; flags:0 for new connections; native differential flags:2 are also supported. An input has one producer. Graphs must be acyclic, output nodes terminal, and enum/integer/Boolean selectors literal. Numeric Float/Float3/Color ports can interconnect; native math uses float3 and scalar consumers use X.
-- Unconnected OutputMaterial inputs inherit the incoming material, including the previous layer. Literal values on unconnected OutputMaterial inputs do not set properties. Connect Constant or Passthrough instead.
-- OutputMaterial inputs: 0 primary color, 1 secondary color, 2 subsurface, 3 metalness, 4 roughness, 5 transmittance, 6 translucency, 7 IOR, 8 iridescence, 9 emission, 10 absorption, 11 sheen, 12 specular tint, 13 translucency weight, 14 material weight, 15 dispersion, 16 displacement. Verify descriptors on the current engine.
-- InputMaterial and the exactly spelled InputUnderlayingMaterial read the incoming layer material, not independently preserved base snapshots. OutputHeight changes shading normals. Material displacement has separate export semantics; do not claim it changed mesh geometry.
-
-Constants and resetting
-- Constant input 0 chooses Pi/Half Pi/Double Pi/Exponent; input 1 is value vector, 2 color, 3 UI exposure enum, 4 scope. Outputs 0 built-in constant, 1 value, 2 color.
-- Give a new adjustable Constant a unique positive safe-integer reference_id, or let write allocate it and read it back. Keep reference IDs stable while editing. Independent constants across layers must have distinct references.
-- constants overrides are keyed by reference ID and contain BOTH value:{x,y,z} and color:{x,y,z}. Native omission zeros the missing counterpart. Use read to preserve it.
-- Reset with constants:{[referenceId]:null}. Kakapo retains deleted override keys in its in-memory cache; Spark gives the reset node a fresh reference and removes the stored old override. Replacing layers on an existing material also gives unoverridden Constants fresh references, so reusing an old graph cannot revive cached overrides. Use the returned referenceIdChanges mapping for subsequent edits. Other materials retain their references and overrides. Reset follows graph defaults and survives reopening.
-
-Units, colors and mapping
-- Graph vectors use renderer coordinates. One native length unit is 25 mm; Spark scene editing flips X/Z into its public basis, so a public mm position maps to {-z/(25*u),y/(25*u),-x/(25*u)}, where u is the scene unit_multiplier (default 1). Do not scale every numeric shader input: colors, frequencies, normals and normalized UVs have different meanings.
-- Mapping computes rotate(value, rotationDegrees) * scale + translation. Set scale explicitly to {x:1,y:1,z:1}; omitted literals are zero. Projection mode comes from the live enum descriptor.
-- InputPosition uses the carrier's local coordinates, including its procedural transform; it is not universally a normalized box or a physical distance. InputWorldPosition uses renderer world coordinates. Pair local position with InputNormal, or world position with InputWorldNormal, for projection. Compensate non-uniform geometry scale in mapping, without changing the geometry. A 1-unit and 0.1-unit object-space grid together reveals actual spacing and stretching in one inspection.
-- Connected procedural colors are linear RGB in 0..1: Constant colors, ramp stops and recipe colorA/colorB. scene materialSetColor uses display RGB 0..255; to reproduce its base color in a procedural graph use (channel/255)**2.2 per channel. This renderer uses gamma 2.2 as its sRGB approximation; exact sRGB decoding is c/12.92 for c<=0.04045, otherwise ((c+0.055)/1.055)**2.4. Use exact decoding for known standard sRGB data, or gamma 2.2 when matching the renderer's base colors and texture transform. Never decode already-linear values, roughness, metalness, height or normals.
-- Native InputMaterial in layer 0 applies pow(color,1/2.2) to incoming primary/secondary/subsurface color, while later slots return linear color. Passing that layer-0 color back to OutputMaterial brightens it. If reading and rewriting incoming color in slot 0, raise it to 2.2 before linear calculations. Direct connected literals need no slot-specific correction. Leading empty slots still determine the shader's slot. PredefinedTexture's sRGB (Color) transform decodes RGB with pow(c,2.2); do not decode its output twice.
-- NoiseFBM detail is 1..16. Coordinate scale changes spatial frequency; noise scale is amplitude. Random is sampled during shading, not a stable per-object seed.
-- WavesTexture is radial in its supplied coordinates. For parallel grain or warp/weft, use the recipe graphs or component-wise periodic functions rather than assuming WavesTexture produces straight stripes.
-
-Resource payloads
-- node({op:'PredefinedTexture',texture:catalogueName,...}) encodes the exact UTF-8 filename plus NUL. The GPU texture slot and dimensions are renderer-owned; never author them. write resolves the current display index from the filename. Texture also requires a discovered resource name; uploading files is host-owned.
-- Refresh requests run reload_textures before get_procedural_nodes; the latter returns a JSON string whose PredefinedTexture.inputs[2].values is authoritative. A refreshed name list does not prove GPU upload success.
-- node({op:'ColorRamp',ramp:[{position:0,color:{x:0,y:0,z:0}},{position:1,color:{x:1,y:1,z:1}}],inputs:{3:0}}) encodes 16 little-endian bytes per stop: position,r,g,b. Use at least two strictly increasing positions in 0..1. Modes come from input 3's enum.
-- node({op:'OptionSelector',options:[{name:'Low',value:0.2},{name:'High',value:0.8}],inputs:{1:0}}) encodes 36 bytes per option: float32 value and 32-byte NUL-terminated name. Maximum 32 options, names at most 31 UTF-8 bytes. Select an integer in [0,count). Dynamic selector connections are refused because this engine's upper clamp can read out of bounds.
-- Hidden/CPU-only payload ports cannot be connected. Unknown operation/payload, invalid selectors, cycles, disabled edges and duplicate output nodes are rejected before commit. Native payload padding is normalized without changing its meaning. HSL's output is vector-valued despite a Float descriptor; native numeric connections preserve it.
-
-Recipe: constant colored material with roughness
-const graph = {
-  nodes: [
-    womp.materials.node({op:'Constant',name:'Color',reference_id:101,inputs:{2:{x:0.65,y:0.12,z:0.03},3:1}}),
-    womp.materials.node({op:'Passthrough',name:'Roughness',inputs:{0:0.35}}),
-    womp.materials.node({op:'OutputMaterial'})
-  ],
-  connections:[
-    {input_node:0,input_slot:2,output_node:2,output_slot:0,flags:0},
-    {input_node:1,input_slot:0,output_node:2,output_slot:4,flags:0}
-  ]
-};
-print(await womp.materials.write({layers:[graph],objectIds:[objectId]}));
-
-For a noise gradient, connect InputPosition to NoiseFBM's coordinate input, NoiseFBM's scalar output to ColorRamp input 0, and the ramp to OutputMaterial input 0. Set frequency, amplitude and detail deliberately. For mapped textures, connect position through Mapping/Projection to PredefinedTexture's coordinate input, then connect its color to the material output. Resolve selectors for custom graphs from the current catalogue; reuse descriptors already read.
-
-Projection and texture controls
-- Resolve projection selectors by their current descriptor names. Match Planar to flat faces, Cubic to box faces, Cylindrical to axial sides and Equirectangular to spheres; inspect caps, seams, poles and transitions where applicable. Center normalized projections on the intended carrier and check the result after resizing.
-- Rotate position and normal inputs consistently, and set Mapping scale explicitly to 1. Compare projection changes under the same light and camera with an asymmetric texture that reveals axis swaps and stretching.
-- Choose PredefinedTexture's transform by the resource's known purpose: sRGB (Color), No transform for scalar data, or Normal for an encoded normal map. False for Disable Filtering or Do not repeat leaves filtering or repetition enabled. Check those settings at the intended image scale.
-- A single-channel texture may sample as (R,0,0). For neutral RGB, connect X through GetComponent to all three CombineValues inputs. A catalogue name does not establish channels, color space or normal convention. Alpha requires an explicit connection to the intended material input.
-- HSL hue, saturation and lightness inputs are additive offsets, not multipliers; use 0 for unchanged channels. Its color input/output is linear RGB. Perceptual palette edits can be performed in a known display-color encoding and decoded back to linear RGB before writing.
-
-Recipe: one-shader noise bump
-Discover InputPosition, Mapping, NoiseFBM, Bump and OutputSurfaceNormal before using this example. It sets gray color, roughness 0.3 and metalness 0.3. Allocate fresh Constant references through write rather than copying IDs from another material.
-${MATERIALS_NOISE_BUMP_RECIPE}
-return await womp.materials.write({layers:[graph],objectIds:[objectId]});
-
-Bump and normal verification
-- Bump Scale changes shading-normal strength; coordinate scale changes feature frequency. Compare positive and negative Bump Scale under the same light when the relief direction matters. Neither changes the silhouette.
-- Strength depends on the height gradient, including feature frequency, contrast and noise detail. Native Bump estimates height differences over local-position offsets and returns a normalized tangent-space normal; its Scale is not a 0..1 blend strength or a physical depth in mm. The offsets depend on scene/object scale and numerical precision, not pixel footprint. More octaves do not guarantee resolved detail. Independently weight defining profiles and micro-noise before Bump; strengthen washed-out structure while preserving coherent highlights and the requested finish. Use calibration only with its stated space and feature size.
-- Feed a Normal-decoded texture into tangent-space OutputSurfaceNormal. Use a known map convention, and inspect flat and green-flipped controls if handedness is uncertain.
-- OutputHeight Scale is separate from tangent-normal-map strength. The current native OutputHeight shader does not use its Coarseness input; texture sampling has a separate control. Match the desired appearance visually rather than treating height and normal strengths as equivalent.
-- Combine normals deliberately and normalize the result. Whiteout composition, normalize(vec3(nTexture.x+nBump.x,nTexture.y+nBump.y,nTexture.z*nBump.z)), is approximate. Compare it with each input alone; these operations change shading normals, not geometry.
-
-Verification
-- When numeric, status().remaining counts compiler tasks globally; null means that query failed. Zero is not a per-graph success flag: old valid shaders can keep rendering during compilation or failure.
-- After writing, inspect a scene screenshot, compare intended channels at a useful scale, and reopen the saved scene when persistence is part of acceptance. Separate committed, persisted, compiler queue idle, and visually verified results.
-- The current SDK does not expose per-shader compiler diagnostics. Retain write receipts and any available runtime error; do not infer compilation success from an idle queue.
-- InputSceneInfo IDs and Random values are runtime evaluation data, not persistent authored seeds. Use Constants when reproducible variation is required.
+export const MATERIALS_REFERENCE = `
+Procedural shaders are material graphs, separate from Geometry Nodes and Workbench Flow. recipe() builds the standard grid, noise, grain and woven graphs with live selectors internally; their controls are already defined. Use catalog() for unfamiliar custom operations or includeTextures:true for resource names. get_node_types is a different graph system.
+
+Storage and sharing
+- Material IDs and shader IDs occupy separate positive 16-bit namespaces; material 0 remains the scene default. There are eight ordered shader slots, where null/0 is empty. write always pads trailing slots to eight to clear the native layer cache.
+- write without materialId creates a material. cloneFrom copies base properties, layers and metadata. Existing materialId edits affect every user of that material. Graph edits copy shared shader storage automatically.
+- Graph nodes have op, optional name/location/editor_flags/reference_id, in0..in19 vectors, and optional external_data bytes. Read preserves native data. Keep unrelated metadata; node() constructs new nodes with scalar broadcasting and payload encoding.
+- Connections use zero-based ARRAY INDICES: input_node/source node, input_slot/source OUTPUT; output_node/destination node, output_slot/destination INPUT; flags:0 for new connections; native differential flags:2 are also supported. An input has one producer. Graphs must be acyclic, output nodes terminal, and enum/integer/Boolean selectors literal. Numeric Float/Float3/Color ports can interconnect; native math uses float3 and scalar consumers use X.
+- Unconnected OutputMaterial inputs inherit the incoming material, including the previous layer. Literal values on unconnected OutputMaterial inputs do not set properties. Connect Constant or Passthrough instead.
+- OutputMaterial inputs: 0 primary color, 1 secondary color, 2 subsurface, 3 metalness, 4 roughness, 5 transmittance, 6 translucency, 7 IOR, 8 iridescence, 9 emission, 10 absorption, 11 sheen, 12 specular tint, 13 translucency weight, 14 material weight, 15 dispersion, 16 displacement. Verify descriptors on the current engine.
+- InputMaterial and the exactly spelled InputUnderlayingMaterial read the incoming layer material, not independently preserved base snapshots. OutputHeight changes shading normals. Material displacement has separate export semantics; do not claim it changed mesh geometry.
+
+Constants and resetting
+- Constant input 0 chooses Pi/Half Pi/Double Pi/Exponent; input 1 is value vector, 2 color, 3 UI exposure enum, 4 scope. Outputs 0 built-in constant, 1 value, 2 color.
+- Give a new adjustable Constant a unique positive safe-integer reference_id, or let write allocate it and read it back. Keep reference IDs stable while editing. Independent constants across layers must have distinct references.
+- constants overrides are keyed by reference ID and contain BOTH value:{x,y,z} and color:{x,y,z}. Native omission zeros the missing counterpart. Use read to preserve it.
+- Reset with constants:{[referenceId]:null}. Kakapo retains deleted override keys in its in-memory cache; Spark gives the reset node a fresh reference and removes the stored old override. Replacing layers on an existing material also gives unoverridden Constants fresh references, so reusing an old graph cannot revive cached overrides. Use the returned referenceIdChanges mapping for subsequent edits. Other materials retain their references and overrides. Reset follows graph defaults and survives reopening.
+
+Units, colors and mapping
+- Graph vectors use renderer coordinates. One native length unit is 25 mm; Spark scene editing flips X/Z into its public basis, so a public mm position maps to {-z/(25*u),y/(25*u),-x/(25*u)}, where u is the scene unit_multiplier (default 1). Do not scale every numeric shader input: colors, frequencies, normals and normalized UVs have different meanings.
+- Mapping computes rotate(value, rotationDegrees) * scale + translation. Set scale explicitly to {x:1,y:1,z:1}; omitted literals are zero. Projection mode comes from the live enum descriptor.
+- InputPosition uses the carrier's local coordinates, including its procedural transform; it is not universally a normalized box or a physical distance. InputWorldPosition uses renderer world coordinates. Pair local position with InputNormal, or world position with InputWorldNormal, for projection. Compensate non-uniform geometry scale in mapping, without changing the geometry. A 1-unit and 0.1-unit object-space grid together reveals actual spacing and stretching in one inspection.
+- Connected procedural colors are linear RGB in 0..1: Constant colors, ramp stops and recipe colorA/colorB. scene materialSetColor uses display RGB 0..255; to reproduce its base color in a procedural graph use (channel/255)**2.2 per channel. This renderer uses gamma 2.2 as its sRGB approximation; exact sRGB decoding is c/12.92 for c<=0.04045, otherwise ((c+0.055)/1.055)**2.4. Use exact decoding for known standard sRGB data, or gamma 2.2 when matching the renderer's base colors and texture transform. Never decode already-linear values, roughness, metalness, height or normals.
+- Native InputMaterial in layer 0 applies pow(color,1/2.2) to incoming primary/secondary/subsurface color, while later slots return linear color. Passing that layer-0 color back to OutputMaterial brightens it. If reading and rewriting incoming color in slot 0, raise it to 2.2 before linear calculations. Direct connected literals need no slot-specific correction. Leading empty slots still determine the shader's slot. PredefinedTexture's sRGB (Color) transform decodes RGB with pow(c,2.2); do not decode its output twice.
+- NoiseFBM detail is 1..16. Coordinate scale changes spatial frequency; noise scale is amplitude. Random is sampled during shading, not a stable per-object seed.
+- WavesTexture is radial in its supplied coordinates. For parallel grain or warp/weft, use the recipe graphs or component-wise periodic functions rather than assuming WavesTexture produces straight stripes.
+
+Resource payloads
+- node({op:'PredefinedTexture',texture:catalogueName,...}) encodes the exact UTF-8 filename plus NUL. The GPU texture slot and dimensions are renderer-owned; never author them. write resolves the current display index from the filename. Texture also requires a discovered resource name; uploading files is host-owned.
+- Refresh requests run reload_textures before get_procedural_nodes; the latter returns a JSON string whose PredefinedTexture.inputs[2].values is authoritative. A refreshed name list does not prove GPU upload success.
+- node({op:'ColorRamp',ramp:[{position:0,color:{x:0,y:0,z:0}},{position:1,color:{x:1,y:1,z:1}}],inputs:{3:0}}) encodes 16 little-endian bytes per stop: position,r,g,b. Use at least two strictly increasing positions in 0..1. Modes come from input 3's enum.
+- node({op:'OptionSelector',options:[{name:'Low',value:0.2},{name:'High',value:0.8}],inputs:{1:0}}) encodes 36 bytes per option: float32 value and 32-byte NUL-terminated name. Maximum 32 options, names at most 31 UTF-8 bytes. Select an integer in [0,count). Dynamic selector connections are refused because this engine's upper clamp can read out of bounds.
+- Hidden/CPU-only payload ports cannot be connected. Unknown operation/payload, invalid selectors, cycles, disabled edges and duplicate output nodes are rejected before commit. Native payload padding is normalized without changing its meaning. HSL's output is vector-valued despite a Float descriptor; native numeric connections preserve it.
+
+Recipe: constant colored material with roughness
+const graph = {
+  nodes: [
+    womp.materials.node({op:'Constant',name:'Color',reference_id:101,inputs:{2:{x:0.65,y:0.12,z:0.03},3:1}}),
+    womp.materials.node({op:'Passthrough',name:'Roughness',inputs:{0:0.35}}),
+    womp.materials.node({op:'OutputMaterial'})
+  ],
+  connections:[
+    {input_node:0,input_slot:2,output_node:2,output_slot:0,flags:0},
+    {input_node:1,input_slot:0,output_node:2,output_slot:4,flags:0}
+  ]
+};
+print(await womp.materials.write({layers:[graph],objectIds:[objectId]}));
+
+For a noise gradient, connect InputPosition to NoiseFBM's coordinate input, NoiseFBM's scalar output to ColorRamp input 0, and the ramp to OutputMaterial input 0. Set frequency, amplitude and detail deliberately. For mapped textures, connect position through Mapping/Projection to PredefinedTexture's coordinate input, then connect its color to the material output. Resolve selectors for custom graphs from the current catalogue; reuse descriptors already read.
+
+Projection and texture controls
+- Resolve projection selectors by their current descriptor names. Match Planar to flat faces, Cubic to box faces, Cylindrical to axial sides and Equirectangular to spheres; inspect caps, seams, poles and transitions where applicable. Center normalized projections on the intended carrier and check the result after resizing.
+- Rotate position and normal inputs consistently, and set Mapping scale explicitly to 1. Compare projection changes under the same light and camera with an asymmetric texture that reveals axis swaps and stretching.
+- Choose PredefinedTexture's transform by the resource's known purpose: sRGB (Color), No transform for scalar data, or Normal for an encoded normal map. False for Disable Filtering or Do not repeat leaves filtering or repetition enabled. Check those settings at the intended image scale.
+- A single-channel texture may sample as (R,0,0). For neutral RGB, connect X through GetComponent to all three CombineValues inputs. A catalogue name does not establish channels, color space or normal convention. Alpha requires an explicit connection to the intended material input.
+- HSL hue, saturation and lightness inputs are additive offsets, not multipliers; use 0 for unchanged channels. Its color input/output is linear RGB. Perceptual palette edits can be performed in a known display-color encoding and decoded back to linear RGB before writing.
+
+Recipe: one-shader noise bump
+Discover InputPosition, Mapping, NoiseFBM, Bump and OutputSurfaceNormal before using this example. It sets gray color, roughness 0.3 and metalness 0.3. Allocate fresh Constant references through write rather than copying IDs from another material.
+${MATERIALS_NOISE_BUMP_RECIPE}
+return await womp.materials.write({layers:[graph],objectIds:[objectId]});
+
+Bump and normal verification
+- Bump Scale changes shading-normal strength; coordinate scale changes feature frequency. Compare positive and negative Bump Scale under the same light when the relief direction matters. Neither changes the silhouette.
+- Strength depends on the height gradient, including feature frequency, contrast and noise detail. Native Bump estimates height differences over local-position offsets and returns a normalized tangent-space normal; its Scale is not a 0..1 blend strength or a physical depth in mm. The offsets depend on scene/object scale and numerical precision, not pixel footprint. More octaves do not guarantee resolved detail. Independently weight defining profiles and micro-noise before Bump; strengthen washed-out structure while preserving coherent highlights and the requested finish. Use calibration only with its stated space and feature size.
+- Feed a Normal-decoded texture into tangent-space OutputSurfaceNormal. Use a known map convention, and inspect flat and green-flipped controls if handedness is uncertain.
+- OutputHeight Scale is separate from tangent-normal-map strength. The current native OutputHeight shader does not use its Coarseness input; texture sampling has a separate control. Match the desired appearance visually rather than treating height and normal strengths as equivalent.
+- Combine normals deliberately and normalize the result. Whiteout composition, normalize(vec3(nTexture.x+nBump.x,nTexture.y+nBump.y,nTexture.z*nBump.z)), is approximate. Compare it with each input alone; these operations change shading normals, not geometry.
+
+Verification
+- When numeric, status().remaining counts compiler tasks globally; null means that query failed. Zero is not a per-graph success flag: old valid shaders can keep rendering during compilation or failure.
+- After writing, inspect a scene screenshot, compare intended channels at a useful scale, and reopen the saved scene when persistence is part of acceptance. Separate committed, persisted, compiler queue idle, and visually verified results.
+- The current SDK does not expose per-shader compiler diagnostics. Retain write receipts and any available runtime error; do not infer compilation success from an idle queue.
+- InputSceneInfo IDs and Random values are runtime evaluation data, not persistent authored seeds. Use Constants when reproducible variation is required.
 `;

package/dist/materials/structure.js

@@ -1,12 +1,12 @@
-export const MATERIALS_STRUCTURE_GUIDANCE = `shape(field, options) constructs generic remap, ridge, periodic, warp, palette and masked-blend fields. Name features for later editing. Remap endpoints, ridge center/width, periodic sharpness and warp frequency/amplitude are exposed Constants; palette stops remain graph data. Remap/ridge/periodic use analytic math. For a smooth nonlinear scalar profile, use the palette shape with mode:'Smooth' and grayscale stops (equal RGB components); compose reads X for relief or masks. Use this when a simple remap or ridge cannot reproduce the intended shape.
-shape(base,{kind:'blend',overlay,mask,name}) layers an RGB/scalar field or linear RGB literal over the base using a field mask or numeric amount. Zero mask retains the base; one selects the overlay. Field masks use clamped X broadcast to RGB. This helper resolves MathLerp internally; literal overlay colors and amounts become editable Constants. Build independent palettes and masks, then chain blend calls for feature-specific colors in one construction batch.
-Periodic and warp coordinates default to the field's feature-size Mapping. Custom fields require an explicit vector coordinate node. Warp frequency/amplitude are relative to those coordinates; preserve measured feature size. Build periodic profiles, warp their coordinates, then form ridges/masks. Resolve indices in each returned graph because unused nodes are pruned. Independent XYZ warp avoids diagonal distortion.
-A generic noise layer counts only when it reproduces the requested shape. Construct defining boundaries, strands and crossings explicitly. Palette vector fields preserve RGB with compose color low:{x:0,y:0,z:0}, high:{x:1,y:1,z:1}, weight 1; use separate scalar fields for finish/relief and combine heights before deriving normals once. Composed fields have independent Constant handles.
+export const MATERIALS_STRUCTURE_GUIDANCE = `shape(field, options) constructs generic remap, ridge, periodic, warp, palette and masked-blend fields. Name features for later editing. Remap endpoints, ridge center/width, periodic sharpness and warp frequency/amplitude are exposed Constants; palette stops remain graph data. Remap/ridge/periodic use analytic math. For a smooth nonlinear scalar profile, use the palette shape with mode:'Smooth' and grayscale stops (equal RGB components); compose reads X for relief or masks. Use this when a simple remap or ridge cannot reproduce the intended shape.
+shape(base,{kind:'blend',overlay,mask,name}) layers an RGB/scalar field or linear RGB literal over the base using a field mask or numeric amount. Zero mask retains the base; one selects the overlay. Field masks use clamped X broadcast to RGB. This helper resolves MathLerp internally; literal overlay colors and amounts become editable Constants. Build independent palettes and masks, then chain blend calls for feature-specific colors in one construction batch.
+Periodic and warp coordinates default to the field's feature-size Mapping. Custom fields require an explicit vector coordinate node. Warp frequency/amplitude are relative to those coordinates; preserve measured feature size. Build periodic profiles, warp their coordinates, then form ridges/masks. Resolve indices in each returned graph because unused nodes are pruned. Independent XYZ warp avoids diagonal distortion.
+A generic noise layer counts only when it reproduces the requested shape. Construct defining boundaries, strands and crossings explicitly. Palette vector fields preserve RGB with compose color low:{x:0,y:0,z:0}, high:{x:1,y:1,z:1}, weight 1; use separate scalar fields for finish/relief and combine heights before deriving normals once. Composed fields have independent Constant handles.
 For custom graphs, node({inputs}) keys are numeric input-slot indices, never displayed port titles. Arithmetic uses op:'Math', with its operation selected by literal input 0; this engine's multiplication selector is 2 (label 'Mulitiply'). Check the current descriptor for other modes. Use exact catalogue operation names. When removing a graph node, remove and reindex its connections instead of leaving an unsupported placeholder.`;
-export const MATERIALS_QUALITY_GUIDANCE = `Create materials with the highest achievable fidelity, quality and detail resolution supported by these capabilities.
-For every new material: inspect target dimensions and ancestor transforms, then create and inspect an isolated base-color grid probe BEFORE building final surface structure. Use object-space featureSize:1: major lines every 1 unit and lower-contrast minor lines every 0.1 unit together, with visible line colors and shallow height relief. Assess spacing, stretch, orientation and relief on relevant faces. Correct unintended coordinate distortion without changing geometry or transforms. Replace the probe completely; preserve other material users and assignments. World-space field sizes are physical millimeters; object-space sizes follow carrier coordinates and transforms. Non-uniform dimensions and ancestor transforms affect mapping. Keep physical feature size consistent and all channels aligned; distinguish intended directional anatomy from smeared stretching.
-Before construction, decompose the description/reference into broad variation, defining structure and fine grain. Record each component's relative scale, shape, direction, distribution, edge character and contrast, and its color/roughness/relief contributions. Apply text overrides while preserving remaining reference features. Distinguish reference illumination from intrinsic structure. Give microstructure independent scale and strength; superimpose components without dominant motifs obscuring it.
-Build all planned components and finish channels together using field, shape and compose. Their supported operations and selectors are resolved internally; construct masks, palettes and blends directly from these helpers. For textured surfaces, apply the tested readability adjustment in the first construction: bump scale ×1.25, palette saturation ×1.15, palette lightness ×0.95 and scalar feature contrast ×1.15 around 0.5, clamped to 0..1. Apply color factors in the known display-color encoding, then decode back to linear RGB; native HSL inputs are additive offsets. Incorporate this once into chosen base controls, without an extra material/render pass or compounding it during refinement. Explicit flat, muted or pale requests take precedence; retain reference hues, defining features and the requested finish. These factors are a starting adjustment, not universal optimum values. Keep defining height and fine-noise height independently weighted; increasing all bump together can erase coherent highlights and change gloss into a matte finish. Relief responds to height slope: finer spacing, sharper edges and more noise octaves can strengthen normals at unchanged scale. Calibrated ranges describe particular fields, not quality ceilings or universal strengths.
-Adjust palette saturation/lightness separately from feature coverage and edge contrast; use bounded scalar remaps before palettes or masked blends, checking clipped colors and changed coverage. Keep intrinsic color separate from illumination; preserve natural low-saturation features and coherent highlights. Author linear RGB; decode reference/display colors and preserve already-linear colors and scalar channels. Use roughness variation for finish breakup and signed height profiles for actual ridges/cavities; a dark spot alone does not establish a pit.
-Inspect complementary overall, close and grazing views together under the existing scene lighting, geometry and render settings; adjust viewpoints for inspection. Match tonal contrast and reflectivity through highlight width, strength and breakup. Confirm every planned feature remains visibly resolved: a fine-noise node does not prove fine grain. Check that defining relief reads through lighting at the intended viewing distance, rather than only through its color mask. Subpixel features cannot remain individually resolved by increasing strength or octaves. If relief destroys the requested sheen, rebalance the offending feature's height/frequency before compensating roughness.
+export const MATERIALS_QUALITY_GUIDANCE = `Create materials with the highest achievable fidelity, quality and detail resolution supported by these capabilities.
+For every new material: inspect target dimensions and ancestor transforms, then create and inspect an isolated base-color grid probe BEFORE building final surface structure. Use object-space featureSize:1: major lines every 1 unit and lower-contrast minor lines every 0.1 unit together, with visible line colors and shallow height relief. Assess spacing, stretch, orientation and relief on relevant faces. Correct unintended coordinate distortion without changing geometry or transforms. Replace the probe completely; preserve other material users and assignments. World-space field sizes are physical millimeters; object-space sizes follow carrier coordinates and transforms. Non-uniform dimensions and ancestor transforms affect mapping. Keep physical feature size consistent and all channels aligned; distinguish intended directional anatomy from smeared stretching.
+Before construction, decompose the description/reference into broad variation, defining structure and fine grain. Record each component's relative scale, shape, direction, distribution, edge character and contrast, and its color/roughness/relief contributions. Apply text overrides while preserving remaining reference features. Distinguish reference illumination from intrinsic structure. Give microstructure independent scale and strength; superimpose components without dominant motifs obscuring it.
+Build all planned components and finish channels together using field, shape and compose. Their supported operations and selectors are resolved internally; construct masks, palettes and blends directly from these helpers. For textured surfaces, apply the tested readability adjustment in the first construction: bump scale ×1.25, palette saturation ×1.15, palette lightness ×0.95 and scalar feature contrast ×1.15 around 0.5, clamped to 0..1. Apply color factors in the known display-color encoding, then decode back to linear RGB; native HSL inputs are additive offsets. Incorporate this once into chosen base controls, without an extra material/render pass or compounding it during refinement. Explicit flat, muted or pale requests take precedence; retain reference hues, defining features and the requested finish. These factors are a starting adjustment, not universal optimum values. Keep defining height and fine-noise height independently weighted; increasing all bump together can erase coherent highlights and change gloss into a matte finish. Relief responds to height slope: finer spacing, sharper edges and more noise octaves can strengthen normals at unchanged scale. Calibrated ranges describe particular fields, not quality ceilings or universal strengths.
+Adjust palette saturation/lightness separately from feature coverage and edge contrast; use bounded scalar remaps before palettes or masked blends, checking clipped colors and changed coverage. Keep intrinsic color separate from illumination; preserve natural low-saturation features and coherent highlights. Author linear RGB; decode reference/display colors and preserve already-linear colors and scalar channels. Use roughness variation for finish breakup and signed height profiles for actual ridges/cavities; a dark spot alone does not establish a pit.
+Inspect complementary overall, close and grazing views together under the existing scene lighting, geometry and render settings; adjust viewpoints for inspection. Match tonal contrast and reflectivity through highlight width, strength and breakup. Confirm every planned feature remains visibly resolved: a fine-noise node does not prove fine grain. Check that defining relief reads through lighting at the intended viewing distance, rather than only through its color mask. Subpixel features cannot remain individually resolved by increasing strength or octaves. If relief destroys the requested sheen, rebalance the offending feature's height/frequency before compensating roughness.
 For each refinement, name the largest visible mismatch and the expected correction. Wrong topology/shape needs construction changes; wrong spacing, color, roughness or relief needs the corresponding parameter changes. Use known construction inputs and returned control handles to apply the correction in that batch. Read graphs when editing a previously unknown material or recovering unavailable/stale handles. Adjust related controls together and inspect once. Compare each candidate with the best inspected version at the same views; restore the better graph if a change weakens a defining feature. If tuning fails to improve a mismatch, change its construction rather than repeating strength changes. Continue while a specific, supported correction is likely to improve a substantial mismatch; stop when the result meets the request or further edits cease to help. Do not end with an uninspected edit. Print only relevant IDs, controls and observations; retain full graphs locally for edits.`;

package/dist/materials/surface-recipes.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
 import { INTERNAL_UNITS_PER_MM } from "../coordinates.js";
 import { makeMaterialNode } from "./graph.js";
-export const MATERIAL_RECIPE_RELIEF_GUIDANCE = `Pattern-specific calibration observations (native strength, object coordinates, detail 4, height and bump tested independently):
-- Dual-scale grid, featureSize 1: height 0.0003–0.001; start at 0.0003.
-- Noise, featureSize 0.04: 0.01–0.03 produced visible fine relief.
-- Crossed periodic threads, featureSize 0.04: 0.003–0.03 retained rounded thread shading.
-- Noise, featureSize 0.08: 0.01–0.03 produced low-amplitude grain.
-- Fine directional grain, featureSize {x:0.015,y:0.015,z:2}: 0.0003–0.003 produced faint directional relief; 0.01 and above produced stronger ridges.
+export const MATERIAL_RECIPE_RELIEF_GUIDANCE = `Pattern-specific calibration observations (native strength, object coordinates, detail 4, height and bump tested independently):
+- Dual-scale grid, featureSize 1: height 0.0003–0.001; start at 0.0003.
+- Noise, featureSize 0.04: 0.01–0.03 produced visible fine relief.
+- Crossed periodic threads, featureSize 0.04: 0.003–0.03 retained rounded thread shading.
+- Noise, featureSize 0.08: 0.01–0.03 produced low-amplitude grain.
+- Fine directional grain, featureSize {x:0.015,y:0.015,z:2}: 0.0003–0.003 produced faint directional relief; 0.01 and above produced stronger ridges.
 These observations on curved and flat fixtures under fixed lighting are starting points, not quality targets or upper limits. Use independently weighted structural and micro height fields. Choose visible relief by its actual gradient, scale and requested finish; universal bump multipliers can destroy gloss. Compare close and grazing views without changing the scene. Height and bump strengths are not generally interchangeable.`;
 const positiveVector = z.object({ x: z.number().finite().positive(), y: z.number().finite().positive(), z: z.number().finite().positive() }).strict();
 const color = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1), z: z.number().min(0).max(1) }).strict();

package/dist/prompt.js

@@ -1,75 +1,75 @@
-export const SPARK_AGENT_PROMPT = `You are Spark, Womp's unified assistant.
-Use read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript
-declarations for documentation; execute_javascript runs JavaScript, with top-level await.
-Only the listed capabilities are available. Reading a skill does not grant additional permissions.
-Use only the supplied womp APIs and output helpers to access application services and state.
-If a capability is unavailable, explain what is missing and ask the user to enable it when applicable.
-Do not work around missing capabilities by inspecting page globals, DOM or framework internals,
-or making direct network requests. Native execution is not a security sandbox; it does not expand
-the supported API or the user's granted capabilities.
-Give each execute_javascript call a concise present-progressive purpose, such as "Generating a car image", "Inspecting the scene", or "Importing the model". Write purpose before code.
-Each execution has fresh local variables. Keep stable object, job, and artifact references.
-Use print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact
-reference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.
-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.
-Do not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.
-Inspect the scene before editing and verify the committed result.
-Preserve existing content unless the user asks to replace or delete it. Use the latest target revision
-when a write requires one. Capabilities own transactions: an entire script is not atomic.
-If an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.
-Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
-Complete related work in this conversation without delegating to another agent. Report limits,
-unsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation
-of the result in the user's language; keep implementation details out of that explanation.
-
-Creation intent
-
-Resolve the requested outcome from the current message and preceding dialogue, not keyword matches.
-Explicit method choices take precedence. Continue edits in the existing representation unless the user
-asks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.
-
-- Build ordinary or underspecified creations directly with editable scene shapes, including
-  "a car" and "make X in 3D". Proceed without an image preview or method-selection menu.
-  Organic appearance alone does not require mesh generation or Geometry Nodes.
-
-- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,
-  except when another method is explicit (including primitives with dimensions), or when
-  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:
-  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.
-
-- For mesh wompification, read mesh-wompify and scene-editing together and reconstruct only the specified reference using primitives and curves.
-
-- Generate/edit images or generate meshes when requested. An attached image or reference alone
-  does not request generation; use it for the requested workflow or clarify an unresolved request.
-  Generating a result does not authorize importing, converting, or building it in the scene.
-
-- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or
-  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be
-  open; explain that prerequisite if closed instead of silently generating inline. Merely opening
-  Flow does not redirect ordinary scene requests or inline generation to it.
-
-- After completing explicitly requested generation, you may briefly suggest a relevant next step
-  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,
-  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing
-  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the
-  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.
-
-- Choose construction methods by the user's requested workflow and the
-  available capabilities, not by assuming editable shapes require lower
-  fidelity. A sculpted appearance does not by itself require mesh generation.
-  Respect an explicit method choice and pursue the reference's visible shape
-  and detail with that method. Offer alternatives only for a specific
-  demonstrated limitation; ask before switching or simplifying the requested
-  result. No method guarantees exact reconstruction from a single image.
-
-- Ask at most one focused question at a time, only when a sensible default
-  would likely produce the wrong outcome. Do not repeat resolved questions.
-  Interpret replies using the preceding offer; if several options were
-  offered and “yes” does not identify one, clarify briefly.
-
-- Treat a clear answer to your question as an instruction to proceed.
-  Continue from existing results rather than restarting the workflow.
-
-Offer only workflows available in this host. Follow their authorization
-and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
+export const SPARK_AGENT_PROMPT = `You are Spark, Womp's unified assistant.
+Use read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript
+declarations for documentation; execute_javascript runs JavaScript, with top-level await.
+Only the listed capabilities are available. Reading a skill does not grant additional permissions.
+Use only the supplied womp APIs and output helpers to access application services and state.
+If a capability is unavailable, explain what is missing and ask the user to enable it when applicable.
+Do not work around missing capabilities by inspecting page globals, DOM or framework internals,
+or making direct network requests. Native execution is not a security sandbox; it does not expand
+the supported API or the user's granted capabilities.
+Give each execute_javascript call a concise present-progressive purpose, such as "Generating a car image", "Inspecting the scene", or "Importing the model". Write purpose before code.
+Each execution has fresh local variables. Keep stable object, job, and artifact references.
+Use print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact
+reference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.
+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.
+Do not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.
+Inspect the scene before editing and verify the committed result.
+Preserve existing content unless the user asks to replace or delete it. Use the latest target revision
+when a write requires one. Capabilities own transactions: an entire script is not atomic.
+If an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.
+Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
+Complete related work in this conversation without delegating to another agent. Report limits,
+unsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation
+of the result in the user's language; keep implementation details out of that explanation.
+
+Creation intent
+
+Resolve the requested outcome from the current message and preceding dialogue, not keyword matches.
+Explicit method choices take precedence. Continue edits in the existing representation unless the user
+asks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.
+
+- Build ordinary or underspecified creations directly with editable scene shapes, including
+  "a car" and "make X in 3D". Proceed without an image preview or method-selection menu.
+  Organic appearance alone does not require mesh generation or Geometry Nodes.
+
+- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,
+  except when another method is explicit (including primitives with dimensions), or when
+  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:
+  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.
+
+- For mesh wompification, read mesh-wompify and scene-editing together and reconstruct only the specified reference using primitives and curves.
+
+- Generate/edit images or generate meshes when requested. An attached image or reference alone
+  does not request generation; use it for the requested workflow or clarify an unresolved request.
+  Generating a result does not authorize importing, converting, or building it in the scene.
+
+- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or
+  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be
+  open; explain that prerequisite if closed instead of silently generating inline. Merely opening
+  Flow does not redirect ordinary scene requests or inline generation to it.
+
+- After completing explicitly requested generation, you may briefly suggest a relevant next step
+  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,
+  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing
+  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the
+  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.
+
+- Choose construction methods by the user's requested workflow and the
+  available capabilities, not by assuming editable shapes require lower
+  fidelity. A sculpted appearance does not by itself require mesh generation.
+  Respect an explicit method choice and pursue the reference's visible shape
+  and detail with that method. Offer alternatives only for a specific
+  demonstrated limitation; ask before switching or simplifying the requested
+  result. No method guarantees exact reconstruction from a single image.
+
+- Ask at most one focused question at a time, only when a sensible default
+  would likely produce the wrong outcome. Do not repeat resolved questions.
+  Interpret replies using the preceding offer; if several options were
+  offered and “yes” does not identify one, clarify briefly.
+
+- Treat a clear answer to your question as an instruction to proceed.
+  Continue from existing results rather than restarting the workflow.
+
+Offer only workflows available in this host. Follow their authorization
+and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
 explain the limitation rather than silently substituting another.`;

package/dist/server/executor.d.ts

@@ -9,7 +9,7 @@ export type ResolvedSparkModel = {
 };
 export type SparkRunExecutorOptions = {
     resolveModel(settings: SparkRunSettings): ResolvedSparkModel | Promise<ResolvedSparkModel>;
-    createHost(context: SparkRunExecutionContext): Promise<Pick<SparkAgentOptions, "capabilities" | "executor" | "artifacts" | "persistence"> & {
+    createHost(context: SparkRunExecutionContext): Promise<Pick<SparkAgentOptions, "capabilities" | "executor" | "artifacts" | "persistence" | "context"> & {
         dispose(): void;
     }>;
 };

package/dist/server/executor.js

@@ -20,9 +20,11 @@ export function createSparkRunExecutor(options) {
                 modelId: resolved.modelId,
                 providerOptions: resolved.providerOptions,
                 maxOutputTokens: resolved.maxOutputTokens,
+                tokenBudget: context.goal?.tokenBudget === undefined ? undefined : Math.max(1, context.goal.tokenBudget - context.goal.tokensUsed),
                 runId: context.runId,
                 messageId: context.assistantMessageId,
                 signal: context.signal,
+                context: [host.context, context.goal ? `Active goal: ${JSON.stringify(context.goal.objective)}\nKeep working toward this objective and verify it with concrete tool results before claiming completion. Do not ask whether to continue. If you need user input or access, explain exactly what is missing. Latest evaluation: ${context.goal.lastReason ?? "Not evaluated yet."}` : undefined].filter(Boolean).join("\n\n"),
             });
             return { stream: run.stream, result: run.result.finally(() => host.dispose()) };
         }

package/dist/server/express.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { SPARK_RUN_STATUSES } from "../ui.js";
 import { SparkServiceError } from "./service.js";
 import { DEFAULT_JSON_LIMIT_BYTES } from "../request-limits.js";
+import { sparkGoalCommandSchema } from "../goals.js";
 import { sparkErrorDiagnostics } from "../error-diagnostics.js";
 const reasoningEffortSchema = z.enum(["low", "medium", "high", "xhigh", "max"]);
 const settingsSchema = z.object({
@@ -21,6 +22,7 @@ const submitSchema = z.object({
     message: messageSchema,
     messageId: z.string().optional(),
     settings: settingsSchema,
+    goal: sparkGoalCommandSchema.optional(),
 });
 function parseSequence(value) {
     if (typeof value !== "string" || /^\d+$/u.test(value) === false)
@@ -72,6 +74,12 @@ export function createSparkAgentRouter(options) {
     router.post("/conversations/:conversationId/messages", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         const body = submitSchema.parse(request.body);
+        const command = body.trigger === "submit-message" ? body.goal : undefined;
+        if (command) {
+            const result = await options.service.goalCommand(ownerId, request.params.conversationId, command, body.settings, command.action === "set" ? body.message : undefined);
+            response.status(result.run ? 202 : 200).json(result);
+            return;
+        }
         const run = await options.service.submitMessage({
             ownerId,
             conversationId: request.params.conversationId,
@@ -82,6 +90,16 @@ export function createSparkAgentRouter(options) {
         });
         response.status(202).json({ run });
     });
+    router.get("/conversations/:conversationId/goal", async (request, response) => {
+        const ownerId = await resolveOwnerId(request);
+        response.json(await options.service.goalCommand(ownerId, request.params.conversationId, { action: "status" }));
+    });
+    router.post("/conversations/:conversationId/goal", async (request, response) => {
+        const ownerId = await resolveOwnerId(request);
+        const body = z.object({ command: sparkGoalCommandSchema, settings: settingsSchema.optional(), message: messageSchema.optional() }).parse(request.body);
+        const result = await options.service.goalCommand(ownerId, request.params.conversationId, body.command, body.settings, body.message);
+        response.status(result.run ? 202 : 200).json(result);
+    });
     router.get("/conversations/:conversationId/active-run", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         const run = await options.service.getActiveRun(ownerId, request.params.conversationId);

package/dist/server/fixtures/materials/matte-blue.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Matte Blue",
-  "resource": {
-    "data": {
-      "color.x": 0.08,
-      "color.y": 0.3,
-      "color.z": 0.8,
-      "roughness": 0.85,
-      "metalness": 0,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Matte Blue",
+  "resource": {
+    "data": {
+      "color.x": 0.08,
+      "color.y": 0.3,
+      "color.z": 0.8,
+      "roughness": 0.85,
+      "metalness": 0,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}

package/dist/server/fixtures/materials/polished-copper.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Polished Copper",
-  "resource": {
-    "data": {
-      "color.x": 0.955,
-      "color.y": 0.638,
-      "color.z": 0.538,
-      "roughness": 0.18,
-      "metalness": 1,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Polished Copper",
+  "resource": {
+    "data": {
+      "color.x": 0.955,
+      "color.y": 0.638,
+      "color.z": 0.538,
+      "roughness": 0.18,
+      "metalness": 1,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}

package/dist/server/goal-evaluator.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { type SparkGoal } from "../goals.js";
+import type { SparkUIMessage } from "../ui.js";
+import type { SparkRunExecutorOptions } from "./executor.js";
+export declare const goalVerdictSchema: z.ZodObject<{
+    verdict: z.ZodEnum<{
+        blocked: "blocked";
+        continue: "continue";
+        met: "met";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type SparkGoalEvaluation = z.infer<typeof goalVerdictSchema> & {
+    tokensUsed?: number;
+};
+export type SparkGoalEvaluator = (input: {
+    ownerId?: string;
+    goal: SparkGoal;
+    messages: SparkUIMessage[];
+    context?: Record<string, unknown>;
+    signal: AbortSignal;
+}) => Promise<SparkGoalEvaluation>;
+/** A separate, tool-free call; it never inherits the worker's instructions. */
+export declare function createSparkGoalEvaluator(options: Pick<SparkRunExecutorOptions, "resolveModel"> & {
+    resolveImage?(ownerId: string, artifactId: string): Promise<{
+        data: Uint8Array;
+        mediaType: string;
+    } | undefined>;
+}): SparkGoalEvaluator;