@womp/spark-agent 5.4.0 → 5.6.0

package/README.md

@@ -74,6 +74,13 @@ Output directories must not already exist. Artifact manifests include IDs, media
 server URLs and relative paths; failed downloads retain their references and report errors.
 Legacy inline base64 uploads in transcripts are replaced with `[inline data omitted]`.
 
+## Mesh Wompify
+
+Swan imports the reference mesh with Disjoint off, then requests reconstruction
+through the shared `mesh-wompify` and `scene-editing` skills. Tier and request
+helpers are exported from `@womp/spark-agent/ui`. Server mode requires Crow to
+install the updated package and be redeployed; a local Swan package link is insufficient.
+
 ## Package entry points
 
 - `@womp/spark-agent` — browser-safe model loop, two tools, persistence hooks, and shared contracts
@@ -280,13 +287,13 @@ variables take precedence over values loaded from the file.
 For repository development, `yarn dev` starts the Express server and Vite demo together. Open
 `http://127.0.0.1:5173`.
 
-Shared SDK scene adapters can omit `operations` to use direct edit/save with
-per-invocation outcomes and conversation receipts. This path does not persist a scene
-journal, recover uncertain edits, or reuse previous operation results. Validation,
-settlement, and the host's save policy still apply; geometry/OpenSCAD refund repair
-attempts only after confirmed rollback. Hosts that supply `operations` retain their
-existing journal and recovery behavior.
-
+Shared SDK scene adapters can omit `operations` to use direct edit/save with
+per-invocation outcomes and conversation receipts. This path does not persist a scene
+journal, recover uncertain edits, or reuse previous operation results. Validation,
+settlement, and the host's save policy still apply; geometry/OpenSCAD refund repair
+attempts only after confirmed rollback. Hosts that supply `operations` retain their
+existing journal and recovery behavior.
+
 Standalone scene edits use the existing `scene_state_patch` command followed by `save_scene` after
 the patch is acknowledged. The durable operation journal records the separate mutation and save
 outcomes. A failed or unknown save stops that operation with an explicit error, retaining any

package/dist/agent-tools.js

@@ -80,10 +80,17 @@ export function createSparkTools(options) {
         read_skill: tool({
             ...inputLabels("name"),
             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.union([
-                z.object({ names: z.array(z.string().min(1).max(160)).min(1) }).strict(),
-                z.object({ name: z.string().min(1).max(160) }).strict(),
-            ]),
+            inputSchema: z.object({
+                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);
@@ -96,7 +103,7 @@ export function createSparkTools(options) {
                     }
                     return { ok: true, ...skill };
                 };
-                if ("name" in input)
+                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/capabilities/scene.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { meshWompifySkill } from "./wompify.js";
 import { maxLightIntensity } from "@womp/kakapo-sdk";
 import { WOMP_SCENE_DECLARATIONS } from "../generated/scene-declarations.js";
 import { unverifiedSceneHealth } from "../scene-health.js";
@@ -130,6 +131,7 @@ A failed script can retain earlier committed effects. Use receipts and inspect u
                     "const snapshot = await womp.scene.access(scene => ({ unitMultiplier: scene.unitMultiplier })); const diameter = 20 * snapshot.unitMultiplier; const result = await womp.scene.access(scene => { const areaId = scene.nodeCreate(scene.NodeType.Union, 0); const bodyId = scene.nodeCreate(scene.NodeType.Primitive, areaId); scene.nodeSetName(bodyId, '20 mm orange sphere'); scene.nodeSetPrimType(bodyId, scene.PrimitiveType.Sphere); scene.nodeSetSize(bodyId, { x: diameter, y: diameter, z: diameter }); scene.nodeSetPos(bodyId, { x: 0, y: diameter / 2, z: 0 }); const materialId = scene.materialCreate(); scene.materialSetColor(materialId, { r: 255, g: 128, b: 0 }); scene.nodeSetMaterialId(bodyId, materialId); return { areaId, bodyId }; }); print(result); await emitImage(await womp.scene.screenshot({ camera: { position: { x: diameter * 2, y: diameter * 1.5, z: diameter * 2 }, target: { x: 0, y: diameter / 2, z: 0 }, projection: 'perspective', horizontalFovDegrees: 60 } }));",
                 ],
             },
+            meshWompifySkill,
         ],
         createApi: (context) => {
             const health = async (objectIds) => {

package/dist/capabilities/wompify.d.ts

@@ -0,0 +1,2 @@
+import type { SparkSkill } from "../capabilities.js";
+export declare const meshWompifySkill: SparkSkill;

package/dist/capabilities/wompify.js

@@ -0,0 +1,19 @@
+import { WOMPIFY_PRESETS } from "../wompify.js";
+export const meshWompifySkill = {
+    name: "mesh-wompify",
+    version: "1",
+    description: "Reconstruct a specific imported mesh with editable primitives and curves, comparing its shape from matching views.",
+    instructions: `The reference mesh is already imported; do not import it again.
+Resolve only the reference object IDs or exact reference names supplied in the request. A named reference prefix includes only that exact name and its numbered -N parts. Include their descendants and preserve their ancestors. If the target is missing or ambiguous, stop and report it; never treat the whole scene as the reference.
+Hide unrelated scene objects, including any starter cube, without deleting or otherwise editing them. Leave them hidden during reconstruction and at completion. Preserve the original reference. Use the supplied result group, or create a separate group named "Wompified model".
+Match the actual shape, geometry, silhouettes and colors, not a conceptual interpretation of the character.
+Separate body parts or regions into named Areas. Minimize primitives and curve control points without oversimplifying: a large arm or leg can often use one curve with about four points; complex shapes may need more.
+Use Add, Subtraction, Intersection and goop/blend where needed. Embed colors in the physical primitives; use stain only as a last resort.
+Detail tiers:
+${Object.values(WOMPIFY_PRESETS).map(tier => `${tier.label}: ${tier.instructions}`).join("\n")}
+Compare orthographic Kakapo screenshots in the prepared lightweight render mode throughout reconstruction. Use identical cameras for reference and result: inspect front, side, back and oblique views, then close-ups.
+Show only the reference and capture/emit it; repeat with only the result. Restore reference/result visibility in finally if a comparison fails; keep unrelated objects hidden. Identify discrepancies and keep refining the same objects toward an accurate match.
+Finish with matched comparisons and verified saved objects, reference hidden and result visible. If unfinished, keep the editable partial result and report remaining mismatches.`,
+    declarations: "",
+    examples: [],
+};

package/dist/prompt.d.ts

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

package/dist/prompt.js

@@ -37,6 +37,8 @@ asks to change it. Creation defaults do not apply to help, discussion, imports,
   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.

package/dist/ui.d.ts

@@ -323,3 +323,4 @@ export declare const sparkDataPartSchemas: {
         usage: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
 };
+export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, type WompifyRequest } from "./wompify.js";

package/dist/ui.js

@@ -79,3 +79,4 @@ export const sparkDataPartSchemas = {
         usage: z.unknown().optional(),
     }),
 };
