feat(toolbox-core): add bound params (#25)

* unclean working code

* fix client tests

* add utils test

* cleanup

* fix

* fix tests

* lint

* fix any type issues

* fix docstrings

* remove redundant check

* merge fix

* Rename private variables and methods

* use default bound params

Author: twishabansal

packages/toolbox-core/src/toolbox_core/client.ts

@@ -18,6 +18,7 @@ import {type AxiosInstance, type AxiosResponse} from 'axios';
 import {ZodManifestSchema, createZodSchemaFromParams} from './protocol.js';
 import {logApiError} from './errorUtils.js';
 import {ZodError} from 'zod';
+import {BoundParams, BoundValue} from './utils.js';
 
 type Manifest = import('zod').infer<typeof ZodManifestSchema>;
 type ToolSchemaFromManifest = Manifest['tools'][string];
@@ -27,8 +28,8 @@ type ToolSchemaFromManifest = Manifest['tools'][string];
  * Manages an Axios Client Session, if not provided.
  */
 class ToolboxClient {
-  private _baseUrl: string;
-  private _session: AxiosInstance;
+  #baseUrl: string;
+  #session: AxiosInstance;
 
   /**
    * Initializes the ToolboxClient.
@@ -37,21 +38,20 @@ class ToolboxClient {
    * requests. If not provided, a new one will be created.
    */
   constructor(url: string, session?: AxiosInstance) {
-    this._baseUrl = url;
-    this._session = session || axios.create({baseURL: this._baseUrl});
+    this.#baseUrl = url;
+    this.#session = session || axios.create({baseURL: this.#baseUrl});
   }
 
   /**
    * Fetches and parses the manifest from a given API path.
    * @param {string} apiPath - The API path to fetch the manifest from (e.g., "/api/tool/mytool").
    * @returns {Promise<Manifest>} A promise that resolves to the parsed manifest.
    * @throws {Error} If there's an error fetching data or if the manifest structure is invalid.
-   * @private
    */
-  private async _fetchAndParseManifest(apiPath: string): Promise<Manifest> {
-    const url = `${this._baseUrl}${apiPath}`;
+  async #fetchAndParseManifest(apiPath: string): Promise<Manifest> {
+    const url = `${this.#baseUrl}${apiPath}`;
     try {
-      const response: AxiosResponse = await this._session.get(url);
+      const response: AxiosResponse = await this.#session.get(url);
       const responseData = response.data;
 
       try {
@@ -85,21 +85,38 @@ class ToolboxClient {
    * Creates a ToolboxTool instance from its schema.
    * @param {string} toolName - The name of the tool.
    * @param {ToolSchemaFromManifest} toolSchema - The schema definition of the tool from the manifest.
+   * @param {BoundParams} [boundParams] - A map of all candidate parameters to bind.
    * @returns {ReturnType<typeof ToolboxTool>} A ToolboxTool function.
-   * @private
    */
-  private _createToolInstance(
+  #createToolInstance(
     toolName: string,
-    toolSchema: ToolSchemaFromManifest
-  ): ReturnType<typeof ToolboxTool> {
+    toolSchema: ToolSchemaFromManifest,
+    boundParams: BoundParams = {}
+  ): {
+    tool: ReturnType<typeof ToolboxTool>;
+    usedBoundKeys: Set<string>;
+  } {
+    const toolParamNames = new Set(toolSchema.parameters.map(p => p.name));
+    const applicableBoundParams: Record<string, BoundValue> = {};
+    const usedBoundKeys = new Set<string>();
+
+    for (const key in boundParams) {
+      if (toolParamNames.has(key)) {
+        applicableBoundParams[key] = boundParams[key];
+        usedBoundKeys.add(key);
+      }
+    }
+
     const paramZodSchema = createZodSchemaFromParams(toolSchema.parameters);
-    return ToolboxTool(
-      this._session,
-      this._baseUrl,
+    const tool = ToolboxTool(
+      this.#session,
+      this.#baseUrl,
       toolName,
       toolSchema.description,
-      paramZodSchema
+      paramZodSchema,
+      boundParams
     );
+    return {tool, usedBoundKeys};
   }
 
   /**
@@ -108,22 +125,42 @@ class ToolboxClient {
    * returns a callable (`ToolboxTool`) that can be used to invoke the
    * tool remotely.
    *
+   * @param {BoundParams} [boundParams] - Optional parameters to pre-bind to the tool.
    * @param {string} name - The unique name or identifier of the tool to load.
    * @returns {Promise<ReturnType<typeof ToolboxTool>>} A promise that resolves
    * to a ToolboxTool function, ready for execution.
    * @throws {Error} If the tool is not found in the manifest, the manifest structure is invalid,
    * or if there's an error fetching data from the API.
    */
-  async loadTool(name: string): Promise<ReturnType<typeof ToolboxTool>> {
+  async loadTool(
+    name: string,
+    boundParams: BoundParams = {}
+  ): Promise<ReturnType<typeof ToolboxTool>> {
     const apiPath = `/api/tool/${name}`;
-    const manifest = await this._fetchAndParseManifest(apiPath);
+    const manifest = await this.#fetchAndParseManifest(apiPath);
 
     if (
       manifest.tools && // Zod ensures manifest.tools exists if schema requires it
       Object.prototype.hasOwnProperty.call(manifest.tools, name)
     ) {
       const specificToolSchema = manifest.tools[name];
-      return this._createToolInstance(name, specificToolSchema);
+      const {tool, usedBoundKeys} = this.#createToolInstance(
+        name,
+        specificToolSchema,
+        boundParams
+      );
+
+      const providedBoundKeys = Object.keys(boundParams);
+      const unusedBound = providedBoundKeys.filter(
+        key => !usedBoundKeys.has(key)
+      );
+
+      if (unusedBound.length > 0) {
+        throw new Error(
+          `Validation failed for tool '${name}': unused bound parameters: ${unusedBound.join(', ')}.`
+        );
+      }
+      return tool;
     } else {
       throw new Error(`Tool "${name}" not found in manifest from ${apiPath}.`);
     }
@@ -133,21 +170,43 @@ class ToolboxClient {
    * Asynchronously fetches a toolset and loads all tools defined within it.
    *
    * @param {string | null} [name] - Name of the toolset to load. If null or undefined, loads the default toolset.
+   * @param {BoundParams} [boundParams] - Optional parameters to pre-bind to the tools in the toolset.
    * @returns {Promise<Array<ReturnType<typeof ToolboxTool>>>} A promise that resolves
    * to a list of ToolboxTool functions, ready for execution.
    * @throws {Error} If the manifest structure is invalid or if there's an error fetching data from the API.
    */
   async loadToolset(
-    name?: string
+    name?: string,
+    boundParams: BoundParams = {}
   ): Promise<Array<ReturnType<typeof ToolboxTool>>> {
     const toolsetName = name || '';
     const apiPath = `/api/toolset/${toolsetName}`;
-    const manifest = await this._fetchAndParseManifest(apiPath);
+
+    const manifest = await this.#fetchAndParseManifest(apiPath);
     const tools: Array<ReturnType<typeof ToolboxTool>> = [];
 
+    const providedBoundKeys = new Set(Object.keys(boundParams));
+    const overallUsedBoundParams: Set<string> = new Set();
+
     for (const [toolName, toolSchema] of Object.entries(manifest.tools)) {
-      const toolInstance = this._createToolInstance(toolName, toolSchema);
-      tools.push(toolInstance);
+      const {tool, usedBoundKeys} = this.#createToolInstance(
+        toolName,
+        toolSchema,
+        boundParams
+      );
+      tools.push(tool);
+      usedBoundKeys.forEach((key: string) => overallUsedBoundParams.add(key));
+    }
+
+    const unusedBound = [...providedBoundKeys].filter(
+      k => !overallUsedBoundParams.has(k)
+    );
+    if (unusedBound.length > 0) {
+      throw new Error(
+        `Validation failed for toolset '${
+          name || 'default'
+        }': unused bound parameters could not be applied to any tool: ${unusedBound.join(', ')}.`
+      );
     }
     return tools;
   }

packages/toolbox-core/src/toolbox_core/tool.ts

@@ -15,6 +15,7 @@
 import {ZodObject, ZodError, ZodRawShape} from 'zod';
 import {AxiosInstance, AxiosResponse} from 'axios';
 import {logApiError} from './errorUtils.js';
+import {BoundParams, BoundValue, resolveValue} from './utils.js';
 
 /**
  * Creates a callable tool function representing a specific tool on a remote
@@ -25,6 +26,7 @@ import {logApiError} from './errorUtils.js';
  * @param {string} name - The name of the remote tool.
  * @param {string} description - A description of the remote tool.
  * @param {ZodObject<any>} paramSchema - The Zod schema for validating the tool's parameters.
+ * @param {BoundParams} [boundParams] - Optional parameters to pre-bind to the tool.
  * @returns {CallableTool & CallableToolProperties} An async function that, when
  * called, invokes the tool with the provided arguments. Validates arguments
  * against the tool's signature, then sends them
@@ -36,16 +38,21 @@ function ToolboxTool(
   baseUrl: string,
   name: string,
   description: string,
-  paramSchema: ZodObject<ZodRawShape>
+  paramSchema: ZodObject<ZodRawShape>,
+  boundParams: BoundParams = {}
 ) {
   const toolUrl = `${baseUrl}/api/tool/${name}/invoke`;
+  const boundKeys = Object.keys(boundParams);
+  const userParamSchema = paramSchema.omit(
+    Object.fromEntries(boundKeys.map(k => [k, true]))
+  );
 
   const callable = async function (
     callArguments: Record<string, unknown> = {}
   ) {
-    let validatedPayload: Record<string, unknown>;
+    let validatedUserArgs: Record<string, unknown>;
     try {
-      validatedPayload = paramSchema.parse(callArguments);
+      validatedUserArgs = userParamSchema.parse(callArguments);
     } catch (error) {
       if (error instanceof ZodError) {
         const errorMessages = error.errors.map(
@@ -57,11 +64,18 @@ function ToolboxTool(
       }
       throw new Error(`Argument validation failed: ${String(error)}`);
     }
+
+    // Resolve any bound parameters that are functions.
+    const resolvedEntries = await Promise.all(
+      Object.entries(boundParams).map(async ([key, value]) => {
+        const resolved = await resolveValue(value);
+        return [key, resolved];
+      })
+    );
+    const resolvedBoundParams = Object.fromEntries(resolvedEntries);
+    const payload = {...validatedUserArgs, ...resolvedBoundParams};
     try {
-      const response: AxiosResponse = await session.post(
-        toolUrl,
-        validatedPayload
-      );
+      const response: AxiosResponse = await session.post(toolUrl, payload);
       return response.data;
     } catch (error) {
       logApiError(`Error posting data to ${toolUrl}:`, error);
@@ -71,6 +85,8 @@ function ToolboxTool(
   callable.toolName = name;
   callable.description = description;
   callable.params = paramSchema;
+  callable.boundParams = boundParams;
+
   callable.getName = function () {
     return this.toolName;
   };
@@ -80,6 +96,36 @@ function ToolboxTool(
   callable.getParamSchema = function () {
     return this.params;
   };
+
+  callable.bindParams = function (paramsToBind: BoundParams) {
+    const originalParamKeys = Object.keys(this.params.shape);
+    for (const paramName of Object.keys(paramsToBind)) {
+      if (paramName in this.boundParams) {
+        throw new Error(
+          `Cannot re-bind parameter: parameter '${paramName}' is already bound in tool '${this.toolName}'.`
+        );
+      }
+      if (!originalParamKeys.includes(paramName)) {
+        throw new Error(
+          `Unable to bind parameter: no parameter named '${paramName}' in tool '${this.toolName}'.`
+        );
+      }
+    }
+
+    const newBoundParams = {...this.boundParams, ...paramsToBind};
+    return ToolboxTool(
+      session,
+      baseUrl,
+      this.toolName,
+      this.description,
+      this.params,
+      newBoundParams
+    );
+  };
+
+  callable.bindParam = function (paramName: string, paramValue: BoundValue) {
+    return this.bindParams({[paramName]: paramValue});
+  };
   return callable;
 }
 

packages/toolbox-core/src/toolbox_core/utils.ts

@@ -0,0 +1,16 @@
+export type BoundValue = unknown | (() => unknown) | (() => Promise<unknown>);
+
+export type BoundParams = Record<string, BoundValue>;
+
+/**
+ * Resolves a value that might be a literal, a function, or a promise-returning function.
+ * @param {BoundValue} value The value to resolve.
+ * @returns {Promise<unknown>} A promise that resolves to the final literal value.
+ */
+export async function resolveValue(value: BoundValue): Promise<unknown> {
+  if (typeof value === 'function') {
+    // Execute the function and await its result, correctly handling both sync and async functions.
+    return await Promise.resolve(value());
+  }
+  return value;
+}

packages/toolbox-core/test/e2e/test.e2e.ts

@@ -127,4 +127,77 @@ describe('ToolboxClient E2E Tests', () => {
       ).rejects.toThrow('Request failed with status code 404');
     });
   });
+  describe('bindParams', () => {
+    it('should successfully bind a parameter with bindParam and invoke', async () => {
+      const newTool = getNRowsTool.bindParam('num_rows', '3');
+      const response = await newTool(); // Invoke with no args
+      const result = response['result'];
+      expect(result).toContain('row1');
+      expect(result).toContain('row2');
+      expect(result).toContain('row3');
+      expect(result).not.toContain('row4');
+    });
+
+    it('should successfully bind parameters with bindParams and invoke', async () => {
+      const newTool = getNRowsTool.bindParams({num_rows: '3'});
+      const response = await newTool(); // Invoke with no args
+      const result = response['result'];
+      expect(result).toContain('row1');
+      expect(result).toContain('row2');
+      expect(result).toContain('row3');
+      expect(result).not.toContain('row4');
+    });
+
+    it('should successfully bind a synchronous function value', async () => {
+      const newTool = getNRowsTool.bindParams({num_rows: () => '1'});
+      const response = await newTool();
+      const result = response['result'];
+      expect(result).toContain('row1');
+      expect(result).not.toContain('row2');
+    });
+
+    it('should successfully bind an asynchronous function value', async () => {
+      const asyncNumProvider = async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        return '1';
+      };
+
+      const newTool = getNRowsTool.bindParams({num_rows: asyncNumProvider});
+      const response = await newTool();
+      const result = response['result'];
+
+      expect(result).toContain('row1');
+
+      expect(result).not.toContain('row2');
+    });
+
+    it('should successfully bind parameters at load time', async () => {
+      const tool = await commonToolboxClient.loadTool('get-n-rows', {
+        num_rows: '3',
+      });
+      const response = await tool();
+      const result = response['result'];
+      expect(result).toContain('row1');
+      expect(result).toContain('row2');
+      expect(result).toContain('row3');
+      expect(result).not.toContain('row4');
+    });
+
+    it('should throw an error when re-binding an existing parameter', () => {
+      const newTool = getNRowsTool.bindParam('num_rows', '1');
+      expect(() => {
+        newTool.bindParam('num_rows', '2');
+      }).toThrow(
+        "Cannot re-bind parameter: parameter 'num_rows' is already bound in tool 'get-n-rows'."
+      );
+    });
+
+    it('should throw an error when binding a non-existent parameter', () => {
+      expect(() => {
+        getNRowsTool.bindParam('non_existent_param', '2');
+      }).toThrow(
+        "Unable to bind parameter: no parameter named 'non_existent_param' in tool 'get-n-rows'."
+      );
+    });
+  });
 });