@framers/agentos 0.1.12 → 0.1.14

package/README.md

@@ -126,117 +126,155 @@ yarn add @framers/agentos
 ## Quick Start
 
 ```typescript
-import { AgentOS } from '@framers/agentos';
+import { AgentOS, AgentOSResponseChunkType } from '@framers/agentos';
+import { createTestAgentOSConfig } from '@framers/agentos/config/AgentOSConfig';
 
-// Initialize
+// Initialize (local/dev defaults)
 const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: {
-    provider: 'openai',
-    apiKey: process.env.OPENAI_API_KEY,
-    model: 'gpt-4o'
-  }
-});
+await agent.initialize(await createTestAgentOSConfig());
 
 // Process requests with streaming
 for await (const chunk of agent.processRequest({
-  message: 'Help me analyze this data',
-  context: { userId: 'user-123' }
+  userId: 'user-123',
+  sessionId: 'session-123',
+  textInput: 'Help me analyze this data',
 })) {
-  if (chunk.type === 'content') {
-    process.stdout.write(chunk.content);
+  if (chunk.type === AgentOSResponseChunkType.TEXT_DELTA) {
+    process.stdout.write(chunk.textDelta);
   }
 }
 ```
 
-### With Tools
+### With Tools (Extension Packs)
 
 ```typescript
-import { AgentOS } from '@framers/agentos';
-
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: {
-    provider: 'openai',
-    apiKey: process.env.OPENAI_API_KEY,
-    model: 'gpt-4o'
-  },
-  tools: [{
-    name: 'get_weather',
-    description: 'Get current weather for a city',
-  parameters: {
+import {
+  AgentOS,
+  AgentOSResponseChunkType,
+  EXTENSION_KIND_TOOL,
+  type ExtensionManifest,
+  type ExtensionPack,
+  type ITool,
+} from '@framers/agentos';
+import { createTestAgentOSConfig } from '@framers/agentos/config/AgentOSConfig';
+
+const helloTool: ITool = {
+  id: 'hello-tool',
+  name: 'hello',
+  displayName: 'Hello',
+  description: 'Return a greeting.',
+  category: 'utility',
+  hasSideEffects: false,
+  inputSchema: {
     type: 'object',
-    properties: {
-        city: { type: 'string' }
-    },
-      required: ['city']
+    properties: { name: { type: 'string' } },
+    required: ['name'],
   },
-    execute: async ({ city }) => {
-      const res = await fetch(`https://api.weather.com/${city}`);
-      return res.json();
-    }
-  }]
-});
+  execute: async (args, _ctx) => {
+    const name = typeof args.name === 'string' ? args.name : String(args.name);
+    return { success: true, output: { text: `Hello, ${name}!` } };
+  },
+};
+
+const manifest: ExtensionManifest = {
+  packs: [
+    {
+      factory: async () =>
+        ({
+          name: 'local-tools',
+          descriptors: [{ id: helloTool.id, kind: EXTENSION_KIND_TOOL, payload: helloTool }],
+        }) satisfies ExtensionPack,
+    },
+  ],
+};
+
+const agent = new AgentOS();
+const base = await createTestAgentOSConfig();
+await agent.initialize({ ...base, extensionManifest: manifest });
 
 // Tools are called automatically when the model decides to use them
-for await (const chunk of agent.processRequest({ message: 'Weather in Tokyo?' })) {
-  if (chunk.type === 'tool_call') console.log('Calling:', chunk.tool);
-  if (chunk.type === 'content') process.stdout.write(chunk.content);
-  }
+for await (const chunk of agent.processRequest({
+  userId: 'user-123',
+  sessionId: 'session-123',
+  textInput: 'Say hello to Ada.',
+})) {
+  if (chunk.type === AgentOSResponseChunkType.TEXT_DELTA) process.stdout.write(chunk.textDelta);
+}
 ```
 
 ### Multiple Providers
 
 ```typescript
-// OpenRouter for multi-model access
-await agent.initialize({
-  llmProvider: {
-    provider: 'openrouter',
-    apiKey: process.env.OPENROUTER_API_KEY,
-    model: 'anthropic/claude-3.5-sonnet'
-  }
-});
+import { AgentOS } from '@framers/agentos';
+import { createTestAgentOSConfig } from '@framers/agentos/config/AgentOSConfig';
+
+const agent = new AgentOS();
+const base = await createTestAgentOSConfig();
 
