@everworker/oneringai 0.4.3 → 0.4.5

package/README.md

@@ -34,6 +34,7 @@
   - [20. Routine Execution](#20-routine-execution) — Multi-step workflows with task dependencies, validation, and memory bridging
   - [21. External API Integration](#21-external-api-integration) — Scoped Registry, Vendor Templates, Tool Discovery
   - [22. Microsoft Graph Connector Tools](#22-microsoft-graph-connector-tools-new) — Email, calendar, meetings, and Teams transcripts
+  - [23. Tool Catalog](#23-tool-catalog-new) — Dynamic tool loading/unloading for agents with 100+ tools
 - [MCP Integration](#mcp-model-context-protocol-integration)
 - [Documentation](#documentation)
 - [Examples](#examples)
@@ -54,12 +55,16 @@
 | **[User Guide](./USER_GUIDE.md)** | Comprehensive guide covering every feature with examples — connectors, agents, context, plugins, audio, video, search, MCP, OAuth, and more |
 | **[API Reference](./API_REFERENCE.md)** | Auto-generated reference for all 600+ public exports — classes, interfaces, types, and functions with signatures |
 | [CHANGELOG](./CHANGELOG.md) | Version history and migration notes |
-| [MCP Integration](./MCP_INTEGRATION.md) | Model Context Protocol setup and usage |
-| [Architecture (CLAUDE.md)](./CLAUDE.md) | Internal architecture guide |
-| [Testing Guide](./TESTING.md) | How to run and write tests |
 
 ---
 
+## Tutorial / Architecture Series
+
+**Part 0**. [One Lib to Rule Them All: Why We Built OneRingAI](https://medium.com/superstringtheory/one-library-to-rule-them-all-why-we-built-oneringai-689f904874d6): introduction and architecture overview
+
+**Part 1**. [Your AI Agent Forgets Everything. Here’s How We Fixed It.](https://medium.com/superstringtheory/your-ai-agent-forgets-everything-heres-how-we-fixed-it-276b39aedbb3): context management plugins
+
+
 ## 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:
 
@@ -87,7 +92,7 @@ Showcasing another amazing "built with oneringai": ["no saas" agentic business t
 - 🔌 **Tool Execution Plugins** - NEW: Pluggable pipeline for logging, analytics, UI updates, custom behavior
 - 💾 **Session Persistence** - Save and resume conversations with full state restoration
 - 👤 **Multi-User Support** - Set `userId` once, flows automatically to all tool executions and session metadata
-- 🔒 **Connector Allowlist** - Restrict agents to a named subset of connectors, composable with access policies
+- 🔒 **Auth Identities** - Restrict agents to specific connectors (and accounts), composable with access policies
 - 🤖 **Universal Agent** - ⚠️ *Deprecated* - Use `Agent` with plugins instead
 - 🤖 **Task Agents** - ⚠️ *Deprecated* - Use `Agent` with `WorkingMemoryPluginNextGen`
 - 🔬 **Research Agent** - ⚠️ *Deprecated* - Use `Agent` with search tools
@@ -109,10 +114,13 @@ Showcasing another amazing "built with oneringai": ["no saas" agentic business t
 - 📦 **Vendor Templates** - NEW: Pre-configured auth templates for 43+ services (GitHub, Slack, Stripe, etc.)
 - 📧 **Microsoft Graph Tools** - NEW: Email, calendar, meetings, and Teams transcripts via Microsoft Graph API
 - 🔁 **Routine Execution** - NEW: Multi-step workflows with task dependencies, LLM validation, retry logic, and memory bridging between tasks
+- 📊 **Execution Recording** - NEW: Persist full routine execution history with `createExecutionRecorder()` — replaces manual hook wiring
+- ⏰ **Scheduling & Triggers** - NEW: `SimpleScheduler` for interval/one-time schedules, `EventEmitterTrigger` for webhook/queue-driven execution
+- 📦 **Tool Catalog** - NEW: Dynamic tool loading/unloading — agents discover and load only the categories they need at runtime
 - 🔄 **Streaming** - Real-time responses with event streams
 - 📝 **TypeScript** - Full type safety and IntelliSense support
 
-> **v0.2.0 — Multi-User Support:** Set `userId` once on an agent and it automatically flows to all tool executions, OAuth token retrieval, session metadata, and connector scoping. Combine with `connectors` allowlist and access policies for complete multi-tenant isolation. See [Multi-User Support](#multi-user-support-userid) and [Connector Allowlist](#connector-allowlist-connectors) in the User Guide.
+> **v0.2.0 — Multi-User Support:** Set `userId` once on an agent and it automatically flows to all tool executions, OAuth token retrieval, session metadata, and connector scoping. Combine with `identities` and access policies for complete multi-tenant isolation. See [Multi-User Support](#multi-user-support-userid) and [Auth Identities](#auth-identities-identities) in the User Guide.
 
 ## Quick Start
 
@@ -446,7 +454,10 @@ const agent = Agent.create({
   connector: 'openai',
   model: 'gpt-4',
   userId: 'user-123',            // Flows to all tool executions automatically
-  connectors: ['github', 'slack'], // Only these connectors visible to tools
+  identities: [                   // Only these connectors visible to tools
+    { connector: 'github' },
+    { connector: 'slack' },
+  ],
   tools: [weatherTool, emailTool],
   context: {
     features: {
@@ -677,7 +688,7 @@ const agent = Agent.create({
   },
 });
 
-// Agent now has memory_store, memory_retrieve, memory_delete, memory_list tools
+// Agent now has memory_store, memory_retrieve, memory_delete, memory_query tools
 await agent.run('Check weather for SF and remember the result');
 ```
 
@@ -785,9 +796,11 @@ const agent = Agent.create({
 **Available Features:**
 | Feature | Default | Plugin | Associated Tools |
 |---------|---------|--------|------------------|
-| `workingMemory` | `true` | WorkingMemoryPluginNextGen | `memory_store/retrieve/delete/list` |
+| `workingMemory` | `true` | WorkingMemoryPluginNextGen | `memory_store/retrieve/delete/query/cleanup_raw` |
 | `inContextMemory` | `false` | InContextMemoryPluginNextGen | `context_set/delete/list` |
 | `persistentInstructions` | `false` | PersistentInstructionsPluginNextGen | `instructions_set/remove/list/clear` |
+| `userInfo` | `false` | UserInfoPluginNextGen | `user_info_set/get/remove/clear`, `todo_add/update/remove` |
+| `toolCatalog` | `false` | ToolCatalogPluginNextGen | `tool_catalog_search/load/unload` |
 
 **AgentContextNextGen architecture:**
 - **Plugin-first design** - All features are composable plugins
@@ -910,13 +923,20 @@ const agent = Agent.create({
 - 👥 **User-Scoped** - Data is per-user, not per-agent — different agents share the same user data
 - 🔧 **LLM-Modifiable** - Agent can update user info during execution
 
-**Available Tools:**
+**User Info Tools:**
 - `user_info_set` - Store/update user information by key (`key`, `value`, `description?`)
 - `user_info_get` - Retrieve one entry by key, or all entries if no key
 - `user_info_remove` - Remove a specific entry
 - `user_info_clear` - Clear all entries (requires confirmation)
 
-**Use cases:** User preferences (theme, language, timezone), user context (role, location), accumulated knowledge about the user.
+**TODO Tools** (built into the same plugin):
+- `todo_add` - Create a TODO (`title`, `description?`, `people?`, `dueDate?`, `tags?`)
+- `todo_update` - Update a TODO (`id`, plus any fields to change including `status: 'done'`)
+- `todo_remove` - Delete a TODO by id
+
+TODOs are stored alongside user info and rendered in a separate **"Current TODOs"** checklist in context. The agent proactively suggests creating TODOs when conversation implies action items, reminds about due/overdue items once per day, and auto-cleans completed TODOs after 48 hours.
+
+**Use cases:** User preferences (theme, language, timezone), user context (role, location), accumulated knowledge about the user, task/TODO tracking with deadlines and people.
 
 ### 11. Direct LLM Access
 
@@ -954,7 +974,7 @@ for await (const event of agent.streamDirect('Tell me a story')) {
 
 **Comparison:**
 
-| Aspect | `run()` / `chat()` | `runDirect()` |
+| Aspect | `run()` | `runDirect()` |
 |--------|-------------------|---------------|
 | History tracking | ✅ | ❌ |
 | Memory/Cache | ✅ | ❌ |
@@ -1311,7 +1331,7 @@ const routine = createRoutineDefinition({
     description: 'Process each item',
     controlFlow: {
       type: 'map',
-      sourceKey: '__items',
+      source: '__items',
       resultKey: '__results',
       iterationTimeoutMs: 60000, // 1 min per item
       tasks: [{ name: 'Process', description: 'Handle the current item' }],
@@ -1320,6 +1340,46 @@ const routine = createRoutineDefinition({
 });
 ```
 
+**Execution Recording:** Persist full execution history (steps, task snapshots, progress) with `createExecutionRecorder()`. Replaces ~140 lines of manual hook wiring with a single factory call:
+
+```typescript
+import {
+  createRoutineExecutionRecord, createExecutionRecorder,
+  type IRoutineExecutionStorage,
+} from '@everworker/oneringai';
+
+const record = createRoutineExecutionRecord(definition, 'openai', 'gpt-4');
+const execId = await storage.insert(userId, record);
+const recorder = createExecutionRecorder({ storage, executionId: execId });
+
+executeRoutine({
+  definition, agent, inputs,
+  hooks: recorder.hooks,
+  onTaskStarted: recorder.onTaskStarted,
+  onTaskComplete: recorder.onTaskComplete,
+  onTaskFailed: recorder.onTaskFailed,
+  onTaskValidation: recorder.onTaskValidation,
+})
+  .then(exec => recorder.finalize(exec))
+  .catch(err => recorder.finalize(null, err));
+```
+
+**Scheduling & Triggers:** Run routines on a timer or from external events:
+
+```typescript
+import { SimpleScheduler, EventEmitterTrigger } from '@everworker/oneringai';
+
+// Schedule: run every hour
+const scheduler = new SimpleScheduler();
+scheduler.schedule('hourly-report', { intervalMs: 3600000 }, () => executeRoutine({ ... }));
+
+// Event trigger: run from webhook
+const trigger = new EventEmitterTrigger();
+trigger.on('new-order', (payload) => executeRoutine({ ... }));
+// In your webhook handler:
+trigger.emit('new-order', { orderId: '123' });
+```
+
 **Routine Persistence:** Save and load routine definitions with `FileRoutineDefinitionStorage` (or implement `IRoutineDefinitionStorage` for custom backends). Per-user isolation via optional `userId`. Integrated into `StorageRegistry` as `routineDefinitions`.
 
 ```typescript
@@ -1582,6 +1642,46 @@ await agent.run('Find available meeting slots for alice and bob this week');
 
 Supports both **delegated** (`/me` — user signs in) and **application** (`/users/{id}` — app-only) permission modes. See the [User Guide](./USER_GUIDE.md#microsoft-graph-connector-tools) for full parameter reference.
 
+### 23. Tool Catalog (NEW)
+
+When agents have 100+ available tools, sending all definitions to the LLM wastes tokens and degrades performance. The Tool Catalog lets agents discover and load only the categories they need:
+
+```typescript
+import { Agent, ToolCatalogRegistry } from '@everworker/oneringai';
+
+// Register custom categories (built-in tools auto-register)
+ToolCatalogRegistry.registerCategory({
+  name: 'knowledge',
+  displayName: 'Knowledge Graph',
+  description: 'Search entities, get facts, manage references',
+});
+ToolCatalogRegistry.registerTools('knowledge', [
+  { name: 'entity_search', displayName: 'Entity Search', description: 'Search entities', tool: entitySearchTool, safeByDefault: true },
+]);
+
+// Enable tool catalog on an agent
+const agent = Agent.create({
+  connector: 'openai',
+  model: 'gpt-4',
+  context: {
+    features: { toolCatalog: true },
+    toolCategories: ['filesystem', 'knowledge'],  // optional scope
+  },
+});
+
+// Agent gets 3 metatools: tool_catalog_search, tool_catalog_load, tool_catalog_unload
+// It can browse categories, load what it needs, and unload when done
+await agent.run('Search for information about quantum computing');
+```
+
+**Key Features:**
+- **Dynamic loading** — Agent loads only needed categories, saving token budget
+- **Category scoping** — Restrict visible categories per agent (allowlist/blocklist)
+- **Connector discovery** — Connector tools auto-discovered as categories
+- **Registry API** — `ToolCatalogRegistry.resolveTools()` for app-level tool resolution
+
+See the [User Guide](./USER_GUIDE.md#tool-catalog) for full documentation.
+
 ---
 
 ## MCP (Model Context Protocol) Integration
@@ -1730,4 +1830,4 @@ MIT License - See [LICENSE](./LICENSE) file.
 
 ---
 
-**Version:** 0.4.3 | **Last Updated:** 2026-02-25 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**
+**Version:** 0.4.4 | **Last Updated:** 2026-02-26 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**

package/dist/capabilities/agents/index.d.cts

@@ -1,4 +1,4 @@
-export { a2 as AfterToolContext, a3 as AgentEventName, w as AgentEvents, a4 as AgenticLoopEventName, a5 as AgenticLoopEvents, a6 as ApprovalResult, a7 as ApproveToolContext, z as AuditEntry, a8 as BeforeToolContext, b8 as ExecutionCompleteEvent, ah as ExecutionConfig, E as ExecutionContext, y as ExecutionMetrics, b9 as ExecutionStartEvent, v as HistoryMode, ai as Hook, H as HookConfig, aj as HookManager, D as HookName, ba as LLMRequestEvent, bb as LLMResponseEvent, as as ModifyingHook, bc as ToolCompleteEvent, aO as ToolModification, bd as ToolStartEvent } from '../../index-CEjKTeSb.cjs';
+export { a3 as AfterToolContext, a4 as AgentEventName, w as AgentEvents, a5 as AgenticLoopEventName, a6 as AgenticLoopEvents, a7 as ApprovalResult, a8 as ApproveToolContext, z as AuditEntry, a9 as BeforeToolContext, be as ExecutionCompleteEvent, al as ExecutionConfig, E as ExecutionContext, y as ExecutionMetrics, bf as ExecutionStartEvent, v as HistoryMode, am as Hook, H as HookConfig, an as HookManager, D as HookName, bg as LLMRequestEvent, bh as LLMResponseEvent, aw as ModifyingHook, bi as ToolCompleteEvent, aU as ToolModification, bj as ToolStartEvent } from '../../index-CsQOVhqe.cjs';
 import '../../IProvider-B8sqUzJG.cjs';
 import '../../Vendor-DYh_bzwo.cjs';
 import 'eventemitter3';

package/dist/capabilities/agents/index.d.ts

@@ -1,4 +1,4 @@
-export { a2 as AfterToolContext, a3 as AgentEventName, w as AgentEvents, a4 as AgenticLoopEventName, a5 as AgenticLoopEvents, a6 as ApprovalResult, a7 as ApproveToolContext, z as AuditEntry, a8 as BeforeToolContext, b8 as ExecutionCompleteEvent, ah as ExecutionConfig, E as ExecutionContext, y as ExecutionMetrics, b9 as ExecutionStartEvent, v as HistoryMode, ai as Hook, H as HookConfig, aj as HookManager, D as HookName, ba as LLMRequestEvent, bb as LLMResponseEvent, as as ModifyingHook, bc as ToolCompleteEvent, aO as ToolModification, bd as ToolStartEvent } from '../../index-CzGnmqOs.js';
+export { a3 as AfterToolContext, a4 as AgentEventName, w as AgentEvents, a5 as AgenticLoopEventName, a6 as AgenticLoopEvents, a7 as ApprovalResult, a8 as ApproveToolContext, z as AuditEntry, a9 as BeforeToolContext, be as ExecutionCompleteEvent, al as ExecutionConfig, E as ExecutionContext, y as ExecutionMetrics, bf as ExecutionStartEvent, v as HistoryMode, am as Hook, H as HookConfig, an as HookManager, D as HookName, bg as LLMRequestEvent, bh as LLMResponseEvent, aw as ModifyingHook, bi as ToolCompleteEvent, aU as ToolModification, bj as ToolStartEvent } from '../../index-C6ApwIzB.js';
 import '../../IProvider-CxDUGl6n.js';
 import '../../Vendor-DYh_bzwo.js';
 import 'eventemitter3';