@tangleai/agents 0.21.1 → 0.25.0

package/src/toolbox.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The toolbox: a registry of tools an AI may call, each declared with
  * a JSON Schema `inputSchema` that Jaren itself compiles and enforces
@@ -16,163 +15,130 @@
  * JSON-encoded text for a structured property — results the calling
  * model can read and recover from.
  */
-
 import { JarenValidator } from '@jarenjs/validate';
 import { registerWebMcp } from '@jarenjs/contract/webmcp';
-
 import { checkOutcome } from '@jarenjs/core/check';
 import { invalidInput } from '@tangleai/models/check';
-
 /** Whether a property schema asks for structure (object or array). */
 function wantsStructure(schema) {
-  const type = schema?.type;
-  return type === 'object' || type === 'array'
-    || (Array.isArray(type) && (type.includes('object') || type.includes('array')));
+    const type = schema?.type;
+    return type === 'object' || type === 'array'
+        || (Array.isArray(type) && (type.includes('object') || type.includes('array')));
 }
-
 /**
  * The top-level properties that wanted structure but arrived as
  * strings — after coercion failed, these are what went wrong.
- * @param {any} inputSchema
- * @param {any} input
- * @returns {string[]}
  */
 function stringStructureKeys(inputSchema, input) {
-  const properties = inputSchema?.properties;
-  if (properties == null || input === null || typeof input !== 'object') return [];
-  return Object.entries(properties)
-    .filter(([key, schema]) => wantsStructure(schema) && typeof input[key] === 'string')
-    .map(([key]) => key);
+    const properties = inputSchema?.properties;
+    if (properties == null || input === null || typeof input !== 'object')
+        return [];
+    return Object.entries(properties)
+        .filter(([key, schema]) => wantsStructure(schema) && typeof input[key] === 'string')
+        .map(([key]) => key);
 }
