autokap 1.0.7 → 1.0.8

package/dist/tools.js

@@ -1,114 +1,57 @@
 // Note: evaluation_previous_action and memory fields are no longer injected into
 // tool schemas. They are documented in the system prompt instead (see prompts.ts),
-// which saves ~1,268 tokens/iteration by avoiding duplication across all tools.
+// which saves tokens on every iteration.
+const akTypeEnum = [
+    'button', 'input', 'link', 'text', 'image', 'heading',
+    'list', 'table', 'container', 'icon', 'toggle', 'select',
+    'checkbox', 'radio', 'slider', 'tab', 'modal', 'nav', 'form',
+    'video', 'audio', 'iframe',
+];
+const semanticPatternEnum = [
+    'cookie-banner', 'modal', 'navbar', 'footer', 'hero',
+    'sidebar', 'dropdown', 'toast', 'tooltip', 'form', 'card',
+    'pricing-table', 'cta-group',
+];
+const semanticTraitEnum = [
+    'floating', 'overlay', 'sticky', 'fixed',
+    'above-fold', 'below-fold', 'full-width', 'scrollable',
+];
 export const agentTools = [
     {
         type: 'function',
         function: {
-            name: 'click',
-            description: 'Click or hover an element. Prefer index ([N] badge). Use hover_only=true for menus, tooltips, popovers.',
+            name: 'tap',
+            description: 'Click an element identified by its AKTree nodeId.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    index: {
-                        type: 'number',
-                        description: 'Element badge index [N].',
-                    },
-                    selector: {
+                    nodeId: {
                         type: 'string',
-                        description: 'CSS selector. Use only when index is unavailable.',
-                    },
-                    x: {
-                        type: 'number',
-                        description: 'X coordinate (viewport pixels). Last resort.',
-                    },
-                    y: {
-                        type: 'number',
-                        description: 'Y coordinate (viewport pixels). Last resort.',
-                    },
-                    hover_only: {
-                        type: 'boolean',
-                        description: 'If true, hover without clicking. Use to reveal dropdown menus, tooltips, mega-navs, or account popovers.',
+                        description: 'Stable AKTree node id, for example "ak_3f8a2c1b".',
                     },
                 },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: ['nodeId'],
             },
         },
     },
     {
         type: 'function',
         function: {
-            name: 'type_text',
-            description: 'Type text into an input field.',
+            name: 'type',
+            description: 'Type text into a text-like control identified by AKTree nodeId.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
+                    nodeId: {
                         type: 'string',
-                        description: 'Brief reason.',
+                        description: 'Stable AKTree node id of the target input.',
                     },
                     text: {
                         type: 'string',
-                        description: 'Text to type. When credentials are available, use placeholders like {{credential.email}} or {{credential.password}} instead of guessing the value.',
-                    },
-                    index: {
-                        type: 'number',
-                        description: 'Index of the input element to type into.',
-                    },
-                    selector: {
-                        type: 'string',
-                        description: 'CSS selector of the input element.',
-                    },
-                    clearFirst: {
-                        type: 'boolean',
-                        description: 'Clear the input before typing. Default false.',
+                        description: 'Text to type. Use credential placeholders when available.',
                     },
                 },
-                required: ['reason', 'text'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'select_option',
-            description: 'Change a native select/dropdown value (sort, filter, language, theme).',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    index: {
-                        type: 'number',
-                        description: 'Element badge index [N].',
-                    },
-                    selector: {
-                        type: 'string',
-                        description: 'CSS selector. Use only when index is unavailable.',
-                    },
-                    optionLabel: {
-                        type: 'string',
-                        description: 'Visible label of the option to choose.',
-                    },
-                    optionValue: {
-                        type: 'string',
-                        description: 'Underlying option value to choose.',
-                    },
-                    optionIndex: {
-                        type: 'number',
-                        description: 'Zero-based option index to choose if label/value are unavailable.',
-                    },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: ['nodeId', 'text'],
             },
         },
     },
