@everworker/oneringai 0.1.3 → 0.2.0

package/README.md

@@ -18,10 +18,10 @@
   - [4. Session Persistence](#4-session-persistence)
   - [5. Working Memory](#5-working-memory)
   - [6. Research with Search Tools](#6-research-with-search-tools)
-  - [6. Context Management](#6-context-management)
-  - [7. InContextMemory](#7-incontextmemory)
-  - [8. Persistent Instructions](#8-persistent-instructions)
-  - [9. Direct LLM Access](#9-direct-llm-access)
+  - [7. Context Management](#7-context-management)
+  - [8. InContextMemory](#8-incontextmemory)
+  - [9. Persistent Instructions](#9-persistent-instructions)
+  - [10. Direct LLM Access](#10-direct-llm-access)
   - [11. Audio Capabilities](#11-audio-capabilities)
   - [12. Model Registry](#12-model-registry)
   - [13. Streaming](#13-streaming)
@@ -67,11 +67,13 @@
 - 🎛️ **Dynamic Tool Management** - Enable/disable tools at runtime, namespaces, priority-based selection
 - 🔌 **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
 - 🤖 **Universal Agent** - ⚠️ *Deprecated* - Use `Agent` with plugins instead
 - 🤖 **Task Agents** - ⚠️ *Deprecated* - Use `Agent` with `WorkingMemoryPluginNextGen`
 - 🔬 **Research Agent** - ⚠️ *Deprecated* - Use `Agent` with search tools
 - 🎯 **Context Management** - Algorithmic compaction with tool-result-to-memory offloading
-- 📌 **InContextMemory** - NEW: Live key-value storage directly in LLM context for instant access
+- 📌 **InContextMemory** - Live key-value storage directly in LLM context with optional UI display (`showInUI`)
 - 📝 **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)
@@ -84,6 +86,8 @@
 - 🔄 **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.
+
 ## Quick Start
 
 ### Installation
@@ -359,6 +363,8 @@ const storage = createFileContextStorage('my-assistant');
 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
   tools: [weatherTool, emailTool],
   context: {
     features: {
@@ -605,7 +611,7 @@ await agent.run('Research AI developments in 2026 and store key findings');
 - 📝 **Working Memory** - Store findings with priority-based eviction
 - 🏗️ **Tiered Memory** - Raw → Summary → Findings pattern
 
-### 6. Context Management
+### 7. Context Management
 
 **AgentContextNextGen** is the modern, plugin-based context manager. It provides clean separation of concerns with composable plugins:
 
@@ -689,7 +695,7 @@ console.log(budget.available);           // Remaining tokens
 console.log(budget.utilizationPercent);  // Usage percentage
 ```
 
-### 7. InContextMemory
+### 8. InContextMemory
 
 Store key-value pairs **directly in context** for instant LLM access without retrieval calls:
 
@@ -711,6 +717,9 @@ const plugin = ctx.getPlugin('in_context_memory');
 plugin.set('current_state', 'Task processing state', { step: 2, status: 'active' });
 plugin.set('user_prefs', 'User preferences', { verbose: true }, 'high');
 
+// Store data with UI display - shown in the host app's sidebar panel
+plugin.set('dashboard', 'Progress dashboard', '## Progress\n- [x] Step 1\n- [ ] Step 2', 'normal', true);
+
 // LLM can use context_set/context_delete/context_list tools
 // Or access directly via plugin API
 const state = plugin.get('current_state');  // { step: 2, status: 'active' }
@@ -720,9 +729,11 @@ const state = plugin.get('current_state');  // { step: 2, status: 'active' }
 - **WorkingMemory**: External storage + index → requires `memory_retrieve()` for values
 - **InContextMemory**: Full values in context → instant access, no retrieval needed
 
-**Use cases:** Session state, user preferences, counters, flags, small accumulated results.
+**UI Display (`showInUI`):** Entries with `showInUI: true` are displayed in the host application's sidebar panel with full markdown rendering (code blocks, tables, charts, diagrams, etc.). The LLM sets this via the `context_set` tool. Users can also pin specific entries to always display them regardless of the agent's setting. See the [User Guide](./USER_GUIDE.md#ui-display-showInUI) for details.
 
-### 8. Persistent Instructions
+**Use cases:** Session state, user preferences, counters, flags, small accumulated results, live dashboards.
+
+### 9. Persistent Instructions
 
 Store agent-level custom instructions that persist across sessions on disk:
 
@@ -758,7 +769,7 @@ const agent = Agent.create({
 
 **Use cases:** Agent personality/behavior, user preferences, learned rules, tool usage patterns.
 
-### 9. Direct LLM Access
+### 10. Direct LLM Access
 
 Bypass all context management for simple, stateless LLM calls:
 
@@ -973,22 +984,25 @@ Connector.create({
 });
 
 // Generate tools from the connector
-// Tools are prefixed with connector name: github_api, github_list_repos, etc.
+// GitHub connectors get 7 dedicated tools + generic API automatically:
+// search_files, search_code, read_file, get_pr, pr_files, pr_comments, create_pr
 const tools = ConnectorTools.for('github');
 
-// Use with an agent
+// Use with an agent — userId flows to all tools automatically
 const agent = Agent.create({
   connector: 'openai',
   model: 'gpt-4',
+  userId: 'user-123',  // All tool API calls use this user's OAuth tokens
   tools: tools,
 });
 
-await agent.run('List all open issues in owner/repo');
+await agent.run('Find all TypeScript files in src/ and show me the entry point');
+await agent.run('Show me PR #42 and summarize the review comments');
 ```
 
 **Supported Services (35+):**
 - **Communication**: Slack, Discord, Microsoft Teams, Twilio
-- **Development**: GitHub, GitLab, Jira, Linear, Bitbucket
+- **Development**: GitHub *(7 built-in tools)*, GitLab, Jira, Linear, Bitbucket
 - **Productivity**: Notion, Asana, Monday, Airtable, Trello
 - **CRM**: Salesforce, HubSpot, Zendesk, Intercom
 - **Payments**: Stripe, PayPal, Square
@@ -1225,21 +1239,21 @@ See [MCP_INTEGRATION.md](./MCP_INTEGRATION.md) for complete documentation.
 
 ```bash
 # Basic examples
-npm run example:basic              # Simple text generation
-npm run example:streaming          # Streaming responses
+npm run example:text               # Simple text generation
+npm run example:agent              # Basic agent with tools
+npm run example:conversation       # Multi-turn conversation
+npm run example:chat               # Interactive chat
 npm run example:vision             # Image analysis
-npm run example:tools              # Tool calling
-
-# Audio examples
-npm run example:audio              # TTS and STT demo
+npm run example:providers          # Multi-provider comparison
 
-# Task Agent examples
-npm run example:task-agent         # Basic task agent
-npm run example:task-agent-demo    # Full demo with memory
-npm run example:planning-agent     # AI-driven planning
+# Tools and hooks
+npm run example:json-tool          # JSON manipulation tool
+npm run example:hooks              # Agent lifecycle hooks
+npm run example:web                # Web research agent
 
-# Context management
-npm run example:context-management # All strategies demo
+# OAuth examples
+npm run example:oauth              # OAuth demo
+npm run example:oauth-registry     # OAuth registry
 ```
 
 ## Development
@@ -1301,4 +1315,4 @@ MIT License - See [LICENSE](./LICENSE) file.
 
 ---
 
-**Version:** 0.1.3 | **Last Updated:** 2026-02-07 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**
+**Version:** 0.2.0 | **Last Updated:** 2026-02-09 | **[User Guide](./USER_GUIDE.md)** | **[API Reference](./API_REFERENCE.md)** | **[Changelog](./CHANGELOG.md)**

package/dist/{ImageModel-BkAX5Rr5.d.ts → IProvider-DcYJ3YE-.d.ts}

@@ -1,34 +1,4 @@
-import { I as IProvider } from './IProvider-BP49c93d.js';
-
-/**
- * Supported AI Vendors
- *
- * Use this enum instead of string literals for type safety.
- * These map to specific provider implementations.
- */
-declare const Vendor: {
-    readonly OpenAI: "openai";
-    readonly Anthropic: "anthropic";
-    readonly Google: "google";
-    readonly GoogleVertex: "google-vertex";
-    readonly Groq: "groq";
-    readonly Together: "together";
-    readonly Perplexity: "perplexity";
-    readonly Grok: "grok";
-    readonly DeepSeek: "deepseek";
-    readonly Mistral: "mistral";
-    readonly Ollama: "ollama";
-    readonly Custom: "custom";
-};
-type Vendor = (typeof Vendor)[keyof typeof Vendor];
-/**
- * All vendor values as array (useful for validation)
- */
-declare const VENDORS: ("openai" | "anthropic" | "google" | "google-vertex" | "groq" | "together" | "perplexity" | "grok" | "deepseek" | "mistral" | "ollama" | "custom")[];
-/**
- * Check if a string is a valid vendor
- */
-declare function isVendor(value: string): value is Vendor;
+import { V as Vendor } from './Vendor-DYh_bzwo.js';
 
 /**
  * Connector - Represents authenticated connection to ANY API
@@ -72,6 +42,8 @@ interface OAuthConnectorAuth {
     audience?: string;
     refreshBeforeExpiry?: number;
     storageKey?: string;
+    /** Vendor-specific extra credentials */
+    extra?: Record<string, string>;
 }
 /**
  * Static API key authentication
@@ -82,6 +54,11 @@ interface APIKeyConnectorAuth {
     apiKey: string;
     headerName?: string;
     headerPrefix?: string;
+    /**
+     * Vendor-specific extra credentials beyond the primary API key.
+     * E.g., Slack Socket Mode needs { appToken: 'xapp-...', signingSecret: '...' }
+     */
+    extra?: Record<string, string>;
 }
 /**
  * JWT Bearer token authentication
@@ -97,6 +74,8 @@ interface JWTConnectorAuth {
     issuer?: string;
     subject?: string;
     audience?: string;
+    /** Vendor-specific extra credentials */
+    extra?: Record<string, string>;
 }
 /**
  * Complete connector configuration
@@ -503,336 +482,24 @@ declare class Connector {
 }
 
 /**
- * Shared types used across all multimodal capabilities
- * This file provides the foundation for Image, Audio, and Video model registries
- */
-
-/**
- * Aspect ratios - normalized across all visual modalities (images, video)
- */
-type AspectRatio$1 = '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '21:9' | '3:2' | '2:3';
-/**
- * Quality levels - normalized across vendors
- * Providers map these to vendor-specific quality settings
- */
-type QualityLevel = 'draft' | 'standard' | 'high' | 'ultra';
-/**
- * Audio output formats
- */
-type AudioFormat = 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm' | 'ogg';
-/**
- * Output format preference for media
- */
-type OutputFormat = 'url' | 'base64' | 'buffer';
-/**
- * Source links for model documentation and maintenance
- * Used to track where information came from and when it was last verified
- */
-interface ISourceLinks {
-    /** Official documentation URL */
-    documentation: string;
-    /** Pricing page URL */
-    pricing?: string;
-    /** API reference URL */
-    apiReference?: string;
-    /** Additional reference (e.g., blog post, announcement) */
-    additional?: string;
-    /** Last verified date (YYYY-MM-DD) */
-    lastVerified: string;
-}
-/**
- * Vendor-specific option schema for validation and documentation
- * Used to describe vendor-specific options that fall outside semantic options
- */
-interface VendorOptionSchema {
-    /** Data type of the option */
-    type: 'string' | 'number' | 'boolean' | 'enum' | 'array';
-    /** Description of the option */
-    description: string;
-    /** Whether the option is required */
-    required?: boolean;
-    /** UI display label */
-    label?: string;
-    /** Valid values for enum/string types */
-    enum?: string[];
-    /** Default value */
-    default?: unknown;
-    /** Minimum value for numbers */
-    min?: number;
-    /** Maximum value for numbers */
-    max?: number;
-    /** Step value for number sliders */
-    step?: number;
-    /** UI control type hint */
-    controlType?: 'select' | 'radio' | 'slider' | 'checkbox' | 'text' | 'textarea';
-}
-/**
- * Base model description - shared by all registries
- * Every model registry (Image, TTS, STT, Video) extends this
- */
-interface IBaseModelDescription {
-    /** Model identifier (e.g., "dall-e-3", "tts-1") */
-    name: string;
-    /** Display name for UI (e.g., "DALL-E 3", "TTS-1") */
-    displayName: string;
-    /** Vendor/provider */
-    provider: Vendor;
-    /** Model description */
-    description?: string;
-    /** Whether the model is currently available */
-    isActive: boolean;
-    /** Release date (YYYY-MM-DD) */
-    releaseDate?: string;
-    /** Deprecation date if scheduled (YYYY-MM-DD) */
-    deprecationDate?: string;
-    /** Documentation/pricing links for maintenance */
-    sources: ISourceLinks;
-}
-
-/**
- * Image generation provider interface
- */
-
-interface ImageGenerateOptions {
-    model: string;
-    prompt: string;
-    size?: string;
-    aspectRatio?: string;
-    quality?: 'standard' | 'hd' | 'low' | 'medium' | 'high' | 'auto';
-    style?: 'vivid' | 'natural';
-    n?: number;
-    response_format?: 'url' | 'b64_json';
-}
-interface ImageEditOptions {
-    model: string;
-    image: Buffer | string;
-    prompt: string;
-    mask?: Buffer | string;
-    size?: string;
-    n?: number;
-    response_format?: 'url' | 'b64_json';
-}
-interface ImageVariationOptions {
-    model: string;
-    image: Buffer | string;
-    n?: number;
-    size?: string;
-    response_format?: 'url' | 'b64_json';
-}
-interface ImageResponse {
-    created: number;
-    data: Array<{
-        url?: string;
-        b64_json?: string;
-        revised_prompt?: string;
-    }>;
-}
-interface IImageProvider extends IProvider {
-    /**
-     * Generate images from text prompt
-     */
-    generateImage(options: ImageGenerateOptions): Promise<ImageResponse>;
-    /**
-     * Edit an existing image (optional - not all providers support)
-     */
-    editImage?(options: ImageEditOptions): Promise<ImageResponse>;
-    /**
-     * Create variations of an image (optional)
-     */
-    createVariation?(options: ImageVariationOptions): Promise<ImageResponse>;
-    /**
-     * List available models
-     */
-    listModels?(): Promise<string[]>;
-}
-
-/**
- * Options for creating an ImageGeneration instance
- */
-interface ImageGenerationCreateOptions {
-    /** Connector name or instance */
-    connector: string | Connector;
-}
-/**
- * Simplified options for quick generation
+ * Base provider interface
  */
-interface SimpleGenerateOptions {
-    /** Text prompt describing the image */
-    prompt: string;
-    /** Model to use (defaults to vendor's best model) */
-    model?: string;
-    /** Image size */
-    size?: string;
-    /** Quality setting */
-    quality?: 'standard' | 'hd';
-    /** Style setting (DALL-E 3 only) */
-    style?: 'vivid' | 'natural';
-    /** Number of images to generate */
-    n?: number;
-    /** Response format */
-    response_format?: 'url' | 'b64_json';
+interface ProviderCapabilities {
+    text: boolean;
+    images: boolean;
+    videos: boolean;
+    audio: boolean;
+    /** Optional feature flags for specific capabilities */
+    features?: Record<string, boolean>;
 }
-/**
- * ImageGeneration capability class
- */
-declare class ImageGeneration {
-    private provider;
-    private connector;
-    private defaultModel;
-    private constructor();
-    /**
-     * Create an ImageGeneration instance
-     */
-    static create(options: ImageGenerationCreateOptions): ImageGeneration;
-    /**
-     * Generate images from a text prompt
-     */
-    generate(options: SimpleGenerateOptions): Promise<ImageResponse>;
-    /**
-     * Edit an existing image
-     * Note: Not all models/vendors support this
-     */
-    edit(options: ImageEditOptions): Promise<ImageResponse>;
-    /**
-     * Create variations of an existing image
-     * Note: Only DALL-E 2 supports this
-     */
-    createVariation(options: ImageVariationOptions): Promise<ImageResponse>;
-    /**
-     * List available models for this provider
-     */
-    listModels(): Promise<string[]>;
-    /**
-     * Get information about a specific model
-     */
-    getModelInfo(modelName: string): IImageModelDescription | undefined;
-    /**
-     * Get the underlying provider
-     */
-    getProvider(): IImageProvider;
-    /**
-     * Get the current connector
-     */
-    getConnector(): Connector;
-    /**
-     * Get the default model for this vendor
-     */
-    private getDefaultModel;
+interface IProvider {
+    readonly name: string;
+    readonly vendor?: string;
+    readonly capabilities: ProviderCapabilities;
     /**
-     * Get the default edit model for this vendor
+     * Validate that the provider configuration is correct
      */
-    private getEditModel;
-}
-
-/**
- * Image generation model registry with comprehensive metadata
- */
-
-/**
- * Supported image sizes by model
- */
-type ImageSize = '256x256' | '512x512' | '1024x1024' | '1024x1536' | '1536x1024' | '1792x1024' | '1024x1792' | 'auto';
-/**
- * Supported aspect ratios
- */
-type AspectRatio = '1:1' | '3:4' | '4:3' | '9:16' | '16:9' | '3:2' | '2:3';
-/**
- * Image model capabilities
- */
-interface ImageModelCapabilities {
-    /** Supported image sizes */
-    sizes: readonly ImageSize[];
-    /** Supported aspect ratios (Google) */
-    aspectRatios?: readonly AspectRatio[];
-    /** Maximum number of images per request */
-    maxImagesPerRequest: number;
-    /** Supported output formats */
-    outputFormats: readonly string[];
-    /** Feature support flags */
-    features: {
-        /** Text-to-image generation */
-        generation: boolean;
-        /** Image editing/inpainting */
-        editing: boolean;
-        /** Image variations */
-        variations: boolean;
-        /** Style control */
-        styleControl: boolean;
-        /** Quality control (standard/hd) */
-        qualityControl: boolean;
-        /** Transparent backgrounds */
-        transparency: boolean;
-        /** Prompt revision/enhancement */
-        promptRevision: boolean;
-    };
-    /** Model limits */
-    limits: {
-        /** Maximum prompt length in characters */
-        maxPromptLength: number;
-        /** Rate limit (requests per minute) */
-        maxRequestsPerMinute?: number;
-    };
-    /** Vendor-specific options schema */
-    vendorOptions?: Record<string, VendorOptionSchema>;
-}
-/**
- * Image model pricing
- */
-interface ImageModelPricing {
-    /** Cost per image at standard quality */
-    perImageStandard?: number;
-    /** Cost per image at HD quality */
-    perImageHD?: number;
-    /** Cost per image (flat rate) */
-    perImage?: number;
-    currency: 'USD';
-}
-/**
- * Complete image model description
- */
-interface IImageModelDescription extends IBaseModelDescription {
-    capabilities: ImageModelCapabilities;
-    pricing?: ImageModelPricing;
+    validateConfig(): Promise<boolean>;
 }
-declare const IMAGE_MODELS: {
-    readonly openai: {
-        /** GPT-Image-1: Latest OpenAI image model with best quality */
-        readonly GPT_IMAGE_1: "gpt-image-1";
-        /** DALL-E 3: High quality image generation */
-        readonly DALL_E_3: "dall-e-3";
-        /** DALL-E 2: Fast, supports editing and variations */
-        readonly DALL_E_2: "dall-e-2";
-    };
-    readonly google: {
-        /** Imagen 4.0: Latest Google image generation model */
-        readonly IMAGEN_4_GENERATE: "imagen-4.0-generate-001";
-        /** Imagen 4.0 Ultra: Highest quality */
-        readonly IMAGEN_4_ULTRA: "imagen-4.0-ultra-generate-001";
-        /** Imagen 4.0 Fast: Optimized for speed */
-        readonly IMAGEN_4_FAST: "imagen-4.0-fast-generate-001";
-    };
-    readonly grok: {
-        /** Grok Imagine Image: xAI image generation with editing support */
-        readonly GROK_IMAGINE_IMAGE: "grok-imagine-image";
-        /** Grok 2 Image: xAI image generation (text-only input) */
-        readonly GROK_2_IMAGE_1212: "grok-2-image-1212";
-    };
-};
-/**
- * Complete image model registry
- * Last full audit: January 2026
- */
-declare const IMAGE_MODEL_REGISTRY: Record<string, IImageModelDescription>;
-declare const getImageModelInfo: (modelName: string) => IImageModelDescription | undefined;
-declare const getImageModelsByVendor: (vendor: Vendor) => IImageModelDescription[];
-declare const getActiveImageModels: () => IImageModelDescription[];
-/**
- * Get image models that support a specific feature
- */
-declare function getImageModelsWithFeature(feature: keyof IImageModelDescription['capabilities']['features']): IImageModelDescription[];
-/**
- * Calculate estimated cost for image generation
- */
-declare function calculateImageCost(modelName: string, imageCount: number, quality?: 'standard' | 'hd'): number | null;
 
-export { type AudioFormat as A, type ImageGenerateOptions as B, type ConnectorAccessContext as C, type ImageEditOptions as D, type ImageVariationOptions as E, type ImageResponse as F, type AspectRatio$1 as G, type OutputFormat as H, type IConnectorRegistry as I, type JWTConnectorAuth as J, type ISourceLinks as K, DEFAULT_CONNECTOR_TIMEOUT as L, DEFAULT_MAX_RETRIES as M, DEFAULT_RETRYABLE_STATUSES as N, type OAuthConnectorAuth as O, DEFAULT_BASE_DELAY_MS as P, type QualityLevel as Q, DEFAULT_MAX_DELAY_MS as R, type StoredToken as S, type VendorOptionSchema as V, type IConnectorAccessPolicy as a, Connector as b, type IBaseModelDescription as c, Vendor as d, type IImageProvider as e, type ConnectorFetchOptions as f, type ITokenStorage as g, type ConnectorConfig as h, type ConnectorAuth as i, type ConnectorConfigResult as j, VENDORS as k, isVendor as l, ImageGeneration as m, type ImageGenerationCreateOptions as n, type SimpleGenerateOptions as o, type APIKeyConnectorAuth as p, type IImageModelDescription as q, type ImageModelCapabilities as r, type ImageModelPricing as s, IMAGE_MODELS as t, IMAGE_MODEL_REGISTRY as u, getImageModelInfo as v, getImageModelsByVendor as w, getActiveImageModels as x, getImageModelsWithFeature as y, calculateImageCost as z };
+export { type APIKeyConnectorAuth as A, type ConnectorAccessContext as C, DEFAULT_CONNECTOR_TIMEOUT as D, type IConnectorRegistry as I, type JWTConnectorAuth as J, type OAuthConnectorAuth as O, type ProviderCapabilities as P, type StoredToken as S, type IConnectorAccessPolicy as a, Connector as b, type IProvider as c, type ConnectorFetchOptions as d, type ITokenStorage as e, type ConnectorConfig as f, type ConnectorAuth as g, type ConnectorConfigResult as h, DEFAULT_MAX_RETRIES as i, DEFAULT_RETRYABLE_STATUSES as j, DEFAULT_BASE_DELAY_MS as k, DEFAULT_MAX_DELAY_MS as l };