@everworker/oneringai 0.4.2 → 0.4.4

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:
 
@@ -109,6 +114,9 @@ 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
 
@@ -788,6 +796,8 @@ const agent = Agent.create({
 | `workingMemory` | `true` | WorkingMemoryPluginNextGen | `memory_store/retrieve/delete/list` |
 | `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 +920,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
 
@@ -1290,13 +1307,75 @@ console.log(execution.status); // 'completed' | 'failed'
 ```
 
 **Key Features:**
-- 🔗 **Task Dependencies** - DAG-based ordering via `dependsOn`
-- 🧠 **Memory Bridging** - In-context memory (`context_set`) + working memory (`memory_store`) persist across tasks while conversation is cleared
-- 🔍 **LLM Validation** - Self-reflection against completion criteria with configurable score thresholds
-- 🔄 **Retry Logic** - Configurable `maxAttempts` per task with automatic retry on validation failure
-- 📊 **Progress Tracking** - Real-time callbacks and progress percentage
-- ⚙️ **Failure Modes** - `fail-fast` (default) or `continue` for independent tasks
-- 🎨 **Custom Prompts** - Override system, task, or validation prompts
+- **Task Dependencies** - DAG-based ordering via `dependsOn`
+- **Memory Bridging** - In-context memory (`context_set`) + working memory (`memory_store`) persist across tasks while conversation is cleared
+- **LLM Validation** - Self-reflection against completion criteria with configurable score thresholds
+- **Retry Logic** - Configurable `maxAttempts` per task with automatic retry on validation failure
+- **Smart Error Classification** - Permanent errors (auth, config, model-not-found) skip retry; transient errors retry normally
+- **Control Flow** - `map`, `fold`, and `until` flows with optional per-iteration timeout (`iterationTimeoutMs`)
+- **Progress Tracking** - Real-time callbacks and progress percentage
+- **Failure Modes** - `fail-fast` (default) or `continue` for independent tasks
+- **Custom Prompts** - Override system, task, or validation prompts
+- **`ROUTINE_KEYS` export** - Well-known ICM/WM key constants for custom integrations
+
+**Control Flow with Timeout:**
+
+```typescript
+const routine = createRoutineDefinition({
+  name: 'Process Batch',
+  tasks: [{
+    name: 'Process Each',
+    description: 'Process each item',
+    controlFlow: {
+      type: 'map',
+      source: '__items',
+      resultKey: '__results',
+      iterationTimeoutMs: 60000, // 1 min per item
+      tasks: [{ name: 'Process', description: 'Handle the current item' }],
+    },
+  }],
+});
+```
+
+**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`.
 
@@ -1560,6 +1639,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
@@ -1708,4 +1827,4 @@ MIT License - See [LICENSE](./LICENSE) file.
 
 ---
 
-**Version:** 0.4.2 | **Last Updated:** 2026-02-22 | **[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/{IProvider-CNJqZItJ.d.cts → IProvider-B8sqUzJG.d.cts}

@@ -204,6 +204,13 @@ interface ITokenStorage {
      * @returns True if token exists
      */
     hasToken(key: string): Promise<boolean>;
+    /**
+     * List all storage keys (for account enumeration).
+     * Optional — implementations that support it enable multi-account listing.
+     *
+     * @returns Array of all stored token keys
+     */
+    listKeys?(): Promise<string[]>;
 }
 
 /**
@@ -406,22 +413,43 @@ declare class Connector {
     /**
      * Get the current access token (for OAuth, JWT, or API key)
      * Handles automatic refresh if needed
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support (e.g., 'work', 'personal')
      */
-    getToken(userId?: string): Promise<string>;
+    getToken(userId?: string, accountId?: string): Promise<string>;
     /**
      * Start OAuth authorization flow
      * Returns the URL to redirect the user to
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support (e.g., 'work', 'personal')
      */
-    startAuth(userId?: string): Promise<string>;
+    startAuth(userId?: string, accountId?: string): Promise<string>;
     /**
      * Handle OAuth callback
      * Call this after user is redirected back from OAuth provider
+     *
+     * @param callbackUrl - Full callback URL with code and state parameters
+     * @param userId - Optional user identifier (can be extracted from state if embedded)
+     * @param accountId - Optional account alias (can be extracted from state if embedded)
      */
-    handleCallback(callbackUrl: string, userId?: string): Promise<void>;
+    handleCallback(callbackUrl: string, userId?: string, accountId?: string): Promise<void>;
     /**
      * Check if the connector has a valid token
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support
+     */
+    hasValidToken(userId?: string, accountId?: string): Promise<boolean>;
+    /**
+     * List account aliases for a user on this connector.
+     * Only applicable for OAuth connectors with multi-account support.
+     *
+     * @param userId - Optional user identifier
+     * @returns Array of account aliases (e.g., ['work', 'personal'])
      */
-    hasValidToken(userId?: string): Promise<boolean>;
+    listAccounts(userId?: string): Promise<string[]>;
     /**
      * Get vendor-specific options from config
      */
@@ -457,9 +485,10 @@ declare class Connector {
      * @param endpoint - API endpoint (relative to baseURL) or full URL
      * @param options - Fetch options with connector-specific settings
      * @param userId - Optional user ID for multi-user OAuth
+     * @param accountId - Optional account alias for multi-account OAuth
      * @returns Fetch Response
      */
-    fetch(endpoint: string, options?: ConnectorFetchOptions, userId?: string): Promise<Response>;
+    fetch(endpoint: string, options?: ConnectorFetchOptions, userId?: string, accountId?: string): Promise<Response>;
     /**
      * Make an authenticated fetch request and parse JSON response
      * Throws on non-OK responses
@@ -467,9 +496,10 @@ declare class Connector {
      * @param endpoint - API endpoint (relative to baseURL) or full URL
      * @param options - Fetch options with connector-specific settings
      * @param userId - Optional user ID for multi-user OAuth
+     * @param accountId - Optional account alias for multi-account OAuth
      * @returns Parsed JSON response
      */
-    fetchJSON<T = unknown>(endpoint: string, options?: ConnectorFetchOptions, userId?: string): Promise<T>;
+    fetchJSON<T = unknown>(endpoint: string, options?: ConnectorFetchOptions, userId?: string, accountId?: string): Promise<T>;
     private sleep;
     private logRequest;
     private logResponse;

package/dist/{IProvider-B6hqVVq8.d.ts → IProvider-CxDUGl6n.d.ts}

@@ -204,6 +204,13 @@ interface ITokenStorage {
      * @returns True if token exists
      */
     hasToken(key: string): Promise<boolean>;
+    /**
+     * List all storage keys (for account enumeration).
+     * Optional — implementations that support it enable multi-account listing.
+     *
+     * @returns Array of all stored token keys
+     */
+    listKeys?(): Promise<string[]>;
 }
 
 /**
@@ -406,22 +413,43 @@ declare class Connector {
     /**
      * Get the current access token (for OAuth, JWT, or API key)
      * Handles automatic refresh if needed
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support (e.g., 'work', 'personal')
      */
-    getToken(userId?: string): Promise<string>;
+    getToken(userId?: string, accountId?: string): Promise<string>;
     /**
      * Start OAuth authorization flow
      * Returns the URL to redirect the user to
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support (e.g., 'work', 'personal')
      */
-    startAuth(userId?: string): Promise<string>;
+    startAuth(userId?: string, accountId?: string): Promise<string>;
     /**
      * Handle OAuth callback
      * Call this after user is redirected back from OAuth provider
+     *
+     * @param callbackUrl - Full callback URL with code and state parameters
+     * @param userId - Optional user identifier (can be extracted from state if embedded)
+     * @param accountId - Optional account alias (can be extracted from state if embedded)
      */
-    handleCallback(callbackUrl: string, userId?: string): Promise<void>;
+    handleCallback(callbackUrl: string, userId?: string, accountId?: string): Promise<void>;
     /**
      * Check if the connector has a valid token
+     *
+     * @param userId - Optional user identifier for multi-user support
+     * @param accountId - Optional account alias for multi-account support
+     */
+    hasValidToken(userId?: string, accountId?: string): Promise<boolean>;
+    /**
+     * List account aliases for a user on this connector.
+     * Only applicable for OAuth connectors with multi-account support.
+     *
+     * @param userId - Optional user identifier
+     * @returns Array of account aliases (e.g., ['work', 'personal'])
      */
-    hasValidToken(userId?: string): Promise<boolean>;
+    listAccounts(userId?: string): Promise<string[]>;
     /**
      * Get vendor-specific options from config
      */
@@ -457,9 +485,10 @@ declare class Connector {
      * @param endpoint - API endpoint (relative to baseURL) or full URL
      * @param options - Fetch options with connector-specific settings
      * @param userId - Optional user ID for multi-user OAuth
+     * @param accountId - Optional account alias for multi-account OAuth
      * @returns Fetch Response
      */
-    fetch(endpoint: string, options?: ConnectorFetchOptions, userId?: string): Promise<Response>;
+    fetch(endpoint: string, options?: ConnectorFetchOptions, userId?: string, accountId?: string): Promise<Response>;
     /**
      * Make an authenticated fetch request and parse JSON response
      * Throws on non-OK responses
@@ -467,9 +496,10 @@ declare class Connector {
      * @param endpoint - API endpoint (relative to baseURL) or full URL
      * @param options - Fetch options with connector-specific settings
      * @param userId - Optional user ID for multi-user OAuth
+     * @param accountId - Optional account alias for multi-account OAuth
      * @returns Parsed JSON response
      */
-    fetchJSON<T = unknown>(endpoint: string, options?: ConnectorFetchOptions, userId?: string): Promise<T>;
+    fetchJSON<T = unknown>(endpoint: string, options?: ConnectorFetchOptions, userId?: string, accountId?: string): Promise<T>;
     private sleep;
     private logRequest;
     private logResponse;

package/dist/{ImageModel-B64HX3lN.d.cts → ImageModel-Ds5_6sf7.d.cts}

@@ -1,4 +1,4 @@
-import { e as IProvider, b as Connector } from './IProvider-CNJqZItJ.cjs';
+import { e as IProvider, b as Connector } from './IProvider-B8sqUzJG.cjs';
 import { V as Vendor } from './Vendor-DYh_bzwo.cjs';
 
 /**

package/dist/{ImageModel-DU-y_WOb.d.ts → ImageModel-OWbA277F.d.ts}

@@ -1,4 +1,4 @@
-import { e as IProvider, b as Connector } from './IProvider-B6hqVVq8.js';
+import { e as IProvider, b as Connector } from './IProvider-CxDUGl6n.js';
 import { V as Vendor } from './Vendor-DYh_bzwo.js';
 
 /**

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

@@ -1,4 +1,4 @@
-export { y as AfterToolContext, z as AgentEventName, A as AgentEvents, B as AgenticLoopEventName, D as AgenticLoopEvents, G as ApprovalResult, J as ApproveToolContext, m as AuditEntry, K as BeforeToolContext, aM as ExecutionCompleteEvent, X as ExecutionConfig, E as ExecutionContext, l as ExecutionMetrics, aN as ExecutionStartEvent, j as HistoryMode, Y as Hook, H as HookConfig, Z as HookManager, n as HookName, aO as LLMRequestEvent, aP as LLMResponseEvent, a6 as ModifyingHook, aQ as ToolCompleteEvent, aq as ToolModification, aR as ToolStartEvent } from '../../index-BMjyFNJQ.cjs';
-import '../../IProvider-CNJqZItJ.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-DmYrHH7d.cjs';
+import '../../IProvider-B8sqUzJG.cjs';
 import '../../Vendor-DYh_bzwo.cjs';
 import 'eventemitter3';

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

@@ -1,4 +1,4 @@
-export { y as AfterToolContext, z as AgentEventName, A as AgentEvents, B as AgenticLoopEventName, D as AgenticLoopEvents, G as ApprovalResult, J as ApproveToolContext, m as AuditEntry, K as BeforeToolContext, aM as ExecutionCompleteEvent, X as ExecutionConfig, E as ExecutionContext, l as ExecutionMetrics, aN as ExecutionStartEvent, j as HistoryMode, Y as Hook, H as HookConfig, Z as HookManager, n as HookName, aO as LLMRequestEvent, aP as LLMResponseEvent, a6 as ModifyingHook, aQ as ToolCompleteEvent, aq as ToolModification, aR as ToolStartEvent } from '../../index-9VOnAX17.js';
-import '../../IProvider-B6hqVVq8.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-Dyl6pHfq.js';
+import '../../IProvider-CxDUGl6n.js';
 import '../../Vendor-DYh_bzwo.js';
 import 'eventemitter3';