@nexface/tools 0.1.0

package/src/runtime.ts

@@ -0,0 +1,722 @@
+import { isValidAgentContextName } from "./definition.js";
+import { validateAgentToolInput } from "./schema.js";
+import type {
+  AgentContextEntry,
+  AgentContextInput,
+  AgentContextRegistration,
+  AgentToolDefinition,
+  AgentToolExecutor,
+} from "./types.js";
+import type { AgentToolExecutionEvent } from "./internal-types.js";
+import {
+  createBrowserToolset,
+  type BrowserToolsConfig,
+  type BrowserToolset,
+} from "./browser/toolset.js";
+
+export interface ToolRuntimeOptions {
+  readonly browserTools?: BrowserToolsConfig;
+}
+
+const CONTEXT_ERROR_CODES = [
+  "CONTEXT_DISPOSED",
+  "CONTEXT_NAME_MISMATCH",
+  "DUPLICATE_CONTEXT",
+  "INVALID_CONTEXT",
+] as const;
+
+const TOOL_ERROR_CODES = [
+  "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",
+  "TOOL_CANCELLED",
+  "TOOL_REGISTRATION_TIMEOUT",
+  "TOOL_SKIPPED",
+  "TOOL_UNAVAILABLE",
+  "UNKNOWN_TOOL",
+] as const;
+
+type AgentContextErrorCode = typeof CONTEXT_ERROR_CODES[number];
+type AgentToolErrorCode = typeof TOOL_ERROR_CODES[number];
+
+const CONTEXT_ERROR_CODE_SET = new Set<string>(CONTEXT_ERROR_CODES);
+const TOOL_ERROR_CODE_SET = new Set<string>(TOOL_ERROR_CODES);
+
+export function isToolRuntimeError(error: unknown): error is {
+  readonly type: "tool_runtime_error";
+  readonly domain: "tool" | "context";
+  readonly code: string;
+  readonly message: string;
+  readonly details?: unknown;
+} {
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as Record<string, unknown>;
+  if (
+    candidate.type !== "tool_runtime_error"
+    || typeof candidate.message !== "string"
+    || typeof candidate.code !== "string"
+  ) {
+    return false;
+  }
+  if (candidate.domain === "tool") {
+    return TOOL_ERROR_CODE_SET.has(candidate.code);
+  }
+  if (candidate.domain === "context") {
+    return CONTEXT_ERROR_CODE_SET.has(candidate.code);
+  }
+  return false;
+}
+
+declare const toolRuntimeBrand: unique symbol;
+
+export interface ToolRuntime {
+  readonly [toolRuntimeBrand]: true;
+
+  getTools(): readonly AgentToolDefinition[];
+  getContexts(options?: {
+    signal?: AbortSignal;
+  }): Promise<readonly AgentContextEntry[]>;
+  execute<TInput, TResult>(
+    definition: AgentToolDefinition<TInput, TResult>,
+    input: TInput,
+    options?: { signal?: AbortSignal },
+  ): Promise<TResult>;
+}
+
+type RuntimeBinding = {
+  definition: AgentToolDefinition<any, any>;
+  execute: AgentToolExecutor<any, any>;
+};
+
+function copyBrowserToolsConfig(
+  config: BrowserToolsConfig | undefined,
+): BrowserToolsConfig {
+  if (config === undefined) return false;
+  if (typeof config === "boolean") return config;
+  return {
+    ...config,
+    ...(config.limits ? { limits: { ...config.limits } } : {}),
+    ...(config.snapshotLimits
+      ? { snapshotLimits: { ...config.snapshotLimits } }
+      : {}),
+  };
+}
+
+function compareStrings(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function assertContextName(name: string): void {
+  if (!isValidAgentContextName(name)) {
+    throw new AgentContextError(
+      "INVALID_CONTEXT",
+      `Invalid or reserved context name: ${name}.`,
+    );
+  }
+}
+
+function normalizeContextValue(
+  value: unknown,
+  path = "value",
+  seen = new WeakSet<object>(),
+): AgentContextEntry["value"] {
+  if (
+    value === null
+    || typeof value === "string"
+    || typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new AgentContextError(
+        "INVALID_CONTEXT",
+        `${path} must contain only finite numbers.`,
+      );
+    }
+    return value;
+  }
+  if (!value || typeof value !== "object") {
+    throw new AgentContextError(
+      "INVALID_CONTEXT",
+      `${path} must be JSON serializable.`,
+    );
+  }
+  if (seen.has(value)) {
+    throw new AgentContextError(
+      "INVALID_CONTEXT",
+      `${path} contains a circular reference.`,
+    );
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item, index) =>
+        normalizeContextValue(item, `${path}[${index}]`, seen));
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new AgentContextError(
+        "INVALID_CONTEXT",
+        `${path} must contain only plain objects.`,
+      );
+    }
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort(compareStrings)
+        .map((key) => [
+          key,
+          normalizeContextValue(
+            (value as Record<string, unknown>)[key],
+            `${path}.${key}`,
+            seen,
+          ),
+        ]),
+    );
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function normalizeContext(context: AgentContextInput): AgentContextEntry {
+  assertContextName(context.name);
+  if (!context.description.trim()) {
+    throw new AgentContextError(
+      "INVALID_CONTEXT",
+      "Context description is required.",
+    );
+  }
+  return {
+    name: context.name,
+    description: context.description,
+    value: normalizeContextValue(context.value),
+  };
+}
+
+class DetailEvent<T> extends Event {
+  constructor(type: string, readonly detail: T) {
+    super(type);
+  }
+}
+
+export class AgentToolError extends Error {
+  readonly type = "tool_runtime_error" as const;
+  readonly domain = "tool" as const;
+
+  constructor(
+    readonly code: AgentToolErrorCode,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "ToolRuntimeError";
+  }
+}
+
+export class AgentContextError extends Error {
+  readonly type = "tool_runtime_error" as const;
+  readonly domain = "context" as const;
+
+  constructor(
+    readonly code: AgentContextErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ToolRuntimeError";
+  }
+}
+
+export interface InternalToolRuntime extends ToolRuntime, EventTarget {
+  register<TInput, TResult>(
+    definition: AgentToolDefinition<TInput, TResult>,
+    execute: AgentToolExecutor<TInput, TResult>,
+    options?: { signal?: AbortSignal },
+  ): () => void;
+  registerContext(
+    input: AgentContextInput,
+    options?: { signal?: AbortSignal },
+  ): AgentContextRegistration;
+  getApplicationTools(): readonly AgentToolDefinition[];
+  isRegistered(name: string): boolean;
+  executeApplicationTool(
+    name: string,
+    input: unknown,
+    options?: {
+      signal?: AbortSignal;
+      expectedDefinition?: AgentToolDefinition;
+    },
+  ): Promise<unknown>;
+  waitForTool(
+    definition: AgentToolDefinition<any, any>,
+    options?: { signal?: AbortSignal; timeoutMs?: number },
+  ): Promise<void>;
+  getContextRevision(): number;
+  getContextsNow(): readonly AgentContextEntry[];
+}
+
+const runtimeInternals = new WeakMap<
+  ToolRuntime,
+  ToolRuntimeImplementation
+>();
+
+export function createToolRuntime(
+  options: ToolRuntimeOptions = {},
+): ToolRuntime {
+  return new ToolRuntimeImplementation(options);
+}
+
+export function getInternalToolRuntime(
+  runtime: ToolRuntime,
+): InternalToolRuntime {
+  const internal = runtimeInternals.get(runtime);
+  if (!internal) {
+    throw new AgentToolError(
+      "INVALID_TOOL_RUNTIME",
+      "ToolRuntime must be created by createToolRuntime().",
+    );
+  }
+  return internal;
+}
+
+export class ToolRuntimeImplementation
+  extends EventTarget
+  implements ToolRuntime, InternalToolRuntime
+{
+  declare readonly [toolRuntimeBrand]: true;
+
+  readonly #browserToolsConfig: BrowserToolsConfig;
+  readonly #bindings = new Map<string, RuntimeBinding>();
+  readonly #contexts = new Map<string, AgentContextEntry>();
+  #contextRevision = 0;
+  #browserToolset: BrowserToolset | undefined;
+  #executionTail: Promise<void> | undefined;
+
+  constructor(options: ToolRuntimeOptions = {}) {
+    super();
+    this.#browserToolsConfig = copyBrowserToolsConfig(options.browserTools);
+    runtimeInternals.set(this, this);
+  }
+
+  register<TInput, TResult>(
+    definition: AgentToolDefinition<TInput, TResult>,
+    execute: AgentToolExecutor<TInput, TResult>,
+    options: { signal?: AbortSignal } = {},
+  ): () => void {
+    if (this.#bindings.has(definition.name)) {
+      throw new AgentToolError(
+        "DUPLICATE_BINDING",
+        `Tool "${definition.name}" already has an active binding.`,
+      );
+    }
+    const binding: RuntimeBinding = { definition, execute };
+    this.#bindings.set(definition.name, binding);
+    this.dispatchEvent(
+      new DetailEvent("toolchange", {
+        name: definition.name,
+        registered: true,
+      }),
+    );
+
+    let disposed = false;
+    const dispose = () => {
+      if (disposed || this.#bindings.get(definition.name) !== binding) return;
+      disposed = true;
+      options.signal?.removeEventListener("abort", dispose);
+      this.#bindings.delete(definition.name);
+      this.dispatchEvent(
+        new DetailEvent("toolchange", {
+          name: definition.name,
+          registered: false,
+        }),
+      );
+    };
+    if (options.signal?.aborted) dispose();
+    else options.signal?.addEventListener("abort", dispose, { once: true });
+    return dispose;
+  }
+
+  registerContext(
+    input: AgentContextInput,
+    options: { signal?: AbortSignal } = {},
+  ): AgentContextRegistration {
+    const initial = normalizeContext(input);
+    if (this.#contexts.has(initial.name)) {
+      throw new AgentContextError(
+        "DUPLICATE_CONTEXT",
+        `Context "${initial.name}" already has an active registration.`,
+      );
+    }
+    this.#contexts.set(initial.name, initial);
+    this.#notifyContextChange(initial.name, "registered");
+
+    let disposed = false;
+    const dispose = () => {
+      if (disposed) return;
+      disposed = true;
+      options.signal?.removeEventListener("abort", dispose);
+      if (this.#contexts.delete(initial.name)) {
+        this.#notifyContextChange(initial.name, "disposed");
+      }
+    };
+    const update = (nextInput: AgentContextInput) => {
+      if (disposed) {
+        throw new AgentContextError(
+          "CONTEXT_DISPOSED",
+          `Context "${initial.name}" registration has been disposed.`,
+        );
+      }
+      const next = normalizeContext(nextInput);
+      if (next.name !== initial.name) {
+        throw new AgentContextError(
+          "CONTEXT_NAME_MISMATCH",
+          `Context registration "${initial.name}" cannot be updated to "${next.name}".`,
+        );
+      }
+      if (JSON.stringify(this.#contexts.get(initial.name)) === JSON.stringify(next)) return;
+      this.#contexts.set(initial.name, next);
+      this.#notifyContextChange(initial.name, "updated");
+    };
+    if (options.signal?.aborted) dispose();
+    else options.signal?.addEventListener("abort", dispose, { once: true });
+    return { update, dispose };
+  }
+
+  getContextsNow(): readonly AgentContextEntry[] {
+    return [...this.#contexts.values()]
+      .sort((left, right) => compareStrings(left.name, right.name))
+      .map(normalizeContext);
+  }
+
+  getContextRevision(): number {
+    return this.#contextRevision;
+  }
+
+  async getContexts(
+    options: { signal?: AbortSignal } = {},
+  ): Promise<readonly AgentContextEntry[]> {
+    options.signal?.throwIfAborted();
+    await Promise.resolve();
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      let frameId: number | undefined;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const cleanup = () => {
+        options.signal?.removeEventListener("abort", onAbort);
+        if (frameId !== undefined && typeof cancelAnimationFrame === "function") {
+          cancelAnimationFrame(frameId);
+        }
+        if (timeoutId !== undefined) clearTimeout(timeoutId);
+      };
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const onAbort = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(options.signal?.reason);
+      };
+      const afterTask = () => {
+        timeoutId = undefined;
+        if (typeof requestAnimationFrame !== "function") {
+          settle();
+          return;
+        }
+        frameId = requestAnimationFrame(settle);
+        timeoutId = setTimeout(settle, 50);
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (options.signal?.aborted) {
+        onAbort();
+        return;
+      }
+      timeoutId = setTimeout(afterTask, 0);
+    });
+    await Promise.resolve();
+    options.signal?.throwIfAborted();
+    return this.getContextsNow();
+  }
+
+  #notifyContextChange(
+    name: string,
+    change: "registered" | "updated" | "disposed",
+  ): void {
+    this.#contextRevision += 1;
+    this.dispatchEvent(new DetailEvent("contextchange", {
+      name,
+      change,
+      revision: this.#contextRevision,
+    }));
+  }
+
+  getApplicationTools(): readonly AgentToolDefinition[] {
+    return [...this.#bindings.values()]
+      .map(({ definition }) => definition)
+      .sort((left, right) => compareStrings(left.name, right.name));
+  }
+
+  isRegistered(name: string): boolean {
+    return this.#bindings.has(name);
+  }
+
+  getTools(): readonly AgentToolDefinition[] {
+    const browserTools = this.#getBrowserToolset()?.definitions ?? [];
+    return [...this.getApplicationTools(), ...browserTools]
+      .sort((left, right) => compareStrings(left.name, right.name));
+  }
+
+  waitForTool(
+    definition: AgentToolDefinition<any, any>,
+    options: { signal?: AbortSignal; timeoutMs?: number } = {},
+  ): Promise<void> {
+    const isTargetRegistered = () => this.#bindings.has(definition.name);
+    if (isTargetRegistered()) return Promise.resolve();
+    const timeoutMs = Math.max(1, options.timeoutMs ?? 5_000);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => {
+        this.removeEventListener("toolchange", onToolChange);
+        options.signal?.removeEventListener("abort", onAbort);
+        clearTimeout(timeoutId);
+      };
+      const settle = (callback: () => void) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        callback();
+      };
+      const onToolChange = (event: Event) => {
+        const detail = (event as Event & {
+          detail?: { name?: string; registered?: boolean };
+        }).detail;
+        if (detail?.name !== definition.name || !detail.registered) return;
+        if (isTargetRegistered()) settle(resolve);
+      };
+      const onAbort = () => settle(() => reject(options.signal?.reason));
+      const timeoutId = setTimeout(() => {
+        settle(() =>
+          reject(
+            new AgentToolError(
+              "TOOL_REGISTRATION_TIMEOUT",
+              `Tool "${definition.name}" did not register within ${timeoutMs}ms.`,
+              {
+                toolName: definition.name,
+                timeoutMs,
+                retryable: false,
+                browserFallbackAllowed: true,
+                toolExecuted: false,
+              },
+            ),
+          ));
+      }, timeoutMs);
+      this.addEventListener("toolchange", onToolChange);
+      if (options.signal?.aborted) onAbort();
+      else options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (isTargetRegistered()) settle(resolve);
+    });
+  }
+
+  execute<TInput, TResult>(
+    definition: AgentToolDefinition<TInput, TResult>,
+    input: TInput,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<TResult> {
+    const name = definition.name;
+    const binding = this.#bindings.get(name);
+    if (binding) {
+      if (binding.definition !== definition) {
+        return Promise.reject(
+          new AgentToolError(
+            "CONTRACT_MISMATCH",
+            `Tool "${name}" is registered with a different Definition.`,
+          ),
+        );
+      }
+      return this.#enqueue(
+        () => this.#executeApplication(name, input, options, binding),
+        options.signal,
+      ) as Promise<TResult>;
+    }
+    try {
+      const browserToolset = this.#getBrowserToolset();
+      const browserHandler = browserToolset?.handlers.get(name);
+      if (!browserHandler) {
+        return Promise.reject(
+          new AgentToolError("UNKNOWN_TOOL", `Unknown tool: ${name}.`),
+        );
+      }
+      if (
+        !browserToolset?.definitions.some(
+          (candidate) => candidate === definition,
+        )
+      ) {
+        return Promise.reject(
+          new AgentToolError(
+            "CONTRACT_MISMATCH",
+            `Tool "${name}" is registered with a different Definition.`,
+          ),
+        );
+      }
+      return this.#enqueue(async () => {
+        const signal = options.signal ?? new AbortController().signal;
+        signal.throwIfAborted();
+        return browserHandler.execute(input as Record<string, unknown>, {
+          signal,
+        });
+      }, options.signal) as Promise<TResult>;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+
+  executeApplicationTool(
+    name: string,
+    input: unknown,
+    options: {
+      signal?: AbortSignal;
+      expectedDefinition?: AgentToolDefinition;
+    } = {},
+  ): Promise<unknown> {
+    const binding = this.#bindings.get(name);
+    if (!binding) {
+      return Promise.reject(
+        new AgentToolError("UNKNOWN_TOOL", `Unknown tool: ${name}.`),
+      );
+    }
+    return this.#enqueue(
+      () => {
+        const activeBinding = this.#bindings.get(name);
+        if (!activeBinding) {
+          throw new AgentToolError("UNKNOWN_TOOL", `Unknown tool: ${name}.`);
+        }
+        if (
+          options.expectedDefinition
+          && activeBinding.definition !== options.expectedDefinition
+        ) {
+          throw new AgentToolError(
+            "CONTRACT_MISMATCH",
+            `Tool "${name}" changed after the model request was sent.`,
+          );
+        }
+        return this.#executeApplication(name, input, options, activeBinding);
+      },
+      options.signal,
+    );
+  }
+
+  #enqueue<TResult>(
+    execute: () => Promise<TResult>,
+    signal?: AbortSignal,
+  ): Promise<TResult> {
+    const previous = this.#executionTail;
+    let removeQueuedAbort = () => {};
+    const queuedExecution = previous
+      ? previous.then(() => {
+          removeQueuedAbort();
+          signal?.throwIfAborted();
+          return execute();
+        })
+      : execute();
+    let execution = queuedExecution;
+    if (previous && signal) {
+      execution = new Promise((resolve, reject) => {
+        const onAbort = () => {
+          removeQueuedAbort();
+          reject(signal.reason);
+        };
+        removeQueuedAbort = () => signal.removeEventListener("abort", onAbort);
+        queuedExecution.then(resolve, reject);
+        if (signal.aborted) onAbort();
+        else signal.addEventListener("abort", onAbort, { once: true });
+      });
+    }
+    const tail = queuedExecution.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.#executionTail = tail;
+    void tail.then(() => {
+      if (this.#executionTail === tail) this.#executionTail = undefined;
+    });
+    return execution;
+  }
+
+  async #executeApplication(
+    name: string,
+    input: unknown,
+    options: { signal?: AbortSignal },
+    binding: RuntimeBinding,
+  ): Promise<unknown> {
+    const id = globalThis.crypto?.randomUUID?.()
+      ?? `${Date.now()}-${Math.random()}`;
+    const startedAt = Date.now();
+    const running: AgentToolExecutionEvent = {
+      id,
+      name,
+      status: "running",
+      startedAt,
+      input,
+    };
+    this.dispatchEvent(new DetailEvent("toolexecution", running));
+    try {
+      if (this.#bindings.get(name) !== binding) {
+        throw new AgentToolError(
+          "UNKNOWN_TOOL",
+          `Tool "${name}" is no longer registered for this call.`,
+        );
+      }
+      const errors = validateAgentToolInput(binding.definition.inputSchema, input);
+      if (errors.length) {
+        throw new AgentToolError("INVALID_INPUT", errors.join(" "), { errors });
+      }
+      const signal = options.signal ?? new AbortController().signal;
+      signal.throwIfAborted();
+      const result = await binding.execute(input, {
+        signal,
+        waitForTool: (definition, waitOptions = {}) =>
+          this.waitForTool(definition, { signal, ...waitOptions }),
+      });
+      signal.throwIfAborted();
+      this.dispatchEvent(
+        new DetailEvent("toolexecution", {
+          ...running,
+          status: "success",
+          finishedAt: Date.now(),
+          result,
+        } satisfies AgentToolExecutionEvent),
+      );
+      return result;
+    } catch (error) {
+      this.dispatchEvent(
+        new DetailEvent("toolexecution", {
+          ...running,
+          status: "error",
+          finishedAt: Date.now(),
+          error,
+        } satisfies AgentToolExecutionEvent),
+      );
+      throw error;
+    }
+  }
+
+  #getBrowserToolset(): BrowserToolset | undefined {
+    if (this.#browserToolsConfig === false) return undefined;
+    if (!this.#browserToolset) {
+      const options = this.#browserToolsConfig === true
+        ? {}
+        : this.#browserToolsConfig;
+      this.#browserToolset = createBrowserToolset(options);
+    }
+    return this.#browserToolset;
+  }
+}