-// Local Ollama
 await agent.initialize({
-  llmProvider: {
-    provider: 'ollama',
-    baseUrl: 'http://localhost:11434',
-    model: 'llama3'
-  }
+  ...base,
+  modelProviderManagerConfig: {
+    providers: [
+      { providerId: 'openai', enabled: true, isDefault: true, config: { apiKey: process.env.OPENAI_API_KEY } },
+      { providerId: 'openrouter', enabled: true, config: { apiKey: process.env.OPENROUTER_API_KEY } },
+      { providerId: 'ollama', enabled: true, config: { baseUrl: 'http://localhost:11434' } },
+    ],
+  },
+  gmiManagerConfig: {
+    ...base.gmiManagerConfig,
+    defaultGMIBaseConfigDefaults: {
+      ...(base.gmiManagerConfig.defaultGMIBaseConfigDefaults ?? {}),
+      defaultLlmProviderId: 'openai',
+      defaultLlmModelId: 'gpt-4o',
+    },
+  },
 });
 ```
 
-### With RAG Memory
+### RAG (RetrievalAugmentor)
 
-```typescript
-import { AgentOS } from '@framers/agentos';
+AgentOS supports embedding-based retrieval via `IRetrievalAugmentor` (vector RAG, optional GraphRAG). You can either:
 
-const agent = new AgentOS();
-await agent.initialize({
-  llmProvider: {
-    provider: 'openai',
-    apiKey: process.env.OPENAI_API_KEY,
-    model: 'gpt-4o'
-  },
-  memory: {
-    vectorStore: 'memory', // or 'sqlite', 'postgres'
-    embeddingModel: 'text-embedding-3-small'
-  }
-});
+- pass a ready augmentor via `AgentOSConfig.retrievalAugmentor`, or
+- let AgentOS initialize it via `AgentOSConfig.ragConfig`
 
-// Ingest documents
-await agent.memory.ingest([
-  { content: 'AgentOS supports streaming responses...', metadata: { source: 'docs' } },
-  { content: 'GMIs maintain context across sessions...', metadata: { source: 'docs' } }
-]);
+See `docs/RAG_MEMORY_CONFIGURATION.md` for full setup details.
 
-// Queries automatically retrieve relevant context
-for await (const chunk of agent.processRequest({ 
-  message: 'How does streaming work?' 
-})) {
-  process.stdout.write(chunk.content);
-}
+```ts
+import { AgentOS } from '@framers/agentos';
+import { createTestAgentOSConfig } from '@framers/agentos/config/AgentOSConfig';
+
+const agentos = new AgentOS();
+const base = await createTestAgentOSConfig();
+await agentos.initialize({
+  ...base,
+  ragConfig: {
+    embeddingManagerConfig: {
+      embeddingModels: [
+        { modelId: 'text-embedding-3-small', providerId: 'openai', dimension: 1536, isDefault: true },
+      ],
+    },
+    vectorStoreManagerConfig: {
+      managerId: 'rag-vsm',
+      providers: [{ id: 'sql-store', type: 'sql', storage: { filePath: './data/agentos_vectors.db' } }],
+      defaultProviderId: 'sql-store',
+      defaultEmbeddingDimension: 1536,
+    },
+    dataSourceConfigs: [
+      {
+        dataSourceId: 'voice_conversation_summaries',
+        displayName: 'Conversation Summaries',
+        vectorStoreProviderId: 'sql-store',
+        actualNameInProvider: 'voice_conversation_summaries',
+        embeddingDimension: 1536,
+      },
+    ],
+    retrievalAugmentorConfig: {
+      defaultDataSourceId: 'voice_conversation_summaries',
+      categoryBehaviors: [],
+    },
+  },
+});
 ```
 
 ### Immutability & Provenance (Optional)