-
 /**
  * A copy of `input` with string-valued top-level properties parsed as
  * JSON wherever the schema wants an object or array — or `null` when
  * nothing was coercible.
- * @param {any} inputSchema
- * @param {any} input
- * @returns {any | null}
  */
 function coerceStringArguments(inputSchema, input) {
-  const properties = inputSchema?.properties;
-  if (properties == null || input === null || typeof input !== 'object') return null;
-  let coerced = null;
-  for (const [key, schema] of Object.entries(properties)) {
-    if (!wantsStructure(schema) || typeof input[key] !== 'string') continue;
-    try {
-      const parsed = JSON.parse(input[key]);
-      if (parsed !== null && typeof parsed === 'object') {
-        if (coerced === null) coerced = { ...input };
-        coerced[key] = parsed;
-      }
+    const properties = inputSchema?.properties;
+    if (properties == null || input === null || typeof input !== 'object')
+        return null;
+    let coerced = null;
+    for (const [key, schema] of Object.entries(properties)) {
+        if (!wantsStructure(schema) || typeof input[key] !== 'string')
+            continue;
+        try {
+            const parsed = JSON.parse(input[key]);
+            if (parsed !== null && typeof parsed === 'object') {
+                if (coerced === null)
+                    coerced = { ...input };
+                coerced[key] = parsed;
+            }
+        }
+        catch {
+            // not JSON text: keep the original so validation reports it
+        }
     }
-    catch {
-      // not JSON text: keep the original so validation reports it
-    }
-  }
-  return coerced;
+    return coerced;
 }
-
-/**
- * @typedef {Object} ToolDef
- * @property {string} name
- * @property {string} description
- * @property {any} inputSchema - JSON Schema for the arguments object
- * @property {(input: any) => any} execute - may return a value or a promise
- */
-
 /**
- * @param {{ validator?: any }} [options] - a shared JarenValidator, if
+ * @param [options] - a shared JarenValidator, if
  *   the host already has one
- * @returns {{
- *   add: (def: ToolDef) => void,
- *   list: () => { name: string, description: string, inputSchema: any }[],
- *   toFunctionTools: () => any[],
- *   execute: (name: string, args: any) => any,
- * }}
  */
 export function createToolbox(options = {}) {
-  const jaren = options.validator ?? new JarenValidator({ skipErrors: false, collectErrors: true });
-  /** @type {Map<string, ToolDef & { check: (input: any) => any }>} */
-  const tools = new Map();
-
-  /** @param {ToolDef} def */
-  function add(def) {
-    tools.set(def.name, { ...def, check: jaren.compile(def.inputSchema) });
-  }
-
-  function list() {
-    return [...tools.values()].map(({ name, description, inputSchema }) =>
-      ({ name, description, inputSchema }));
-  }
-
-  function toFunctionTools() {
-    return [...tools.values()].map(({ name, description, inputSchema }) => ({
-      type: 'function',
-      function: { name, description, parameters: inputSchema },
-    }));
-  }
-
-  /**
-   * Dispatch one call. Synchronous tools answer synchronously (WebMCP
-   * hosts call `execute` directly); a promise-returning tool resolves
-   * to its value with rejections folded into `{ error }`. A rejected
-   * call answers `{ error, errors, inputSchema }` — the first
-   * `MAX_INPUT_ERRORS` validation errors plus the schema to re-read —
-   * with a `hint` added when a property wanting structure arrived as
-   * unparseable JSON text.
-   * @param {string} name
-   * @param {any} args
-   */
-  function execute(name, args) {
-    const tool = tools.get(name);
-    if (tool === undefined) return { error: `unknown tool '${name}'` };
-    let input = args ?? {};
-    let outcome = checkOutcome(tool.check(input));
-    if (!outcome.valid) {
-      // models routinely JSON-encode nested arguments; when a property
-      // wanted structure but arrived as parseable JSON text, validate
-      // the parsed value instead — valid or not, its errors point into
-      // the structure the model meant to send
-      const coerced = coerceStringArguments(tool.inputSchema, input);
-      if (coerced !== null) {
-        input = coerced;
-        outcome = checkOutcome(tool.check(coerced));
-      }
+    const jaren = options.validator ?? new JarenValidator({ skipErrors: false, collectErrors: true });
+    const tools = new Map();
+    /** @param def */
+    function add(def) {
+        tools.set(def.name, { ...def, check: jaren.compile(def.inputSchema) });
     }
-    if (!outcome.valid) {
-      const stringly = stringStructureKeys(tool.inputSchema, input);
-      return invalidInput(name, outcome, tool.inputSchema,
-        stringly.length === 0 ? {} : {
-          hint: `${stringly.map((k) => `'${k}'`).join(', ')} arrived as a JSON-encoded string that does not parse — pass a real JSON value, not quoted JSON text`,
-        });
+    function list() {
+        return [...tools.values()].map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
     }
-    try {
-      const value = tool.execute(input);
-      return typeof value?.then === 'function'
-        ? value.then((resolved) => resolved, (/** @type {any} */ err) =>
-          ({ error: err?.message ?? String(err) }))
-        : value;
+    function toFunctionTools() {
+        return [...tools.values()].map(({ name, description, inputSchema }) => ({
+            type: 'function',
+            function: { name, description, parameters: inputSchema },
+        }));
     }
-    catch (err) {
-      return { error: /** @type {any} */ (err)?.message ?? String(err) };
+    /**
+     * Dispatch one call. Synchronous tools answer synchronously (WebMCP
+     * hosts call `execute` directly); a promise-returning tool resolves
+     * to its value with rejections folded into `{ error }`. A rejected
+     * call answers `{ error, errors, inputSchema }` — the first
+     * `MAX_INPUT_ERRORS` validation errors plus the schema to re-read —
+     * with a `hint` added when a property wanting structure arrived as
+     * unparseable JSON text.
+     */
+    function execute(name, args) {
+        const tool = tools.get(name);
+        if (tool === undefined)
+            return { error: `unknown tool '${name}'` };
+        let input = args ?? {};
+        let outcome = checkOutcome(tool.check(input));
+        if (!outcome.valid) {
+            // models routinely JSON-encode nested arguments; when a property
+            // wanted structure but arrived as parseable JSON text, validate
+            // the parsed value instead — valid or not, its errors point into
+            // the structure the model meant to send
+            const coerced = coerceStringArguments(tool.inputSchema, input);
+            if (coerced !== null) {
+                input = coerced;
+                outcome = checkOutcome(tool.check(coerced));
+            }
+        }
+        if (!outcome.valid) {
+            const stringly = stringStructureKeys(tool.inputSchema, input);
+            return invalidInput(name, outcome, tool.inputSchema, stringly.length === 0 ? {} : {
+                hint: `${stringly.map((k) => `'${k}'`).join(', ')} arrived as a JSON-encoded string that does not parse — pass a real JSON value, not quoted JSON text`,
+            });
+        }
+        try {
+            const value = tool.execute(input);
+            return typeof value?.then === 'function'
+                ? value.then((resolved) => resolved, (err) => ({ error: err?.message ?? String(err) }))
+                : value;
+        }
+        catch (err) {
+            return { error: err?.message ?? String(err) };
+        }
     }
-  }
-
-  return { add, list, toFunctionTools, execute };
+    return { add, list, toFunctionTools, execute };
 }
-
 /**
  * Publish validated tools through the shared browser adapter. Await `ready`
  * for completion and call `dispose` when the host leaves. The optional context
  * remains the second argument; undefined requests automatic discovery.
- * @param {ReturnType<typeof createToolbox>} toolbox
- * @param {unknown} [modelContext]
- * @param {(error: unknown) => void} [onError]
- * @param {Omit<import('@jarenjs/contract/webmcp').WebMcpOptions, 'context'|'onError'>} [options]
+ * @param [modelContext]
+ * @param [onError]
+ * @param [options]
  */
 export function registerModelContext(toolbox, modelContext, onError, options = {}) {
-  return registerWebMcp(toolbox.list().map(def => ({ ...def,
-    execute: (args) => toolbox.execute(def.name, args),
-  })), { ...options, ...(modelContext === undefined ? {} : { context: modelContext }), onError });
+    return registerWebMcp(toolbox.list().map(def => ({
+        ...def,
+        execute: (args) => toolbox.execute(def.name, args),
+    })), { ...options, ...(modelContext === undefined ? {} : { context: modelContext }), onError });
 }