@nexface/tools 0.1.0

package/dist/browser/worker-runner.js

@@ -0,0 +1,400 @@
+export function createWorkerRuntimeSource(executionId, code) {
+    return `
+const executionId = ${JSON.stringify(executionId)};
+let requestId = 0;
+let commandSeq = 0;
+const pending = new Map();
+
+self.onmessage = (event) => {
+  const message = event.data;
+  if (message.type !== "response") return;
+  const entry = pending.get(message.requestId);
+  if (!entry) return;
+  pending.delete(message.requestId);
+  if (message.response.ok) entry.resolve(message.response.value);
+  else {
+    const error = new Error(message.response.error?.message || "Page command failed");
+    error.code = message.response.error?.code || "PAGE_COMMAND_FAILED";
+    error.candidates = message.response.error?.candidates;
+    entry.reject(error);
+  }
+};
+
+function normalizeRPCValue(value) {
+  if (value instanceof RegExp) {
+    return { source: value.source, flags: value.flags };
+  }
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalizeRPCValue);
+  if (value && typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error("Page API arguments must be plain JSON values or RegExp.");
+    }
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, normalizeRPCValue(item)])
+    );
+  }
+  throw new Error("Page API arguments contain an unsupported value.");
+}
+
+function normalizeResult(value, seen = new Set()) {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) throw new Error("executeCode returned a cyclic value.");
+    seen.add(value);
+    const result = value.map((item) => normalizeResult(item, seen));
+    seen.delete(value);
+    return result;
+  }
+  if (value && typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error("executeCode must return JSON-serializable data.");
+    }
+    if (seen.has(value)) throw new Error("executeCode returned a cyclic value.");
+    seen.add(value);
+    const result = Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, normalizeResult(item, seen)])
+    );
+    seen.delete(value);
+    return result;
+  }
+  throw new Error("executeCode must return JSON-serializable data.");
+}
+
+function rpc(target, method, args) {
+  if (pending.size > 0) {
+    const error = new Error("Page API operations must be awaited sequentially.");
+    error.code = "CONCURRENT_PAGE_OPERATION";
+    throw error;
+  }
+  const id = ++requestId;
+  const command = {
+    executionId,
+    commandSeq: ++commandSeq,
+    target: normalizeRPCValue(target),
+    method,
+    args: normalizeRPCValue(args)
+  };
+  self.postMessage({ type: "command", requestId: id, command });
+  return new Promise((resolve, reject) =>
+    pending.set(id, { resolve, reject })
+  );
+}
+
+class Locator {
+  constructor(steps) { this.steps = steps; }
+  getByRole(role, options = {}) {
+    return new Locator([...this.steps, { kind: "role", role, options }]);
+  }
+  getByText(text, options = {}) {
+    return new Locator([...this.steps, { kind: "text", text, options }]);
+  }
+  getByLabel(text, options = {}) {
+    return new Locator([...this.steps, { kind: "label", text, options }]);
+  }
+  filter(options) {
+    return new Locator([...this.steps, { kind: "filter", hasText: options.hasText }]);
+  }
+  call(method, ...args) {
+    return rpc(
+      { type: "locator", locator: { steps: this.steps } },
+      method,
+      args
+    );
+  }
+  click() { return this.call("click"); }
+  fill(value) { return this.call("fill", value); }
+  press(key) { return this.call("press", key); }
+  check() { return this.call("check"); }
+  uncheck() { return this.call("uncheck"); }
+  selectOption(value) { return this.call("selectOption", value); }
+  hover() { return this.call("hover"); }
+  focus() { return this.call("focus"); }
+  blur() { return this.call("blur"); }
+  scrollBy(value) { return this.call("scrollBy", value); }
+  scrollTo(value) { return this.call("scrollTo", value); }
+  scrollIntoView() { return this.call("scrollIntoView"); }
+  exists() { return this.call("exists"); }
+  text() { return this.call("text"); }
+  waitFor(options = {}) { return this.call("waitFor", options); }
+}
+
+const uiTarget = Object.freeze({
+  ref: (ref) => {
+    if (typeof ref !== "string" || !/^@\\d+$/.test(ref)) {
+      throw new Error("ui.ref(ref) requires a Snapshot ref such as @12.");
+    }
+    return new LocatorProxy({ type: "ref", ref });
+  },
+  getByRole: (role, options = {}) =>
+    new Locator([{ kind: "role", role, options }]),
+  getByText: (text, options = {}) =>
+    new Locator([{ kind: "text", text, options }]),
+  getByLabel: (text, options = {}) =>
+    new Locator([{ kind: "label", text, options }]),
+  scrollBy: (value) => rpc({ type: "page" }, "scrollBy", [value]),
+  waitForTimeout: (ms) => rpc({ type: "page" }, "waitForTimeout", [ms]),
+  waitForURL: (url, options = {}) =>
+    rpc({ type: "page" }, "waitForURL", [url, options])
+});
+const ui = new Proxy(uiTarget, {
+  get(target, property, receiver) {
+    if (typeof property !== "string" || Object.hasOwn(target, property)) {
+      return Reflect.get(target, property, receiver);
+    }
+    const error = new Error(
+      'UI API method "' + property + '" is not available. Supported methods: '
+        + Object.keys(uiTarget).join(", ") + "."
+    );
+    error.code = "UI_API_NOT_AVAILABLE";
+    throw error;
+  }
+});
+
+function LocatorProxy(target) {
+  this.target = target;
+}
+LocatorProxy.prototype.call = function(method, ...args) {
+  return rpc(this.target, method, args);
+};
+for (const method of [
+  "click",
+  "check",
+  "uncheck",
+  "hover",
+  "focus",
+  "blur",
+  "scrollIntoView",
+  "exists",
+  "text"
+]) {
+  LocatorProxy.prototype[method] = function() {
+    return this.call(method);
+  };
+}
+LocatorProxy.prototype.fill = function(value) { return this.call("fill", value); };
+LocatorProxy.prototype.press = function(key) { return this.call("press", key); };
+LocatorProxy.prototype.selectOption = function(value) {
+  return this.call("selectOption", value);
+};
+LocatorProxy.prototype.scrollBy = function(value) {
+  return this.call("scrollBy", value);
+};
+LocatorProxy.prototype.scrollTo = function(value) {
+  return this.call("scrollTo", value);
+};
+LocatorProxy.prototype.waitFor = function(options = {}) {
+  return this.call("waitFor", options);
+};
+
+(async () => {
+  try {
+    const rawResult = await (async () => {
+${code}
+    })();
+    if (pending.size > 0) {
+      const error = new Error("Every Page API operation must be awaited before executeCode returns.");
+      error.code = "UNAWAITED_PAGE_OPERATION";
+      throw error;
+    }
+    const hasValue = rawResult !== undefined;
+    const value = hasValue ? normalizeResult(rawResult) : undefined;
+    self.postMessage({ type: "done", hasValue, value });
+  } catch (error) {
+    self.postMessage({
+      type: "error",
+      error: {
+        code: error?.code || "CODE_EXECUTION_FAILED",
+        message: error?.message || String(error),
+        statement: error?.statement || error?.stack?.split("\\n")[1]?.trim()
+      }
+    });
+  }
+})();`;
+}
+function validateJSONValue(value, maxChars) {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+        throw new Error("executeCode returned a non-JSON value.");
+    }
+    if (serialized.length > maxChars) {
+        throw new Error(`executeCode result exceeds ${maxChars} serialized characters.`);
+    }
+    return JSON.parse(serialized);
+}
+export class WorkerRunner {
+    controller;
+    limits;
+    active;
+    constructor(controller, limits) {
+        this.controller = controller;
+        this.limits = limits;
+    }
+    async execute(code, registry, maxDurationMs = this.limits.maxDurationMs) {
+        if (code.length > this.limits.maxCodeLength) {
+            return {
+                executionId: "rejected",
+                ok: false,
+                completedActions: [],
+                error: {
+                    code: "CODE_TOO_LONG",
+                    message: `Code exceeds ${this.limits.maxCodeLength} characters.`,
+                },
+            };
+        }
+        if (this.active && !this.active.settled) {
+            return {
+                executionId: "rejected",
+                ok: false,
+                completedActions: [],
+                error: {
+                    code: "EXECUTION_IN_PROGRESS",
+                    message: "Another executeCode call is still running.",
+                },
+            };
+        }
+        const executionId = crypto.randomUUID();
+        const source = createWorkerRuntimeSource(executionId, code);
+        const blob = new Blob([source], {
+            type: "text/javascript",
+        });
+        const objectUrl = URL.createObjectURL(blob);
+        const worker = new Worker(objectUrl, {
+            name: `nexface-${executionId}`,
+        });
+        this.controller.beginExecution(executionId, registry);
+        return new Promise((resolve) => {
+            const active = {
+                executionId,
+                worker,
+                objectUrl,
+                settled: false,
+                cancel: () => { },
+            };
+            this.active = active;
+            const settle = (partial) => {
+                if (active.settled)
+                    return;
+                active.settled = true;
+                window.clearTimeout(timer);
+                worker.terminate();
+                URL.revokeObjectURL(objectUrl);
+                const receipt = this.controller.completeExecution(executionId);
+                if (this.active === active)
+                    this.active = undefined;
+                resolve({
+                    executionId,
+                    ...partial,
+                    completedActions: receipt.completedActions,
+                    ...(receipt.failedCall ? { failedCall: receipt.failedCall } : {}),
+                });
+            };
+            active.cancel = () => {
+                this.controller.cancelExecution(executionId);
+                settle({
+                    ok: false,
+                    error: {
+                        code: "EXECUTION_CANCELLED",
+                        message: "Execution was cancelled.",
+                    },
+                });
+            };
+            const timer = window.setTimeout(() => {
+                this.controller.cancelExecution(executionId);
+                settle({
+                    ok: false,
+                    error: {
+                        code: "EXECUTION_TIMEOUT",
+                        message: `Execution exceeded ${maxDurationMs}ms.`,
+                    },
+                });
+            }, maxDurationMs);
+            worker.onmessage = async (event) => {
+                const message = event.data;
+                if (message.type === "command") {
+                    let response = await this.controller.execute(message.command);
+                    if (response.ok && response.value !== undefined) {
+                        try {
+                            response = {
+                                ...response,
+                                value: validateJSONValue(response.value, this.limits.maxResultChars),
+                            };
+                        }
+                        catch (error) {
+                            response = {
+                                ok: false,
+                                error: {
+                                    code: "RESULT_TOO_LARGE",
+                                    message: error instanceof Error ? error.message : String(error),
+                                },
+                            };
+                        }
+                    }
+                    if (!active.settled) {
+                        worker.postMessage({
+                            type: "response",
+                            requestId: message.requestId,
+                            response,
+                        });
+                    }
+                    return;
+                }
+                if (message.type === "done") {
+                    if (!message.hasValue) {
+                        settle({ ok: true });
+                        return;
+                    }
+                    try {
+                        settle({
+                            ok: true,
+                            value: validateJSONValue(message.value, this.limits.maxResultChars),
+                        });
+                    }
+                    catch (error) {
+                        settle({
+                            ok: false,
+                            error: {
+                                code: "RESULT_INVALID",
+                                message: error instanceof Error ? error.message : String(error),
+                            },
+                        });
+                    }
+                    return;
+                }
+                settle({ ok: false, error: message.error });
+            };
+            worker.onerror = (event) => {
+                settle({
+                    ok: false,
+                    error: {
+                        code: "WORKER_ERROR",
+                        message: event.message || "Worker execution failed.",
+                    },
+                });
+            };
+        });
+    }
+    cancel() {
+        const active = this.active;
+        if (!active || active.settled)
+            return;
+        active.cancel();
+    }
+}
+//# sourceMappingURL=worker-runner.js.map

