@nexface/tools 0.1.0

package/src/schema.ts

@@ -0,0 +1,52 @@
+import type { JsonSchema } from "./types.js";
+
+function typeMatches(schema: JsonSchema, value: unknown): boolean {
+  switch (schema.type) {
+    case undefined:
+      return true;
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return value !== null && typeof value === "object" && !Array.isArray(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    default:
+      return typeof value === schema.type;
+  }
+}
+
+export function validateAgentToolInput(
+  schema: JsonSchema,
+  value: unknown,
+  path = "input",
+): string[] {
+  if (!typeMatches(schema, value)) {
+    return [`${path} must be ${schema.type}.`];
+  }
+  if (schema.enum && !schema.enum.some((item) => Object.is(item, value))) {
+    return [`${path} must be one of the declared enum values.`];
+  }
+  if (schema.type === "array" && Array.isArray(value) && schema.items) {
+    return value.flatMap((item, index) =>
+      validateAgentToolInput(schema.items!, item, `${path}[${index}]`),
+    );
+  }
+  if (schema.type !== "object" || value === null || typeof value !== "object") {
+    return [];
+  }
+  const record = value as Record<string, unknown>;
+  const errors: string[] = [];
+  for (const key of schema.required ?? []) {
+    if (!(key in record)) errors.push(`${path}.${key} is required.`);
+  }
+  for (const [key, item] of Object.entries(record)) {
+    const property = schema.properties?.[key];
+    if (property) errors.push(...validateAgentToolInput(property, item, `${path}.${key}`));
+    else if (schema.additionalProperties === false) {
+      errors.push(`${path}.${key} is not allowed.`);
+    }
+  }
+  return errors;
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+export type JsonSchema = {
+  type?: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: readonly string[];
+  items?: JsonSchema;
+  enum?: readonly unknown[];
+  additionalProperties?: boolean;
+};
+
+export type AgentToolInputSchema = JsonSchema & {
+  type: "object";
+};
+
+type Simplify<TValue> = { [TKey in keyof TValue]: TValue[TKey] };
+
+type RequiredPropertyKeys<
+  TSchema extends JsonSchema,
+  TProperties extends Record<string, JsonSchema>,
+> = TSchema extends { readonly required: readonly (infer TKey)[] }
+  ? Extract<TKey, keyof TProperties>
+  : never;
+
+type InferObjectSchema<
+  TSchema extends JsonSchema,
+  TProperties extends Record<string, JsonSchema>,
+> = keyof TProperties extends never
+  ? TSchema extends { readonly additionalProperties: false }
+    ? Record<string, never>
+    : Record<string, unknown>
+  : Simplify<{
+      [TKey in RequiredPropertyKeys<TSchema, TProperties>]-?: InferJsonSchema<
+        TProperties[TKey]
+      >;
+    } & {
+      [TKey in Exclude<
+        keyof TProperties,
+        RequiredPropertyKeys<TSchema, TProperties>
+      >]?: InferJsonSchema<TProperties[TKey]>;
+    }> & (TSchema extends { readonly additionalProperties: false }
+      ? unknown
+      : Record<string, unknown>);
+
+export type InferJsonSchema<TSchema extends JsonSchema> =
+  TSchema extends { readonly enum: readonly (infer TValue)[] }
+    ? TValue
+    : TSchema extends { readonly type: "string" }
+      ? string
+      : TSchema extends { readonly type: "number" | "integer" }
+        ? number
+        : TSchema extends { readonly type: "boolean" }
+          ? boolean
+          : TSchema extends { readonly type: "null" }
+            ? null
+            : TSchema extends {
+                  readonly type: "array";
+                  readonly items: infer TItem extends JsonSchema;
+                }
+              ? InferJsonSchema<TItem>[]
+              : TSchema extends { readonly type: "array" }
+                ? unknown[]
+                : TSchema extends {
+                      readonly type: "object";
+                      readonly properties: infer TProperties extends Record<
+                        string,
+                        JsonSchema
+                      >;
+                    }
+                  ? InferObjectSchema<TSchema, TProperties>
+                  : TSchema extends { readonly type: "object" }
+                    ? TSchema extends { readonly additionalProperties: false }
+                      ? Record<string, never>
+                      : Record<string, unknown>
+                    : unknown;
+
+export type AgentContextValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly AgentContextValue[]
+  | { readonly [key: string]: AgentContextValue };
+
+export interface AgentContextEntry {
+  name: string;
+  description: string;
+  value: AgentContextValue;
+}
+
+export type AgentContextInput = AgentContextEntry;
+
+export interface AgentContextRegistration {
+  update(context: AgentContextInput): void;
+  dispose(): void;
+}
+
+export interface AgentToolMetadata {
+  name: string;
+  description: string;
+  inputSchema: AgentToolInputSchema;
+}
+
+export interface AgentToolDefinition<
+  TInput = Record<string, unknown>,
+  TResult = unknown,
+>
+  extends AgentToolMetadata {
+  readonly __input?: TInput;
+  readonly __result?: TResult;
+}
+
+export interface AgentToolExecutionContext {
+  signal: AbortSignal;
+  waitForTool(
+    definition: AgentToolDefinition<any, any>,
+    options?: { timeoutMs?: number },
+  ): Promise<void>;
+}
+
+export type AgentToolExecutor<TInput, TResult> = (
+  input: TInput,
+  context: AgentToolExecutionContext,
+) => TResult | Promise<TResult>;

package/src/webmcp.ts

@@ -0,0 +1,102 @@
+import type { InternalToolRuntime } from "./runtime.js";
+import type { AgentToolDefinition } from "./types.js";
+
+interface WebMcpTool {
+  name: string;
+  description: string;
+  inputSchema: object;
+  execute(input: object): Promise<unknown>;
+}
+
+interface WebMcpModelContext {
+  addEventListener?(type: "toolchange", listener: EventListener): void;
+  removeEventListener?(type: "toolchange", listener: EventListener): void;
+  registerTool(
+    tool: WebMcpTool,
+    options?: { signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+type WebMcpRegistration = {
+  controller: AbortController;
+  definition: AgentToolDefinition;
+};
+
+function getWebMcpModelContext(): WebMcpModelContext | undefined {
+  if (typeof document === "undefined") return undefined;
+  const modelContext = (document as Document & {
+    modelContext?: Partial<WebMcpModelContext>;
+  }).modelContext;
+  return typeof modelContext?.registerTool === "function"
+    ? modelContext as WebMcpModelContext
+    : undefined;
+}
+
+function warnWebMcpRegistration(name: string, error: unknown): void {
+  console.warn(`Unable to register WebMCP Tool "${name}".`, error);
+}
+
+export function connectToolRuntimeToWebMcp(
+  runtime: InternalToolRuntime,
+): () => void {
+  const modelContext = getWebMcpModelContext();
+  if (!modelContext) return () => undefined;
+
+  const registrations = new Map<string, WebMcpRegistration>();
+  let disposed = false;
+
+  const register = (definition: AgentToolDefinition) => {
+    const controller = new AbortController();
+    const registration = { controller, definition };
+    registrations.set(definition.name, registration);
+    let result: Promise<void>;
+    try {
+      result = modelContext.registerTool({
+        name: definition.name,
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        execute: async (input) => runtime.execute(definition, input),
+      }, { signal: controller.signal });
+    } catch (error) {
+      registrations.delete(definition.name);
+      warnWebMcpRegistration(definition.name, error);
+      return;
+    }
+    Promise.resolve(result).catch((error: unknown) => {
+      if (controller.signal.aborted || disposed) return;
+      if (registrations.get(definition.name) === registration) {
+        registrations.delete(definition.name);
+      }
+      warnWebMcpRegistration(definition.name, error);
+    });
+  };
+
+  const reconcile = () => {
+    const definitions = new Map(
+      runtime.getApplicationTools().map((definition) => [definition.name, definition]),
+    );
+    for (const [name, registration] of registrations) {
+      if (definitions.get(name) === registration.definition) continue;
+      registration.controller.abort();
+      registrations.delete(name);
+    }
+    for (const definition of definitions.values()) {
+      if (!registrations.has(definition.name)) register(definition);
+    }
+  };
+
+  runtime.addEventListener("toolchange", reconcile);
+  modelContext.addEventListener?.("toolchange", reconcile);
+  reconcile();
+
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    runtime.removeEventListener("toolchange", reconcile);
+    modelContext.removeEventListener?.("toolchange", reconcile);
+    for (const registration of registrations.values()) {
+      registration.controller.abort();
+    }
+    registrations.clear();
+  };
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}