+export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt } from "./wompify.js";

package/dist/wompify.d.ts

@@ -0,0 +1,22 @@
+export declare const WOMPIFY_PRESETS: {
+    readonly simple: {
+        readonly label: "Simple";
+        readonly instructions: "Prioritize the main forms, proportions, silhouettes and colors, with a compact editable construction.";
+    };
+    readonly high: {
+        readonly label: "High res";
+        readonly instructions: "Refine both the main forms and smaller characteristic shapes, checking each region from multiple views.";
+    };
+    readonly ultra: {
+        readonly label: "Ultra";
+        readonly instructions: "Target the closest practical geometric match, including subtle contours and small modeled details, with thorough close-up comparisons.";
+    };
+};
+export type WompifyRequest = {
+    preset: keyof typeof WOMPIFY_PRESETS;
+};
+export declare function wompifyPrompt(preset: WompifyRequest["preset"], referenceName: string, note?: string): string;
+export declare function parseWompifyCommand(text: string): {
+    preset: WompifyRequest["preset"];
+    note: string;
+} | undefined;

package/dist/wompify.js

@@ -0,0 +1,13 @@
+export const WOMPIFY_PRESETS = {
+    simple: { label: "Simple", instructions: "Prioritize the main forms, proportions, silhouettes and colors, with a compact editable construction." },
+    high: { label: "High res", instructions: "Refine both the main forms and smaller characteristic shapes, checking each region from multiple views." },
+    ultra: { label: "Ultra", instructions: "Target the closest practical geometric match, including subtle contours and small modeled details, with thorough close-up comparisons." },
+};
+export function wompifyPrompt(preset, referenceName, note = "") {
+    return `Wompify ${JSON.stringify(referenceName)} using the mesh-wompify skill; stop if that skill is unavailable.
+Selected tier: ${WOMPIFY_PRESETS[preset].label}.${note.trim() ? `\nUser request: ${note.trim()}` : ""}`;
+}
+export function parseWompifyCommand(text) {
+    const match = /^\/wompify (simple|high|ultra)(?:\n([\s\S]*))?$/u.exec(text.trim());
+    return match ? { preset: match[1], note: match[2]?.trim() ?? "" } : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",