@nxisai/agent-harness 0.2.4 → 0.4.0

package/dist/harness/tools/action-tools.js

@@ -0,0 +1,724 @@
+/**
+ * Registers the site's Actions as tools the agent can see from any page.
+ *
+ * A site repeats the same form across many pages: the listings demo has one
+ * quote form per business, which are 38 actions with the same name and the
+ * same fields. Registered one by one they would be 38 indistinguishable tools,
+ * so actions that share a name and a field list become a single tool, and the
+ * field whose default value differs between them — the site's own name for the
+ * target, such as `business` — chooses which one runs.
+ *
+ * Each is named for the reach it adds: `quote_form_anywhere` beside the page's
+ * own `quote_form`. It is a courier rather than a second form — it captures an
+ * action's inputs wherever the agent happens to be, carries them to the page
+ * that can submit them, and calls the tool there, never filling a field
+ * itself. The distinct name also matters mechanically: a registry treats a
+ * repeated name as a duplicate, so the polyfill would replace the very tool
+ * this one delegates to, and a native registry would reject the registration.
+ *
+ * On the action's own page there is nothing to carry, and it calls the page's
+ * tool directly.
+ *
+ * @module
+ */
+import { samePage, sameActionPage } from './site-actions.js';
+import { savePendingAction } from './pending-action.js';
+import { journeySteps } from '../steps.js';
+/** Marks a tool this module registered. */
+export const SITE_ACTION_HINT = 'ai.nxis/siteAction';
+/** The `@id`s a site tool covers. */
+export const ACTION_IDS_HINT = 'ai.nxis/actionIds';
+/** The pages those actions live on. */
+export const PAGE_URLS_HINT = 'ai.nxis/pageUrls';
+/** What the page's own script names the same actions. */
+export const PAGE_TOOL_NAMES_HINT = 'ai.nxis/pageToolNames';
+/**
+ * Marks a response that started a page change instead of submitting.
+ *
+ * Carried in `structuredContent`, where a renderer can find it without
+ * parsing prose.
+ */
+export const HANDOFF_RESULT = 'ai.nxis/handoff';
+/** The field whose value says which of the covered actions a call means. */
+export const CHOOSER_HINT = 'ai.nxis/chooser';
+/** That field's values, one per covered action, in the same order. */
+export const CHOICES_HINT = 'ai.nxis/choices';
+/** The `@id` of the action a page tool came from, where the page records it. */
+export const ACTION_ID_HINT = 'ai.nxis/actionId';
+/** Appended to the action's own name, keeping it clear of the page's tool. */
+const NAME_SUFFIX = '_anywhere';
+/** WebMCP tool names are capped at this length. */
+const MAX_NAME = 64;
+// ── names ───────────────────────────────────────────────────────────────────
+/**
+ * An action name as a tool name.
+ *
+ * Mirrors the page script's own sanitiser, so the two agree on what a given
+ * action is called.
+ */
+export function sanitizeToolName(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[\s-]+/g, '_')
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '')
+        .slice(0, MAX_NAME) || 'unnamed_action');
+}
+/**
+ * The name a site-wide tool is registered under.
+ *
+ * The stem is the action's own name, so the model still reads what the form is
+ * called and matches it to what the visitor asked for; the suffix says this is
+ * the one that reaches the form from any page, and keeps it clear of the
+ * page's own tool of the same name.
+ *
+ * @param actionName - The action's name, as the record gives it.
+ * @returns The tool name, within the length a registry accepts.
+ */
+export function siteToolName(actionName) {
+    return sanitizeToolName(actionName).slice(0, MAX_NAME - NAME_SUFFIX.length) + NAME_SUFFIX;
+}
+/**
+ * A tool's name without the site-wide suffix, for showing to a person.
+ *
+ * `quote_form_anywhere` exists to be told apart from the page's `quote_form`
+ * in a registry; to the visitor both are the quote form.
+ */
+export function withoutSiteSuffix(toolName) {
+    return toolName.endsWith(NAME_SUFFIX) ? toolName.slice(0, -NAME_SUFFIX.length) : toolName;
+}
+/** A page URL's last path segment, as a label: `/listings/royal-oak.html` → `royal oak`. */
+function pageLabel(pageUrl) {
+    if (!pageUrl)
+        return 'this page';
+    let path;
+    try {
+        path = new URL(pageUrl).pathname;
+    }
+    catch {
+        path = pageUrl;
+    }
+    const slug = path.split('/').filter(Boolean).pop() ?? '';
+    return slug.replace(/\.\w+$/, '').replace(/[-_]+/g, ' ') || 'home';
+}
+// ── grouping ────────────────────────────────────────────────────────────────
+const fieldNames = (action) => (action.input ?? []).map((i) => i.valueName);
+/**
+ * Actions with the same name and the same fields are one tool.
+ *
+ * JSON rather than a joined string, so a separator character cannot appear in
+ * a field name and merge two groups that differ.
+ */
+const groupKey = (action) => JSON.stringify([sanitizeToolName(action.name), [...fieldNames(action)].sort()]);
+/**
+ * Which field distinguishes the members of a group.
+ *
+ * The crawler records what a form already says about itself: on a per-business
+ * quote form, the `business` field carries that business's name as its default.
+ * A field every member fills with a different value is therefore the site's own
+ * way of naming the target, and is used in preference to anything invented.
+ *
+ * @param actions - The group's actions, in order.
+ * @returns The field name and each action's value, or null when no field
+ * separates them.
+ */
+export function findDiscriminator(actions) {
+    if (actions.length < 2)
+        return null;
+    for (const field of fieldNames(actions[0])) {
+        const values = actions.map((a) => (a.input ?? []).find((i) => i.valueName === field)?.defaultValue?.trim() ?? '');
+        if (values.some((v) => !v))
+            continue;
+        if (new Set(values).size === actions.length)
+            return { field, values };
+    }
+    return null;
+}
+/** Labels for a group whose own fields do not tell its actions apart. */
+function pageLabels(actions) {
+    const labels = actions.map((a) => pageLabel(a.target['nxis:pageUrl']));
+    if (new Set(labels).size === labels.length)
+        return labels;
+    // Two pages with the same last segment: fall back to the whole path.
+    return actions.map((a) => a.target['nxis:pageUrl'] ?? pageLabel(a.target['nxis:pageUrl']));
+}
+// ── schema ──────────────────────────────────────────────────────────────────
+const JSON_TYPES = {
+    string: 'string',
+    number: 'number',
+    integer: 'integer',
+    boolean: 'boolean',
+    date: 'string',
+    file: 'string',
+};
+/** One field's schema, following the same rules as the page script. */
+function propertySchema(spec) {
+    const valueType = spec['nxis:valueType'] ?? 'string';
+    const prop = { type: JSON_TYPES[valueType] ?? 'string' };
+    if (valueType === 'date')
+        prop.format = 'date';
+    if (spec.description)
+        prop.description = spec.description;
+    if (spec.defaultValue !== undefined)
+        prop.default = coerce(spec.defaultValue, valueType);
+    if (spec.valueMinLength !== undefined)
+        prop.minLength = spec.valueMinLength;
+    if (spec.valueMaxLength !== undefined)
+        prop.maxLength = spec.valueMaxLength;
+    if (spec.valuePattern) {
+        const p = spec.valuePattern;
+        prop.pattern = p.startsWith('^') && p.endsWith('$') ? p : `^${p}$`;
+    }
+    if (spec.minValue !== undefined)
+        prop.minimum = spec.minValue;
+    if (spec.maxValue !== undefined)
+        prop.maximum = spec.maxValue;
+    if (spec.stepValue !== undefined)
+        prop.multipleOf = spec.stepValue;
+    if (spec.readonlyValue)
+        prop.readOnly = true;
+    const options = spec['nxis:valueOption'] ?? [];
+    if (options.length) {
+        prop.enum = options.map((o) => o.value);
+        const labelled = options.filter((o) => o.name && o.name !== o.value);
+        if (labelled.length) {
+            // What each value means, for the model to read in the serialised schema.
+            // Deliberately not folded into `description`: every surface renders that
+            // as the field's label, and a sentence there becomes a label wide enough
+            // to crush the value beside it.
+            prop['nxis:valueLabels'] = Object.fromEntries(labelled.map((o) => [o.value, o.name]));
+        }
+    }
+    if (spec.multipleValues) {
+        const items = { ...prop };
+        const array = { type: 'array', items };
+        if (spec.valueMinLength !== undefined) {
+            array.minItems = spec.valueMinLength;
+            delete items.minLength;
+        }
+        if (spec.valueMaxLength !== undefined) {
+            array.maxItems = spec.valueMaxLength;
+            delete items.maxLength;
+        }
+        if (items.description) {
+            array.description = items.description;
+            delete items.description;
+        }
+        return array;
+    }
+    return prop;
+}
+function coerce(value, valueType) {
+    if (valueType === 'number' || valueType === 'integer') {
+        const n = Number(value);
+        return Number.isNaN(n) ? value : n;
+    }
+    if (valueType === 'boolean')
+        return value === 'true' || value === '1';
+    return value;
+}
+/** Merge the group's field schemas, widening each enum to what any member accepts. */
+function mergedSchema(actions) {
+    const properties = {};
+    const required = new Set();
+    for (const action of actions) {
+        for (const spec of action.input ?? []) {
+            const prop = propertySchema(spec);
+            const existing = properties[spec.valueName];
+            if (!existing) {
+                properties[spec.valueName] = prop;
+            }
+            else if (Array.isArray(existing.enum) && Array.isArray(prop.enum)) {
+                // The same field offers different options per page: accept any of them,
+                // since the form on the page decides what is really valid.
+                existing.enum = [...new Set([...existing.enum, ...prop.enum])];
+            }
+            if (spec.valueRequired)
+                required.add(spec.valueName);
+        }
+    }
+    const schema = { type: 'object', properties };
+    if (required.size)
+        schema.required = [...required];
+    return schema;
+}
+/**
+ * Group the site's actions and build one tool definition for each group.
+ *
+ * Names are derived from the whole set rather than the order actions arrive
+ * in, so a tool is called the same thing on every page of the site.
+ *
+ * @param actions - The site's actions.
+ * @param mc - The registry the tools will run against, used to find the page's
+ * own tool when the agent is already on the right page.
+ * @param opts - The current page.
+ * @returns One entry per group, ordered by tool name.
+ */
+export function buildSiteActionTools(actions, mc, opts = {}) {
+    const groups = new Map();
+    for (const action of actions) {
+        const key = groupKey(action);
+        const group = groups.get(key);
+        if (group)
+            group.push(action);
+        else
+            groups.set(key, [action]);
+    }
+    const taken = new Set();
+    const tools = [];
+    // Sorted so that two groups whose names collide are numbered the same way on
+    // every page, whatever order the server returned them in.
+    for (const key of [...groups.keys()].sort()) {
+        const group = groups.get(key);
+        const tool = buildTool(group, mc, taken, opts);
+        built.set(tool.name, tool);
+        tools.push(tool);
+    }
+    return tools;
+}
+/**
+ * Every site-wide tool built in this page, by registered name.
+ *
+ * Annotations are the obvious place to record what a tool covers, and a tool
+ * read back from `getTools()` carries them only if the registry kept them: a
+ * native one keeps the hints it recognises and drops the rest, which leaves
+ * one of these indistinguishable from any other write. The builder and the
+ * harness run in the same page, so what was built is remembered here, and
+ * annotations are the fallback for anything registered elsewhere.
+ */
+const built = new Map();
+/**
+ * Whether a tool is a site-wide one, reaching a form from any page.
+ *
+ * Checked against what this page built, then the tool's annotations, so it
+ * holds even where a native registry has stripped them.
+ */
+export function isSiteTool(tool) {
+    return coverageOf(tool) !== null;
+}
+/** A tool's coverage, from what this page built or from what it carries. */
+function coverageOf(tool) {
+    const local = built.get(tool.name);
+    if (local) {
+        return {
+            ids: local.actions.map((a) => a['@id']),
+            pages: local.actions.map((a) => a.target['nxis:pageUrl'] ?? ''),
+            pageToolNames: [...new Set(local.actions.map((a) => sanitizeToolName(a.name)))],
+            chooser: local.discriminator ?? '',
+            choices: local.choices ?? [],
+        };
+    }
+    const notes = tool.annotations;
+    if (!notes?.[SITE_ACTION_HINT])
+        return null;
+    return {
+        ids: notes[ACTION_IDS_HINT] ?? [],
+        pages: notes[PAGE_URLS_HINT] ?? [],
+        pageToolNames: notes[PAGE_TOOL_NAMES_HINT] ?? [],
+        chooser: notes[CHOOSER_HINT] ?? '',
+        choices: notes[CHOICES_HINT] ?? [],
+    };
+}
+function buildTool(actions, mc, taken, opts) {
+    const first = actions[0];
+    const name = uniqueName(siteToolName(first.name), taken);
+    taken.add(name);
+    const schema = mergedSchema(actions);
+    const found = findDiscriminator(actions);
+    const discriminator = actions.length > 1 ? (found?.field ?? 'target') : undefined;
+    const choices = actions.length > 1 ? (found?.values ?? pageLabels(actions)) : undefined;
+    if (discriminator && choices) {
+        const here = actions.findIndex((a) => sameActionPage(a, opts.href));
+        schema.properties ?? (schema.properties = {});
+        const existing = { ...(schema.properties[discriminator] ?? { type: 'string' }) };
+        // The merged schema carries the first action's own default — the first
+        // business's name. Left there, a call that named no business would submit
+        // to that one, so the choice starts empty unless this page settles it.
+        delete existing.default;
+        // A label, not an instruction: what this field is for belongs in the
+        // tool's description, which the model reads and no surface renders as a
+        // field name. A real field keeps whatever the form called it, and an
+        // added one is named after what it selects.
+        const label = found ? existing.description : 'Page';
+        schema.properties[discriminator] = {
+            ...existing,
+            type: 'string',
+            ...(label ? { description: label } : {}),
+            enum: choices,
+            // On a page this tool covers, that page's action is the obvious one.
+            ...(here >= 0 ? { default: choices[here] } : {}),
+        };
+        schema.required = [...new Set([...(schema.required ?? []), discriminator])];
+    }
+    const definition = {
+        name,
+        description: describe(actions, discriminator, choices),
+        inputSchema: schema,
+        annotations: {
+            // Actions submit a form. Never run one without a human pressing Submit.
+            readOnlyHint: false,
+            [SITE_ACTION_HINT]: true,
+            [ACTION_IDS_HINT]: actions.map((a) => a['@id']),
+            [PAGE_URLS_HINT]: actions.map((a) => a.target['nxis:pageUrl'] ?? ''),
+            [PAGE_TOOL_NAMES_HINT]: [...new Set(actions.map((a) => sanitizeToolName(a.name)))],
+            // Enough for a caller that holds only the registered tool — the harness,
+            // drawing a confirmation — to work out where a call is bound for.
+            [CHOOSER_HINT]: discriminator ?? '',
+            [CHOICES_HINT]: choices ?? [],
+        },
+        execute: (input) => runSiteAction({ actions, discriminator, choices }, mc, input, opts),
+    };
+    return { name, actions, discriminator, choices, definition };
+}
+function uniqueName(base, taken) {
+    if (!taken.has(base))
+        return base;
+    for (let i = 2;; i++) {
+        const suffix = `_${i}`;
+        const candidate = base.slice(0, MAX_NAME - suffix.length) + suffix;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+function describe(actions, discriminator, choices) {
+    const base = actions[0].description ?? `Submit the "${actions[0].name}" form.`;
+    if (!discriminator || !choices)
+        return base;
+    const shown = choices.slice(0, 8).join(', ');
+    const rest = choices.length > 8 ? `, and ${choices.length - 8} more` : '';
+    return `${base} Set ${discriminator} to choose which: ${shown}${rest}.`;
+}
+// ── running ─────────────────────────────────────────────────────────────────
+const text = (body, isError = false) => ({
+    content: [{ type: 'text', text: body }],
+    isError,
+});
+/** The action a call refers to, by the value of the deciding field. */
+function pickAction(tool, input) {
+    if (tool.actions.length === 1)
+        return tool.actions[0];
+    if (!tool.discriminator || !tool.choices)
+        return null;
+    const wanted = String(input[tool.discriminator] ?? '').trim();
+    if (!wanted)
+        return null;
+    const exact = tool.choices.indexOf(wanted);
+    if (exact >= 0)
+        return tool.actions[exact];
+    const loose = tool.choices.findIndex((c) => c.toLowerCase() === wanted.toLowerCase());
+    return loose >= 0 ? tool.actions[loose] : null;
+}
+/** The reference for an action. */
+export const pageToolRef = (action) => ({
+    id: action['@id'],
+    name: sanitizeToolName(action.name),
+});
+/** The page's own tool for an action: by recorded `@id`, else by name. */
+export async function findPageTool(mc, ref) {
+    let tools;
+    try {
+        tools = await mc.getTools();
+    }
+    catch {
+        return null;
+    }
+    const byId = tools.find((t) => t.annotations?.[ACTION_ID_HINT] === ref.id);
+    if (byId)
+        return byId;
+    // Only on the action's own page: elsewhere a tool of the same name belongs
+    // to a different form.
+    return tools.find((t) => t.name === ref.name && !t.annotations?.[SITE_ACTION_HINT]) ?? null;
+}
+/**
+ * Wait for the page's own tool to register.
+ *
+ * After a page change the agent is running before the page's script has read
+ * its JSON-LD, so the tool a resumed call needs does not exist yet.
+ *
+ * @param mc - The page's registry.
+ * @param ref - The tool to wait for.
+ * @param timeoutMs - How long to wait before giving up.
+ * @returns The tool, or null if it never appears.
+ */
+export async function awaitPageTool(mc, ref, timeoutMs = 8000) {
+    const found = await findPageTool(mc, ref);
+    if (found)
+        return found;
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (tool) => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(poll);
+            clearTimeout(timer);
+            mc.removeEventListener('toolchange', onChange);
+            resolve(tool);
+        };
+        const check = async () => {
+            const tool = await findPageTool(mc, ref);
+            if (tool)
+                finish(tool);
+        };
+        const onChange = () => void check();
+        mc.addEventListener('toolchange', onChange);
+        // Polled as well as event-driven: a native registry need not announce a
+        // registration that happened before this listener was attached.
+        const poll = setInterval(() => void check(), 300);
+        const timer = setTimeout(() => finish(null), timeoutMs);
+    });
+}
+/**
+ * Where a call to a site tool will have to go, if not here.
+ *
+ * Needs nothing but the tool, so a caller holding only what the registry
+ * reported — the harness, labelling a confirmation — can tell that pressing
+ * submit also means a page change.
+ *
+ * @param tool - The tool about to be called.
+ * @param values - The arguments resolved so far.
+ * @param href - The current page. Defaults to the browser's.
+ * @returns The destination, or null when the call runs here, when the tool is
+ * not one of these, or when the values do not yet say which action is meant.
+ */
+export function handoffFor(tool, values, href) {
+    const cover = coverageOf(tool);
+    if (!cover)
+        return null;
+    let index = 0;
+    if (cover.ids.length > 1) {
+        if (!cover.chooser)
+            return null;
+        const wanted = String(values?.[cover.chooser] ?? '').trim();
+        if (!wanted)
+            return null;
+        index = cover.choices.indexOf(wanted);
+        if (index < 0) {
+            index = cover.choices.findIndex((c) => c.toLowerCase() === wanted.toLowerCase());
+        }
+        if (index < 0)
+            return null;
+    }
+    const pageUrl = cover.pages[index];
+    if (!pageUrl || samePage(pageUrl, href ?? (typeof location === 'undefined' ? '' : location.href))) {
+        return null;
+    }
+    return {
+        actionId: cover.ids[index],
+        pageUrl,
+        label: cover.choices[index] || pageLabel(pageUrl),
+        // One name covers the group: these actions share the name they came from.
+        pageToolName: cover.pageToolNames[0] ?? '',
+    };
+}
+async function runSiteAction(tool, mc, input, opts) {
+    const action = pickAction(tool, input ?? {});
+    if (!action) {
+        const choices = (tool.choices ?? []).join(', ');
+        return text(`Say which one this is for. Choices: ${choices}.`, true);
+    }
+    const pageUrl = action.target['nxis:pageUrl'] ?? '';
+    if (!sameActionPage(action, opts.href)) {
+        // Filling the form means being on its page, so the confirmed call travels:
+        // held in this tab, submitted once the browser arrives.
+        const index = tool.actions.indexOf(action);
+        const label = tool.choices?.[index] || pageLabel(pageUrl);
+        const here = opts.href ?? (typeof location === 'undefined' ? '' : location.href);
+        if (!sameOrigin(pageUrl, here)) {
+            return text(`"${action.name}" belongs to another site, so I did not open it.`, true);
+        }
+        const held = savePendingAction({
+            actionId: action['@id'],
+            pageToolName: sanitizeToolName(action.name),
+            toolName: siteToolName(action.name),
+            values: withoutChooser(tool, input ?? {}),
+            pageUrl,
+            conversationId: opts.conversationId,
+            // The steps that led here happened on a page that is about to stop
+            // existing. Carried, so the surface on the other side can show why
+            // it is there rather than starting mid-journey.
+            steps: journeySteps(),
+        }, { storage: opts.storage });
+        if (!held) {
+            return text(`This form is on ${pageUrl}. I could not carry the details there, ` +
+                'so open that page and I will fill it in.', true);
+        }
+        (opts.navigate ?? ((url) => location.assign(url)))(pageUrl);
+        // Not a submission: the form has not been filled, and the page is about to
+        // change under us. Marked so a renderer reports a journey rather than
+        // drawing the "submitted" card that every other write earns.
+        return {
+            content: [{ type: 'text', text: `Opening ${label} to submit this…` }],
+            structuredContent: { [HANDOFF_RESULT]: { pageUrl, label } },
+        };
+    }
+    const pageTool = await findPageTool(mc, pageToolRef(action));
+    if (!pageTool) {
+        return text(`The form for "${action.name}" is not registered on this page yet. Reload and try again.`, true);
+    }
+    const args = withoutChooser(tool, input ?? {});
+    return mc.executeTool(pageTool, JSON.stringify(args)).catch(() => mc.executeTool(pageTool.name, args));
+}
+/**
+ * The arguments the form itself takes.
+ *
+ * A `target` field is the group's own invention, for choosing between pages;
+ * a real field such as `business` belongs to the form and stays.
+ */
+function withoutChooser(tool, input) {
+    const args = { ...input };
+    if (tool.discriminator === 'target')
+        delete args.target;
+    return args;
+}
+/** Same origin, so a stale or tampered record cannot send a visitor away. */
+function sameOrigin(url, here) {
+    try {
+        return new URL(url, here).origin === new URL(here).origin;
+    }
+    catch {
+        return false;
+    }
+}
+// ── registering ─────────────────────────────────────────────────────────────
+/**
+ * Register a tool for each of the site's actions.
+ *
+ * @param mc - The registry to register into.
+ * @param actions - The site's actions.
+ * @param opts - The current page.
+ * @returns The names registered. A name the registry already holds is left
+ * alone, and a registration it refuses is warned about rather than thrown.
+ */
+export async function registerSiteActionTools(mc, actions, opts = {}) {
+    if (!actions.length)
+        return [];
+    const tools = buildSiteActionTools(actions, mc, opts);
+    let present;
+    try {
+        present = new Set((await mc.getTools()).map((t) => t.name));
+    }
+    catch {
+        present = new Set();
+    }
+    const registered = [];
+    for (const tool of tools) {
+        if (present.has(tool.name))
+            continue;
+        try {
+            await mc.registerTool(tool.definition);
+        }
+        catch (err) {
+            console.warn(`[nxis-mcp] could not register ${tool.name}:`, err);
+            continue;
+        }
+        registered.push(tool.name);
+    }
+    return registered;
+}
+// ── what reaches the prompt ─────────────────────────────────────────────────
+/** How many site-wide tools a turn may carry, before relevance decides. */
+export const DEFAULT_SITE_TOOL_LIMIT = 8;
+/** Words too common to say anything about which form is meant. */
+const STOP = new Set([
+    'the', 'and', 'for', 'from', 'with', 'this', 'that', 'need', 'want', 'would',
+    'like', 'please', 'can', 'you', 'get', 'got', 'have', 'has', 'about', 'out',
+    'she', 'her', 'his', 'him', 'they', 'them', 'their', 'some', 'any', 'here',
+]);
+const words = (text) => new Set((text.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((w) => w.length > 2 && !STOP.has(w)));
+/** How well a tool answers what was asked. */
+function relevance(tool, cover, goal, asked) {
+    let score = 0;
+    for (const word of words(`${tool.name} ${tool.description ?? ''}`)) {
+        if (asked.has(word))
+            score += 1;
+    }
+    // A choice named in the request is the strongest signal there is: these are
+    // the site's own names for what each action acts on.
+    const lower = goal.toLowerCase();
+    if (cover.choices.some((c) => c && lower.includes(c.toLowerCase())))
+        score += 3;
+    return score;
+}
+/**
+ * Narrow the site-wide tools to those this turn could plausibly need.
+ *
+ * Every registered tool's schema is written into every prompt, and a site
+ * with many distinct forms would fill the context with forms nobody asked
+ * about. Tools belonging to the page the agent is on are always kept — they
+ * are what "this form" means — and the rest compete on how well they answer
+ * what was asked.
+ *
+ * Only site-wide tools are ever dropped. The page's own tools and the
+ * retrieval tools are few, and losing one of those loses a capability rather
+ * than trimming a list.
+ *
+ * @param tools - The tools on offer this turn.
+ * @param goal - What the user asked for.
+ * @param opts - The budget and the current page.
+ * @returns The tools to show, in the order they arrived.
+ */
+export function selectSiteTools(tools, goal, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_SITE_TOOL_LIMIT;
+    const here = opts.href ?? (typeof location === 'undefined' ? '' : location.href);
+    const asked = words(goal ?? '');
+    const ranked = [];
+    for (const tool of tools) {
+        const cover = coverageOf(tool);
+        if (!cover)
+            continue;
+        ranked.push({
+            name: tool.name,
+            onPage: cover.pages.some((p) => samePage(p, here)),
+            score: relevance(tool, cover, goal ?? '', asked),
+        });
+    }
+    if (ranked.length <= limit)
+        return tools;
+    ranked.sort((a, b) => Number(b.onPage) - Number(a.onPage) || b.score - a.score);
+    const keep = new Set(ranked.slice(0, limit).map((r) => r.name));
+    return tools.filter((tool) => !coverageOf(tool) || keep.has(tool.name));
+}
+// ── one route per action ────────────────────────────────────────────────────
+/**
+ * Drop page tools that a site tool already covers.
+ *
+ * On the page an action belongs to, the page's script registers its own tool
+ * and the site tool delegates to it. Both in the prompt would offer the model
+ * two ways to do one thing, and the second is chosen half the time.
+ *
+ * @param tools - Every tool the registry reported.
+ * @param href - The current page. Defaults to the browser's.
+ * @returns The tools to show the model.
+ */
+export function withoutShadowedTools(tools, href) {
+    const coveredIds = new Set();
+    const coveredNames = new Set();
+    const here = href ?? (typeof location === 'undefined' ? '' : location.href);
+    for (const tool of tools) {
+        const cover = coverageOf(tool);
+        if (!cover)
+            continue;
+        for (const id of cover.ids)
+            coveredIds.add(id);
+        // Names are only ambiguous evidence, so they count only where this tool
+        // actually covers the page the agent is on.
+        if (cover.pages.some((p) => samePage(p, here))) {
+            for (const name of cover.pageToolNames)
+                coveredNames.add(name);
+        }
+    }
+    if (!coveredIds.size && !coveredNames.size)
+        return tools;
+    return tools.filter((tool) => {
+        // The site-wide tool is never hidden: it is the route, not the duplicate.
+        if (coverageOf(tool))
+            return true;
+        const id = tool.annotations?.[ACTION_ID_HINT];
+        if (typeof id === 'string' && coveredIds.has(id))
+            return false;
+        return !coveredNames.has(tool.name);
+    });
+}
+//# sourceMappingURL=action-tools.js.map