@@ -270,6 +308,10 @@ const provenancePack = createProvenancePack(
 
 **Sealed conversation persistence:** when using `sealed` storage policy with SQL conversation persistence, set `ConversationManagerConfig.appendOnlyPersistence=true` so conversation history remains append-only (no UPDATE/DELETE/UPSERT on protected tables).
 
+**Toolset pinning (recommended):** treat the enabled toolset as part of the sealed spec. Disable dynamic tool registration and (optionally) store a toolset manifest hash at seal time so you can verify you’re running the same tools/versions later.
+
+**“Forgetting” memory in sealed mode:** avoid hard deletes. Prefer append-only **redaction/tombstone** events that remove items from retrieval while keeping an auditable trail.
+
 ---
 
 ## Architecture
@@ -359,6 +401,7 @@ Supported platforms: `telegram`, `whatsapp`, `discord`, `slack`, `webchat`, `sig
 | Guide | Description |
 |-------|-------------|
 | [Cost Optimization](./docs/COST_OPTIMIZATION.md) | Token usage and cost management |
+| [Observability](./docs/OBSERVABILITY.md) | OpenTelemetry spans and trace/log correlation (opt-in) |
 | [Platform Support](./docs/PLATFORM_SUPPORT.md) | Supported platforms and environments |
 | [Releasing](./docs/RELEASING.md) | How to publish new versions |
 | [API Reference](./docs/api/index.html) | TypeDoc-generated API docs |

package/dist/api/AgentOS.d.ts

@@ -52,12 +52,17 @@ import { ConversationManagerConfig } from '../core/conversation/ConversationMana
 import { ConversationContext } from '../core/conversation/ConversationContext';
 import type { IRollingSummaryMemorySink } from '../core/conversation/IRollingSummaryMemorySink';
 import type { ILongTermMemoryRetriever } from '../core/conversation/ILongTermMemoryRetriever';
+import type { IRetrievalAugmentor } from '../rag/IRetrievalAugmentor';
+import type { EmbeddingManagerConfig } from '../config/EmbeddingManagerConfiguration';
+import type { RetrievalAugmentorServiceConfig } from '../config/RetrievalAugmentorConfiguration';
+import type { RagDataSourceConfig, VectorStoreManagerConfig } from '../config/VectorStoreConfiguration';
 import type { PrismaClient } from '../stubs/prismaClient.js';
 import type { StorageAdapter } from '@framers/sql-storage-adapter';
 import { IPersonaDefinition } from '../cognitive_substrate/personas/IPersonaDefinition';
 import { StreamingManagerConfig, StreamId } from '../core/streaming/StreamingManager';
 import { GMIError, GMIErrorCode } from '../utils/errors';
 import { ILogger } from '../logging/ILogger';
+import { type AgentOSObservabilityConfig } from '../core/observability/otel';
 import type { IGuardrailService } from '../core/guardrails/IGuardrailService';
 import type { IPersonaLoader } from '../cognitive_substrate/personas/IPersonaLoader';
 import { type ExtensionManifest, type ExtensionOverrides } from '../extensions';
@@ -137,6 +142,59 @@ export interface AgentOSConfig {
      * (e.g. user/org/persona memories stored in a RAG/KG).
      */
     longTermMemoryRetriever?: ILongTermMemoryRetriever;
+    /**
+     * Optional retrieval augmentor enabling vector-based RAG and/or GraphRAG.
+     * When provided, it is passed into GMIs via the GMIManager.
+     *
+     * Notes:
+     * - This is separate from `longTermMemoryRetriever`, which injects pre-formatted
+     *   memory text into prompts.
+     * - The augmentor instance is typically shared across GMIs; do not shut it down
+     *   from individual GMIs.
+     */
+    retrievalAugmentor?: IRetrievalAugmentor;
+    /**
+     * If true, AgentOS will call `retrievalAugmentor.shutdown()` during `AgentOS.shutdown()`.
+     * Default: false (caller manages lifecycle).
+     */
+    manageRetrievalAugmentorLifecycle?: boolean;
+    /**
+     * Optional configuration for AgentOS-managed RAG subsystem initialization.
+     *
+     * When provided and enabled, AgentOS will:
+     * - Initialize an {@link EmbeddingManager} with {@link EmbeddingManagerConfig}
+     * - Initialize a {@link VectorStoreManager} with {@link VectorStoreManagerConfig} + {@link RagDataSourceConfig}
+     * - Initialize a {@link RetrievalAugmentor} with {@link RetrievalAugmentorServiceConfig}
+     * - Pass the resulting {@link IRetrievalAugmentor} into GMIs via the {@link GMIManager}
+     *
+     * Notes:
+     * - If `retrievalAugmentor` is provided, it takes precedence and this config is ignored.
+     * - By default, when AgentOS creates the RAG subsystem it also manages lifecycle and will
+     *   shut it down during {@link AgentOS.shutdown}.
+     */
+    ragConfig?: {
+        /** Enable or disable AgentOS-managed RAG initialization. Default: true. */
+        enabled?: boolean;
+        /** Embedding manager configuration (must include at least one embedding model). */
+        embeddingManagerConfig: EmbeddingManagerConfig;
+        /** Vector store manager configuration (providers). */
+        vectorStoreManagerConfig: VectorStoreManagerConfig;
+        /** Logical data sources mapped onto vector store providers. */
+        dataSourceConfigs: RagDataSourceConfig[];
+        /** Retrieval augmentor configuration (category behaviors, defaults). */
+        retrievalAugmentorConfig: RetrievalAugmentorServiceConfig;
+        /**
+         * If true, AgentOS will shut down the augmentor and any owned vector store providers
+         * during {@link AgentOS.shutdown}. Default: true.
+         */
+        manageLifecycle?: boolean;
+        /**
+         * When true (default), AgentOS injects its `storageAdapter` into SQL vector-store providers
+         * that did not specify `adapter` or `storage`. This keeps vector persistence colocated with
+         * the host database by default.
+         */
+        bindToStorageAdapter?: boolean;
+    };
     /** Configuration for the {@link PromptEngine}. */
     promptEngineConfig: PromptEngineConfig;
     /** Configuration for the {@link ToolOrchestrator}. */
@@ -176,6 +234,24 @@ export interface AgentOSConfig {
     guardrailService?: IGuardrailService;
     /** Optional map of secretId -> value for extension/tool credentials. */
     extensionSecrets?: Record<string, string>;
+    /**
+     * Optional: enable schema-on-demand meta tools for lazy tool schema loading.
+     *
+     * When enabled, AgentOS registers three meta tools:
+     * - `extensions_list`
+     * - `extensions_enable` (side effects)
+     * - `extensions_status`
+     *
+     * These tools allow an agent to load additional extension packs at runtime,
+     * so newly-enabled tool schemas appear in the next `listAvailableTools()` call.
+     */
+    schemaOnDemandTools?: {
+        enabled?: boolean;
+        /** Allow enabling packs by explicit npm package name (source='package'). Default: true. */
+        allowPackages?: boolean;
+        /** Allow enabling packs by local module specifier/path (source='module'). Default: false. */
+        allowModules?: boolean;
+    };
     /**
      * Optional. An instance of a utility AI service.
      * This service should conform to {@link IUtilityAI} for general utility tasks.
@@ -248,10 +324,15 @@ export interface AgentOSConfig {
      *
      * **Graceful Degradation:**
      * - If omitted, AgentOS falls back to Prisma (server-side only).
-     * - If provided, AgentOS uses storageAdapter for conversations, Prisma only for auth/subscriptions.
-     * - Recommended: Always provide storageAdapter for cross-platform compatibility.
-     */
+    * - If provided, AgentOS uses storageAdapter for conversations, Prisma only for auth/subscriptions.
+    * - Recommended: Always provide storageAdapter for cross-platform compatibility.
+    */
     storageAdapter?: StorageAdapter;
+    /**
+     * Optional observability config for tracing, metrics, and log correlation.
+     * Default: disabled (opt-in).
+     */
+    observability?: AgentOSObservabilityConfig;
 }
 /**
  * @class AgentOS
@@ -286,6 +367,9 @@ export declare class AgentOS implements IAgentOS {
     private workflowExtensionListener?;
     private workflowRuntime?;
     private agencyRegistry?;
+    private retrievalAugmentor?;
+    private ragVectorStoreManager?;
+    private manageRetrievalAugmentorLifecycle;
     private authService;
     private subscriptionService;
     private prisma;
@@ -459,5 +543,6 @@ export declare class AgentOS implements IAgentOS {
      * @throws {AgentOSServiceError} If an error occurs during the shutdown of any critical component.
      */
     shutdown(): Promise<void>;
+    private initializeRagSubsystem;
 }
 //# sourceMappingURL=AgentOS.d.ts.map

package/dist/api/AgentOS.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentOS.d.ts","sourceRoot":"","sources":["../../src/api/AgentOS.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentOS.d.ts","sourceRoot":"","sources":["../../src/api/AgentOS.ts"],"names":[],"mappings":"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"}

package/dist/api/AgentOS.js

@@ -52,9 +52,11 @@ import { StreamingManager } from '../core/streaming/StreamingManager.js';
 import { GMIError, GMIErrorCode } from '../utils/errors.js';
 import { uuidv4 } from '../utils/uuid.js';
 import { createLogger } from '../logging/loggerFactory.js';
+import { configureAgentOSObservability } from '../core/observability/otel.js';
 import { GuardrailAction } from '../core/guardrails/IGuardrailService.js';
 import { evaluateInputGuardrails, createGuardrailBlockedStream, wrapOutputGuardrails, } from '../core/guardrails/guardrailDispatcher.js';
 import { ExtensionManager, EXTENSION_KIND_GUARDRAIL, EXTENSION_KIND_PROVENANCE, EXTENSION_KIND_TOOL, EXTENSION_KIND_WORKFLOW, } from '../extensions/index.js';
+import { createSchemaOnDemandPack } from '../extensions/packs/schema-on-demand-pack.js';
 import { WorkflowRuntime } from '../core/workflows/runtime/WorkflowRuntime.js';
 import { AgencyRegistry } from '../core/agency/AgencyRegistry.js';
 import { WorkflowEngine } from '../core/workflows/WorkflowEngine.js';
@@ -215,6 +217,7 @@ export class AgentOS {
     constructor(logger = createLogger('AgentOS')) {
         this.logger = logger;
         this.initialized = false;
+        this.manageRetrievalAugmentorLifecycle = false;
     }
     /**
      * Initializes the `AgentOS` service and all its core dependencies.
@@ -237,6 +240,8 @@ export class AgentOS {
         this.validateConfiguration(config);
         // Make the configuration immutable after validation to prevent runtime changes.
         this.config = Object.freeze({ ...config });
+        // Observability is opt-in (config + env). Safe no-op if OTEL is not installed by host.
+        configureAgentOSObservability(this.config.observability);
         // Initialize LanguageService early if configured so downstream orchestration can use it.
         if (config.languageConfig) {
             try {
@@ -263,10 +268,22 @@ export class AgentOS {
         this.extensionManager = new ExtensionManager({
             manifest: this.config.extensionManifest,
             secrets: this.config.extensionSecrets,
+            overrides: this.config.extensionOverrides,
         });
         const extensionLifecycleContext = { logger: this.logger };
         await this.extensionManager.loadManifest(extensionLifecycleContext);
         await this.registerConfigGuardrailService(extensionLifecycleContext);
+        if (this.config.schemaOnDemandTools?.enabled === true) {
+            const pack = createSchemaOnDemandPack({
+                extensionManager: this.extensionManager,
+                options: {
+                    allowPackages: this.config.schemaOnDemandTools.allowPackages,
+                    allowModules: this.config.schemaOnDemandTools.allowModules,
+                },
+            });
+            await this.extensionManager.loadPackFromFactory(pack, 'schema-on-demand', undefined, extensionLifecycleContext);
+            this.logger.info('[AgentOS] Schema-on-demand tools enabled');
+        }
         let storageAdapter = this.config.storageAdapter;
         if (storageAdapter) {
             try {
@@ -290,6 +307,7 @@ export class AgentOS {
             await this.modelProviderManager.initialize(this.config.modelProviderManagerConfig);
             console.log('AgentOS: AIModelProviderManager initialized.');
             await this.ensureUtilityAIService();
+            await this.initializeRagSubsystem(storageAdapter);
             // Initialize Prompt Engine
             this.promptEngine = new PromptEngine();
             const peUtility = this.utilityAIService;
@@ -323,7 +341,7 @@ export class AgentOS {
             // Initialize GMI Manager
             this.gmiManager = new GMIManager(this.config.gmiManagerConfig, this.subscriptionService, this.authService, this.conversationManager, // Removed Prisma parameter
             this.promptEngine, this.modelProviderManager, this.utilityAIService, // Pass the potentially dual-role utility service
-            this.toolOrchestrator, undefined, this.config.personaLoader);
+            this.toolOrchestrator, this.retrievalAugmentor, this.config.personaLoader);
             await this.gmiManager.initialize();
             console.log('AgentOS: GMIManager initialized.');
             await this.startWorkflowRuntime();
@@ -1030,6 +1048,14 @@ export class AgentOS {
                 await this.toolOrchestrator.shutdown();
                 console.log('AgentOS: ToolOrchestrator shut down.');
             }
+            if (this.manageRetrievalAugmentorLifecycle && this.retrievalAugmentor?.shutdown) {
+                await this.retrievalAugmentor.shutdown();
+                console.log('AgentOS: RetrievalAugmentor shut down.');
+            }
+            if (this.manageRetrievalAugmentorLifecycle && this.ragVectorStoreManager?.shutdownAllProviders) {
+                await this.ragVectorStoreManager.shutdownAllProviders();
+                console.log('AgentOS: VectorStore providers shut down.');
+            }
             // PromptEngine might have a cleanup method like clearCache
             if (this.promptEngine && typeof this.promptEngine.clearCache === 'function') {
                 await this.promptEngine.clearCache();
@@ -1058,6 +1084,52 @@ export class AgentOS {
             this.initialized = false; // Mark as uninitialized regardless of shutdown errors.
         }
     }
+    async initializeRagSubsystem(storageAdapter) {
+        // Prefer caller-provided augmentor instance.
+        if (this.config.retrievalAugmentor) {
+            this.retrievalAugmentor = this.config.retrievalAugmentor;
+            this.manageRetrievalAugmentorLifecycle = this.config.manageRetrievalAugmentorLifecycle === true;
+            return;
+        }
+        const ragConfig = this.config.ragConfig;
+        if (!ragConfig || ragConfig.enabled === false) {
+            return;
+        }
+        try {
+            const { EmbeddingManager } = await import('../rag/EmbeddingManager.js');
+            const { VectorStoreManager } = await import('../rag/VectorStoreManager.js');
+            const { RetrievalAugmentor } = await import('../rag/RetrievalAugmentor.js');
+            const embeddingManager = new EmbeddingManager();
+            await embeddingManager.initialize(ragConfig.embeddingManagerConfig, this.modelProviderManager);
+            const bindToStorageAdapter = ragConfig.bindToStorageAdapter === undefined ? true : ragConfig.bindToStorageAdapter === true;
+            const patchedVectorStoreConfig = {
+                ...ragConfig.vectorStoreManagerConfig,
+                providers: ragConfig.vectorStoreManagerConfig.providers.map((provider) => {
+                    if (bindToStorageAdapter &&
+                        storageAdapter &&
+                        provider?.type === 'sql' &&
+                        !provider.adapter &&
+                        !provider.storage) {
+                        return { ...provider, adapter: storageAdapter };
+                    }
+                    return provider;
+                }),
+            };
+            const vectorStoreManager = new VectorStoreManager();
+            await vectorStoreManager.initialize(patchedVectorStoreConfig, ragConfig.dataSourceConfigs);
+            const retrievalAugmentor = new RetrievalAugmentor();
+            await retrievalAugmentor.initialize(ragConfig.retrievalAugmentorConfig, embeddingManager, vectorStoreManager);
+            this.retrievalAugmentor = retrievalAugmentor;
+            this.ragVectorStoreManager = vectorStoreManager;
+            this.manageRetrievalAugmentorLifecycle = ragConfig.manageLifecycle !== false;
+            console.log('AgentOS: RAG subsystem initialized.');
+        }
+        catch (error) {
+            this.logger.error('AgentOS: Failed to initialize RAG subsystem; continuing without retrieval augmentor.', {
+                error: error?.message ?? error,
+            });
+        }
+    }
 }
 /**
  * @class AsyncStreamClientBridge