@smythos/sre 1.6.0 → 1.6.8

package/CHANGELOG

@@ -1,111 +1,111 @@
-# Changelog
-
-All notable changes to the SmythOS CORE Runtime Engine will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [1.6.0]
-
-### Features
-
--   Add Memory Components
--   Add Milvus VectorDB Connector
--   Add support to Google embeddings
--   Add support to OpenAI responses API
--   Agent Runtime optimizations : better memory management + stability fixes
-
-### Code and tooling
-
--   Added multiple unit tests for a better code coveragge
--   Updated dependencies
--   Updated .cursor/rules/sre-ai-rules.mdc to enhance the qualty of AI based contributions
-
-## [v1.5.60]
-
-### Features
-
--   Fixed memory leak in Agent context manager
--   Optimized performances and resolved a rare case causing CPU usage spikes
-
-## [v1.5.50]
-
-### Features
-
--   Added support for OpenAI Responses API
--   Added support for GPT-5 family models with reasoning capabilities .
--   MCP Client component : support for Streamable HTTP transport
-
-## [v1.5.31]
-
-### LLM & Model Support:
-
--   Added support for new models (Claude 4, xAI/Grok 4, and more).
--   Improved model configuration, including support for unlisted/custom models
--   better handling of Anthropic tool calling.
--   Enhanced multimodal and streaming capabilities for LLMs.
-
-### Components & Connectors:
-
--   Introduced AWS Lambda code component and connector.
--   Added serverless code component.
--   Enhanced and unified connectors for S3, Redis, LocalStorage, and JSON vault.
--   Added support for local storage cache and improved NKV (key-value) handling.
-
-### Fixes
-
--   Numerous bug fixes for LLM connectors, model selection, and streaming.
--   Fixed issues with S3 connector initialization, serverless code component, and vault key fetching.
--   Improved error handling for binary input, file uploads, and API calls.
--   Fixed issues with usage reporting, especially for user-managed keys and custom models.
-
-### Improvements
-
--   Optimized build processes.
--   Improved strong typing and code auto-completion.
-
-## [v1.5.0] SmythOS becomes open source!
-
-### Features
-
--   Moved to a monorepo structure
--   Implemented an SDK that provides an abstracted interface for all SmythOS components
--   Implemented a CLI to help running agents and scaffolding SDK and SRE projects along
-
-## [v1.4.0]
-
-### Features
-
--   New connectors : JSON Account connector, RAMVec vectordb, localStorage
--   Conversation manager: better handling of agent chats
--   logger becomes a connector
--   Add support for usage reporting
--   LLM : new models provider connector allows loading custom models including local models
-
-## [v1.2.0]
-
-### Features
-
--   New connectors : AWS Secret Manager Vault, Redis, and RAM Cache
--   Conversation manager: better handling of agent chats
--   All connectors inherit from SecureConnector using a common security layer
--   LLM : support for anthropic, Groq and Gemini
-
-## [v1.1.0]
-
-### Features
-
--   New connectors : S3, Pinecone, and local vault
--   LLM : implemented common LLM interface to support more providers
-
-## [v1.0.0]
-
-### Features
-
--   Initial release
--   LLM : support for openai API
--   Smyth Runtime Core
--   Connectors Serivece
--   Subsystems architecture
--   Security & ACL helpers
--   Implemented services : AgentData, Storage, Account, VectorDB
+# Changelog
+
+All notable changes to the SmythOS CORE Runtime Engine will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.6.0]
+
+### Features
+
+-   Add Memory Components
+-   Add Milvus VectorDB Connector
+-   Add support to Google embeddings
+-   Add support to OpenAI responses API
+-   Agent Runtime optimizations : better memory management + stability fixes
+
+### Code and tooling
+
+-   Added multiple unit tests for a better code coveragge
+-   Updated dependencies
+-   Updated .cursor/rules/sre-ai-rules.mdc to enhance the qualty of AI based contributions
+
+## [v1.5.60]
+
+### Features
+
+-   Fixed memory leak in Agent context manager
+-   Optimized performances and resolved a rare case causing CPU usage spikes
+
+## [v1.5.50]
+
+### Features
+
+-   Added support for OpenAI Responses API
+-   Added support for GPT-5 family models with reasoning capabilities .
+-   MCP Client component : support for Streamable HTTP transport
+
+## [v1.5.31]
+
+### LLM & Model Support:
+
+-   Added support for new models (Claude 4, xAI/Grok 4, and more).
+-   Improved model configuration, including support for unlisted/custom models
+-   better handling of Anthropic tool calling.
+-   Enhanced multimodal and streaming capabilities for LLMs.
+
+### Components & Connectors:
+
+-   Introduced AWS Lambda code component and connector.
+-   Added serverless code component.
+-   Enhanced and unified connectors for S3, Redis, LocalStorage, and JSON vault.
+-   Added support for local storage cache and improved NKV (key-value) handling.
+
+### Fixes
+
+-   Numerous bug fixes for LLM connectors, model selection, and streaming.
+-   Fixed issues with S3 connector initialization, serverless code component, and vault key fetching.
+-   Improved error handling for binary input, file uploads, and API calls.
+-   Fixed issues with usage reporting, especially for user-managed keys and custom models.
+
+### Improvements
+
+-   Optimized build processes.
+-   Improved strong typing and code auto-completion.
+
+## [v1.5.0] SmythOS becomes open source!
+
+### Features
+
+-   Moved to a monorepo structure
+-   Implemented an SDK that provides an abstracted interface for all SmythOS components
+-   Implemented a CLI to help running agents and scaffolding SDK and SRE projects along
+
+## [v1.4.0]
+
+### Features
+
+-   New connectors : JSON Account connector, RAMVec vectordb, localStorage
+-   Conversation manager: better handling of agent chats
+-   logger becomes a connector
+-   Add support for usage reporting
+-   LLM : new models provider connector allows loading custom models including local models
+
+## [v1.2.0]
+
+### Features
+
+-   New connectors : AWS Secret Manager Vault, Redis, and RAM Cache
+-   Conversation manager: better handling of agent chats
+-   All connectors inherit from SecureConnector using a common security layer
+-   LLM : support for anthropic, Groq and Gemini
+
+## [v1.1.0]
+
+### Features
+
+-   New connectors : S3, Pinecone, and local vault
+-   LLM : implemented common LLM interface to support more providers
+
+## [v1.0.0]
+
+### Features
+
+-   Initial release
+-   LLM : support for openai API
+-   Smyth Runtime Core
+-   Connectors Serivece
+-   Subsystems architecture
+-   Security & ACL helpers
+-   Implemented services : AgentData, Storage, Account, VectorDB

