@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/src/agent/mcp/tools.js

@@ -222,51 +222,64 @@ export const toolDefinitions = {
     // Onboarding Tools
     get_sdk_context: {
         name: 'get_sdk_context',
-        description: 'Returns essential SDK context for agent onboarding. Call this first to understand the system.',
+        description: 'Returns a compact capability manifest: what systems exist, what tools are available, what parameter ranges are valid, and what the current engine state is. Designed for injection into agent context — call once at session start, not repeatedly.',
         inputSchema: {
             type: 'object',
-            properties: {}
+            properties: {
+                include_state: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Include current engine state in response'
+                },
+                include_tools: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Include tool summary list (names + one-line descriptions)'
+                }
+            }
         }
     },
 
-    verify_knowledge: {
-        name: 'verify_knowledge',
-        description: 'Verifies agent has absorbed SDK context. Multiple choice quiz - submit letter answers (a/b/c/d).',
+    inspect_layers: {
+        name: 'inspect_layers',
+        description: 'Returns the current state of all holographic canvas layers with per-layer metadata: role, opacity, blend mode, reactivity multiplier, role-specific parameters, and enabled state. Only meaningful when holographic system is active.',
         inputSchema: {
             type: 'object',
             properties: {
-                q1_rotation_planes: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q1: How many rotation planes? a)3 b)4 c)6 d)8'
-                },
-                q2_geometry_formula: {
+                layer: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q2: Geometry encoding formula? a)base*3+core b)core*8+base c)base+core d)core*base'
-                },
-                q3_canvas_layers: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q3: Canvas layers per system? a)3 b)4 c)5 d)6'
-                },
-                q4_active_systems: {
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent', 'all'],
+                    default: 'all',
+                    description: 'Inspect a specific layer or all layers'
+                }
+            }
+        }
+    },
+
+    set_holographic_layer: {
+        name: 'set_holographic_layer',
+        description: 'Controls individual holographic layer properties. Set opacity, blend mode, enable/disable, or override role parameters for any of the 5 layers (background, shadow, content, highlight, accent). Only works when holographic system is active.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q4: Which are the 3 ACTIVE systems? a)quantum,faceted,holographic b)quantum,faceted,polychora c)faceted,holographic,polychora d)all four'
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Target layer role name'
                 },
-                q5_base_geometries: {
+                opacity: { type: 'number', minimum: 0, maximum: 1, description: 'Layer opacity (0=invisible, 1=full)' },
+                blendMode: {
                     type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q5: How many base geometry types? a)6 b)8 c)10 d)24'
+                    enum: ['normal', 'screen', 'multiply', 'add', 'overlay'],
+                    description: 'CSS blend mode for this layer'
                 },
-                q6_core_types: {
-                    type: 'string',
-                    enum: ['a', 'b', 'c', 'd'],
-                    description: 'Q6: Core warp types? a)base,sphere,cube b)base,hypersphere,hypertetrahedron c)none,partial,full d)2D,3D,4D'
-                }
+                enabled: { type: 'boolean', description: 'Show/hide this layer' },
+                colorShift: { type: 'number', minimum: 0, maximum: 360, description: 'Hue offset for this layer' },
+                densityMult: { type: 'number', minimum: 0.1, maximum: 5, description: 'Grid density multiplier' },
+                speedMult: { type: 'number', minimum: 0, maximum: 3, description: 'Animation speed multiplier' },
+                reactivity: { type: 'number', minimum: 0, maximum: 3, description: 'Mouse/touch reactivity multiplier' }
             },
-            required: ['q1_rotation_planes', 'q2_geometry_formula', 'q3_canvas_layers']
+            required: ['layer']
         }
     },
 
@@ -395,6 +408,460 @@ export const toolDefinitions = {
             type: 'object',
             properties: {}
         }
