@nexface/tools 0.1.15-alpha.1 → 0.1.15-alpha.11

package/dist/browser/toolset.js

@@ -27,11 +27,7 @@ const DEFAULT_SNAPSHOT_LIMITS = {
     fullMaxVisitedNodes: 40_000,
 };
 function isIgnoredMutationNode(node) {
-    const element = node instanceof Element
-        ? node
-        : node instanceof Text
-            ? node.parentElement
-            : null;
+    const element = node instanceof Element ? node : node instanceof Text ? node.parentElement : null;
     return Boolean(element?.closest("[data-nexface-ignore]"));
 }
 function isRelevantMutation(record) {
@@ -40,8 +36,7 @@ function isRelevantMutation(record) {
     if (record.type !== "childList")
         return true;
     const changedNodes = [...record.addedNodes, ...record.removedNodes];
-    return (changedNodes.length === 0
-        || changedNodes.some((node) => !isIgnoredMutationNode(node)));
+    return changedNodes.length === 0 || changedNodes.some((node) => !isIgnoredMutationNode(node));
 }
 let activeHistoryPatch;
 function subscribeHistoryChanges(subscriber) {
@@ -223,12 +218,12 @@ function validateInput(definition, input) {
     }
 }
 export function browserToolsAvailable() {
-    return (typeof window !== "undefined"
-        && typeof document !== "undefined"
-        && typeof Worker !== "undefined"
-        && typeof Blob !== "undefined"
-        && typeof URL?.createObjectURL === "function"
-        && typeof MutationObserver !== "undefined");
+    return (typeof window !== "undefined" &&
+        typeof document !== "undefined" &&
+        typeof Worker !== "undefined" &&
+        typeof Blob !== "undefined" &&
+        typeof URL?.createObjectURL === "function" &&
+        typeof MutationObserver !== "undefined");
 }
 export function createBrowserToolset(options = {}) {
     if (!browserToolsAvailable()) {
@@ -236,19 +231,14 @@ export function createBrowserToolset(options = {}) {
     }
     const limits = {
         ...DEFAULT_EXECUTION_LIMITS,
-        maxDurationMs: options.limits?.maxDurationMs
-            ?? DEFAULT_EXECUTION_LIMITS.maxDurationMs,
-        maxResultChars: options.limits?.maxResultChars
-            ?? DEFAULT_EXECUTION_LIMITS.maxResultChars,
-        singleActionTimeoutMs: options.limits?.singleActionTimeoutMs
-            ?? DEFAULT_EXECUTION_LIMITS.singleActionTimeoutMs,
+        maxDurationMs: options.limits?.maxDurationMs ?? DEFAULT_EXECUTION_LIMITS.maxDurationMs,
+        maxResultChars: options.limits?.maxResultChars ?? DEFAULT_EXECUTION_LIMITS.maxResultChars,
+        singleActionTimeoutMs: options.limits?.singleActionTimeoutMs ?? DEFAULT_EXECUTION_LIMITS.singleActionTimeoutMs,
     };
     const snapshotLimits = {
         ...DEFAULT_SNAPSHOT_LIMITS,
-        viewportMaxChars: options.snapshotLimits?.viewportMaxChars
-            ?? DEFAULT_SNAPSHOT_LIMITS.viewportMaxChars,
-        fullMaxChars: options.snapshotLimits?.fullMaxChars
-            ?? DEFAULT_SNAPSHOT_LIMITS.fullMaxChars,
+        viewportMaxChars: options.snapshotLimits?.viewportMaxChars ?? DEFAULT_SNAPSHOT_LIMITS.viewportMaxChars,
+        fullMaxChars: options.snapshotLimits?.fullMaxChars ?? DEFAULT_SNAPSHOT_LIMITS.fullMaxChars,
     };
     const feedback = new ActionFeedback();
     const controller = new PageController(limits, feedback);
@@ -285,7 +275,8 @@ export function createBrowserToolset(options = {}) {
             const scope = normalizedInput.scope;
             const deadline = performance.now() + limits.maxDurationMs;
             signal.throwIfAborted();
-            return (await observe(scope, { deadline, signal }, pageDecision ? "actions" : "text")).snapshot;
+            return (await observe(scope, { deadline, signal }, pageDecision ? "actions" : "text"))
+                .snapshot;
         },
     };
     const executeObserved = async (signal, execute, cancel, mode = "code", onFeedback, assertActive) => {
@@ -316,7 +307,8 @@ export function createBrowserToolset(options = {}) {
             }
             result = await measurePagePhase("execution", () => execute(activeRegistry, workerBudget));
             signal.throwIfAborted();
-            if (result.error && ["EXECUTION_TIMEOUT", "WORKER_ERROR", "EXECUTION_OUTCOME_UNKNOWN"].includes(result.error.code)) {
+            if (result.error &&
+                ["EXECUTION_TIMEOUT", "WORKER_ERROR", "EXECUTION_OUTCOME_UNKNOWN"].includes(result.error.code)) {
                 result.error.code = "EXECUTION_OUTCOME_UNKNOWN";
             }
             if (!result.ok && result.completedActions.length === 0) {
@@ -325,9 +317,7 @@ export function createBrowserToolset(options = {}) {
             try {
                 const settled = await measurePagePhase("settle", () => tracker.waitForSettle({ deadline, signal }));
                 signal.throwIfAborted();
-                if (settled.timedOut
-                    && settled.urlChanged
-                    && !settled.mutationObservedAfterUrlChange) {
+                if (settled.timedOut && settled.urlChanged && !settled.mutationObservedAfterUrlChange) {
                     result.snapshotUnavailable = true;
                     return expireRefs(result);
                 }
@@ -382,7 +372,9 @@ export function createBrowserToolset(options = {}) {
             if (!bundle || bundle.snapshot.snapshotId !== input.snapshotId)
                 return undefined;
             const selected = bundle.actions?.get(input.actionId);
-            if (!selected || selected.command.method === "scrollBy" || selected.command.method === "waitForTimeout")
+            if (!selected ||
+                selected.command.method === "scrollBy" ||
+                selected.command.method === "waitForTimeout")
                 return undefined;
             const target = selected.command.target;
             const element = target?.type === "ref" ? bundle.registry.refs.get(target.ref)?.element : undefined;
@@ -396,14 +388,21 @@ export function createBrowserToolset(options = {}) {
             const selected = bundle.actions.get(input.actionId);
             if (!selected)
                 throw new AgentToolError("INVALID_INPUT", "Action is not a candidate of this observation.");
-            if (selected.command.method === "fill" ? typeof input.text !== "string" || !input.text.trim() : input.text !== undefined) {
+            if (selected.command.method === "fill"
+                ? typeof input.text !== "string" || !input.text.trim()
+                : input.text !== undefined) {
                 throw new AgentToolError("INVALID_INPUT", "Only fill actions require a non-empty text value.");
             }
             if (selected.command.method === "selectOption") {
                 const target = selected.command.target;
                 const element = target.type === "ref" ? bundle.registry.refs.get(target.ref)?.element : undefined;
-                const options = element instanceof HTMLSelectElement ? [...element.options].filter((option) => option.value === selected.command.args[0]) : [];
-                if (options.length !== 1 || options[0].disabled || options[0].closest("optgroup[disabled]") || options[0].label.slice(0, 500) !== selected.candidate.option) {
+                const options = element instanceof HTMLSelectElement
+                    ? [...element.options].filter((option) => option.value === selected.command.args[0])
+                    : [];
+                if (options.length !== 1 ||
+                    options[0].disabled ||
+                    options[0].closest("optgroup[disabled]") ||
+                    options[0].label.slice(0, 500) !== selected.candidate.option) {
                     throw new AgentToolError("INVALID_INPUT", "The observed option changed or is no longer available. Observe again.");
                 }
             }
@@ -413,7 +412,9 @@ export function createBrowserToolset(options = {}) {
                 let timer;
                 try {
                     const command = {
-                        ...selected.command, executionId, commandSeq: 1,
+                        ...selected.command,
+                        executionId,
+                        commandSeq: 1,
                         args: selected.command.method === "fill" ? [input.text] : selected.command.args,
                     };
                     const response = await Promise.race([
@@ -421,7 +422,8 @@ export function createBrowserToolset(options = {}) {
                             if (selected.optionElement) {
                                 const target = selected.command.target;
                                 const element = target.type === "ref" ? registry.refs.get(target.ref)?.element : undefined;
-                                if (!selected.optionElement.isConnected || selected.optionElement.closest("select") !== element) {
+                                if (!selected.optionElement.isConnected ||
+                                    selected.optionElement.closest("select") !== element) {
                                     throw new AgentToolError("INVALID_INPUT", "The observed option was replaced. Observe again.");
                                 }
                             }
@@ -434,7 +436,12 @@ export function createBrowserToolset(options = {}) {
                         }),
                     ]);
                     const receipt = controller.completeExecution(executionId);
-                    return { executionId, ...receipt, ok: response.ok, ...(response.error ? { error: response.error } : {}) };
+                    return {
+                        executionId,
+                        ...receipt,
+                        ok: response.ok,
+                        ...(response.error ? { error: response.error } : {}),
+                    };
                 }
                 finally {
                     clearTimeout(timer);
@@ -449,4 +456,3 @@ export function createBrowserToolset(options = {}) {
         handlers: new Map(toolHandlers.map((tool) => [tool.definition.name, tool])),
     };
 }
-//# sourceMappingURL=toolset.js.map

package/dist/browser/types.d.ts

@@ -1,6 +1,6 @@
 import type { ObservedAction } from "./actions.js";
 import type { PageSnapshot } from "../shared/page-protocol.js";
-export type { SnapshotScope, SnapshotFormat, SemanticState, PageActionCandidate, PageSnapshot } from "../shared/page-protocol.js";
+export type { SnapshotScope, SnapshotFormat, SemanticState, PageActionCandidate, PageSnapshot, } from "../shared/page-protocol.js";
 export interface RefTarget {
     element: Element;
     identity: string;

package/dist/browser/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/browser/worker-runner.js

@@ -397,4 +397,3 @@ export class WorkerRunner {
         active.cancel();
     }
 }
-//# sourceMappingURL=worker-runner.js.map

package/dist/definition.d.ts

@@ -8,7 +8,5 @@ export declare function isValidAgentContextName(name: string): boolean;
 export declare function defineAgentTool<TResult = unknown>(metadata: AgentToolMetadataInput): AgentToolDefinition<Record<string, never>, TResult>;
 export declare function defineAgentTool<TInput = never, TResult = unknown, const TSchema extends AgentToolInputSchema = AgentToolInputSchema>(metadata: AgentToolMetadataInput & {
     inputSchema: TSchema;
-}): AgentToolDefinition<[
-    TInput
-] extends [never] ? InferJsonSchema<TSchema> : TInput, TResult>;
+}): AgentToolDefinition<[TInput] extends [never] ? InferJsonSchema<TSchema> : TInput, TResult>;
 export {};

package/dist/definition.js

@@ -6,7 +6,8 @@ const emptyInputSchema = Object.freeze({
 });
 const agentNamePattern = /^[A-Za-z0-9_-]{1,64}$/;
 const reservedContextNames = new Set([
-    "nxf_applyAction", "nxf_delegatePageTask",
+    "nxf_applyAction",
+    "nxf_delegatePageTask",
     "nxf_callAppTool",
     "nxf_finish",
     "nxf_getSnapshot",
@@ -33,4 +34,3 @@ export function defineAgentTool(metadata) {
         inputSchema: metadata.inputSchema === undefined ? emptyInputSchema : metadata.inputSchema,
     });
 }
-//# sourceMappingURL=definition.js.map

package/dist/index.browser.js

@@ -1,4 +1,3 @@
 import "./styles.css";
 export * from "./index.js";
 export { registerAgentTool } from "./registration.js";
-//# sourceMappingURL=index.browser.js.map

package/dist/index.js

@@ -4,4 +4,3 @@ export { AgentOperationSurface } from "./operation-surface.js";
 export { createToolRuntime, isToolRuntimeError, } from "./runtime.js";
 export { AgentContext, ToolsProvider, AgentUIAction, useAgentContext, useAgentNavigation, useAgentTool, } from "./react.js";
 export { registerAgentTool } from "./registration.js";
-//# sourceMappingURL=index.js.map

package/dist/internal-react.d.ts

@@ -3,7 +3,7 @@ import { type ToolRuntime, type InternalToolRuntime } from "./runtime.js";
 export interface InternalToolRuntimeHostProps {
     children: ReactNode;
 }
-export declare function InternalToolRuntimeHost({ children, }: InternalToolRuntimeHostProps): ReactElement;
+export declare function InternalToolRuntimeHost({ children }: InternalToolRuntimeHostProps): ReactElement;
 export declare function InternalToolRuntimeScope({ children, runtime, }: {
     children: ReactNode;
     runtime: ToolRuntime;

package/dist/internal-react.js

@@ -1,10 +1,10 @@
 import * as React from "react";
-import { createContext, useContext, useMemo, } from "react";
+import { createContext, useContext, useMemo } from "react";
 import { createToolRuntime, getInternalToolRuntime, } from "./runtime.js";
 const InternalToolRuntimeContext = createContext(null);
-export function InternalToolRuntimeHost({ children, }) {
+export function InternalToolRuntimeHost({ children }) {
     const runtime = useMemo(() => createToolRuntime(), []);
-    return (React.createElement(InternalToolRuntimeScope, { runtime: runtime }, children));
+    return React.createElement(InternalToolRuntimeScope, { runtime: runtime }, children);
 }
 export function InternalToolRuntimeScope({ children, runtime, }) {
     const internalRuntime = getInternalToolRuntime(runtime);
@@ -20,4 +20,3 @@ export function useInternalToolRuntime() {
 export function useOptionalInternalToolRuntime() {
     return useContext(InternalToolRuntimeContext);
 }
-//# sourceMappingURL=internal-react.js.map

package/dist/internal-types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=internal-types.js.map

package/dist/navigation.js

@@ -37,4 +37,3 @@ export function getAgentNavigationEntries(navigation) {
     }
     return entries;
 }
-//# sourceMappingURL=navigation.js.map

package/dist/operation-lock.d.ts

@@ -1,3 +1,3 @@
 export declare function isOperationSurfaceLocked(surface: HTMLElement): boolean;
 /** Block user input inside the surface without hiding DOM from page tools. */
-export declare function lockOperationSurface(surface: HTMLElement, redirectFocus?: () => void): () => void;
+export declare function lockOperationSurface(surface: HTMLElement): () => void;

package/dist/operation-lock.js

@@ -1,36 +1,54 @@
-import { isAgentActivation, isAgentFocus } from "./browser/focus.js";
+import { isAgentActivation } from "./browser/focus.js";
 const lockedSurfaces = new WeakSet();
 export function isOperationSurfaceLocked(surface) {
     return lockedSurfaces.has(surface);
 }
 /** Block user input inside the surface without hiding DOM from page tools. */
-export function lockOperationSurface(surface, redirectFocus) {
+export function lockOperationSurface(surface) {
     const previousBusy = surface.getAttribute("aria-busy");
     const block = (event) => {
         if ((event.type === "submit" || event.type === "reset") && isAgentActivation())
             return;
         if (!event.isTrusted)
             return;
-        if (event.type === "focus" || event.type === "focusin") {
-            if (isAgentFocus())
-                return;
-            event.stopImmediatePropagation();
-            if (event.target instanceof HTMLElement)
-                event.target.blur();
-            redirectFocus?.();
-            return;
-        }
-        if (event.type === "keydown" && event.key === "Tab") {
-            event.preventDefault();
-            event.stopImmediatePropagation();
-            redirectFocus?.();
-            return;
-        }
         event.preventDefault();
         event.stopImmediatePropagation();
     };
     // Wheel and touch defaults are blocked here: React delegates them passively.
-    const events = ["focus", "focusin", "mouseenter", "mouseleave", "pointerenter", "pointerleave", "pointerdown", "pointerup", "pointermove", "pointerover", "pointerout", "mousedown", "mouseup", "mousemove", "mouseover", "mouseout", "click", "dblclick", "auxclick", "contextmenu", "keydown", "keyup", "beforeinput", "paste", "cut", "drop", "dragstart", "touchstart", "touchmove", "touchend", "touchcancel", "wheel", "submit", "reset"];
+    const events = [
+        "mouseenter",
+        "mouseleave",
+        "pointerenter",
+        "pointerleave",
+        "pointerdown",
+        "pointerup",
+        "pointermove",
+        "pointerover",
+        "pointerout",
+        "mousedown",
+        "mouseup",
+        "mousemove",
+        "mouseover",
+        "mouseout",
+        "click",
+        "dblclick",
+        "auxclick",
+        "contextmenu",
+        "keydown",
+        "keyup",
+        "beforeinput",
+        "paste",
+        "cut",
+        "drop",
+        "dragstart",
+        "touchstart",
+        "touchmove",
+        "touchend",
+        "touchcancel",
+        "wheel",
+        "submit",
+        "reset",
+    ];
     lockedSurfaces.add(surface);
     surface.setAttribute("aria-busy", "true");
     for (const name of events)
@@ -45,4 +63,3 @@ export function lockOperationSurface(surface, redirectFocus) {
             surface.setAttribute("aria-busy", previousBusy);
     };
 }
-//# sourceMappingURL=operation-lock.js.map

package/dist/operation-runtime.js

@@ -4,17 +4,24 @@ export class OperationTracker {
     #unscoped = 0;
     #executions = new Map();
     #listeners = new Set();
-    #snapshot = Object.freeze({ operation: null, executions: Object.freeze([]) });
+    #snapshot = Object.freeze({
+        operation: null,
+        executions: Object.freeze([]),
+    });
     getSnapshot = () => this.#snapshot;
     subscribe = (listener) => {
         this.#listeners.add(listener);
-        return () => { this.#listeners.delete(listener); };
+        return () => {
+            this.#listeners.delete(listener);
+        };
     };
     begin(options = {}) {
         options.signal?.throwIfAborted();
         const previous = this.#operation;
-        const replacing = previous && previous.handle === options.replaceWaiting
-            && previous.snapshot.status === "waiting" && previous.pending === 0;
+        const replacing = previous &&
+            previous.handle === options.replaceWaiting &&
+            previous.snapshot.status === "waiting" &&
+            previous.pending === 0;
         if (this.#unscoped || (previous && !replacing)) {
             throw new AgentToolError("OPERATION_BUSY", "The Runtime already has an operation or outstanding tool calls.");
         }
@@ -23,11 +30,22 @@ export class OperationTracker {
             previous.resolveEnd();
         }
         let resolveEnd;
-        const endPromise = new Promise((resolve) => { resolveEnd = resolve; });
+        const endPromise = new Promise((resolve) => {
+            resolveEnd = resolve;
+        });
         const id = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
         const operation = {
-            snapshot: Object.freeze({ id, source: options.source ?? "host", status: "running", hasExecuted: false, canCancel: Boolean(options.onCancel), ...(options.taskProgress ? { taskProgress: Object.freeze(options.taskProgress) } : {}) }),
-            handle: undefined, pending: 0, resolveEnd,
+            snapshot: Object.freeze({
+                id,
+                source: options.source ?? "host",
+                status: "running",
+                hasExecuted: false,
+                canCancel: Boolean(options.onCancel),
+                ...(options.taskProgress ? { taskProgress: Object.freeze(options.taskProgress) } : {}),
+            }),
+            handle: undefined,
+            pending: 0,
+            resolveEnd,
             ...(options.onCancel ? { onCancel: options.onCancel } : {}),
             removeAbort: () => options.signal?.removeEventListener("abort", onAbort),
         };
@@ -42,7 +60,11 @@ export class OperationTracker {
                 if (this.#operation !== operation || operation.snapshot.status === "ending")
                     return endPromise;
                 operation.removeAbort();
-                operation.snapshot = Object.freeze({ ...operation.snapshot, status: "ending", outcome: endOptions?.outcome ?? "completed" });
+                operation.snapshot = Object.freeze({
+                    ...operation.snapshot,
+                    status: "ending",
+                    outcome: endOptions?.outcome ?? "completed",
+                });
                 this.#publish();
                 if (this.#finish(operation))
                     this.#publish();
@@ -77,8 +99,11 @@ export class OperationTracker {
     }
     requestCancel(id) {
         const operation = this.#operation;
-        if (!operation || operation.snapshot.id !== id || !operation.onCancel
-            || operation.snapshot.status === "ending" || operation.snapshot.status === "cancelling")
+        if (!operation ||
+            operation.snapshot.id !== id ||
+            !operation.onCancel ||
+            operation.snapshot.status === "ending" ||
+            operation.snapshot.status === "cancelling")
             return;
         const previous = operation.snapshot.status;
         this.#update(operation, { status: "cancelling" });
@@ -123,7 +148,9 @@ export class OperationTracker {
         if (event.status === "running") {
             this.#executions.set(event.id, event);
             const operation = this.#operation;
-            if (operation && event.operationId === operation.snapshot.id && !operation.snapshot.hasExecuted) {
+            if (operation &&
+                event.operationId === operation.snapshot.id &&
+                !operation.snapshot.hasExecuted) {
                 operation.snapshot = Object.freeze({ ...operation.snapshot, hasExecuted: true });
             }
         }
@@ -132,7 +159,9 @@ export class OperationTracker {
         this.#publish();
     }
     #finish(operation) {
-        if (operation.pending || operation.snapshot.status !== "ending" || this.#operation !== operation)
+        if (operation.pending ||
+            operation.snapshot.status !== "ending" ||
+            this.#operation !== operation)
             return false;
         this.#operation = undefined;
         operation.resolveEnd();
@@ -151,4 +180,3 @@ export class OperationTracker {
             listener();
     }
 }
-//# sourceMappingURL=operation-runtime.js.map