@@ -116,123 +59,80 @@ export const agentTools = [
         type: 'function',
         function: {
             name: 'scroll',
-            description: 'Scroll the page or bring an element into view. Use index to scroll element into view (preferred); direction+amount for general scrolling.',
+            description: 'Scroll the page or a scrollable AKTree container. Use direction/offset for manual scrolling, or centerOn to center another AKTree node inside the page or container.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
                     direction: {
                         type: 'string',
                         enum: ['up', 'down', 'left', 'right'],
-                        description: 'Scroll direction. Required unless using index.',
-                    },
-                    amount: {
-                        type: 'number',
-                        description: 'Pixels to scroll. Default 500.',
-                    },
-                    selector: {
-                        type: 'string',
-                        description: 'CSS selector of a scrollable container. Omit for page scroll.',
+                        description: 'Scroll direction for manual scrolling. Optional when centerOn is provided.',
                     },
-                    index: {
+                    offset: {
                         type: 'number',
-                        description: 'Element index to scroll into view. Ignores direction/amount.',
+                        description: 'Optional scroll offset in pixels for manual scrolling, or bias in pixels from perfect center when centerOn is provided.',
                     },
-                    align: {
+                    target: {
                         type: 'string',
-                        enum: ['start', 'center', 'end'],
-                        description: 'Where to place the element when using index. Default: center.',
+                        description: 'Optional AKTree node id of a scrollable container. Omit to scroll the page.',
                     },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'press_key',
-            description: 'Press a key or combination. Examples: "Escape", "Enter", "Tab", "ArrowDown".',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    key: {
+                    centerOn: {
                         type: 'string',
-                        description: 'Key to press (Playwright key names).',
+                        description: 'Optional AKTree node id to bring to the center of the page or of the target container.',
                     },
                 },
-                required: ['reason', 'key'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: [],
             },
         },
     },
     {
         type: 'function',
         function: {
-            name: 'dismiss_overlays',
-            description: 'Dismiss cookie banners and chat/feedback widgets. Use after navigation, after resize, or when the screenshot is obstructed.',
+            name: 'navigate_to',
+            description: 'Navigate directly to a URL on the current site when that is the fastest deterministic way to reach the target.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
+                    url: {
                         type: 'string',
-                        description: 'Brief reason.',
+                        description: 'Absolute or site-relative URL to navigate to.',
                     },
                 },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: ['url'],
             },
         },
     },
     {
         type: 'function',
         function: {
-            name: 'wait',
-            description: 'Wait for a duration. Use when the page is loading or animating.',
+            name: 'press_key',
+            description: 'Press a keyboard key when the workflow requires Escape, Enter, Tab, or arrow keys.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
+                    key: {
                         type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    milliseconds: {
-                        type: 'number',
-                        description: 'Wait duration in ms. Default 1000, max 5000.',
+                        description: 'Keyboard key name, for example "Escape", "Enter", "Tab", "ArrowDown".',
                     },
                 },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: ['key'],
             },
         },
     },
     {
         type: 'function',
         function: {
-            name: 'search_text',
-            description: 'Search the DOM for elements containing text — use when an element is visible in the screenshot but absent from the elements list. Returns tag, text, position and size for clicking by coordinates.',
+            name: 'capture',
+            description: 'Capture the current target and end the current run. When nodeId is provided, crop to that node bounds.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    query: {
+                    nodeId: {
                         type: 'string',
-                        description: 'Text to search (case-insensitive partial match). Use a short phrase visible on the page.',
+                        description: 'Optional AKTree node id to crop. Omit for a page-level capture.',
                     },
                 },
-                required: ['reason', 'query'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: [],
             },
         },
     },