package/dist/browser/worker-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-runner.js","sourceRoot":"","sources":["../../src/browser/worker-runner.ts"],"names":[],"mappings":"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"}

package/dist/definition.d.ts

@@ -0,0 +1,16 @@
+import type { AgentToolDefinition, AgentToolInputSchema, InferJsonSchema } from "./types.js";
+interface AgentToolMetadataInput {
+    name: string;
+    description: string;
+}
+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>;
+export declare function defineSystemAgentTool<TInput, TResult>(metadata: AgentToolMetadataInput & {
+    inputSchema: AgentToolInputSchema;
+}): AgentToolDefinition<TInput, TResult>;
+export {};

package/dist/definition.js

@@ -0,0 +1,72 @@
+const emptyInputSchema = Object.freeze({
+    type: "object",
+    properties: Object.freeze({}),
+    additionalProperties: false,
+});
+const agentNamePattern = /^[A-Za-z0-9_-]{1,64}$/;
+const reservedContextNames = new Set([
+    "callAppTool",
+    "finish",
+    "getSnapshot",
+    "executeCode",
+]);
+const reservedToolNames = new Set([
+    ...reservedContextNames,
+    "loadSkill",
+]);
+export function isValidAgentContextName(name) {
+    return agentNamePattern.test(name) && !reservedContextNames.has(name);
+}
+function assertName(name) {
+    if (!agentNamePattern.test(name) || reservedToolNames.has(name)) {
+        throw new Error(`Invalid or reserved agent tool name: ${name}.`);
+    }
+}
+function assertSystemName(name) {
+    if (!agentNamePattern.test(name)) {
+        throw new Error(`Invalid system agent tool name: ${name}.`);
+    }
+}
+export function defineAgentTool(metadata) {
+    assertName(metadata.name);
+    if (!metadata.description.trim())
+        throw new Error("Tool description is required.");
+    const inputSchema = metadata.inputSchema ?? emptyInputSchema;
+    if (inputSchema.type !== "object") {
+        throw new Error("Tool inputSchema root type must be object.");
+    }
+    return freezeAgentToolDefinition({
+        ...metadata,
+        inputSchema,
+    });
+}
+export function defineSystemAgentTool(metadata) {
+    assertSystemName(metadata.name);
+    if (!metadata.description.trim()) {
+        throw new Error("Tool description is required.");
+    }
+    if (metadata.inputSchema.type !== "object") {
+        throw new Error("Tool inputSchema root type must be object.");
+    }
+    return freezeAgentToolDefinition(metadata);
+}
+function cloneAndFreeze(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map(cloneAndFreeze));
+    }
+    if (value && typeof value === "object") {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            cloneAndFreeze(item),
+        ])));
+    }
+    return value;
+}
+function freezeAgentToolDefinition(definition) {
+    return Object.freeze({
+        name: definition.name,
+        description: definition.description,
+        inputSchema: cloneAndFreeze(definition.inputSchema),
+    });
+}
+//# sourceMappingURL=definition.js.map

