@everworker/oneringai 0.2.2 → 0.2.3

package/README.md

@@ -27,8 +27,9 @@
   - [13. Streaming](#13-streaming)
   - [14. OAuth for External APIs](#14-oauth-for-external-apis)
   - [15. Developer Tools](#15-developer-tools)
-  - [16. Document Reader](#16-document-reader-new) — PDF, DOCX, XLSX, PPTX, CSV, HTML, images
-  - [17. External API Integration](#17-external-api-integration) — Scoped Registry, Vendor Templates, Tool Discovery
+  - [16. Custom Tool Generation](#16-custom-tool-generation-new) — Agents create, test, and persist their own tools
+  - [17. Document Reader](#17-document-reader) — PDF, DOCX, XLSX, PPTX, CSV, HTML, images
+  - [18. External API Integration](#18-external-api-integration) — Scoped Registry, Vendor Templates, Tool Discovery
 - [MCP Integration](#mcp-model-context-protocol-integration)
 - [Documentation](#documentation)
 - [Examples](#examples)
@@ -58,7 +59,7 @@
 ## HOSEA APP
 We realize that library alone in these times is not enough to get you excited, so we built a FREE FOREVER desktop app on top of this library to showcase its power! It's as easy to start using as cloning this library's repo, and then `cd apps/hosea` and then `npm install` and then `npm run dev`. Or watch the video first:
 
-![Watch the demo](https://img.youtube.com/vi/_LzDiuOQD8Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=_LzDiuOQD8Y)
+[![Watch the demo](https://img.youtube.com/vi/_LzDiuOQD8Y/maxresdefault.jpg)](https://www.youtube.com/watch?v=_LzDiuOQD8Y)
 
 Or read the more detailed installation / setup instructions [here](https://github.com/Integrail/oneringai/blob/main/apps/hosea/README.md)
 
@@ -87,6 +88,7 @@ Better to see once and then dig in the code! :)
 - 📝 **Persistent Instructions** - NEW: Agent-level custom instructions that persist across sessions on disk
 - 🛠️ **Agentic Workflows** - Built-in tool calling and multi-turn conversations
 - 🔧 **Developer Tools** - NEW: Filesystem and shell tools for coding assistants (read, write, edit, grep, glob, bash)
+- 🧰 **Custom Tool Generation** - NEW: Let agents create, test, and persist their own reusable tools at runtime — complete meta-tool system with VM sandbox
 - 🖥️ **Desktop Automation** - NEW: OS-level computer use — screenshot, mouse, keyboard, and window control for vision-driven agent loops
 - 📄 **Document Reader** - NEW: Universal file-to-text converter — PDF, DOCX, XLSX, PPTX, CSV, HTML, images auto-converted to markdown
 - 🔌 **MCP Integration** - NEW: Model Context Protocol client for seamless tool discovery from local and remote servers
@@ -320,7 +322,7 @@ const response = await agent.run([
 Connector-based web search with multiple providers:
 
 ```typescript
-import { Connector, SearchProvider, Services, webSearch, Agent } from '@everworker/oneringai';
+import { Connector, SearchProvider, ConnectorTools, Services, Agent, tools } from '@everworker/oneringai';
 
 // Create search connector
 Connector.create({
@@ -338,11 +340,13 @@ const results = await search.search('latest AI developments 2026', {
   language: 'en',
 });
 
-// Option 2: Use with Agent
+// Option 2: Use with Agent via ConnectorTools
+const searchTools = ConnectorTools.for('serper-main');
+
 const agent = Agent.create({
   connector: 'openai',
   model: 'gpt-4',
-  tools: [webSearch],
+  tools: [...searchTools, tools.webFetch],
 });
 
 await agent.run('Search for quantum computing news and summarize');
@@ -359,7 +363,7 @@ await agent.run('Search for quantum computing news and summarize');
 Enterprise web scraping with automatic fallback and bot protection bypass:
 
 ```typescript
-import { Connector, ScrapeProvider, Services, webScrape, Agent } from '@everworker/oneringai';
+import { Connector, ScrapeProvider, ConnectorTools, Services, Agent, tools } from '@everworker/oneringai';
 
 // Create ZenRows connector for bot-protected sites
 Connector.create({
@@ -379,19 +383,24 @@ const result = await scraper.scrape('https://protected-site.com', {
   },
 });
 
-// Option 2: Use webScrape tool with Agent
+// Option 2: Use web_scrape tool with Agent via ConnectorTools
+const scrapeTools = ConnectorTools.for('zenrows');
+
 const agent = Agent.create({
   connector: 'openai',
   model: 'gpt-4',
-  tools: [webScrape],
+  tools: [...scrapeTools, tools.webFetch],
 });
 
-// webScrape auto-falls back: native → JS → API
+// web_scrape auto-falls back: native → API
 await agent.run('Scrape https://example.com and summarize');
 ```
 
 **Supported Scrape Providers:**
 - **ZenRows** - Enterprise scraping with JS rendering, residential proxies, anti-bot bypass
+- **Jina Reader** - Clean content extraction with AI-powered readability
+- **Firecrawl** - Web scraping with JavaScript rendering
+- **ScrapingBee** - Headless browser scraping with proxy rotation
 
 ## Supported Providers
 
@@ -401,7 +410,7 @@ await agent.run('Scrape https://example.com and summarize');
 | **Anthropic (Claude)** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | 200K |
 | **Google (Gemini)** | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | 1M |
 | **Google Vertex AI** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | 1M |
-| **Grok (xAI)** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | 128K |
+| **Grok (xAI)** | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | 128K |
 | **Groq** | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | 128K |
 | **Together AI** | ✅ | Some | ❌ | ❌ | ❌ | ❌ | ✅ | 128K |
 | **DeepSeek** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 64K |
@@ -643,7 +652,7 @@ await agent.run('Check weather for SF and remember the result');
 Use `Agent` with search tools and `WorkingMemoryPluginNextGen` for research workflows:
 
 ```typescript
-import { Agent, webSearch, SearchProvider, Connector, Services } from '@everworker/oneringai';
+import { Agent, ConnectorTools, Connector, Services, tools } from '@everworker/oneringai';
 
 // Setup search connector
 Connector.create({
@@ -654,10 +663,12 @@ Connector.create({
 });
 
 // Create agent with search and memory
+const searchTools = ConnectorTools.for('serper-main');
+
 const agent = Agent.create({
   connector: 'openai',
   model: 'gpt-4',
-  tools: [webSearch],
+  tools: [...searchTools, tools.webFetch],
   context: {
     features: { workingMemory: true },
   },
@@ -1024,7 +1035,42 @@ await agent.run('Run npm test and report any failures');
 - Timeout protection (default 2 min)
 - Output truncation for large outputs
 
-### 16. Desktop Automation Tools (NEW)
+### 16. Custom Tool Generation (NEW)
+
+Let agents **create their own tools** at runtime — draft, test, iterate, save, and reuse. The agent writes JavaScript code, validates it, tests it in the VM sandbox, and persists it for future use. All 6 meta-tools are auto-registered and visible in Hosea.
+
+```typescript
+import { createCustomToolMetaTools, hydrateCustomTool } from '@everworker/oneringai';
+
+// Give an agent the ability to create tools
+const agent = Agent.create({
+  connector: 'openai',
+  model: 'gpt-4',
+  tools: [...createCustomToolMetaTools()],
+});
+
+// The agent can now: draft → test → save tools autonomously
+await agent.run('Create a tool that fetches weather data from the OpenWeather API');
+
+// Later: load and use a saved tool
+import { createFileCustomToolStorage } from '@everworker/oneringai';
+const storage = createFileCustomToolStorage();
+const definition = await storage.load('fetch_weather');
+const weatherTool = hydrateCustomTool(definition!);
+
+// Register on any agent
+agent.tools.register(weatherTool, { source: 'custom', tags: ['weather', 'api'] });
+```
+
+**Meta-Tools:** `custom_tool_draft` (validate), `custom_tool_test` (execute in sandbox), `custom_tool_save` (persist), `custom_tool_list` (search), `custom_tool_load` (retrieve), `custom_tool_delete` (remove)
+
+**Dynamic Descriptions:** Draft and test tools use `descriptionFactory` to show all available connectors and the full sandbox API — automatically updated when connectors are added or removed.
+
+**Pluggable Storage:** Default `FileCustomToolStorage` saves to `~/.oneringai/custom-tools/`. Implement `ICustomToolStorage` for MongoDB, S3, or any backend.
+
+> See the [User Guide](./USER_GUIDE.md#custom-tool-generation) for the complete workflow, sandbox API reference, and examples.
+
+### 17. Desktop Automation Tools (NEW)
 
 OS-level desktop automation for building "computer use" agents — screenshot the screen, send to a vision model, receive tool calls (click, type, etc.), execute them, repeat:
 
@@ -1060,7 +1106,7 @@ await agent.run('Open Safari and search for "weather forecast"');
 - Screenshots use the `__images` convention for automatic multimodal handling across all providers (Anthropic, OpenAI, Google)
 - Requires `@nut-tree-fork/nut-js` as an optional peer dependency: `npm install @nut-tree-fork/nut-js`
 
-### 17. Document Reader (NEW)
+### 18. Document Reader
 
 Universal file-to-LLM-content converter. Reads arbitrary document formats and produces clean markdown text with optional image extraction:
 
@@ -1125,7 +1171,7 @@ await agent.run([
 
 See the [User Guide](./USER_GUIDE.md#document-reader) for complete API reference and configuration options.
 
-### 18. External API Integration
+### 19. External API Integration
 
 Connect your AI agents to 35+ external services with enterprise-grade resilience:
 
@@ -1477,4 +1523,4 @@ MIT License - See [LICENSE](./LICENSE) file.
 
 ---
 
-**Version:** 0.2.1 | **Last Updated:** 2026-02-11 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**
+**Version:** 0.2.1 | **Last Updated:** 2026-02-17 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**