@nexface/tools 0.1.0

package/src/internal.ts

@@ -0,0 +1,36 @@
+export {
+  AgentContextError,
+  ToolRuntimeImplementation,
+  ToolRuntimeImplementation as ToolRuntime,
+  AgentToolError,
+  createToolRuntime,
+  getInternalToolRuntime,
+} from "./runtime.js";
+export type {
+  ToolRuntime as PublicToolRuntime,
+  ToolRuntimeOptions,
+  InternalToolRuntime,
+} from "./runtime.js";
+export type { AgentToolExecutionEvent } from "./internal-types.js";
+export { defineSystemAgentTool } from "./definition.js";
+export {
+  browserToolsAvailable,
+  createBrowserToolset,
+  executeCodeTool,
+  getSnapshotTool,
+  startPageTransitionTracker,
+} from "./browser/toolset.js";
+export {
+  BROWSER_TOOLS_SKILL,
+  serializeBrowserToolsSkill,
+} from "./browser/prompt.js";
+export type {
+  BrowserToolHandler,
+  BrowserToolsConfig,
+  BrowserToolsOptions,
+  BrowserToolset,
+  PageTransitionSettleResult,
+  PageTransitionTracker,
+} from "./browser/toolset.js";
+export type * from "./browser/types.js";
+export type { AgentContextRegistration } from "./types.js";

package/src/react.tsx

