@nexface/tools 0.1.13 → 0.1.14

package/dist/runtime.js

@@ -1,13 +1,14 @@
+import { searchNavigationTools, searchToolDefinition } from "./tool-search.js";
 import { pageDecisionSymbol } from "./shared/runtime-execution.js";
 import { PageCommandError } from "./browser/locator.js";
 import { measurePagePhase } from "./browser/diagnostics.js";
-import { runtimeControllerSymbol } from "./shared/runtime-controller.js";
+import { runtimeControllerSymbol, } from "./shared/runtime-controller.js";
 import { AgentToolError, TOOL_ERROR_CODES } from "./shared/errors.js";
 export { AgentToolError } from "./shared/errors.js";
 import { OperationTracker } from "./operation-runtime.js";
 import { isValidAgentContextName } from "./definition.js";
 import { assertAgentToolInputSchema, validateAgentToolInput } from "./shared/schema.js";
-import { createBrowserToolset, } from "./browser/toolset.js";
+import { createBrowserToolset } from "./browser/toolset.js";
 const CONTEXT_ERROR_CODES = [
     "CONTEXT_DISPOSED",
     "CONTEXT_NAME_MISMATCH",
@@ -20,9 +21,9 @@ export function isToolRuntimeError(error) {
     if (!error || typeof error !== "object")
         return false;
     const candidate = error;
-    if (candidate.type !== "tool_runtime_error"
-        || typeof candidate.message !== "string"
-        || typeof candidate.code !== "string") {
+    if (candidate.type !== "tool_runtime_error" ||
+        typeof candidate.message !== "string" ||
+        typeof candidate.code !== "string") {
         return false;
     }
     if (candidate.domain === "tool") {
@@ -43,9 +44,7 @@ function assertContextName(name) {
     }
 }
 function normalizeContextValue(value, path = "value", seen = new WeakSet()) {
-    if (value === null
-        || typeof value === "string"
-        || typeof value === "boolean") {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
         return value;
     }
     if (typeof value === "number") {
@@ -82,8 +81,8 @@ function normalizeContextValue(value, path = "value", seen = new WeakSet()) {
 }
 function normalizeContext(context) {
     assertContextName(context.name);
-    if (context.description !== undefined
-        && (typeof context.description !== "string" || !context.description.trim())) {
+    if (context.description !== undefined &&
+        (typeof context.description !== "string" || !context.description.trim())) {
         throw new AgentContextError("INVALID_CONTEXT", "Context description must be a non-empty string when provided.");
     }
     return {
@@ -123,6 +122,8 @@ export function getInternalToolRuntime(runtime) {
 export class ToolRuntimeImplementation extends EventTarget {
     [toolRuntimeBrand] = true;
     #bindings = new Map();
+    #routeSearch;
+    #visibleNavigation = new Set();
     #contexts = new Map();
     #contextRevision = 0;
     #browserToolset;
@@ -136,16 +137,22 @@ export class ToolRuntimeImplementation extends EventTarget {
     beginInternalOperation(options = {}) {
         return this.#operations.begin(options);
     }
-    endBridgeOperation(handle) { return this.#operations.disposeBridge(handle); }
+    endBridgeOperation(handle) {
+        return this.#operations.disposeBridge(handle);
+    }
     setTaskProgress = (handle, progress) => this.#operations.setTaskProgress(handle, progress);
     setOperationWaiting = (handle, waiting) => this.#operations.setWaitingForUser(handle, waiting);
     getActivitySnapshot = () => this.#operations.getSnapshot();
     subscribeActivity = (listener) => this.#operations.subscribe(listener);
-    requestOperationCancel(id) { this.#operations.requestCancel(id); }
+    requestOperationCancel(id) {
+        this.#operations.requestCancel(id);
+    }
     setPageActionFeedback(listener) {
         this.#pageActionFeedback = listener;
-        return () => { if (this.#pageActionFeedback === listener)
-            this.#pageActionFeedback = undefined; };
+        return () => {
+            if (this.#pageActionFeedback === listener)
+                this.#pageActionFeedback = undefined;
+        };
     }
     #emitExecution(event) {
         this.#operations.observe(event);
@@ -153,10 +160,40 @@ export class ToolRuntimeImplementation extends EventTarget {
     }
     constructor(options = {}) {
         super();
-        if (options.pageAutomation !== undefined &&
-            typeof options.pageAutomation !== "boolean") {
+        if (options.pageAutomation !== undefined && typeof options.pageAutomation !== "boolean") {
             throw new AgentToolError("INVALID_INPUT", "pageAutomation must be a boolean.");
         }
+        if (options.routeSearch !== undefined && typeof options.routeSearch !== "boolean") {
+            throw new AgentToolError("INVALID_INPUT", "routeSearch must be a boolean.");
+        }
+        this.#routeSearch = options.routeSearch ?? false;
+        if (this.#routeSearch)
+            this.register(searchToolDefinition, ({ query, queries }) => {
+                if (query !== undefined && queries !== undefined)
+                    throw new AgentToolError("INVALID_INPUT", "Use either query or queries, not both.");
+                const searchQueries = queries === undefined ? (query === undefined ? undefined : [query]) : [...queries];
+                if (searchQueries?.some((phrase) => typeof phrase !== "string" || !phrase.trim()))
+                    throw new AgentToolError("INVALID_INPUT", "Search queries must contain nonblank strings.");
+                const navigation = this.getRegisteredTools().filter(({ definition }) => definition.effect === "navigate");
+                const candidates = searchQueries === undefined
+                    ? navigation
+                    : searchNavigationTools(navigation, searchQueries.map((phrase) => phrase.trim()));
+                if (searchQueries !== undefined) {
+                    const previous = this.#visibleNavigation;
+                    this.#visibleNavigation = new Set(candidates);
+                    for (const tool of new Set([...previous, ...candidates])) {
+                        if (previous.has(tool) === this.#visibleNavigation.has(tool))
+                            continue;
+                        this.dispatchEvent(new DetailEvent("toolchange", Object.freeze({
+                            toolName: tool.definition.name,
+                            change: "visibility",
+                        })));
+                    }
+                }
+                return {
+                    tools: candidates.map(({ definition: { name, description } }) => ({ name, description })),
+                };
+            });
         this.#browserToolset = options.pageAutomation ? createBrowserToolset() : undefined;
         runtimeInternals.set(this, this);
         const controller = Object.freeze({
@@ -165,6 +202,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             setTaskProgress: this.setTaskProgress,
             getOperationSnapshot: () => this.getActivitySnapshot().operation,
             subscribeOperation: this.subscribeActivity,
+            getRegisteredTools: () => this.getRegisteredTools(),
         });
         Object.defineProperty(this, runtimeControllerSymbol, { value: controller });
     }
@@ -196,9 +234,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             definition,
             get confirmation() {
                 const confirmation = options.getConfirmation?.();
-                return confirmation === undefined
-                    ? undefined
-                    : Object.freeze({ ...confirmation });
+                return confirmation === undefined ? undefined : Object.freeze({ ...confirmation });
             },
             lifecycleSignal: lifecycleController.signal,
         });
@@ -207,9 +243,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             definition,
             runtimeTool,
             execute,
-            ...(options.getConfirmation
-                ? { getConfirmation: options.getConfirmation }
-                : {}),
+            ...(options.getConfirmation ? { getConfirmation: options.getConfirmation } : {}),
             lifecycleController,
         };
         this.#bindings.set(definition.name, binding);
@@ -224,6 +258,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             disposed = true;
             options.signal?.removeEventListener("abort", dispose);
             this.#bindings.delete(definition.name);
+            this.#visibleNavigation.delete(runtimeTool);
             lifecycleController.abort();
             this.dispatchEvent(new DetailEvent("toolchange", Object.freeze({
                 toolName: definition.name,
@@ -337,21 +372,27 @@ export class ToolRuntimeImplementation extends EventTarget {
             revision: this.#contextRevision,
         }));
     }
+    getRegisteredTools() {
+        return [...this.#bindings.values()]
+            .map(({ runtimeTool }) => runtimeTool)
+            .filter(({ definition }) => !this.#routeSearch || definition !== searchToolDefinition)
+            .sort((left, right) => compareStrings(left.definition.name, right.definition.name));
+    }
     getWebMcpTools() {
         return [...this.#bindings.values()]
             .map(({ runtimeTool }) => runtimeTool)
+            .filter((tool) => !this.#routeSearch ||
+            tool.definition.effect !== "navigate" ||
+            this.#visibleNavigation.has(tool))
             .sort((left, right) => compareStrings(left.definition.name, right.definition.name));
     }
     isRegistered(name) {
         return this.#bindings.has(name);
     }
     getTools() {
-        const applicationTools = [...this.#bindings.values()]
-            .map(({ runtimeTool }) => runtimeTool);
-        const browserTools = (this.#browserToolset?.definitions ?? [])
-            .map((definition) => this.#getBrowserRuntimeTool(definition));
-        return [...applicationTools, ...browserTools]
-            .sort((left, right) => compareStrings(left.definition.name, right.definition.name));
+        const applicationTools = this.getWebMcpTools();
+        const browserTools = (this.#browserToolset?.definitions ?? []).map((definition) => this.#getBrowserRuntimeTool(definition));
+        return [...applicationTools, ...browserTools].sort((left, right) => compareStrings(left.definition.name, right.definition.name));
     }
     waitForTool(definition, options = {}) {
         const isTargetRegistered = () => this.#bindings.has(definition.name);
@@ -374,8 +415,7 @@ export class ToolRuntimeImplementation extends EventTarget {
             };
             const onToolChange = (event) => {
                 const detail = event.detail;
-                if (detail?.toolName !== definition.name
-                    || detail.change !== "registered")
+                if (detail?.toolName !== definition.name || detail.change !== "registered")
                     return;
                 if (isTargetRegistered())
                     settle(resolve);
@@ -401,7 +441,11 @@ export class ToolRuntimeImplementation extends EventTarget {
     }
     execute(tool, input, options = {}) {
         const label = options.progressLabel?.trim().replace(/\s+/g, " ").slice(0, 48);
-        options = { ...(options.signal ? { signal: options.signal } : {}), ...(label ? { progressLabel: label } : {}), ...(options[pageDecisionSymbol] ? { [pageDecisionSymbol]: true } : {}) };
+        options = {
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(label ? { progressLabel: label } : {}),
+            ...(options[pageDecisionSymbol] ? { [pageDecisionSymbol]: true } : {}),
+        };
         const definition = tool.definition;
         const name = definition.name;
         const binding = this.#bindings.get(name);
@@ -417,8 +461,8 @@ export class ToolRuntimeImplementation extends EventTarget {
             if (!browserHandler) {
                 return Promise.reject(new AgentToolError("UNKNOWN_TOOL", `Unknown tool: ${name}.`));
             }
-            if (!browserToolset?.definitions.some((candidate) => candidate === definition)
-                || this.#getBrowserRuntimeTool(definition) !== tool) {
+            if (!browserToolset?.definitions.some((candidate) => candidate === definition) ||
+                this.#getBrowserRuntimeTool(definition) !== tool) {
                 return Promise.reject(new AgentToolError("CONTRACT_MISMATCH", `Tool "${name}" is registered with a different Definition.`));
             }
             return this.#enqueue((operationId) => this.#observeExecution(tool, input, options.signal, async (onFeedback, assertActive) => {
@@ -460,7 +504,9 @@ export class ToolRuntimeImplementation extends EventTarget {
         };
         // Reserve the tail before invoking executors or notifying synchronous listeners.
         let settleTail;
-        const tail = new Promise((resolve) => { settleTail = resolve; });
+        const tail = new Promise((resolve) => {
+            settleTail = resolve;
+        });
         this.#executionTail = tail;
         const queuedExecution = previous ? previous.then(start) : start();
         let execution = queuedExecution;
@@ -492,9 +538,13 @@ export class ToolRuntimeImplementation extends EventTarget {
             const target = binding.resolveTarget?.(input);
             return target?.isConnected ? target : undefined;
         }
-        if (this.#browserRuntimeTools.get(tool.definition) !== tool || !input || typeof input !== "object")
+        if (this.#browserRuntimeTools.get(tool.definition) !== tool ||
+            !input ||
+            typeof input !== "object")
             return undefined;
-        return this.#browserToolset?.handlers.get(tool.definition.name)?.resolveTarget?.(input);
+        return this.#browserToolset?.handlers
+            .get(tool.definition.name)
+            ?.resolveTarget?.(input);
     }
     async #observeExecution(tool, input, signal, execute, progressLabel, operationId) {
         const running = {
@@ -511,7 +561,10 @@ export class ToolRuntimeImplementation extends EventTarget {
         const assertActive = () => {
             signal?.throwIfAborted();
             if (presentation && this.#pageActionFeedback !== presentation) {
-                throw new PageCommandError({ code: "EXECUTION_CANCELLED", message: "Page action presentation was detached." });
+                throw new PageCommandError({
+                    code: "EXECUTION_CANCELLED",
+                    message: "Page action presentation was detached.",
+                });
             }
         };
         this.#emitExecution(running);
@@ -520,26 +573,33 @@ export class ToolRuntimeImplementation extends EventTarget {
             const result = await execute(async (feedback) => {
                 assertActive();
                 if (presentation)
-                    await measurePagePhase("presentation", async () => { await presentation(running, feedback, signal); });
+                    await measurePagePhase("presentation", async () => {
+                        await presentation(running, feedback, signal);
+                    });
                 assertActive();
             }, assertActive);
             signal?.throwIfAborted();
             this.#emitExecution({
-                ...running, status: "success", finishedAt: Date.now(), result,
+                ...running,
+                status: "success",
+                finishedAt: Date.now(),
+                result,
             });
             return result;
         }
         catch (error) {
             this.#emitExecution({
-                ...running, status: "error", cancelled: signal?.aborted === true,
-                finishedAt: Date.now(), error,
+                ...running,
+                status: "error",
+                cancelled: signal?.aborted === true,
+                finishedAt: Date.now(),
+                error,
             });
             throw error;
         }
     }
     async #executeApplication(name, input, options, binding, operationId) {
-        const id = globalThis.crypto?.randomUUID?.()
-            ?? `${Date.now()}-${Math.random()}`;
+        const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
         const startedAt = Date.now();
         const running = {
             ...(operationId ? { operationId } : {}),
@@ -599,4 +659,3 @@ export class ToolRuntimeImplementation extends EventTarget {
         return runtimeTool;
     }
 }
-//# sourceMappingURL=runtime.js.map

package/dist/shared/definition.js

@@ -30,4 +30,3 @@ function cloneAndFreeze(value) {
     }
     return value;
 }
-//# sourceMappingURL=definition.js.map

package/dist/shared/errors.d.ts

@@ -1,5 +1,5 @@
 export declare const TOOL_ERROR_CODES: readonly ["EXECUTION_OUTCOME_UNKNOWN", "ACTION_IN_FLIGHT", "ACTION_NOT_HANDLED", "ACTION_TARGET_UNAVAILABLE", "BROWSER_EXECUTION_FAILED", "BROWSER_SNAPSHOT_REQUIRED", "BROWSER_TOOLS_UNAVAILABLE", "CONTRACT_MISMATCH", "DUPLICATE_BINDING", "INVALID_INPUT", "INVALID_TOOL_RUNTIME", "OPERATION_BUSY", "TOOL_CANCELLED", "TOOL_CONFIRMATION_INVALIDATED", "TOOL_CONFIRMATION_REJECTED", "TOOL_ERROR", "TOOL_REGISTRATION_TIMEOUT", "TOOL_SKIPPED", "TOOL_UNAVAILABLE", "UNKNOWN_TOOL"];
-type AgentToolErrorCode = typeof TOOL_ERROR_CODES[number];
+type AgentToolErrorCode = (typeof TOOL_ERROR_CODES)[number];
 export declare class AgentToolError extends Error {
     readonly code: AgentToolErrorCode;
     readonly details?: unknown | undefined;

package/dist/shared/errors.js

@@ -33,4 +33,3 @@ export class AgentToolError extends Error {
         this.name = "ToolRuntimeError";
     }
 }
-//# sourceMappingURL=errors.js.map

package/dist/shared/page-protocol.js

@@ -1,3 +1,2 @@
 // Generated from shared/page-protocol.ts. Do not edit manually.
 export {};
-//# sourceMappingURL=page-protocol.js.map

package/dist/shared/page-tools.js

@@ -40,4 +40,3 @@ export const applyActionTool = createAgentToolDefinition({
         additionalProperties: false,
     },
 });
-//# sourceMappingURL=page-tools.js.map

package/dist/shared/runtime-controller.d.ts

@@ -12,6 +12,7 @@ interface OperationSnapshot {
     readonly taskProgress?: TaskProgress;
 }
 export interface RuntimeController {
+    getRegisteredTools(): ReturnType<ToolRuntime["getTools"]>;
     beginInternalOperation(options?: {
         signal?: AbortSignal;
         onCancel?: () => void;

package/dist/shared/runtime-controller.js

@@ -8,4 +8,3 @@ export function getRuntimeController(runtime) {
     }
     return controller;
 }
-//# sourceMappingURL=runtime-controller.js.map

package/dist/shared/runtime-execution.js

@@ -1,3 +1,2 @@
 // Generated from shared/runtime-execution.ts. Do not edit manually.
 export const pageDecisionSymbol = Symbol.for("@nexface/tools/page-decision");
-//# sourceMappingURL=runtime-execution.js.map

package/dist/shared/schema.js

@@ -3,8 +3,17 @@ const types = new Set(["object", "array", "string", "number", "integer", "boolea
 const counts = ["minLength", "maxLength", "minItems", "maxItems"];
 const bounds = ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"];
 const keywords = new Set([
-    "type", "description", "properties", "required", "items", "enum", "additionalProperties",
-    ...counts, ...bounds, "pattern", "uniqueItems",
+    "type",
+    "description",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "additionalProperties",
+    ...counts,
+    ...bounds,
+    "pattern",
+    "uniqueItems",
 ]);
 const checkedSchemas = new WeakSet();
 const patterns = new WeakMap();
@@ -24,7 +33,9 @@ function assertJson(value, path, ancestors = new Set()) {
         invalid(path, "must be JSON-compatible.");
     if (ancestors.has(value))
         invalid(path, "must not contain circular references.");
-    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    if (!Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null) {
         invalid(path, "must be a plain JSON object.");
     }
     if (Object.getOwnPropertySymbols(value).length)
@@ -85,7 +96,8 @@ function assertSchema(value, path) {
             invalid(`${path}.${key}`, "must be a non-negative integer.");
     }
     for (const key of bounds) {
-        if (value[key] !== undefined && (typeof value[key] !== "number" || !Number.isFinite(value[key])))
+        if (value[key] !== undefined &&
+            (typeof value[key] !== "number" || !Number.isFinite(value[key])))
             invalid(`${path}.${key}`, "must be a finite number.");
     }
     if (value.pattern !== undefined) {
@@ -95,7 +107,8 @@ function assertSchema(value, path) {
     }
     if (value.enum !== undefined && (!Array.isArray(value.enum) || value.enum.length === 0))
         invalid(`${path}.enum`, "must be a non-empty array.");
-    if (Array.isArray(value.enum) && value.enum.some((item, index, entries) => entries.slice(0, index).some((other) => jsonEqual(item, other))))
+    if (Array.isArray(value.enum) &&
+        value.enum.some((item, index, entries) => entries.slice(0, index).some((other) => jsonEqual(item, other))))
         invalid(`${path}.enum`, "must contain unique values.");
     if (value.properties !== undefined) {
         if (value.type !== "object" || !isRecord(value.properties))
@@ -104,7 +117,10 @@ function assertSchema(value, path) {
             assertSchema(property, `${path}.properties.${name}`);
     }
     if (value.required !== undefined) {
-        if (value.type !== "object" || !Array.isArray(value.required) || value.required.some((name) => typeof name !== "string") || new Set(value.required).size !== value.required.length)
+        if (value.type !== "object" ||
+            !Array.isArray(value.required) ||
+            value.required.some((name) => typeof name !== "string") ||
+            new Set(value.required).size !== value.required.length)
             invalid(`${path}.required`, "must contain unique property names.");
         const properties = value.properties;
         if (value.required.some((name) => !properties || !Object.hasOwn(properties, name)))
@@ -118,7 +134,7 @@ function assertSchema(value, path) {
 }
 export function assertAgentToolInputSchema(value, path = "inputSchema") {
     if (!isRecord(value) || value.type !== "object")
-        invalid(path, 'root type must be object.');
+        invalid(path, "root type must be object.");
     if (checkedSchemas.has(value))
         return;
     const frozen = assertJson(value, path);
@@ -130,21 +146,29 @@ function jsonEqual(left, right) {
     if (left === right)
         return true;
     if (Array.isArray(left) && Array.isArray(right))
-        return left.length === right.length && left.every((item, index) => jsonEqual(item, right[index]));
+        return (left.length === right.length && left.every((item, index) => jsonEqual(item, right[index])));
     if (!isRecord(left) || !isRecord(right))
         return false;
     const keys = Object.keys(left);
-    return keys.length === Object.keys(right).length && keys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]));
+    return (keys.length === Object.keys(right).length &&
+        keys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key])));
 }
 function typeMatches(schema, value) {
     switch (schema.type) {
-        case undefined: return true;
-        case "null": return value === null;
-        case "array": return Array.isArray(value);
-        case "object": return isRecord(value);
-        case "integer": return typeof value === "number" && Number.isInteger(value);
-        case "number": return typeof value === "number" && Number.isFinite(value);
-        default: return typeof value === schema.type;
+        case undefined:
+            return true;
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        default:
+            return typeof value === schema.type;
     }
 }
 export function validateAgentToolInput(schema, value, path = "input") {
@@ -177,7 +201,8 @@ export function validateAgentToolInput(schema, value, path = "input") {
             errors.push(`${path} must have at least ${schema.minItems} items.`);
         if (schema.maxItems !== undefined && value.length > schema.maxItems)
             errors.push(`${path} must have at most ${schema.maxItems} items.`);
-        if (schema.uniqueItems && value.some((item, index) => value.slice(0, index).some((other) => jsonEqual(item, other))))
+        if (schema.uniqueItems &&
+            value.some((item, index) => value.slice(0, index).some((other) => jsonEqual(item, other))))
             errors.push(`${path} must contain unique items.`);
         if (schema.items)
             value.forEach((item, index) => errors.push(...validateAgentToolInput(schema.items, item, `${path}[${index}]`)));
@@ -188,7 +213,9 @@ export function validateAgentToolInput(schema, value, path = "input") {
                 errors.push(`${path}.${key} is required.`);
         }
         for (const [key, item] of Object.entries(value)) {
-            const property = schema.properties && Object.hasOwn(schema.properties, key) ? schema.properties[key] : undefined;
+            const property = schema.properties && Object.hasOwn(schema.properties, key)
+                ? schema.properties[key]
+                : undefined;
             if (property)
                 errors.push(...validateAgentToolInput(property, item, `${path}.${key}`));
             else if (schema.additionalProperties === false)
@@ -197,4 +224,3 @@ export function validateAgentToolInput(schema, value, path = "input") {
     }
     return errors;
 }
-//# sourceMappingURL=schema.js.map