package/dist/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../src/definition.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { defineAgentTool } from "./definition.js";
+export { createToolRuntime, isToolRuntimeError, } from "./runtime.js";
+export { AgentContext, AgentToolsProvider, AgentUIAction, useAgentContext, useAgentTool, } from "./react.js";
+export type { AgentUIActionChildProps, AgentUIActionEvent, AgentUIActionProps, } from "./react.js";
+export type { ToolRuntime, ToolRuntimeOptions, } from "./runtime.js";
+export type { BrowserToolsConfig, BrowserToolsOptions, } from "./browser/toolset.js";
+export type { AgentContextEntry, AgentContextValue, AgentToolDefinition, AgentToolExecutionContext, AgentToolExecutor, AgentToolInputSchema, InferJsonSchema, JsonSchema, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { defineAgentTool } from "./definition.js";
+export { createToolRuntime, isToolRuntimeError, } from "./runtime.js";
+export { AgentContext, AgentToolsProvider, AgentUIAction, useAgentContext, useAgentTool, } from "./react.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/internal-react.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+import { type ToolRuntime, type InternalToolRuntime } from "./runtime.js";
+export interface InternalToolRuntimeHostProps {
+    children: ReactNode;
+}
+export declare function InternalToolRuntimeHost({ children, }: InternalToolRuntimeHostProps): import("react").JSX.Element;
+export declare function InternalToolRuntimeScope({ children, runtime, }: {
+    children: ReactNode;
+    runtime: ToolRuntime;
+}): import("react").JSX.Element;
+export declare function useInternalToolRuntime(): InternalToolRuntime;
+export declare function useOptionalInternalToolRuntime(): InternalToolRuntime | null;

package/dist/internal-react.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, } from "react";
+import { createToolRuntime, getInternalToolRuntime, } from "./runtime.js";
+const InternalToolRuntimeContext = createContext(null);
+export function InternalToolRuntimeHost({ children, }) {
+    const runtime = useMemo(() => createToolRuntime(), []);
+    return (_jsx(InternalToolRuntimeScope, { runtime: runtime, children: children }));
+}
+export function InternalToolRuntimeScope({ children, runtime, }) {
+    const internalRuntime = getInternalToolRuntime(runtime);
+    return (_jsx(InternalToolRuntimeContext.Provider, { value: internalRuntime, children: children }));
+}
+export function useInternalToolRuntime() {
+    const runtime = useContext(InternalToolRuntimeContext);
+    if (!runtime) {
+        throw new Error("Nexface components must be rendered inside AgentToolsProvider, AgentProvider, or ChatProvider.");
+    }
+    return runtime;
+}
+export function useOptionalInternalToolRuntime() {
+    return useContext(InternalToolRuntimeContext);
+}
+//# sourceMappingURL=internal-react.js.map