@@ -240,339 +140,77 @@ export const agentTools = [
         type: 'function',
         function: {
             name: 'analyze_screenshot',
-            description: 'Request a visual analysis of the current page screenshot. Use when the DOM structure alone is insufficient — for visual layout, colors, theme checks, overlay/spinner detection, or rendering verification. Returns a text description of what is visually on screen.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Why visual analysis is needed (e.g., "check theme colors", "verify no overlay blocking content").',
-                    },
-                },
-                required: ['reason'],
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'navigate_to',
-            description: 'Navigate to a URL. Page fully loads before continuing.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    url: {
-                        type: 'string',
-                        description: 'The full URL to navigate to.',
-                    },
-                },
-                required: ['reason', 'url'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'resize_viewport',
-            description: 'Resize viewport (desktop/tablet/mobile). Wait after resizing for layout to settle.',
+            description: 'Ask the vision model a targeted question about the current screenshot when AKTree structure is insufficient.',
             parameters: {
                 type: 'object',
                 properties: {
-                    reason: {
+                    question: {
                         type: 'string',
-                        description: 'Brief reason.',
-                    },
-                    width: {
-                        type: 'number',
-                        description: 'Width in px (e.g. 1440 desktop, 768 tablet, 375 mobile).',
-                    },
-                    height: {
-                        type: 'number',
-                        description: 'Height in px (e.g. 900 desktop, 1024 tablet, 812 mobile).',
+                        description: 'Specific visual question to answer, for example "Is a modal blocking the page?" or "Does this dialog already show the target template selected?"',
                     },
                 },
-                required: ['reason', 'width', 'height'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: ['question'],
             },
         },
     },
     {
         type: 'function',
         function: {
-            name: 'take_screenshot',
-            description: 'Capture a screenshot without ending the session — use for intermediate captures in multi-step workflows. Loop continues after this. Use ready_to_capture for the final screenshot.',
+            name: 'focus',
+            description: 'Return a filtered AKTree view using typed filters only.',
             parameters: {
                 type: 'object',
                 properties: {
-                    label: {
-                        type: 'string',
-                        description: 'Short label, e.g. "Landing page hero section", "Dashboard after login".',
+                    type: {
+                        type: 'array',
+                        items: { type: 'string', enum: [...akTypeEnum] },
+                        description: 'Optional node types to keep.',
                     },
-                    assessment: {
-                        type: 'string',
-                        description: 'Why this is a good capture moment (no overlays/spinners, correct content visible).',
+                    semantic: {
+                        type: 'array',
+                        items: { type: 'string', enum: [...semanticPatternEnum] },
+                        description: 'Optional semantic patterns to keep.',
                     },
-                },
-                required: ['label', 'assessment'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'ready_to_capture',
-            description: 'Signal the ENTIRE workflow is complete and capture the final screenshot — ends the session. Use take_screenshot for intermediate captures. Set force=true only if the blocking dialog IS the intended capture target.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    assessment: {
-                        type: 'string',
-                        description: 'Why the workflow is complete and the page is ready.',
+                    trait: {
+                        type: 'array',
+                        items: { type: 'string', enum: [...semanticTraitEnum] },
+                        description: 'Optional semantic traits to keep.',
                     },
-                    force: {
+                    interactive: {
                         type: 'boolean',
-                        description: 'Bypass dialog check when the dialog IS the capture target. Only after a "Blocking dialog" failure.',
+                        description: 'Optional interactive filter.',
                     },
-                },
-                required: ['assessment'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'give_up',
-            description: 'Signal that the requested screenshot cannot be achieved. Use when: login required, content missing, or stuck in a loop.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Explanation of why capture cannot be completed.',
+                    visible: {
+                        type: 'boolean',
+                        description: 'Optional visibility filter.',
                     },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'begin_subgoal',
-            description: 'Declare a new sub-objective. Archives previous notes and resets working memory. Use at natural workflow boundaries: after login, before language/theme change, before new section, before final capture.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    name: {
+                    within: {
                         type: 'string',
-                        description: 'Snake_case name (max 4 words). Examples: login, set_language, navigate_to_pricing.',
+                        description: 'Optional AKTree node id used as subtree scope.',
                     },
-                    progress_summary: {
+                    labelContains: {
                         type: 'string',
-                        description: 'One-line summary of what was accomplished in the PREVIOUS subgoal (max 120 chars). Omit on the very first subgoal.',
+                        description: 'Case-insensitive substring match against node labels.',
                     },
-                },
-                required: ['name'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'note',
-            description: 'Store a key observation or fact to remember across iterations. Use when you discover important information (element locations, page state, multi-step findings) that you will need in later iterations.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Short label for this note (snake_case, max 6 tokens).',
+                    maxDepth: {
+                        type: 'number',
+                        description: 'Optional maximum subtree depth.',
                     },
-                    content: {
-                        type: 'string',
-                        description: 'The observation to store (max 120 chars).',
+                    includeAncestors: {
+                        type: 'boolean',
+                        description: 'Include parent path to the root when true.',
                     },
                 },
-                required: ['reason', 'content'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
+                required: [],
             },
         },
     },
 ];
 /** Restricted tool set for the element capture mini-agent */
 export const elementCaptureTools = [
-    {
-        type: 'function',
-        function: {
-            name: 'capture_by_selector',
-            description: 'Capture a screenshot of a page element or component identified by a unique CSS selector. ' +
-                'Works for both single interactive elements (buttons, inputs) and full components or sections ' +
-                '(navigation bars, forms, pricing tables, hero sections). ' +
-                'The selector MUST match exactly one visible element — the system validates this before capturing. ' +
-                'Resolve the selector using this priority order: ' +
-                '1) [data-testid="..."] or [data-component="..."] — most stable; ' +
-                '2) ARIA landmark with label: nav[aria-label="Main"], [role="dialog"]; ' +
-                '3) Unique ID: #hero-section, #pricing-table; ' +
-                '4) Semantic class on a semantic element: form.login-form, section.pricing, nav.main-nav; ' +
-                '5) DOM path as last resort: header > .site-logo. ' +
-                'If the system returns a validation error (no match, ambiguous, invisible), read the reason and retry with a refined selector. ' +
-                'Use the sel="" values shown in the interactive elements list as starting points for selector construction. ' +
-                'If a previous capture was rejected only because the crop was too loose, stay grounded on sel="" values returned by the tools and prefer any search_text container selector instead of inventing a tag-only DOM path from the simplified DOM.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    selector: {
-                        type: 'string',
-                        description: 'A unique CSS selector matching exactly one visible element. ' +
-                            'Examples: [data-testid="pricing-card"], #hero-section, nav[aria-label="Main navigation"], ' +
-                            '.pricing-table, form.login-form, header > .navbar',
-                    },
-                    confidence: {
-                        type: 'number',
-                        description: 'How confident you are this selector matches the correct element (0.0 to 1.0).',
-                    },
-                    reasoning: {
-                        type: 'string',
-                        description: 'Brief explanation of why this selector was chosen and what it should match.',
-                    },
-                },
-                required: ['selector', 'confidence', 'reasoning'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'scroll',
-            description: 'Scroll the page to reveal off-screen elements. Provide index to snap a known interactive element into view (preferred). Provide direction+amount for general scrolling.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief explanation of why you are scrolling.',
-                    },
-                    direction: {
-                        type: 'string',
-                        enum: ['up', 'down'],
-                        description: 'Scroll direction. Required unless using index.',
-                    },
-                    amount: {
-                        type: 'number',
-                        description: 'Pixels to scroll. Default 500.',
-                    },
-                    index: {
-                        type: 'number',
-                        description: 'Index of an interactive element to scroll into view. When provided, direction/amount are ignored.',
-                    },
-                    align: {
-                        type: 'string',
-                        enum: ['start', 'center', 'end'],
-                        description: 'Alignment when using index. Default: center.',
-                    },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'dismiss_overlays',
-            description: 'Dismiss cookie banners and hide common sticky overlays/widgets before capturing an element.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief explanation of why you are dismissing overlays.',
-                    },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'search_text',
-            description: 'Search the entire page DOM for elements containing specific text. ' +
-                'Returns matching elements with tag, text, position, size, and a sel="..." CSS selector. ' +
-                'Use the sel= value directly in capture_by_selector — no need to scroll first.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief explanation of why you are searching for this text.',
-                    },
-                    query: {
-                        type: 'string',
-                        description: 'Text to search for (case-insensitive partial match).',
-                    },
-                },
-                required: ['reason', 'query'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'resize_viewport',
-            description: 'Resize the browser viewport. Use this when the target component is taller or wider than the current viewport ' +
-                'and you need to see or capture it in full. After resizing, the page re-renders and you get an updated screenshot ' +
-                'on the next iteration. The viewport will be restored to its original size after capture.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Brief explanation of why you are resizing the viewport.',
-                    },
-                    width: {
-                        type: 'number',
-                        description: 'New viewport width in CSS pixels.',
-                    },
-                    height: {
-                        type: 'number',
-                        description: 'New viewport height in CSS pixels.',
-                    },
-                },
-                required: ['reason', 'width', 'height'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'give_up',
-            description: 'Signal that the described element cannot be found on the page.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    reason: {
-                        type: 'string',
-                        description: 'Explanation of why the element cannot be found.',
-                    },
-                },
-                required: ['reason'],
-                // NOTE: additionalProperties omitted — strict schema validation can cause tool parsing failures on some models
-            },
-        },
-    },
+    agentTools[7],
+    agentTools[2],
+    agentTools[6],
+    agentTools[5],
 ];
 //# sourceMappingURL=tools.js.map