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

package/playground/src/chat.tsx

@@ -3,6 +3,8 @@ import { PersonaRuntimeProvider, PersonaConsoleLogger, Session, usePersonaRuntim
 import { useMemo } from 'react';
 import _ from 'lodash';
 import { TooltipProvider } from './components/ui/tooltip';
+import { tools } from '@/tools';
+
 const logger = new PersonaConsoleLogger();
 
 function generateSID() {
@@ -58,7 +60,8 @@ function MessageLogger() {
 }
 
 function Chat() {
-  const agent = getQueryParam('agentId');
+  const agentId = getQueryParam('agentId');
+  const apiKey = getQueryParam('apiKey');
   const sid = getQueryParam('sid');
 
   const session = useMemo((): Session => {
@@ -74,26 +77,19 @@ function Chat() {
       logger={logger}
       context={{
         data: {
-          username: 'Bruno Trimone Agent',
-          userAgent: navigator.userAgent,
-        },
-      }}
-      tools={{
-        get_user_agent: () => {
-          const userAgent = 'Bruno Trimone Agent';
-          return { userAgent };
-        },
-        get_client_date: () => {
-          const date = new Date();
-          return { date: date.toISOString() };
+          username: 'Roberto',
+          userAgent: 'Google Tridroid 14',
         },
       }}
+      tools={tools}
       protocols={{
-        rest: true,
+        rest: false,
+        websocket: true,
+        webrtc: true,
       }}
       session={session}
-      apiKey="2398utf8g$9pahwv8#93q8.h8349q*!ty89w4uefghwqh849tg934yg894hq3g89q34h9"
-      agentId={(agent as string) || 'default'}
+      apiKey={apiKey!}
+      agentId={agentId!}
     >
       <div className="h-dvh w-full">
         <TooltipProvider>

package/playground/src/tools.ts

@@ -0,0 +1,127 @@
+/**
+ * Example Tool Library
+ *
+ * This file demonstrates how to define and export a library of example tools
+ * using the Persona SDK's createTool utility. These tools can be imported
+ * and used in PersonaRuntimeProvider or other parts of the application to
+ * showcase or test tool integration.
+ */
+
+import { createTool, PersonaTools } from '@applica-software-guru/persona-sdk';
+
+const toolLibrary = [
+  createTool({
+    name: 'sum',
+    title: 'Sum two numbers',
+    description: 'Sums two numbers and returns the result.',
+    parameters: {
+      a: { type: 'number', description: 'First number to sum', required: true },
+      b: { type: 'number', description: 'Second number to sum', required: true },
+    },
+    output: {
+      result: { type: 'number', description: 'Sum of the two numbers' },
+    },
+    implementation: async (a: number, b: number) => {
+      const result = a + b;
+      return { result };
+    },
+  }),
+  createTool({
+    name: 'concat',
+    title: 'Concatenate two strings',
+    description: 'Concatenates two strings and returns the result.',
+    parameters: {
+      str1: { type: 'string', description: 'First string to concatenate', required: true },
+      str2: { type: 'string', description: 'Second string to concatenate', required: true },
+    },
+    output: {
+      result: { type: 'string', description: 'Concatenated result of the two strings' },
+    },
+    implementation: async (str1: string, str2: string) => {
+      const result = str1 + str2;
+      return { result };
+    },
+  }),
+  // User agent tool:
+  createTool({
+    name: 'userAgent',
+    title: 'Get User Agent',
+    description: 'Retrieves the user agent string from the client.',
+    parameters: {},
+    output: {
+      result: { type: 'string', description: 'User agent string' },
+    },
+    implementation: async () => {
+      return { result: navigator.userAgent };
+    },
+  }),
+  // Navigate to URL tool:
+  createTool({
+    name: 'navigateTo',
+    title: 'Navigate to URL',
+    description: 'Navigates the browser to a specified URL.',
+    parameters: {
+      url: { type: 'string', description: 'The URL to navigate to', required: true },
+    },
+    output: {
+      success: { type: 'boolean', description: 'Indicates if navigation was successful' },
+    },
+    implementation: async (url: string) => {
+      window.location.href = url;
+      return { success: true };
+    },
+  }),
+  // Get current URL tool:
+  createTool({
+    name: 'getCurrentUrl',
+    title: 'Get Current URL',
+    description: 'Retrieves the current browser URL.',
+    parameters: {},
+    output: {
+      url: { type: 'string', description: 'Current browser URL' },
+    },
+    implementation: async () => {
+      return { url: window.location.href };
+    },
+  }),
+
+  // Current client date and time tool:
+  createTool({
+    name: 'getCurrentDateTime',
+    title: 'Get Current Date and Time',
+    description: 'Retrieves the current date and time from the client.',
+    parameters: {},
+    output: {
+      dateTime: { type: 'string', description: 'Current date and time in ISO format' },
+    },
+    implementation: async () => {
+      return { dateTime: new Date().toISOString() };
+    },
+  }),
+];
+
+const tools: PersonaTools = {
+  sum: function (a: number, b: number) {
+    const result = a + b;
+    return { result };
+  },
+  concat: function (str1: string, str2: string) {
+    const result = str1 + str2;
+    return { result };
+  },
+  navigateTo: function (url: string) {
+    window.location.href = url;
+    return { success: true };
+  },
+  getUserAgent: function () {
+    return { result: navigator.userAgent };
+  },
+  getCurrentUrl: function () {
+    return { url: window.location.href };
+  },
+  getCurrentDateTime: function () {
+    return { dateTime: new Date().toISOString() };
+  },
+};
+
+export { toolLibrary, tools };

package/src/index.ts

@@ -2,3 +2,4 @@ export * from './runtime';
 export * from './logging';
 export * from './protocol';
 export * from './types';
+export * from './tools';

package/src/protocol/rest.ts

@@ -8,6 +8,7 @@ import {
   PersonaPacket,
   PersonaCommand,
 } from '../types';
+import { ToolInstance } from '../tools';
 
 type PersonaRESTProtocolConfig = PersonaProtocolBaseConfig & {
   apiUrl: string;
@@ -20,6 +21,7 @@ class PersonaRESTProtocol extends PersonaProtocolBase {
   config: PersonaRESTProtocolConfig;
   notify: boolean = true;
   context: Record<string, any> = {};
+  tools: ToolInstance[] = [];
 
   constructor(config: PersonaRESTProtocolConfig) {
     super();
@@ -56,10 +58,15 @@ class PersonaRESTProtocol extends PersonaProtocolBase {
     if (packet.type === 'command' && (packet?.payload as PersonaCommand)?.command == 'set_initial_context') {
       this.context = (packet?.payload as PersonaCommand)?.arguments;
       return;
+    } else if (packet.type === 'command' && (packet?.payload as PersonaCommand)?.command == 'set_local_tools') {
+      const args = (packet?.payload as PersonaCommand)?.arguments;
+      this.tools = args?.tools as ToolInstance[];
+      this.config?.logger?.warn('Local tools are not supported in REST protocol, ignoring command');
+      return;
     }
     const input = packet.payload as PersonaMessage;
     const response = await fetch(`${apiUrl}/sessions/${sessionId}/messages`, {
-      body: JSON.stringify({ agentId, userMessage: input, initial_context: this.context }),
+      body: JSON.stringify({ agentId, userMessage: input, initialContext: this.context, tools: this.tools }),
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',

package/src/protocol/transaction.ts

@@ -1,13 +1,6 @@
 import { PersonaProtocolBase } from './base';
-import {
-  Session,
-  ProtocolStatus,
-  PersonaProtocolBaseConfig,
-  PersonaTransaction,
-  FunctionCall,
-  ReadonlyJSONObject,
-  PersonaPacket,
-} from '../types';
+import { Session, ProtocolStatus, PersonaProtocolBaseConfig, PersonaTransaction, FunctionCall, PersonaPacket } from '../types';
+import { ToolInstance } from '../tools';
 
 type FinishTransactionRequest = {
   success: boolean;
@@ -45,7 +38,7 @@ class PersonaTransactionsManager {
   }
 }
 
-export type PersonaToolCallback = (args: ReadonlyJSONObject | undefined) => void;
+export type PersonaToolCallback = (...args: any[]) => void | Record<string, any> | Promise<void | Record<string, any>>;
 export type PersonaTools = {
   [key: string]: PersonaToolCallback;
 };
@@ -77,7 +70,7 @@ class PersonaPersistableTransaction {
       return;
     }
     try {
-      const result = await tool(functionArgs);
+      const result = await tool.apply(null, Object.values(functionArgs));
       await this.complete(result);
     } catch (error) {
       await this.fail(`Error executing tool ${functionName}: ${error}`);
@@ -95,7 +88,8 @@ type PersonaTransactionCallback = (transaction: PersonaPersistableTransaction) =
 
 type PersonaTransactionProtocolConfig = PersonaProtocolBaseConfig & {
   apiUrl: string;
-  onTransaction: PersonaTransactionCallback;
+  tools: PersonaTools | ToolInstance[];
+  onTransaction?: PersonaTransactionCallback;
 };
 
 class PersonaTransactionProtocol extends PersonaProtocolBase {
@@ -104,12 +98,23 @@ class PersonaTransactionProtocol extends PersonaProtocolBase {
   session: Session;
   config: PersonaTransactionProtocolConfig;
   notify: boolean = true;
+  private _tools: PersonaTools;
 
   constructor(config: PersonaTransactionProtocolConfig) {
     super();
     this.config = config;
     this.status = 'disconnected';
     this.autostart = true;
+    if (Array.isArray(config.tools)) {
+      this._tools = {};
+      for (const tool of config.tools as ToolInstance[]) {
+        if (tool.schema && tool.implementation) {
+          this._tools[tool.schema.name] = tool.implementation;
+        }
+      }
+    } else {
+      this._tools = config.tools as PersonaTools;
+    }
   }
 
   public getName(): string {
@@ -137,13 +142,18 @@ class PersonaTransactionProtocol extends PersonaProtocolBase {
   public async sendPacket(_: PersonaPacket): Promise<void> {}
 
   public onTransaction(transaction: PersonaTransaction): void {
-    if (!this.config.onTransaction) {
-      this.config.logger?.error('Transaction protocol config is not set');
-      return;
-    }
+    console.log('transaction received:', transaction);
     const manager = new PersonaTransactionsManager(this.config);
     const persistable = new PersonaPersistableTransaction(transaction, manager);
-    this.config.onTransaction(persistable);
+    if (this.config.onTransaction) {
+      this.config.onTransaction(persistable);
+    } else {
+      persistable.invoke(this._tools);
+    }
+  }
+
+  public getTools(): PersonaTools {
+    return this._tools;
   }
 }
 

package/src/protocol/webrtc.ts

@@ -31,6 +31,7 @@ class PersonaWebRTCClient {
   private isConnected: boolean = false;
   private visualizerCallbacks: AudioVisualizerCallback[] = [];
   private messageCallbacks: PersonaWebRTCMessageCallback[] = [];
+  private queuedMessages: PersonaPacket[] = [];
 
   constructor(config: PersonaWebRTCConfig) {
     this.config = config;
@@ -100,6 +101,15 @@ class PersonaWebRTCClient {
           callback(msg);
         });
       };
+      channel.onopen = () => {
+        while (this.queuedMessages.length > 0) {
+          const packet = this.queuedMessages.shift();
+          if (packet) {
+            channel.send(JSON.stringify(packet));
+            this.config.logger?.info('Sent queued message:', packet);
+          }
+        }
+      };
     };
 
     const url = this.config.webrtcUrl || 'wss://persona.applica.guru/api/webrtc';
@@ -179,7 +189,16 @@ class PersonaWebRTCClient {
   public createDataChannel(label = 'messages'): void {
     if (!this.pc) return;
     this.dataChannel = this.pc.createDataChannel(label);
-    this.dataChannel.onopen = () => this.config.logger?.info('Data channel opened');
+    this.dataChannel.onopen = () => {
+      this.config.logger?.info('Data channel opened');
+      while (this.queuedMessages.length > 0) {
+        const packet = this.queuedMessages.shift();
+        if (packet) {
+          this.dataChannel!.send(JSON.stringify(packet));
+          this.config.logger?.info('Sent queued message:', packet);
+        }
+      }
+    };
     this.dataChannel.onmessage = (msg: MessageEvent) => {
       this.messageCallbacks.forEach((callback) => {
         callback(msg);
@@ -188,8 +207,8 @@ class PersonaWebRTCClient {
   }
 
   public sendPacket(packet: PersonaPacket): void {
-    if (!this.dataChannel) {
-      this.config.logger?.warn('Data channel is not open, cannot send message');
+    if (!this.dataChannel || this.dataChannel.readyState !== 'open') {
+      this.queuedMessages.push(packet);
       return;
     }
 

package/src/runtime.tsx

@@ -20,7 +20,6 @@ import {
 } from './types';
 import { parseMessages, convertMessage } from './messages';
 import {
-  PersonaPersistableTransaction,
   PersonaRESTProtocol,
   PersonaRESTProtocolConfig,
   PersonaTransactionProtocol,
@@ -137,9 +136,7 @@ function PersonaRuntimeProviderInner({
             apiUrl: `${baseEndpointProtocol}://${baseEndpoint}`,
             apiKey: config.apiKey,
             agentId: config.agentId,
-            onTransaction: async (transaction: PersonaPersistableTransaction) => {
-              await transaction.invoke(config.tools!);
-            },
+            tools: config.tools, // Pass raw tools
             logger,
           }),
         );
@@ -163,14 +160,27 @@ function PersonaRuntimeProviderInner({
       protocol.addStatusChangeListener((status: ProtocolStatus) => {
         logger?.debug(`${protocol.getName()} has notified new status: ${status}`);
         protocolsStatus.set(protocol.getName(), status);
-        if (status === 'connected' && config.context) {
-          protocol.sendPacket({
-            type: 'command',
-            payload: {
-              command: 'set_initial_context',
-              arguments: config.context,
-            },
-          });
+        if (status === 'connected') {
+          if (config.context) {
+            protocol.sendPacket({
+              type: 'command',
+              payload: {
+                command: 'set_initial_context',
+                arguments: config.context,
+              },
+            });
+          }
+          if (config.tools && Array.isArray(config.tools)) {
+            protocol.sendPacket({
+              type: 'command',
+              payload: {
+                command: 'set_local_tools',
+                arguments: {
+                  tools: config.tools.map((tool) => tool.schema),
+                },
+              },
+            });
+          }
         }
         setProtocolsStatus(new Map(protocolsStatus));
       });

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[];
   };