+    },
+
+    // ===== AGENT-POWER TOOLS (Phase 7 — Agent Harness) =====
+
+    describe_visual_state: {
+        name: 'describe_visual_state',
+        description: 'Returns a structured natural-language description of the current visualization state. Useful for multimodal agents to understand what the visualization looks like without a screenshot. Includes system, geometry, color mood, motion character, and complexity assessment.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    batch_set_parameters: {
+        name: 'batch_set_parameters',
+        description: 'Atomically sets multiple parameters including rotation, visual, and system in one call. Prevents intermediate render states. More efficient than calling set_rotation + set_visual_parameters separately.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                system: {
+                    type: 'string',
+                    enum: ['quantum', 'faceted', 'holographic'],
+                    description: 'Optional: switch system first'
+                },
+                geometry: {
+                    type: 'integer',
+                    minimum: 0,
+                    maximum: 23,
+                    description: 'Geometry index'
+                },
+                rotation: {
+                    type: 'object',
+                    description: '6D rotation angles (all optional)',
+                    properties: {
+                        XY: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        XZ: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        YZ: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        XW: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        YW: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        ZW: { type: 'number', minimum: -6.28, maximum: 6.28 }
+                    }
+                },
+                visual: {
+                    type: 'object',
+                    description: 'Visual parameters (all optional)',
+                    properties: {
+                        hue: { type: 'integer', minimum: 0, maximum: 360 },
+                        saturation: { type: 'number', minimum: 0, maximum: 1 },
+                        intensity: { type: 'number', minimum: 0, maximum: 1 },
+                        speed: { type: 'number', minimum: 0.1, maximum: 3 },
+                        chaos: { type: 'number', minimum: 0, maximum: 1 },
+                        morphFactor: { type: 'number', minimum: 0, maximum: 2 },
+                        gridDensity: { type: 'number', minimum: 4, maximum: 100 },
+                        dimension: { type: 'number', minimum: 3.0, maximum: 4.5 }
+                    }
+                },
+                preset: {
+                    type: 'string',
+                    enum: ['ambient', 'reactive', 'immersive', 'energetic', 'calm', 'cinematic'],
+                    description: 'Optional: apply behavior preset after setting params'
+                }
+            }
+        }
+    },
+
+    create_timeline: {
+        name: 'create_timeline',
+        description: 'Creates a ParameterTimeline animation from a track specification. Supports multi-parameter keyframe animation with per-keyframe easing, BPM sync, and loop modes. Returns timeline ID for playback control.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Timeline name' },
+                duration_ms: { type: 'integer', minimum: 100, maximum: 600000, description: 'Total duration in milliseconds' },
+                bpm: { type: 'number', minimum: 20, maximum: 300, description: 'Optional BPM for beat-sync quantization' },
+                loop_mode: {
+                    type: 'string',
+                    enum: ['loop', 'bounce', 'once'],
+                    default: 'once',
+                    description: 'Playback loop mode'
+                },
+                tracks: {
+                    type: 'object',
+                    description: 'Parameter tracks. Each key is a parameter name, value is array of keyframes [{time, value, easing}]',
+                    additionalProperties: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                time: { type: 'number', description: 'Time in ms from start' },
+                                value: { type: 'number', description: 'Parameter value at this keyframe' },
+                                easing: {
+                                    type: 'string',
+                                    enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'quadIn', 'quadOut', 'cubicIn', 'cubicOut', 'elastic', 'bounce', 'spring', 'overshoot', 'sine', 'exponential'],
+                                    default: 'easeInOut',
+                                    description: 'Easing function for interpolation TO this keyframe'
+                                }
+                            },
+                            required: ['time', 'value']
+                        }
+                    }
+                }
+            },
+            required: ['duration_ms', 'tracks']
+        }
+    },
+
+    play_transition: {
+        name: 'play_transition',
+        description: 'Plays a smooth animated transition from current parameter values to target values, or a sequence of transitions. Uses the TransitionAnimator system with configurable easing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sequence: {
+                    type: 'array',
+                    description: 'Array of transition steps. Each step smoothly animates to target params.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            params: {
+                                type: 'object',
+                                description: 'Target parameter values (any VIB3+ parameter)',
+                                additionalProperties: { type: 'number' }
+                            },
+                            duration: { type: 'integer', minimum: 50, maximum: 30000, default: 1000, description: 'Step duration in ms' },
+                            easing: {
+                                type: 'string',
+                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'quadIn', 'quadOut', 'cubicIn', 'cubicOut', 'elastic', 'bounce', 'spring', 'overshoot', 'sine', 'exponential'],
+                                default: 'easeInOut'
+                            },
+                            delay: { type: 'integer', minimum: 0, default: 0, description: 'Delay before this step starts (ms)' }
+                        },
+                        required: ['params']
+                    }
+                }
+            },
+            required: ['sequence']
+        }
+    },
+
+    apply_color_preset: {
+        name: 'apply_color_preset',
+        description: 'Applies one of 22 themed color presets that set hue, saturation, intensity, and optionally post-processing to create a cohesive visual theme.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                preset: {
+                    type: 'string',
+                    enum: ['Ocean', 'Lava', 'Neon', 'Monochrome', 'Sunset', 'Aurora', 'Cyberpunk', 'Forest', 'Desert', 'Galaxy', 'Ice', 'Fire', 'Toxic', 'Royal', 'Pastel', 'Retro', 'Midnight', 'Tropical', 'Ethereal', 'Volcanic', 'Holographic', 'Vaporwave'],
+                    description: 'Color preset name'
+                }
+            },
+            required: ['preset']
+        }
+    },
+
+    set_post_processing: {
+        name: 'set_post_processing',
+        description: 'Configures post-processing effects pipeline. Supports 14 composable effects and 7 preset chains. Effects are applied in order.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                effects: {
+                    type: 'array',
+                    description: 'Ordered list of effects to apply',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                enum: ['bloom', 'chromaticAberration', 'vignette', 'filmGrain', 'scanlines', 'pixelate', 'blur', 'sharpen', 'colorGrade', 'noise', 'distort', 'glitch', 'rgbShift', 'feedback'],
+                                description: 'Effect name'
+                            },
+                            intensity: { type: 'number', minimum: 0, maximum: 1, default: 0.5, description: 'Effect strength' },
+                            enabled: { type: 'boolean', default: true }
+                        },
+                        required: ['name']
+                    }
+                },
+                chain_preset: {
+                    type: 'string',
+                    description: 'Alternative: apply a named preset chain instead of individual effects'
+                },
+                clear_first: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Clear existing effects before applying new ones'
+                }
+            }
+        }
+    },
+
+    create_choreography: {
+        name: 'create_choreography',
+        description: 'Creates a multi-scene choreography specification with system transitions, timelines, audio config, and post-processing per scene. This is the most powerful agent tool — it allows designing complete synchronized visual performances that would be extremely difficult to create manually.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Choreography name' },
+                duration_ms: { type: 'integer', minimum: 1000, description: 'Total choreography duration' },
+                bpm: { type: 'number', minimum: 20, maximum: 300, description: 'Optional BPM for beat sync' },
+                scenes: {
+                    type: 'array',
+                    description: 'Ordered scene definitions. Each scene has a time range, system/geometry, and parameter timeline.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            time_start: { type: 'integer', minimum: 0, description: 'Scene start time (ms)' },
+                            time_end: { type: 'integer', description: 'Scene end time (ms)' },
+                            system: { type: 'string', enum: ['quantum', 'faceted', 'holographic'] },
+                            geometry: { type: 'integer', minimum: 0, maximum: 23 },
+                            transition_in: {
+                                type: 'object',
+                                description: 'How this scene enters (crossfade, cut, etc.)',
+                                properties: {
+                                    type: { type: 'string', enum: ['cut', 'crossfade', 'wipe', 'dissolve', 'zoom'] },
+                                    duration: { type: 'integer', minimum: 0 }
+                                }
+                            },
+                            tracks: {
+                                type: 'object',
+                                description: 'Parameter timeline tracks for this scene (same format as create_timeline)',
+                                additionalProperties: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            time: { type: 'number' },
+                                            value: { type: 'number' },
+                                            easing: { type: 'string' }
+                                        }
+                                    }
+                                }
+                            },
+                            color_preset: { type: 'string', description: 'Color preset for this scene' },
+                            post_processing: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Post-processing effects active during this scene'
+                            },
+                            audio: {
+                                type: 'object',
+                                description: 'Audio reactivity config for this scene'
+                            }
+                        },
+                        required: ['time_start', 'time_end', 'system']
+                    }
+                }
+            },
+            required: ['name', 'duration_ms', 'scenes']
+        }
+    },
+
+    // ===== VISUAL FEEDBACK TOOLS (Phase 7.1 — Agent Harness) =====
+
+    capture_screenshot: {
+        name: 'capture_screenshot',
+        description: 'Captures current visualization as a base64-encoded PNG by compositing canvas layers. BROWSER-ONLY: returns an EnvironmentError with capability report in headless/Node contexts. When available, returns data_url for multimodal analysis. Use describe_visual_state as a text-based alternative in non-browser environments.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                width: { type: 'integer', minimum: 64, maximum: 2048, default: 512, description: 'Output image width' },
+                height: { type: 'integer', minimum: 64, maximum: 2048, default: 512, description: 'Output image height' },
+                format: {
+                    type: 'string',
+                    enum: ['png', 'jpeg', 'webp'],
+                    default: 'png',
+                    description: 'Image format'
+                },
+                quality: { type: 'number', minimum: 0.1, maximum: 1.0, default: 0.92, description: 'JPEG/WebP quality' }
+            }
+        }
+    },
+
+    design_from_description: {
+        name: 'design_from_description',
+        description: 'Maps a natural-language aesthetic description to VIB3+ parameters. Understands emotions (serene, energetic, mysterious), styles (minimal, intricate, organic), colors (ocean, neon, cyberpunk), motion (flowing, pulsing, hypnotic), depth (deep, flat), and geometry (spherical, fractal, crystal). Combine multiple words for precise targeting.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'Space-separated aesthetic descriptors. Examples: "serene ocean deep minimal", "energetic neon geometric", "mysterious galaxy intricate hypnotic"'
+                },
+                apply: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'If true, immediately apply the resolved parameters to the engine'
+                }
+            },
+            required: ['description']
+        }
+    },
+
+    get_aesthetic_vocabulary: {
+        name: 'get_aesthetic_vocabulary',
+        description: 'Returns the full vocabulary of aesthetic descriptor words organized by category (emotions, styles, colors, motion, depth, geometry). Use this to discover what descriptions the system understands.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    play_choreography: {
+        name: 'play_choreography',
+        description: 'Loads and plays a choreography specification on the engine. Requires a choreography spec (from create_choreography) or a stored choreography ID. Controls: play, pause, stop, seek.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                choreography: {
+                    type: 'object',
+                    description: 'Full choreography spec (from create_choreography output). Provide this OR choreography_id.'
+                },
+                choreography_id: {
+                    type: 'string',
+                    description: 'ID of a previously created choreography (from create_choreography)'
+                },
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'stop', 'seek'],
+                    default: 'play',
+                    description: 'Playback action'
+                },
+                seek_percent: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: 'For seek action: position as 0-1 percentage'
+                },
+                loop: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Loop the choreography'
+                }
+            }
+        }
+    },
+
+    control_timeline: {
+        name: 'control_timeline',
+        description: 'Controls playback of a previously created timeline (from create_timeline). Actions: play, pause, stop, seek, set_speed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timeline_id: {
+                    type: 'string',
+                    description: 'ID of the timeline to control'
+                },
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'stop', 'seek', 'set_speed'],
+                    description: 'Playback control action'
+                },
+                seek_percent: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: 'For seek: position as 0-1 percentage'
+                },
+                speed: {
+                    type: 'number',
+                    minimum: 0.1,
+                    maximum: 10,
+                    description: 'For set_speed: playback speed multiplier'
+                }
+            },
+            required: ['timeline_id', 'action']
+        }
+    },
+
+    // Layer Relationship Tools (Phase 8)
+    set_layer_profile: {
+        name: 'set_layer_profile',
+        description: 'Loads a named layer relationship profile that configures how the 5 canvas layers relate to each other. Profiles: holographic (default), symmetry, chord, storm, legacy (original static behavior).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                profile: {
+                    type: 'string',
+                    enum: ['holographic', 'symmetry', 'chord', 'storm', 'legacy'],
+                    description: 'Named profile to load'
+                }
+            },
+            required: ['profile']
+        }
+    },
+
+    set_layer_relationship: {
+        name: 'set_layer_relationship',
+        description: 'Sets the relationship type for a specific layer relative to the keystone. Available relationships: echo (attenuated follower), mirror (inverted rotation/hue), complement (color opposite), harmonic (musical intervals), reactive (amplifies changes), chase (delayed follower).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Target layer name'
+                },
+                relationship: {
+                    type: 'string',
+                    enum: ['echo', 'mirror', 'complement', 'harmonic', 'reactive', 'chase'],
+                    description: 'Relationship preset name'
+                },
+                config: {
+                    type: 'object',
+                    description: 'Optional config overrides for the relationship (e.g., { opacity: 0.5, gain: 3 })'
+                }
+            },
+            required: ['layer', 'relationship']
+        }
+    },
+
+    set_layer_keystone: {
+        name: 'set_layer_keystone',
+        description: 'Changes which layer acts as the keystone (driver) for the layer relationship graph. Other layers derive their parameters from the keystone through relationship functions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Layer to designate as keystone'
+                }
+            },
+            required: ['layer']
+        }
+    },
+
+    get_layer_config: {
+        name: 'get_layer_config',
+        description: 'Returns the current layer relationship configuration including keystone, profile, and per-layer relationships with their config parameters.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    tune_layer_relationship: {
+        name: 'tune_layer_relationship',
+        description: 'Hot-patches a layer relationship config without replacing the full graph. Merges provided config values into the existing relationship (e.g., increase reactive gain, shift harmonic hue angle).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                layer: {
+                    type: 'string',
+                    enum: ['background', 'shadow', 'content', 'highlight', 'accent'],
+                    description: 'Layer to tune'
+                },
+                config: {
+                    type: 'object',
+                    description: 'Config values to merge (e.g., { opacity: 0.6, gain: 3.0, hueAngle: 120 })'
+                }
+            },
+            required: ['layer', 'config']
+        }
     }
 };