package/dist/internal-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-react.js","sourceRoot":"","sources":["../src/internal-react.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,aAAa,EACb,UAAU,EACV,OAAO,GAER,MAAM,OAAO,CAAC;AAEf,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GAGvB,MAAM,cAAc,CAAC;AAEtB,MAAM,0BAA0B,GAC9B,aAAa,CAA6B,IAAI,CAAC,CAAC;AAMlD,MAAM,UAAU,uBAAuB,CAAC,EACtC,QAAQ,GACqB;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,iBAAiB,EAAE,EAAE,EAAE,CAAC,CAAC;IACvD,OAAO,CACL,KAAC,wBAAwB,IAAC,OAAO,EAAE,OAAO,YACvC,QAAQ,GACgB,CAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,EACvC,QAAQ,EACR,OAAO,GAIR;IACC,MAAM,eAAe,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACxD,OAAO,CACL,KAAC,0BAA0B,CAAC,QAAQ,IAAC,KAAK,EAAE,eAAe,YACxD,QAAQ,GAC2B,CACvC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,MAAM,OAAO,GAAG,UAAU,CAAC,0BAA0B,CAAC,CAAC;IACvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,8BAA8B;IAG5C,OAAO,UAAU,CAAC,0BAA0B,CAAC,CAAC;AAChD,CAAC"}

