site-agent-pro 1.0.0

package/dist/core/taskDirectives.js

@@ -0,0 +1,279 @@
+import { normalizeTaskText } from "./taskHeuristics.js";
+const ACTION_WORD_PATTERN = "(?:click|tap|press|open|select|choose|copy|fill(?:\\s+(?:out|up|in))?|enter|type|input|provide|submit|create|register|sign\\s*up|signup|join|scroll|swipe|wait|pause|hold|go back|back|stop|halt)";
+function cleanDirectiveText(value) {
+    return normalizeTaskText(value
+        .replace(/^["'`]+|["'`]+$/g, "")
+        .replace(/^(?:task|step)\s+\d+[:.)-]?\s*/i, "")
+        .replace(/[.?!,]+$/g, ""));
+}
+function cleanDirectiveTarget(value) {
+    return cleanDirectiveText(value
+        .replace(/^(?:on|into|to)\s+/i, "")
+        .replace(/^(?:the|a|an|your|my|this|that)\s+/i, "")
+        .replace(/^(?:only|just)\s+/i, "")
+        .replace(/\s+(?:tab|tabs|button|buttons|link|links|option|options|page|pages|screen|screens|section|sections|menu|item|items|cta|card|cards)\b.*$/i, ""));
+}
+function splitDirectiveSegments(taskText) {
+    const normalized = normalizeTaskText(taskText)
+        .replace(new RegExp(`\\b(?:and then|then|after that|afterwards)\\b`, "gi"), "; ")
+        .replace(new RegExp(`\\bnext\\b(?=\\s*${ACTION_WORD_PATTERN}\\b)`, "gi"), "; ")
+        .replace(new RegExp(`\\band\\b(?=\\s*${ACTION_WORD_PATTERN}\\b)`, "gi"), "; ")
+        .replace(new RegExp(`,(?=\\s*${ACTION_WORD_PATTERN}\\b)`, "gi"), "; ");
+    return normalized
+        .split(/[;]+/)
+        .map((segment) => segment
+        .replace(/^(?:first|second|third|fourth|fifth)\b[:,]?\s*/i, "")
+        .replace(/^(?:task|step)\s+\d+[:.)-]?\s*/i, "")
+        .trim())
+        .filter(Boolean);
+}
+function extractClickTargets(remainder) {
+    const cleanedRemainder = cleanDirectiveText(remainder.replace(/^(?:on|into|to)\s+/i, ""));
+    if (!cleanedRemainder) {
+        return [];
+    }
+    const pluralControlMatch = cleanedRemainder.match(/(.+?)\s+(?:tabs|buttons|links|options|cards|sections|pages|screens)\b/i);
+    const listSource = pluralControlMatch?.[1] ?? cleanedRemainder;
+    if (pluralControlMatch && /,|\band\b/i.test(listSource)) {
+        const splitTargets = listSource
+            .split(/\s*,\s*|\s+\band\b\s+/i)
+            .map((part) => cleanDirectiveTarget(part))
+            .filter(Boolean);
+        if (splitTargets.length > 1) {
+            return splitTargets;
+        }
+    }
+    const singleTarget = cleanDirectiveTarget(cleanedRemainder);
+    return singleTarget ? [singleTarget] : [];
+}
+function isGenericVisibleFormInstruction(remainder) {
+    const normalized = cleanDirectiveText(remainder);
+    if (!normalized) {
+        return true;
+    }
+    return (/^(?:it|them|the form)(?:\s+out)?$/i.test(normalized) ||
+        /(?:all|every)\s+(?:the\s+)?(?:visible\s+|required\s+)?(?:details?|fields?|inputs?|boxes?|blanks?|information|info|questions?|form(?:\s+fields?)?)/i.test(normalized) ||
+        /visible\s+(?:details?|fields?|inputs?|information|form)/i.test(normalized));
+}
+function isCompleteVisibleFormInstruction(segment) {
+    const normalized = cleanDirectiveText(segment);
+    if (!/^complete\b/i.test(normalized)) {
+        return false;
+    }
+    const remainder = normalized.replace(/^complete\b\s*/i, "");
+    return (isGenericVisibleFormInstruction(remainder) ||
+        /^(?:the\s+)?(?:(?:sign\s*up|signup|registration|account(?:\s+creation)?)\s+)?form(?:\s+out)?$/i.test(remainder));
+}
+function extractCompactExchangeAmountDirective(raw) {
+    const match = raw.match(/^(buy|sell)(?:\s+me)?(?:\s+(?:crypto|cypto|coin|token))?(?:\s+worth)?\s+([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z₦]+)?$/i);
+    if (!match?.[1] || !match[2]) {
+        return null;
+    }
+    const action = match[1].toLowerCase();
+    const unit = (match[3] ?? "").toLowerCase();
+    const target = action === "buy" || /\b(?:ngn|naira|₦)\b/i.test(unit) ? "Naira amount" : "crypto amount";
+    return {
+        action: "type_field",
+        raw,
+        target,
+        value: match[2]
+    };
+}
+function extractExplicitFieldValueDirective(raw) {
+    const intoMatch = raw.match(/^(?:fill(?:\s+(?:out|up|in))?|enter|type|input|provide)\s+["'“]?(.+?)["'”]?\s+(?:into|in)\s+(?:the\s+|your\s+)?(.+?)(?:\s+(?:field|box|input|textbox|text box|value|details?))?$/i);
+    if (intoMatch?.[1] && intoMatch[2]) {
+        const value = cleanDirectiveText(intoMatch[1]);
+        const target = cleanDirectiveTarget(intoMatch[2]);
+        if (value && target && !isGenericVisibleFormInstruction(target)) {
+            return {
+                action: "type_field",
+                raw,
+                target,
+                value
+            };
+        }
+    }
+    const match = raw.match(/^(?:fill(?:\s+(?:out|up|in))?|enter|type|input|provide)\s+(?:the\s+|your\s+)?(.+?)\s+(?:with|as|to)\s+["'“]?(.+?)["'”]?$/i);
+    if (!match?.[1] || !match[2]) {
+        return null;
+    }
+    const target = cleanDirectiveTarget(match[1]);
+    const value = cleanDirectiveText(match[2]);
+    if (isGenericVisibleFormInstruction(`${target} ${value}`) || isGenericVisibleFormInstruction(target)) {
+        return null;
+    }
+    if (!target || !value) {
+        return null;
+    }
+    return {
+        action: "type_field",
+        raw,
+        target,
+        value
+    };
+}
+function extractBareNumericEntryDirective(raw) {
+    const match = raw.match(/^(?:enter|type|input|provide|fill(?:\s+(?:out|up|in))?)\s+([0-9]+(?:\.[0-9]+)?)\s*([A-Za-z₦]+)?$/i);
+    if (!match?.[1]) {
+        return null;
+    }
+    const unit = (match[2] ?? "").toLowerCase();
+    return {
+        action: "type_field",
+        raw,
+        target: /\b(?:crypto|usdt|btc|eth|usdc)\b/i.test(unit) ? "crypto amount" : "amount",
+        value: match[1]
+    };
+}
+export function parseTaskDirectives(taskText) {
+    const directives = [];
+    for (const segment of splitDirectiveSegments(taskText)) {
+        const raw = cleanDirectiveText(segment);
+        if (!raw) {
+            continue;
+        }
+        if (isCompleteVisibleFormInstruction(raw)) {
+            directives.push({
+                action: "fill_visible_form",
+                raw,
+                target: ""
+            });
+            continue;
+        }
+        const compactExchangeAmountDirective = extractCompactExchangeAmountDirective(raw);
+        if (compactExchangeAmountDirective) {
+            directives.push(compactExchangeAmountDirective);
+            continue;
+        }
+        const explicitFieldValueDirective = extractExplicitFieldValueDirective(raw);
+        if (explicitFieldValueDirective) {
+            directives.push(explicitFieldValueDirective);
+            continue;
+        }
+        const bareNumericEntryDirective = extractBareNumericEntryDirective(raw);
+        if (bareNumericEntryDirective) {
+            directives.push(bareNumericEntryDirective);
+            continue;
+        }
+        const match = segment.match(/^(click|tap|press|open|select|choose|copy|fill(?:\s+(?:out|up|in))?|enter|type|input|provide|submit|create|register|sign\s*up|signup|join|scroll|swipe|wait|pause|hold|go back|back|stop|halt)\b\s*(.*)$/i);
+        if (!match) {
+            directives.push({
+                action: "unstructured",
+                raw,
+                target: raw
+            });
+            continue;
+        }
+        const verb = (match[1] ?? "").toLowerCase();
+        const remainder = match[2] ?? "";
+        if (!verb) {
+            continue;
+        }
+        if (verb === "copy") {
+            directives.push({
+                action: "click",
+                raw,
+                target: "Copy"
+            });
+            continue;
+        }
+        if (["click", "tap", "press", "open", "select", "choose"].includes(verb)) {
+            for (const target of extractClickTargets(remainder)) {
+                directives.push({
+                    action: "click",
+                    raw,
+                    target
+                });
+            }
+            continue;
+        }
+        if (["fill", "fill out", "fill up", "fill in", "enter", "type", "input", "provide"].includes(verb)) {
+            if (isGenericVisibleFormInstruction(remainder)) {
+                directives.push({
+                    action: "fill_visible_form",
+                    raw,
+                    target: ""
+                });
+                continue;
+            }
+            const target = cleanDirectiveTarget(remainder.replace(/\s+(?:field|box|input|value|details?)\b.*$/i, ""));
+            if (target) {
+                directives.push({
+                    action: "type_field",
+                    raw,
+                    target
+                });
+            }
+            continue;
+        }
+        if (verb === "submit" ||
+            ((verb === "create" || verb === "register" || verb === "sign up" || verb === "signup" || verb === "join") &&
+                /\b(?:account|profile|registration|sign[- ]?up|signup|membership)\b/i.test(remainder || raw))) {
+            directives.push({
+                action: "submit",
+                raw,
+                target: ""
+            });
+            continue;
+        }
+        if (verb === "scroll" || verb === "swipe") {
+            directives.push({
+                action: "scroll",
+                raw,
+                target: ""
+            });
+            continue;
+        }
+        if (["wait", "pause", "hold"].includes(verb)) {
+            directives.push({
+                action: "wait",
+                raw,
+                target: ""
+            });
+            continue;
+        }
+        if (verb === "go back" || verb === "back") {
+            directives.push({
+                action: "back",
+                raw,
+                target: ""
+            });
+            continue;
+        }
+        if (verb === "stop" || verb === "halt") {
+            directives.push({
+                action: "stop",
+                raw,
+                target: ""
+            });
+        }
+    }
+    return directives;
+}
+export function describeTaskDirective(directive) {
+    switch (directive.action) {
+        case "click":
+            return `Click the visible control labeled '${directive.target}' before any later step.`;
+        case "type_field":
+            return `Fill the visible field matching '${directive.target}'.`;
+        case "fill_visible_form":
+            return "Fill the visible form fields in on-page order until no safe pending visible fields remain.";
+        case "submit":
+            return "Submit the form only after the earlier form-filling steps are complete.";
+        case "scroll":
+            return "Scroll once, then reassess the next visible step.";
+        case "wait":
+            return "Wait briefly before taking any later action.";
+        case "back":
+            return "Go back once before taking any later action.";
+        case "stop":
+            return "Stop execution immediately and perform no further actions.";
+        case "unstructured":
+            return `Follow the user's instruction: '${directive.target}'.`;
+        default:
+            return "";
+    }
+}
+export function buildTaskDirectiveSummary(taskText) {
+    return parseTaskDirectives(taskText).map((directive, index) => `${index + 1}. ${describeTaskDirective(directive)}`);
+}

package/dist/core/taskHeuristics.js

@@ -0,0 +1,263 @@
+const TASK_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "at",
+    "be",
+    "by",
+    "check",
+    "click",
+    "do",
+    "does",
+    "every",
+    "for",
+    "from",
+    "go",
+    "how",
+    "i",
+    "if",
+    "in",
+    "interact",
+    "into",
+    "is",
+    "it",
+    "me",
+    "of",
+    "on",
+    "or",
+    "please",
+    "read",
+    "report",
+    "step",
+    "stepwise",
+    "steps",
+    "supplied",
+    "that",
+    "the",
+    "them",
+    "through",
+    "to",
+    "was",
+    "were",
+    "what",
+    "when",
+    "whether",
+    "with",
+    "you",
+    "your"
+]);
+const INSTRUCTION_PATTERNS = [/\bhow to play\b/i, /\binstructions?\b/i, /\brules?\b/i, /\btutorial\b/i, /\bhow it works\b/i];
+const BUTTON_COVERAGE_PATTERNS = [/\bevery button\b/i, /\ball buttons?\b/i, /\beach button\b/i, /\binteract with .*buttons?\b/i];
+const ENGAGEMENT_PATTERNS = [/\bengage\b/i, /\binteract\b/i, /\binteraction\b/i, /\btry it\b/i, /\buse it\b/i];
+const PLAY_ACTION_PATTERNS = [
+    /\bplay\b/i,
+    /\bplace bet\b/i,
+    /\bbet\b/i,
+    /\bstart\b/i,
+    /\bspin\b/i,
+    /\bdeal\b/i,
+    /\blaunch\b/i,
+    /\bcash ?out\b/i,
+    /\bretry\b/i,
+    /\brestart\b/i,
+    /\bplay again\b/i,
+    /\bnew game\b/i,
+    /\bgo\b/i
+];
+const GAMEPLAY_PATTERNS = [
+    /\bgame\b/i,
+    /\bplay\b/i,
+    /\bbet\b/i,
+    /\bround\b/i,
+    /\bscore\b/i,
+    /\bwin\b/i,
+    /\bwins\b/i,
+    /\bloss\b/i,
+    /\blost\b/i,
+    /\blose\b/i,
+    /\bdraw\b/i,
+    /\bcrash\b/i,
+    /\bmultiplier\b/i
+];
+const OUTCOME_PATTERNS = [
+    /\byou win\b/i,
+    /\bvictory\b/i,
+    /\bwon\b/i,
+    /\bwinner\b/i,
+    /\blevel complete\b/i,
+    /\byou lose\b/i,
+    /\blost\b/i,
+    /\bdefeat\b/i,
+    /\bgame over\b/i,
+    /\bbetter luck next time\b/i,
+    /\bdraw\b/i,
+    /\btie\b/i,
+    /\bstalemate\b/i
+];
+const BROAD_NAVIGATION_PATTERNS = [/\bgo through\b/i, /\bexplore\b/i, /\bbrowse\b/i, /\breview\b/i, /\bvisit\b/i, /\bwalk through\b/i];
+function hasPattern(patterns, value) {
+    return patterns.some((pattern) => pattern.test(value));
+}
+export function normalizeTaskText(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+export function extractTaskKeywords(value) {
+    return [...new Set(normalizeTaskText(value)
+            .toLowerCase()
+            .split(/[^a-z0-9$%.+-]+/)
+            .map((part) => part.trim())
+            .filter((part) => part.length >= 3 && !TASK_STOP_WORDS.has(part)))];
+}
+function parseRequestedRounds(taskText) {
+    const explicitRoundCount = taskText.match(/\b(\d+)\s+(?:rounds?|games?|times?)\b/i);
+    if (explicitRoundCount) {
+        const rounds = Number(explicitRoundCount[1]);
+        return Number.isFinite(rounds) && rounds > 0 ? rounds : undefined;
+    }
+    if (/\bhow many times\b/i.test(taskText) || /\bwins?\b.*\bloss(?:es)?\b/i.test(taskText)) {
+        return 3;
+    }
+    if (hasPattern(GAMEPLAY_PATTERNS, taskText)) {
+        return 1;
+    }
+    return undefined;
+}
+export function classifyTaskText(taskText) {
+    const normalized = normalizeTaskText(taskText);
+    const instructionFocus = hasPattern(INSTRUCTION_PATTERNS, normalized);
+    const buttonCoverage = hasPattern(BUTTON_COVERAGE_PATTERNS, normalized);
+    const gameplay = hasPattern(GAMEPLAY_PATTERNS, normalized);
+    const engagement = gameplay || buttonCoverage || hasPattern(ENGAGEMENT_PATTERNS, normalized);
+    const outcomeReporting = /\bhow many times\b/i.test(normalized) || /\bwins?\b.*\bloss(?:es)?\b/i.test(normalized);
+    const requestedRounds = gameplay ? parseRequestedRounds(normalized) : undefined;
+    return {
+        broadNavigation: hasPattern(BROAD_NAVIGATION_PATTERNS, normalized),
+        buttonCoverage,
+        engagement,
+        gameplay,
+        instructionFocus,
+        outcomeReporting,
+        ...(requestedRounds ? { requestedRounds } : {}),
+        requireHowToPlay: instructionFocus
+    };
+}
+export function inferGameplayConfigFromTask(taskText) {
+    const profile = classifyTaskText(taskText);
+    if (!profile.gameplay) {
+        return undefined;
+    }
+    const gameplay = {
+        ...(profile.requestedRounds ? { rounds: profile.requestedRounds } : {}),
+        ...(profile.requireHowToPlay ? { requireHowToPlay: true } : {})
+    };
+    return Object.keys(gameplay).length > 0 ? gameplay : {};
+}
+export function textHasInstructionCue(value) {
+    return hasPattern(INSTRUCTION_PATTERNS, value);
+}
+export function textHasOutcomeCue(value) {
+    return hasPattern(OUTCOME_PATTERNS, value);
+}
+export function textHasPlayActionCue(value) {
+    return hasPattern(PLAY_ACTION_PATTERNS, value);
+}
+export function hasTaskKeywordEvidence(taskText, values) {
+    const keywords = extractTaskKeywords(taskText);
+    if (keywords.length === 0) {
+        return false;
+    }
+    const blob = normalizeTaskText(values.join(" ")).toLowerCase();
+    return keywords.some((keyword) => blob.includes(keyword));
+}
+function countKeywordMatches(label, taskText) {
+    const keywords = extractTaskKeywords(taskText);
+    if (keywords.length === 0) {
+        return 0;
+    }
+    const normalizedLabel = normalizeTaskText(label).toLowerCase();
+    return keywords.filter((keyword) => normalizedLabel.includes(keyword)).length;
+}
+function labelMatchesPatterns(label, patterns) {
+    return hasPattern(patterns, label);
+}
+function isGenericUtilityLabel(label) {
+    return /^(?:home|about|contact|privacy|terms|menu|close|cancel)$/i.test(label);
+}
+export function isRegressiveTaskControlLabel(label) {
+    return /^(?:update|edit|change|reset|clear)\s+(?:profile|details?|settings?)$/i.test(label) ||
+        /^(?:log ?out|sign ?out|back|previous)$/i.test(label);
+}
+export function scoreInteractiveForTask(args) {
+    const taskProfile = classifyTaskText(args.task.goal);
+    const label = normalizeTaskText(args.item.text || "");
+    if (!label || args.item.disabled) {
+        return Number.NEGATIVE_INFINITY;
+    }
+    const attemptedTargetIds = new Set(args.history
+        .map((entry) => normalizeTaskText(entry.decision.target_id || ""))
+        .filter(Boolean));
+    if (attemptedTargetIds.has(args.item.agentId)) {
+        return -1000;
+    }
+    const attemptedTargets = new Set(args.history
+        .map((entry) => normalizeTaskText(entry.decision.target).toLowerCase())
+        .filter(Boolean));
+    if (attemptedTargets.has(label.toLowerCase())) {
+        return -1000;
+    }
+    let score = 0;
+    const role = args.item.role.toLowerCase();
+    const tag = args.item.tag.toLowerCase();
+    if (role === "button" || tag === "button") {
+        score += 18;
+    }
+    else if (role === "tab" || role === "menuitem") {
+        score += 14;
+    }
+    else if (role === "link" || tag === "a") {
+        score += 10;
+    }
+    else {
+        score += 4;
+    }
+    if (taskProfile.buttonCoverage && (role === "button" || tag === "button")) {
+        score += 40;
+    }
+    if (taskProfile.engagement && (role === "button" || tag === "button")) {
+        score += 22;
+    }
+    if (taskProfile.instructionFocus && labelMatchesPatterns(label, INSTRUCTION_PATTERNS)) {
+        score += 120;
+    }
+    const isInstructionLabel = labelMatchesPatterns(label, INSTRUCTION_PATTERNS);
+    if ((taskProfile.gameplay || taskProfile.engagement) && labelMatchesPatterns(label, PLAY_ACTION_PATTERNS)) {
+        score += taskProfile.gameplay
+            ? isInstructionLabel ? (taskProfile.instructionFocus ? 36 : 6) : 110
+            : 90;
+    }
+    if (taskProfile.gameplay && !taskProfile.instructionFocus && isInstructionLabel) {
+        score += 10;
+    }
+    if (taskProfile.gameplay && /\$\d+|^\d+(?:\.\d+)?x$/i.test(label)) {
+        score += 24;
+    }
+    if (taskProfile.outcomeReporting && /(?:history|results?|stats?|dashboard|recent)/i.test(label)) {
+        score += 50;
+    }
+    const keywordMatches = countKeywordMatches(label, args.task.goal);
+    score += keywordMatches * 30;
+    if (taskProfile.engagement && isRegressiveTaskControlLabel(label)) {
+        score -= 140;
+    }
+    if (isGenericUtilityLabel(label) && keywordMatches === 0) {
+        score -= 18;
+    }
+    if (/^https?:\/\//i.test(label)) {
+        score -= 24;
+    }
+    if (label.length <= 2 && !/\$\d+|^\d+(?:\.\d+)?x$/i.test(label)) {
+        score -= 8;
+    }
+    return score;
+}