@@ -0,0 +1,397 @@
+import {
+  Children,
+  Fragment,
+  cloneElement,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type MouseEvent,
+  type Ref,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { defineAgentTool } from "./definition.js";
+import { AgentToolError, getInternalToolRuntime } from "./runtime.js";
+import {
+  InternalToolRuntimeScope,
+  useInternalToolRuntime,
+} from "./internal-react.js";
+import type { ToolRuntime } from "./runtime.js";
+import type {
+  AgentContextEntry,
+  AgentContextRegistration,
+  AgentToolDefinition,
+  AgentToolExecutor,
+} from "./types.js";
+import { connectToolRuntimeToWebMcp } from "./webmcp.js";
+
+function useAgentBinding<
+  TInput,
+  TResult,
+>(
+  definition: AgentToolDefinition<TInput, TResult>,
+  execute: AgentToolExecutor<TInput, TResult>,
+): void {
+  const runtime = useInternalToolRuntime();
+  const executeRef = useRef(execute);
+  executeRef.current = execute;
+  useLayoutEffect(() => {
+    const controller = new AbortController();
+    runtime.register(
+      definition,
+      (input, context) => executeRef.current(input, context),
+      { signal: controller.signal },
+    );
+    return () => controller.abort();
+  }, [runtime, definition]);
+}
+
+export function useAgentTool<
+  TInput,
+  TResult,
+>(
+  definition: AgentToolDefinition<TInput, TResult>,
+  execute: AgentToolExecutor<TInput, TResult>,
+): void {
+  useAgentBinding(definition, execute);
+}
+
+export function AgentToolsProvider({
+  children,
+  toolRuntime,
+  webMcp = true,
+}: {
+  children: ReactNode;
+  toolRuntime: ToolRuntime;
+  webMcp?: boolean;
+}) {
+  const runtime = getInternalToolRuntime(toolRuntime);
+  return (
+    <InternalToolRuntimeScope runtime={toolRuntime}>
+      <WebMcpRuntimeBridge enabled={webMcp} runtime={runtime} />
+      {children}
+    </InternalToolRuntimeScope>
+  );
+}
+
+function WebMcpRuntimeBridge({
+  enabled,
+  runtime,
+}: {
+  enabled: boolean;
+  runtime: ReturnType<typeof getInternalToolRuntime>;
+}) {
+  useEffect(() => {
+    if (!enabled) return undefined;
+    return connectToolRuntimeToWebMcp(runtime);
+  }, [enabled, runtime]);
+  return null;
+}
+
+export function useAgentContext(context: AgentContextEntry): void {
+  const runtime = useInternalToolRuntime();
+  const registrationRef = useRef<AgentContextRegistration | undefined>(undefined);
+  useLayoutEffect(() => {
+    const controller = new AbortController();
+    const registration = runtime.registerContext(context, { signal: controller.signal });
+    registrationRef.current = registration;
+    return () => {
+      if (registrationRef.current === registration) registrationRef.current = undefined;
+      controller.abort();
+    };
+  }, [runtime, context.name]);
+  useLayoutEffect(() => {
+    registrationRef.current?.update(context);
+  }, [runtime, context.name, context.description, context.value]);
+}
+
+export function AgentContext(context: AgentContextEntry): null {
+  useAgentContext(context);
+  return null;
+}
+
+function waitForActionResult<TResult>(
+  result: TResult | Promise<TResult>,
+  signal: AbortSignal,
+): Promise<TResult> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(result).then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+export type AgentUIActionEvent = "click";
+
+type Awaitable<TResult> = TResult | Promise<TResult>;
+
+export interface AgentUIActionChildProps<TResult = void> {
+  onClick: (event: MouseEvent<HTMLElement>) => Awaitable<TResult>;
+  disabled?: boolean;
+}
+
+export interface AgentUIActionProps<TResult = void> {
+  name: string;
+  description: string;
+  event?: AgentUIActionEvent;
+  children: ReactElement<AgentUIActionChildProps<TResult>>;
+}
+
+type PendingInvocation<TResult> = {
+  resolve: (value: TResult | PromiseLike<TResult>) => void;
+  reject: (reason?: unknown) => void;
+};
+
+function setRefValue<T>(ref: Ref<T> | undefined, value: T | null): (() => void) | undefined {
+  if (typeof ref === "function") {
+    const cleanup = ref(value);
+    return typeof cleanup === "function" ? cleanup : undefined;
+  }
+  if (ref) ref.current = value;
+}
+
+function getElementRef(element: ReactElement): Ref<HTMLElement> | undefined {
+  const props = element.props as Record<string, unknown>;
+  const refDescriptor = Object.getOwnPropertyDescriptor(element, "ref");
+  if (refDescriptor && "value" in refDescriptor) {
+    return refDescriptor.value as Ref<HTMLElement> | undefined;
+  }
+  return (props as { ref?: Ref<HTMLElement> }).ref;
+}
+
+function isHTMLElement(value: unknown): value is HTMLElement {
+  if (!value || typeof value !== "object") return false;
+  const ownerDocument = (value as { ownerDocument?: Document }).ownerDocument;
+  const ElementConstructor =
+    ownerDocument?.defaultView?.HTMLElement ??
+    (typeof HTMLElement === "undefined" ? undefined : HTMLElement);
+  return ElementConstructor !== undefined && value instanceof ElementConstructor;
+}
+
+function warnAgentUIAction(message: string): void {
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+    console.warn(message);
+  }
+}
+
+const eventAdapters: Record<AgentUIActionEvent, { invoke(target: HTMLElement): void }> = {
+  click: {
+    invoke(target) {
+      target.click();
+    },
+  },
+};
+
+export function AgentUIAction<TResult = void>({
+  name,
+  description,
+  event = "click",
+  children,
+}: AgentUIActionProps<TResult>) {
+  const runtime = useInternalToolRuntime();
+  const child = Children.only(children) as ReactElement<AgentUIActionChildProps<TResult>>;
+  const isFragment = child.type === Fragment;
+  const handler = isFragment ? undefined : child.props.onClick;
+  const childDisabled = isFragment ? false : Boolean(child.props.disabled);
+  const childRef = isFragment ? undefined : getElementRef(child);
+  const [target, setTarget] = useState<HTMLElement | null>(null);
+  const targetRef = useRef<HTMLElement | null>(null);
+  const handlerRef = useRef(handler);
+  const disabledRef = useRef(childDisabled);
+  const pendingInvocationRef = useRef<PendingInvocation<TResult> | null>(null);
+  const invalidTargetRef = useRef(false);
+  const warnedTargetRef = useRef(false);
+  const warnedChildRef = useRef<"fragment" | "handler" | null>(null);
+  const invokingRef = useRef(false);
+
+  useLayoutEffect(() => {
+    handlerRef.current = handler;
+    disabledRef.current = childDisabled;
+  });
+
+  const mergedRef = useCallback(
+    (value: unknown) => {
+      const element = isHTMLElement(value) ? value : null;
+      const cleanupChildRef = setRefValue(childRef as Ref<unknown> | undefined, value);
+      invalidTargetRef.current = value !== null && !element;
+      targetRef.current = element;
+      setTarget(element);
+      if (element) warnedTargetRef.current = false;
+      if (cleanupChildRef) {
+        return () => {
+          cleanupChildRef();
+          if (targetRef.current === element) {
+            invalidTargetRef.current = false;
+            targetRef.current = null;
+            setTarget(null);
+          }
+        };
+      }
+    },
+    [childRef],
+  );
+
+  const invokeHandler = useCallback((mouseEvent: MouseEvent<HTMLElement>) => {
+    const currentHandler = handlerRef.current;
+    const pending = pendingInvocationRef.current;
+    if (pending) pendingInvocationRef.current = null;
+    if (!currentHandler) {
+      pending?.reject(
+        new AgentToolError(
+          "ACTION_NOT_HANDLED",
+          `AgentUIAction "${name}" does not have an onClick handler.`,
+        ),
+      );
+      return undefined as TResult;
+    }
+    try {
+      const result = currentHandler(mouseEvent);
+      if (pending) Promise.resolve(result).then(pending.resolve, pending.reject);
+      return result;
+    } catch (error) {
+      if (pending) {
+        pending.reject(error);
+        return undefined as TResult;
+      }
+      throw error;
+    }
+  }, [name]);
+
+  const definition = useMemo(
+    () =>
+      defineAgentTool<TResult>({
+        name,
+        description,
+      }),
+    [name, description],
+  );
+
+  useLayoutEffect(() => {
+    if (isFragment || !handler) {
+      const warningType = isFragment ? "fragment" : "handler";
+      if (warnedChildRef.current !== warningType) {
+        warnedChildRef.current = warningType;
+        warnAgentUIAction(
+          isFragment
+            ? `AgentUIAction "${name}" does not support React.Fragment children.`
+            : `AgentUIAction "${name}" needs a child with onClick.`,
+        );
+      }
+      return;
+    }
+    warnedChildRef.current = null;
+    if (!target) {
+      if (!targetRef.current && !warnedTargetRef.current) {
+        warnedTargetRef.current = true;
+        warnAgentUIAction(
+          invalidTargetRef.current
+            ? `AgentUIAction "${name}" needs its child ref to resolve to an HTMLElement; the Tool is not registered.`
+            : `AgentUIAction "${name}" needs its child to forward ref to an HTMLElement; the Tool is not registered.`,
+        );
+      }
+      return;
+    }
+
+    const controller = new AbortController();
+    runtime.register(
+      definition,
+      async (_input, context) => {
+        if (invokingRef.current) {
+          throw new AgentToolError(
+            "ACTION_IN_FLIGHT",
+            `AgentUIAction "${name}" is already being invoked.`,
+          );
+        }
+        if (disabledRef.current) {
+          throw new AgentToolError(
+            "TOOL_UNAVAILABLE",
+            `AgentUIAction "${name}" is disabled.`,
+          );
+        }
+        const currentTarget = targetRef.current;
+        if (!currentTarget || !currentTarget.isConnected) {
+          throw new AgentToolError(
+            "ACTION_TARGET_UNAVAILABLE",
+            `AgentUIAction "${name}" target is not available.`,
+          );
+        }
+        invokingRef.current = true;
+        let resolveInvocation!: (value: TResult | PromiseLike<TResult>) => void;
+        let rejectInvocation!: (reason?: unknown) => void;
+        const actionPromise = new Promise<TResult>((resolve, reject) => {
+          resolveInvocation = resolve;
+          rejectInvocation = reject;
+        });
+        const pendingInvocation = {
+          resolve: resolveInvocation,
+          reject: rejectInvocation,
+        };
+        pendingInvocationRef.current = pendingInvocation;
+        try {
+          eventAdapters[event].invoke(currentTarget);
+        } catch (error) {
+          if (pendingInvocationRef.current === pendingInvocation) {
+            pendingInvocationRef.current = null;
+          }
+          invokingRef.current = false;
+          throw error;
+        }
+        if (pendingInvocationRef.current === pendingInvocation) {
+          pendingInvocationRef.current = null;
+          invokingRef.current = false;
+          throw new AgentToolError(
+            "ACTION_NOT_HANDLED",
+            `AgentUIAction "${name}" click did not invoke its onClick handler.`,
+          );
+        }
+        try {
+          return await waitForActionResult(actionPromise, context.signal);
+        } finally {
+          if (context.signal.aborted) {
+            void actionPromise.then(
+              () => {
+                invokingRef.current = false;
+              },
+              () => {
+                invokingRef.current = false;
+              },
+            );
+          } else {
+            invokingRef.current = false;
+          }
+        }
+      },
+      { signal: controller.signal },
+    );
+    return () => controller.abort();
+  }, [runtime, definition, event, handler !== undefined, isFragment, name, target]);
+
+  if (isFragment) return child;
+  return cloneElement(child, {
+    onClick: invokeHandler,
+    ref: mergedRef,
+  } as AgentUIActionChildProps<TResult> & { ref: Ref<HTMLElement> });
+}
+
+export type {
+  AgentContextValue,
+  AgentToolDefinition,
+  AgentToolExecutor,
+} from "./types.js";