feat(agents): add client-side tool execution support

[netanelgilad]

Enable agent tools to run in the browser (e.g., geolocation, clipboard,
DOM access) rather than on the server. Adds registerClientToolHandlers(),
submitToolResults(), and handlePendingClientTools() methods. The WebSocket
subscription auto-detects pending_client_execution tool calls, runs
registered handlers, and POSTs results back to the server.

https://claude.ai/code/session_01LZMZNv1qXXeibBhqYRuR54

[claude]

Claude finished @netanelgilad's task —— View job

---

PR Review: Client-Side Tool Execution Support

I've reviewed the changes to add client-side tool execution support for agents. Here's my comprehensive feedback:

Review Checklist

• Check for CLAUDE.md repository guidelines
• Review src/modules/agents.ts changes
• Review src/modules/agents.types.ts changes
• Analyze code quality and best practices
• Identify potential bugs or issues
• Evaluate performance considerations
• Assess security concerns
• Check test coverage

🟢 Code Quality and Best Practices

The implementation follows good patterns overall:

• Clean separation of concerns with dedicated types and interfaces
• Proper TypeScript typing throughout
• Good JSDoc documentation for all new methods
• Consistent code style with the existing codebase
• Clear and descriptive variable/function naming

🟡 Potential Bugs or Issues

1. Race Condition in handlePendingClientTools (src/modules/agents.ts:111)

   • The messages context uses currentConversations[conversationId]?.messages || []
   • If the conversation hasn't been loaded yet, handlers receive an empty messages array
   • Consider ensuring the conversation is loaded before processing tools

2. Missing Handler Error Handling (src/modules/agents.ts:96-101)

   • When a handler is missing, the error message is generic
   • Consider providing more context about available handlers or how to register them

3. Potential Memory Leak (src/modules/agents.ts:26)

   • clientToolHandlers accumulates handlers but never cleans them up
   • Consider adding an unregisterClientToolHandlers method or cleanup on conversation close

🟡 Performance Considerations

1. Sequential Tool Execution (src/modules/agents.ts:94)

   • Tools are executed sequentially in a for loop
   • Consider using Promise.all() for parallel execution when tools are independent

2. JSON Parsing in Hot Path (src/modules/agents.ts:105)

   • JSON.parse is called for every tool call without try-catch
   • The error handling at line 118 might not catch malformed JSON
   • Consider wrapping JSON.parse in its own try-catch

🔴 Security Concerns

1. Unrestricted Tool Execution (src/modules/agents.ts:113)

   • Client tools execute with full access to browser APIs
   • No validation of tool arguments before passing to handlers
   • Consider adding argument validation or sanitization

2. Information Disclosure (src/modules/agents.ts:99)

   • Error messages include the tool name which could reveal internal implementation details
   • Consider using generic error messages for production

3. No Rate Limiting

   • Client tools could be called repeatedly without any throttling
   • Consider adding rate limiting or debouncing for certain tool types

🔴 Test Coverage

No tests were added for the new functionality. Consider adding tests for:

• registerClientToolHandlers - registration and overwriting
• handlePendingClientTools - success and error cases
• submitToolResults - API interaction
• WebSocket integration with auto-handling
• Edge cases like missing handlers, malformed arguments

💡 Suggestions

1. Add a method to list registered handlers:

getRegisteredHandlers(conversationId: string): string[] {
  return Object.keys(clientToolHandlers[conversationId] || {});
}

2. Consider adding timeout support for client tools to prevent hanging:

const result = await Promise.race([
  handler(args, context),
  new Promise((_, reject) => 
    setTimeout(() => reject(new Error('Tool timeout')), 30000)
  )
]);

3. Add validation for the tool result type to ensure it's serializable before stringifying.

Overall, this is a solid implementation that adds valuable functionality. The main concerns are around security validation, error handling edge cases, and the lack of test coverage. Addressing these would make this feature production-ready.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.19-pr.126.c537ed8

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.19-pr.126.c537ed8"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.19-pr.126.c537ed8"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.19-pr.126.c537ed8
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}