package/dist/internal-types.d.ts

@@ -0,0 +1,11 @@
+export type AgentToolExecutionStatus = "running" | "success" | "error";
+export interface AgentToolExecutionEvent {
+    id: string;
+    name: string;
+    status: AgentToolExecutionStatus;
+    startedAt: number;
+    finishedAt?: number;
+    input: unknown;
+    result?: unknown;
+    error?: unknown;
+}

package/dist/internal-types.js

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

package/dist/internal-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-types.js","sourceRoot":"","sources":["../src/internal-types.ts"],"names":[],"mappings":""}

package/dist/internal.d.ts

@@ -0,0 +1,9 @@
+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/dist/internal.js

@@ -0,0 +1,5 @@
+export { AgentContextError, ToolRuntimeImplementation, ToolRuntimeImplementation as ToolRuntime, AgentToolError, createToolRuntime, getInternalToolRuntime, } from "./runtime.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";
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,yBAAyB,IAAI,WAAW,EACxC,cAAc,EACd,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,25 @@
+import { type MouseEvent, type ReactElement, type ReactNode } from "react";
+import type { ToolRuntime } from "./runtime.js";
+import type { AgentContextEntry, AgentToolDefinition, AgentToolExecutor } from "./types.js";
+export declare function useAgentTool<TInput, TResult>(definition: AgentToolDefinition<TInput, TResult>, execute: AgentToolExecutor<TInput, TResult>): void;
+export declare function AgentToolsProvider({ children, toolRuntime, webMcp, }: {
+    children: ReactNode;
+    toolRuntime: ToolRuntime;
+    webMcp?: boolean;
+}): import("react").JSX.Element;
+export declare function useAgentContext(context: AgentContextEntry): void;
+export declare function AgentContext(context: AgentContextEntry): null;
+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>>;
+}
+export declare function AgentUIAction<TResult = void>({ name, description, event, children, }: AgentUIActionProps<TResult>): ReactElement<AgentUIActionChildProps<TResult>, string | import("react").JSXElementConstructor<any>>;
+export type { AgentContextValue, AgentToolDefinition, AgentToolExecutor, } from "./types.js";