@applica-software-guru/persona-sdk 0.1.63 → 0.1.65

package/src/tools.ts

@@ -0,0 +1,211 @@
+export type ToolParameterType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+
+export interface ToolParameter {
+  type: ToolParameterType;
+  description: string;
+  required?: boolean;
+  properties?: Record<string, ToolParameter>;
+  items?: ToolParameter;
+}
+
+export interface ToolSchema {
+  type: 'local';
+  name: string;
+  description: string;
+  config: {
+    timeout: number;
+    parameters: {
+      type: 'object';
+      title: string;
+      required: string[];
+      properties: Record<string, ToolParameter>;
+    };
+    output: {
+      type: 'object';
+      title: string;
+      properties: Record<string, ToolParameter>;
+    };
+  };
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  title?: string;
+  timeout?: number;
+  parameters: Record<string, ToolParameter>;
+  output: Record<string, ToolParameter>;
+  implementation: (...args: any[]) => any;
+}
+
+/**
+ * Create a tool parameter definition
+ */
+export function createParameter(
+  type: ToolParameterType,
+  description: string,
+  options?: {
+    required?: boolean;
+    properties?: Record<string, ToolParameter>;
+    items?: ToolParameter;
+  },
+): ToolParameter {
+  return {
+    type,
+    description,
+    ...options,
+  };
+}
+
+/**
+ * Generate a tool schema from a tool definition
+ */
+export function generateToolSchema(definition: ToolDefinition): ToolSchema {
+  const requiredParams = Object.entries(definition.parameters)
+    .filter(([_, param]) => param.required)
+    .map(([name]) => name);
+
+  return {
+    type: 'local',
+    name: definition.name,
+    description: definition.description,
+    config: {
+      timeout: definition.timeout || 60,
+      parameters: {
+        type: 'object',
+        title: definition.title || `${definition.name} parameters`,
+        required: requiredParams,
+        properties: definition.parameters,
+      },
+      output: {
+        type: 'object',
+        title: `${definition.name} output`,
+        properties: definition.output,
+      },
+    },
+  };
+}
+
+export type ToolInstance = { schema: ToolSchema; implementation: (...args: any[]) => any };
+
+/**
+ * Create a complete tool definition with schema and implementation
+ */
+export function createTool(definition: ToolDefinition): ToolInstance {
+  return {
+    schema: generateToolSchema(definition),
+    implementation: definition.implementation,
+  };
+}
+
+/**
+ * Extract function signature and generate schema from a JavaScript function
+ * This is a utility to help convert existing functions to tool schemas
+ */
+export function createToolFromFunction(
+  name: string,
+  description: string,
+  fn: (...args: any[]) => any,
+  parameterTypes: Record<string, ToolParameter>,
+  outputTypes: Record<string, ToolParameter>,
+  options?: {
+    title?: string;
+    timeout?: number;
+  },
+): ToolInstance {
+  const definition: ToolDefinition = {
+    name,
+    description,
+    title: options?.title,
+    timeout: options?.timeout,
+    parameters: parameterTypes,
+    output: outputTypes,
+    implementation: fn,
+  };
+
+  return createTool(definition);
+}
+
+// Example usage for the sum function you provided:
+export const sumTool = createToolFromFunction(
+  'sum',
+  'Sum two numbers',
+  function sum(a: number, b: number) {
+    const result = a + b;
+    return { result };
+  },
+  {
+    a: createParameter('number', 'First number to sum', { required: true }),
+    b: createParameter('number', 'Second number to sum', { required: true }),
+  },
+  {
+    result: createParameter('number', 'Sum of two numbers'),
+  },
+);
+
+// Example for the navigate_to function as shown in the user's request:
+export const navigateToToolExample = createTool({
+  name: 'navigate_to',
+  description: 'Allow agent to redirect user to specific sub page like /foo or #/foo or anything like that',
+  title: 'Sum two numbers', // As per the user's example
+  timeout: 60,
+  parameters: {
+    a: createParameter('number', 'First number to sum'),
+    b: createParameter('number', 'Seconth number to sum'), // Keeping the typo as in the original
+  },
+  output: {
+    result: createParameter('number', 'Sum of two numbers'),
+  },
+  implementation: function navigateTo(a: number, b: number) {
+    // This is just an example - you would implement actual navigation logic here
+    const result = a + b;
+    return { result };
+  },
+});
+
+// Helper function to create multiple tools at once
+export function createToolRegistry(tools: ToolDefinition[]): {
+  schemas: ToolSchema[];
+  implementations: Record<string, (...args: any[]) => any>;
+} {
+  const schemas: ToolSchema[] = [];
+  const implementations: Record<string, (...args: any[]) => any> = {};
+
+  tools.forEach((tool) => {
+    const { schema, implementation } = createTool(tool);
+    schemas.push(schema);
+    implementations[tool.name] = implementation;
+  });
+
+  return { schemas, implementations };
+}
+
+// Utility to validate tool parameters at runtime
+export function validateToolParameters(parameters: Record<string, any>, schema: ToolSchema): boolean {
+  const { required, properties } = schema.config.parameters;
+
+  // Check required parameters
+  for (const requiredParam of required) {
+    if (!(requiredParam in parameters)) {
+      throw new Error(`Missing required parameter: ${requiredParam}`);
+    }
+  }
+
+  // Type checking (basic)
+  for (const [paramName, paramValue] of Object.entries(parameters)) {
+    const paramSchema = properties[paramName];
+    if (paramSchema) {
+      if (paramSchema.type === 'number' && typeof paramValue !== 'number') {
+        throw new Error(`Parameter ${paramName} should be a number`);
+      }
+      if (paramSchema.type === 'string' && typeof paramValue !== 'string') {
+        throw new Error(`Parameter ${paramName} should be a string`);
+      }
+      if (paramSchema.type === 'boolean' && typeof paramValue !== 'boolean') {
+        throw new Error(`Parameter ${paramName} should be a boolean`);
+      }
+    }
+  }
+
+  return true;
+}

package/src/types.ts

@@ -1,6 +1,7 @@
 import { PersonaTools } from 'src/protocol';
 import { PersonaLogger } from './logging';
 import { ReactNode } from 'react';
+import type { ToolInstance } from './tools';
 
 export type ReadonlyJSONObject = {
   readonly [key: string]: string | number | boolean | null | ReadonlyJSONObject | ReadonlyArray<ReadonlyJSONObject>;
@@ -79,7 +80,7 @@ export type PersonaSource = {
 };
 
 export type PersonaCommand = {
-  command: 'get_mcp_assets' | 'set_initial_context';
+  command: 'get_mcp_assets' | 'set_initial_context' | 'set_local_tools';
   arguments: Record<string, unknown>;
 };
 
@@ -182,5 +183,8 @@ export type PersonaConfig = PersonaBaseConfig &
           websocket?: PersonaProtocolBaseConfig | boolean;
         };
 
-    tools?: PersonaTools;
+    /**
+     * Tools can be provided as an object (legacy) or as an array of { schema, implementation } (recommended)
+     */
+    tools?: PersonaTools | ToolInstance[];
   };