package/LICENSE

@@ -1,18 +1,18 @@
-The MIT License
-
-Copyright 2025, INK Content, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
-documentation files (the “Software”), to deal in the Software without restriction, including without limitation
-the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
-to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all copies or substantial portions
-of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+The MIT License
+
+Copyright 2025, INK Content, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the “Software”), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,135 +1,135 @@
-# Smyth Runtime Environment (SRE) Core
-
-This package contains the **Smyth Runtime Environment (SRE)**, the core of SmythOS. It is responsible for low-level agent orchestration, secure resource management, and providing the foundational services upon which all higher-level agent functionalities are built.
-
-This document provides a technical deep-dive into the SRE's architecture, you only need to read this if you are interested in the internals of SmythOS or if you are planning to [contribute](../../CONTRIBUTING.md) to the SmythOS codebase.
-For building applications and agents on top of SmythOS, please refer to the developer-friendly **[@smythos/sdk](../sdk)** package.
-
----
-
-## 🏗️ Core Architecture
-
-SRE is designed with a philosophy inspired by operating system kernels, establishing a clear separation between the core runtime and the pluggable **Connectors** that interface with external services and infrastructure.
-
-### The SRE Lifecycle & Initialization
-
-The SRE is a singleton that gets initialized via the `SRE.init()` method. This critical step bootstraps the entire environment based on the provided configuration. The `sre.ready()` method then ensures all configured connectors are initialized and operational.
-
-An SRE initialization looks like this:
-
-```typescript
-import { SRE } from '@smythos/sre';
-
-// 1. SRE.init() loads the configuration for each subsystem
-const sre = SRE.init({
-    Vault: { Connector: 'JSONFileVault', Settings: { file: 'vault.json' } },
-    Cache: { Connector: 'RAM' },
-    Storage: { Connector: 'Local' },
-    Log: { Connector: 'ConsoleLog' },
-});
-
-// 2. sre.ready() asynchronously initializes all configured connectors
-await sre.ready();
-
-console.log('SRE is operational.');
-```
-
-### 🛡️ Security Model: The Candidate & ACL System
-
-Security is a foundational, non-negotiable aspect of SRE. Every operation that accesses a resource is governed by the **Candidate/ACL system**. An **Access Candidate** is an object representing the entity (e.g., an agent, a user, an internal process) requesting access.
-
-Connectors use the candidate to scope and isolate resources, preventing data leakage between tenants.
-
-```typescript
-// Internally, when an agent requests a resource, this happens:
-
-// 1. An Access Candidate is created for the specific agent
-const candidate = AccessCandidate.agent(agentId);
-
-// 2. A handle to the underlying storage connector is retrieved
-const storageConnector = ConnectorService.getStorageConnector();
-
-// 3. The connector is scoped to the candidate's context
-// The resulting `storage` object is now a sandboxed view for that agent
-const storage = storageConnector.user(candidate);
-
-// 4. This write operation is now isolated. Another agent writing to 'data.json'
-// will write to a completely different, isolated location.
-await storage.write('data.json', content);
-```
-
-This design ensures that multi-tenancy and security are enforced at the lowest level of the runtime.
-
-### Subsystem Deep Dive
-
-SRE's functionality is partitioned into several discrete subsystems.
-
-#### 🤖 Agent Manager
-
-The heart of agent execution. It manages the entire agent lifecycle (start, stop, pause), monitors performance, and orchestrates the complex workflows defined within an agent's components.
-
-#### 💾 Memory Manager
-
-Provides intelligent state and context management for agents. It includes:
-
--   **Cache Service**: A multi-tiered caching system (RAM, Redis) for fast data retrieval.
--   **Runtime Context**: Manages an agent's state during execution.
--   **LLM Context**: Manages conversation history and context windows for LLMs.
-
-#### 🛡️ Security Manager
-
-Handles all security-related primitives.
-
--   **Vault Service**: Provides a secure connector-based interface for storing and retrieving secrets (e.g., from HashiCorp Vault, AWS Secrets Manager, or a local JSON file).
--   **Account Management**: Manages identity and authentication.
--   **Access Control**: Implements the granular Candidate/ACL permission system.
-
-#### 📥 IO Subsystem
-
-The gateway to the outside world. It provides a set of unified connector interfaces for all input/output operations.
-
-| Service      | Purpose                    | Example Connectors   |
-| ------------ | -------------------------- | -------------------- |
-| **Storage**  | File & data persistence    | `LocalStorage`, `S3` |
-| **VectorDB** | Vector storage & retrieval | `Pinecone`, `Milvus` |
-| **Log**      | Activity & debug logging   | `Console`            |
-| **NKV**      | Key-value storage          | `Redis`, `RAM`       |
-
-#### 🧠 LLM Manager
-
-A powerful abstraction layer for over 8 different LLM providers. It handles API variations between providers and offers features like smart inference, response caching, and unified usage tracking.
-
----
-
-<details>
-<summary>💻 Code Standards & Best Practices</summary>
-
-### Folder Structure
-
--   **/subsystems**: Contains the core service definitions and connector interfaces for all major subsystems (IO, AgentManager, MemoryManager, etc.).
--   **/Components**: SmythOS Agent Components.
--   **/utils**: Contains utility functions. Functions in this folder should not depend on other packages of the project outside of /utils/\*. These functions are reusable throughout the code.
--   **/helpers**: Contains general helper classes/objects/structures. Unlike utils, helpers export an object that exposes a collection of functions specific to a given task.
--   **/types**: This folder contains SmythOS-specific type declarations.
-
-### Naming Standards
-
-#### File Naming
-
-Use the following extensions for specific code roles to maintain consistency across the codebase:
-
--   `.service.ts` for top-level services
--   `.class.ts` for classes and connectors
--   `.utils.ts` for utility collections
--   `.helper.ts` for task-specific helpers
--   `.handler.ts` for event handlers
--   `.mw.ts` for middlewares
-
-#### Declaration Naming
-
--   **Constants**: Uppercase with underscores (e.g., `MAX_RETRIES`).
--   **Enums and Types**: Start with `T` (e.g., `TAccessLevel`).
--   **Interfaces**: Start with `I` (e.g., `IStorageConnector`).
--   **Classes**: Use PascalCase without a prefix (e.g., `MyAgent`).
-
-</details>
+# Smyth Runtime Environment (SRE) Core
+
+This package contains the **Smyth Runtime Environment (SRE)**, the core of SmythOS. It is responsible for low-level agent orchestration, secure resource management, and providing the foundational services upon which all higher-level agent functionalities are built.
+
+This document provides a technical deep-dive into the SRE's architecture, you only need to read this if you are interested in the internals of SmythOS or if you are planning to [contribute](../../CONTRIBUTING.md) to the SmythOS codebase.
+For building applications and agents on top of SmythOS, please refer to the developer-friendly **[@smythos/sdk](../sdk)** package.
+
+---
+
+## 🏗️ Core Architecture
+
+SRE is designed with a philosophy inspired by operating system kernels, establishing a clear separation between the core runtime and the pluggable **Connectors** that interface with external services and infrastructure.
+
+### The SRE Lifecycle & Initialization
+
+The SRE is a singleton that gets initialized via the `SRE.init()` method. This critical step bootstraps the entire environment based on the provided configuration. The `sre.ready()` method then ensures all configured connectors are initialized and operational.
+
+An SRE initialization looks like this:
+
+```typescript
+import { SRE } from '@smythos/sre';
+
+// 1. SRE.init() loads the configuration for each subsystem
+const sre = SRE.init({
+    Vault: { Connector: 'JSONFileVault', Settings: { file: 'vault.json' } },
+    Cache: { Connector: 'RAM' },
+    Storage: { Connector: 'Local' },
+    Log: { Connector: 'ConsoleLog' },
+});
+
+// 2. sre.ready() asynchronously initializes all configured connectors
+await sre.ready();
+
+console.log('SRE is operational.');
+```
+
+### 🛡️ Security Model: The Candidate & ACL System
+
+Security is a foundational, non-negotiable aspect of SRE. Every operation that accesses a resource is governed by the **Candidate/ACL system**. An **Access Candidate** is an object representing the entity (e.g., an agent, a user, an internal process) requesting access.
+
+Connectors use the candidate to scope and isolate resources, preventing data leakage between tenants.
+
+```typescript
+// Internally, when an agent requests a resource, this happens:
+
+// 1. An Access Candidate is created for the specific agent
+const candidate = AccessCandidate.agent(agentId);
+
+// 2. A handle to the underlying storage connector is retrieved
+const storageConnector = ConnectorService.getStorageConnector();
+
+// 3. The connector is scoped to the candidate's context
+// The resulting `storage` object is now a sandboxed view for that agent
+const storage = storageConnector.user(candidate);
+
+// 4. This write operation is now isolated. Another agent writing to 'data.json'
+// will write to a completely different, isolated location.
+await storage.write('data.json', content);
+```
+
+This design ensures that multi-tenancy and security are enforced at the lowest level of the runtime.
+
+### Subsystem Deep Dive
+
+SRE's functionality is partitioned into several discrete subsystems.
+
+#### 🤖 Agent Manager
+
+The heart of agent execution. It manages the entire agent lifecycle (start, stop, pause), monitors performance, and orchestrates the complex workflows defined within an agent's components.
+
+#### 💾 Memory Manager
+
+Provides intelligent state and context management for agents. It includes:
+
+-   **Cache Service**: A multi-tiered caching system (RAM, Redis) for fast data retrieval.
+-   **Runtime Context**: Manages an agent's state during execution.
+-   **LLM Context**: Manages conversation history and context windows for LLMs.
+
+#### 🛡️ Security Manager
+
+Handles all security-related primitives.
+
+-   **Vault Service**: Provides a secure connector-based interface for storing and retrieving secrets (e.g., from HashiCorp Vault, AWS Secrets Manager, or a local JSON file).
+-   **Account Management**: Manages identity and authentication.
+-   **Access Control**: Implements the granular Candidate/ACL permission system.
+
+#### 📥 IO Subsystem
+
+The gateway to the outside world. It provides a set of unified connector interfaces for all input/output operations.
+
+| Service      | Purpose                    | Example Connectors   |
+| ------------ | -------------------------- | -------------------- |
+| **Storage**  | File & data persistence    | `LocalStorage`, `S3` |
+| **VectorDB** | Vector storage & retrieval | `Pinecone`, `Milvus` |
+| **Log**      | Activity & debug logging   | `Console`            |
+| **NKV**      | Key-value storage          | `Redis`, `RAM`       |
+
+#### 🧠 LLM Manager
+
+A powerful abstraction layer for over 8 different LLM providers. It handles API variations between providers and offers features like smart inference, response caching, and unified usage tracking.
+
+---
+
+<details>
+<summary>💻 Code Standards & Best Practices</summary>
+
+### Folder Structure
+
+-   **/subsystems**: Contains the core service definitions and connector interfaces for all major subsystems (IO, AgentManager, MemoryManager, etc.).
+-   **/Components**: SmythOS Agent Components.
+-   **/utils**: Contains utility functions. Functions in this folder should not depend on other packages of the project outside of /utils/\*. These functions are reusable throughout the code.
+-   **/helpers**: Contains general helper classes/objects/structures. Unlike utils, helpers export an object that exposes a collection of functions specific to a given task.
+-   **/types**: This folder contains SmythOS-specific type declarations.
+
+### Naming Standards
+
+#### File Naming
+
+Use the following extensions for specific code roles to maintain consistency across the codebase:
+
+-   `.service.ts` for top-level services
+-   `.class.ts` for classes and connectors
+-   `.utils.ts` for utility collections
+-   `.helper.ts` for task-specific helpers
+-   `.handler.ts` for event handlers
+-   `.mw.ts` for middlewares
+
+#### Declaration Naming
+
+-   **Constants**: Uppercase with underscores (e.g., `MAX_RETRIES`).
+-   **Enums and Types**: Start with `T` (e.g., `TAccessLevel`).
+-   **Interfaces**: Start with `I` (e.g., `IStorageConnector`).
+-   **Classes**: Use PascalCase without a prefix (e.g., `MyAgent`).
+
+</details>