@framers/agentos 0.1.126 → 0.1.127

package/dist/core/config/MemoryLifecycleManagerConfiguration.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Defines configuration structures for the MemoryLifecycleManager.
+ * This includes defining individual lifecycle policies, their triggers, actions,
+ * and how they apply to different categories or data sources within the RAG system.
+ *
+ * These configurations guide the MemoryLifecycleManager in automatically managing
+ * the retention, eviction, or archival of stored information, potentially involving
+ * negotiation with GMI instances for critical data.
+ *
+ * @module backend/agentos/config/MemoryLifecycleManagerConfiguration
+ * @see ../memory/lifecycle/IMemoryLifecycleManager.ts
+ * @see ../rag/IRetrievalAugmentor.ts for RagMemoryCategory
+ * @see ../core/vector-store/IVectorStore.ts for MetadataFilter
+ */
+import { RagMemoryCategory } from '../../rag/IRetrievalAugmentor.js';
+import type { MetadataFilter } from '../vector-store/IVectorStore.js';
+import type { LifecycleAction } from '../../cognitive_substrate/IGMI.js';
+/**
+ * Specifies the conditions under which a MemoryLifecyclePolicy is triggered.
+ *
+ * @interface PolicyTriggerCondition
+ * @property {'periodic' | 'on_storage_threshold' | 'on_item_age'} type - The type of trigger.
+ * - `periodic`: The policy check runs at regular intervals.
+ * - `on_storage_threshold`: Triggered when a data source or category exceeds a size/item count. (Requires monitoring)
+ * - `on_item_age`: Policy applies based on individual item age (implicitly handled by retentionDays).
+ * @property {string} [checkInterval] - For `periodic` trigger, the interval (e.g., "1h", "30m", "7d").
+ * This will be parsed into seconds or milliseconds by the manager.
+ * @property {number} [itemCountThreshold] - For `on_storage_threshold`, max number of items.
+ * @property {number} [sizeBytesThreshold] - For `on_storage_threshold`, max size in bytes.
+ */
+export interface PolicyTriggerCondition {
+    type: 'periodic' | 'on_storage_threshold' | 'on_item_age';
+    checkInterval?: string;
+    itemCountThreshold?: number;
+    sizeBytesThreshold?: number;
+}
+/**
+ * Defines the action to be taken when a policy's conditions are met.
+ *
+ * @interface PolicyAction
+ * @property {'delete' | 'archive' | 'summarize_and_delete' | 'summarize_and_archive' | 'notify_gmi_owner'} type - The lifecycle action.
+ * - `delete`: Permanently remove the item.
+ * - `archive`: Move the item to a designated archive location/store.
+ * - `summarize_and_delete`: Generate a summary (requires UtilityAI), store summary (optional), then delete original.
+ * - `summarize_and_archive`: Generate summary, store summary, then archive original.
+ * - `notify_gmi_owner`: Only notify the owning GMI about the item meeting criteria, letting GMI decide via other means.
+ * @property {string} [archiveTargetId] - Identifier for the archive storage (e.g., a different vector store collection ID or a cold storage path).
+ * @property {string} [summaryDataSourceId] - If summarizing, the data source ID where the summary should be stored.
+ * @property {boolean} [deleteOriginalAfterSummary=true] - If summarizing, whether to delete the original item.
+ */
+export interface PolicyAction {
+    type: 'delete' | 'archive' | 'summarize_and_delete' | 'summarize_and_archive' | 'notify_gmi_owner';
+    archiveTargetId?: string;
+    summaryDataSourceId?: string;
+    deleteOriginalAfterSummary?: boolean;
+    /**
+     * Optional model override for summarisation flows. Falls back to
+     * `MemoryLifecycleManagerConfig.defaultSummarizationModelId` when omitted.
+     */
+    llmModelForSummary?: string;
+}
+/**
+ * Configuration for GMI negotiation during lifecycle events.
+ *
+ * @interface GMINegotiationConfig
+ * @property {boolean} enabled - Whether GMI negotiation is enabled for items matching this policy.
+ * If true, the owning GMI will be consulted before taking the lifecycle action.
+ * @property {number} [timeoutMs=30000] - Timeout in milliseconds for waiting for a GMI's response
+ * during negotiation.
+ * @property {LifecycleAction} [defaultActionOnTimeout='ALLOW_ACTION'] - The action to take if the GMI negotiation times out
+ * or if the GMI instance cannot be resolved or fails to respond.
+ * @property {string[]} [criticalMetadataFields] - List of metadata fields that, if present and matching certain criteria
+ * (not defined here, but could be used by GMI), might make an item critical.
+ */
+export interface GMINegotiationConfig {
+    enabled: boolean;
+    timeoutMs?: number;
+    defaultActionOnTimeout?: LifecycleAction;
+    criticalMetadataFields?: string[];
+}
+/**
+ * Defines a single memory lifecycle policy.
+ *
+ * @interface MemoryLifecyclePolicy
+ * @property {string} policyId - A unique identifier for this policy (e.g., "user-notes-retention-90d").
+ * @property {string} [description] - A human-readable description of the policy's purpose.
+ * @property {boolean} [isEnabled=true] - Whether this policy is currently active.
+ * @property {object} appliesTo - Criteria defining which data items this policy applies to.
+ * @property {RagMemoryCategory[]} [appliesTo.categories] - Logical RAG memory categories.
+ * @property {string[]} [appliesTo.dataSourceIds] - Specific RAG Data Source IDs.
+ * @property {MetadataFilter} [appliesTo.metadataFilter] - Filter based on document metadata.
+ * Policy applies if an item matches ANY of the categories, dataSourceIds, OR the metadataFilter if specified.
+ * If multiple are specified, it's typically an OR unless an explicit AND structure is introduced.
+ * For simplicity, let's assume if multiple fields in `appliesTo` are set, an item must satisfy conditions from each set field (implicit AND).
+ * E.g., category 'X' AND dataSourceId 'Y'. Or, this needs a more complex structure like an array of condition groups.
+ * Let's refine: an item matches if it belongs to *any* of the specified categories (if categories are present)
+ * AND belongs to *any* of the specified dataSourceIds (if dataSourceIds are present)
+ * AND matches the metadataFilter (if metadataFilter is present).
+ * If a field (categories, dataSourceIds, metadataFilter) is omitted, it's not considered for matching for that field.
+ * @property {PolicyTriggerCondition} [trigger] - Conditions that trigger the policy check.
+ * If not provided, `retentionDays` might be the primary trigger.
+ * @property {PolicyAction} action - The action to take when the policy applies and conditions are met.
+ * @property {number} [retentionDays] - If positive, items older than this many days are subject to the policy's action.
+ * This is a primary condition for many policies. `0` or undefined might mean no age-based retention by this policy.
+ * @property {'lru' | 'lfu' | 'oldest_first' | 'lowest_importance' | 'custom'} [evictionStrategy] - Strategy for selecting items
+ * when a storage threshold is met. `custom` would require a pluggable component.
+ * `lowest_importance` implies items have an `importance` score in their metadata.
+ * @property {GMINegotiationConfig} [gmiNegotiation] - Configuration for how to negotiate with an owning GMI
+ * before applying the action.
+ * @property {number} [priority=0] - Execution priority of this policy (lower numbers run first if policies conflict or overlap).
+ */
+export interface MemoryLifecyclePolicy {
+    policyId: string;
+    description?: string;
+    isEnabled?: boolean;
+    appliesTo: {
+        categories?: RagMemoryCategory[];
+        dataSourceIds?: string[];
+        metadataFilter?: MetadataFilter;
+        gmiOwnerId?: string;
+        personaOwnerId?: string;
+    };
+    trigger?: PolicyTriggerCondition;
+    action: PolicyAction;
+    retentionDays?: number;
+    evictionStrategy?: 'lru' | 'lfu' | 'oldest_first' | 'lowest_importance' | 'custom';
+    gmiNegotiation?: GMINegotiationConfig;
+    priority?: number;
+}
+/**
+ * Top-level configuration for the MemoryLifecycleManager.
+ *
+ * @interface MemoryLifecycleManagerConfig
+ * @property {string} managerId - A unique identifier for this manager instance.
+ * @property {MemoryLifecyclePolicy[]} policies - An array of lifecycle policies to be enforced.
+ * @property {string} [defaultCheckInterval="PT6H"] - Default interval (ISO 8601 duration format, e.g., "PT6H" for 6 hours)
+ * for periodic policy checks if a policy itself doesn't define one.
+ * @property {number} [defaultGMINegotiationTimeoutMs=30000] - Global default timeout for GMI negotiations.
+ * @property {string} [defaultArchiveStoreId] - Default target ID for 'archive' actions if not specified in the policy.
+ * This could be a specific RAG data source ID configured for archival.
+ * @property {boolean} [dryRunMode=false] - If true, the manager will log actions it would take but not actually
+ * execute them (e.g., no actual deletions or archival). Useful for testing policies.
+ * @property {number} [maxConcurrentOperations=5] - Maximum number of concurrent lifecycle operations (e.g., item deletions).
+ * @property {string} [gmiOwnerIdMetadataField="gmiOwnerId"] - The metadata field name in vector documents
+ * that stores the ID of the owning GMI.
+ * @property {string} [personaOwnerIdMetadataField="personaOwnerId"] - The metadata field name for the owning Persona.
+ * @property {string} [itemTimestampMetadataField="creationTimestamp"] - The metadata field used to determine item age for retention.
+ * Should store an ISO 8601 date string.
+ */
+export interface MemoryLifecycleManagerConfig {
+    managerId: string;
+    policies: MemoryLifecyclePolicy[];
+    defaultCheckInterval?: string;
+    defaultGMINegotiationTimeoutMs?: number;
+    defaultArchiveStoreId?: string;
+    defaultSummarizationModelId?: string;
+    dryRunMode?: boolean;
+    maxConcurrentOperations?: number;
+    gmiOwnerIdMetadataField?: string;
+    personaOwnerIdMetadataField?: string;
+    itemTimestampMetadataField?: string;
+    /** Default retention days when no specific policy applies */
+    defaultRetentionDays?: number;
+}
+//# sourceMappingURL=MemoryLifecycleManagerConfiguration.d.ts.map

package/dist/core/config/MemoryLifecycleManagerConfiguration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryLifecycleManagerConfiguration.d.ts","sourceRoot":"","sources":["../../../src/core/config/MemoryLifecycleManagerConfiguration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,GAAG,sBAAsB,GAAG,aAAa,CAAC;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,sBAAsB,GAAG,uBAAuB,GAAG,kBAAkB,CAAC;IACnG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB,CAAC,EAAE,eAAe,CAAC;IACzC,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE;QACT,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,cAAc,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IACnF,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/core/config/MemoryLifecycleManagerConfiguration.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Defines configuration structures for the MemoryLifecycleManager.
+ * This includes defining individual lifecycle policies, their triggers, actions,
+ * and how they apply to different categories or data sources within the RAG system.
+ *
+ * These configurations guide the MemoryLifecycleManager in automatically managing
+ * the retention, eviction, or archival of stored information, potentially involving
+ * negotiation with GMI instances for critical data.
+ *
+ * @module backend/agentos/config/MemoryLifecycleManagerConfiguration
+ * @see ../memory/lifecycle/IMemoryLifecycleManager.ts
+ * @see ../rag/IRetrievalAugmentor.ts for RagMemoryCategory
+ * @see ../core/vector-store/IVectorStore.ts for MetadataFilter
+ */
+export {};
+// Example Configuration:
+/*
+const exampleMLMConfig: MemoryLifecycleManagerConfig = {
+  managerId: "mlm-main-01",
+  defaultCheckInterval: "PT1H", // Check hourly by default
+  defaultGMINegotiationTimeoutMs: 20000,
+  dryRunMode: false,
+  gmiOwnerIdMetadataField: "gmiInstanceId", // Field in RAG metadata
+  itemTimestampMetadataField: "doc_creation_date", // Field in RAG metadata
+  policies: [
+    {
+      policyId: "delete-old-episodic-logs",
+      description: "Delete episodic context logs older than 7 days.",
+      isEnabled: true,
+      appliesTo: {
+        categories: [RagMemoryCategory.EPISODIC_CONTEXT],
+      },
+      retentionDays: 7,
+      action: { type: 'delete' },
+      gmiNegotiation: { enabled: false }, // No negotiation for simple logs
+      priority: 10,
+    },
+    {
+      policyId: "archive-user-memory-over-1yr",
+      description: "Archive user explicit memory older than 1 year, with GMI negotiation.",
+      isEnabled: true,
+      appliesTo: {
+        categories: [RagMemoryCategory.USER_EXPLICIT_MEMORY],
+      },
+      retentionDays: 365,
+      action: { type: 'archive', archiveTargetId: 'cold-storage-user-memory' },
+      gmiNegotiation: { enabled: true, timeoutMs: 60000, defaultActionOnTimeout: 'ARCHIVE' },
+      priority: 50,
+    },
+    {
+        policyId: "summarize-gmi-experience",
+        description: "Summarize and delete very old GMI personal experiences (older than 180 days).",
+        isEnabled: true,
+        appliesTo: {
+            categories: [RagMemoryCategory.PERSONAL_LLM_EXPERIENCE],
+        },
+        retentionDays: 180,
+        action: {
+            type: 'summarize_and_delete',
+            summaryDataSourceId: 'gmi_experience_summaries', // Store summary in a different RAG source
+            deleteOriginalAfterSummary: true,
+        },
+        gmiNegotiation: { enabled: true, defaultActionOnTimeout: 'SUMMARIZE_AND_DELETE' },
+        priority: 30,
+    }
+  ],
+};
+*/
+//# sourceMappingURL=MemoryLifecycleManagerConfiguration.js.map

package/dist/core/config/MemoryLifecycleManagerConfiguration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryLifecycleManagerConfiguration.js","sourceRoot":"","sources":["../../../src/core/config/MemoryLifecycleManagerConfiguration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;;AA8JH,yBAAyB;AACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmDE"}

package/dist/core/config/RetrievalAugmentorConfiguration.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Defines configuration structures for the RetrievalAugmentor.
+ * This includes how different RAG memory categories are handled, default
+ * behaviors for ingestion and retrieval, and other operational parameters for
+ * the core RAG orchestration service.
+ *
+ * The configurations here rely on data contract types (like options and results
+ * for retrieval/ingestion) defined in `../rag/IRetrievalAugmentor.ts`.
+ *
+ * @module backend/agentos/config/RetrievalAugmentorConfiguration
+ * @see ../rag/IRetrievalAugmentor.ts for operational data contracts.
+ * @see ../rag/RetrievalAugmentor.ts for the concrete implementation using this config.
+ */
+import { RagMemoryCategory, RagRetrievalOptions, // Assuming this is defined in IRetrievalAugmentor.ts
+RagIngestionOptions } from '../../rag/IRetrievalAugmentor.js';
+import type { RerankerServiceConfig } from '../../rag/reranking/IRerankerService.js';
+/**
+ * Defines default behaviors and mappings for different RAG memory categories.
+ * Each memory category can be configured to use specific data collections,
+ * default operational parameters, and retention policies.
+ *
+ * @interface RagCategoryBehavior
+ * @property {RagMemoryCategory} category - The logical memory category (e.g., 'user_explicit_memory').
+ * @property {string[]} targetDataSourceIds - The actual data source ID(s) (collections/indexes
+ * in a vector store) that this logical category maps to. A category can map to multiple physical data sources.
+ * @property {Partial<RagRetrievalOptions>} [defaultRetrievalOptions] - Default retrieval options specific to this category,
+ * overriding global defaults. These are partial because they only override specified fields.
+ * @property {Partial<RagIngestionOptions>} [defaultIngestionOptions] - Default ingestion options specific to this category,
+ * overriding global defaults.
+ * @property {string} [defaultEmbeddingModelId] - Default embedding model ID for this category, overriding
+ * the EmbeddingManager's default or the RetrievalAugmentor's default query model.
+ * @property {number} [retentionDays] - Optional: How long to retain items in this category in days.
+ * A value of 0 or undefined might imply indefinite retention or reliance on underlying store policies.
+ * @property {boolean} [isUserSpecific] - True if data in this category is typically tied to a `userId` and
+ * should be filtered accordingly during retrieval by default.
+ * @property {boolean} [isPersonaSpecific] - True if data in this category is typically tied to a specific
+ * `personaId` and might require persona-based access or filtering.
+ * @property {number} [queryPriority=0] - Priority for querying this category when multiple categories are searched.
+ * Higher values indicate higher priority. This can influence result merging or ordering.
+ * @property {Record<string, any>} [customMetadata] - Any other custom metadata or flags associated with this category's behavior.
+ */
+export interface RagCategoryBehavior {
+    category: RagMemoryCategory;
+    targetDataSourceIds: string[];
+    defaultRetrievalOptions?: Partial<RagRetrievalOptions>;
+    defaultIngestionOptions?: Partial<RagIngestionOptions>;
+    defaultEmbeddingModelId?: string;
+    retentionDays?: number;
+    isUserSpecific?: boolean;
+    isPersonaSpecific?: boolean;
+    queryPriority?: number;
+    customMetadata?: Record<string, any>;
+}
+/**
+ * Configuration for the RetrievalAugmentor service itself.
+ * This structure is typically loaded at application startup to initialize the
+ * RetrievalAugmentor instance.
+ *
+ * @interface RetrievalAugmentorServiceConfig
+ * @property {string} [defaultQueryEmbeddingModelId] - Optional: An embedding model ID that overrides the
+ * EmbeddingManager's default, specifically for generating query embeddings within the RetrievalAugmentor.
+ * If not set, the EmbeddingManager's default will be used.
+ * @property {string} [defaultEmbeddingModelId] - Optional: default embedding model for document ingestion when
+ * individual requests or categories do not override it.
+ * @property {string} [defaultDataSourceId] - Optional: fallback data source / collection for ingestion + retrieval.
+ * @property {RagIngestionOptions['chunkingStrategy']} [defaultChunkingStrategy] - Optional fallback chunking strategy.
+ * @property {Partial<RagRetrievalOptions>} [globalDefaultRetrievalOptions] - Global default retrieval options that apply if
+ * no category-specific or request-specific options are provided.
+ * @property {Partial<RagIngestionOptions>} [globalDefaultIngestionOptions] - Global default ingestion options.
+ * @property {RagCategoryBehavior[]} categoryBehaviors - An array defining the behavior and mapping for each
+ * supported RAG memory category. This is a core part of the configuration, dictating how different
+ * types of information are handled.
+ * @property {number} [maxCharsForAugmentedPrompt=4000] - The maximum number of characters to include in the
+ * `augmentedPromptText` generated by `retrieveContext`. This helps in managing token limits for LLMs.
+ * @property {string} [contextJoinSeparator="\n\n---\n\n"] - The separator string used when joining multiple
+ * retrieved context snippets into the single `augmentedPromptText`.
+ * @property {boolean} [enableExperimentalFeatures=false] - A flag to enable or disable experimental RAG features,
+ * allowing for controlled rollout and testing.
+ * @property {object} [performanceTuning] - Optional advanced settings for performance tuning.
+ * @property {number} [performanceTuning.maxConcurrentQueries] - Max concurrent queries to vector stores.
+ * @property {number} [performanceTuning.queryTimeoutMs] - Default timeout for RAG queries.
+ */
+export interface RetrievalAugmentorServiceConfig {
+    defaultQueryEmbeddingModelId?: string;
+    defaultEmbeddingModelId?: string;
+    defaultDataSourceId?: string;
+    defaultChunkingStrategy?: RagIngestionOptions['chunkingStrategy'];
+    globalDefaultRetrievalOptions?: Partial<RagRetrievalOptions>;
+    globalDefaultIngestionOptions?: Partial<RagIngestionOptions>;
+    categoryBehaviors: RagCategoryBehavior[];
+    maxCharsForAugmentedPrompt?: number;
+    contextJoinSeparator?: string;
+    enableExperimentalFeatures?: boolean;
+    performanceTuning?: {
+        maxConcurrentQueries?: number;
+        queryTimeoutMs?: number;
+    };
+    /**
+     * Cross-encoder reranker service configuration.
+     *
+     * When configured, enables optional reranking of retrieved chunks using
+     * cross-encoder models. Reranking is disabled by default and must be
+     * explicitly enabled per-request via `rerankerConfig.enabled: true`.
+     *
+     * @see RerankerServiceConfig for provider configuration details
+     */
+    rerankerServiceConfig?: RerankerServiceConfig;
+    /**
+     * Default reranker provider ID when reranking is enabled but no provider specified.
+     * Common values: 'cohere', 'local'
+     */
+    defaultRerankerProviderId?: string;
+    /**
+     * Default reranker model ID when reranking is enabled but no model specified.
+     * Examples: 'rerank-v3.5' (Cohere), 'cross-encoder/ms-marco-MiniLM-L-6-v2' (local)
+     */
+    defaultRerankerModelId?: string;
+}
+//# sourceMappingURL=RetrievalAugmentorConfiguration.d.ts.map

package/dist/core/config/RetrievalAugmentorConfiguration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalAugmentorConfiguration.d.ts","sourceRoot":"","sources":["../../../src/core/config/RetrievalAugmentorConfiguration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EAAE,qDAAqD;AAC1E,mBAAmB,EACpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD,uBAAuB,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB,CAAC,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IAClE,6BAA6B,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7D,6BAA6B,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7D,iBAAiB,EAAE,mBAAmB,EAAE,CAAC;IACzC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,iBAAiB,CAAC,EAAE;QAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;;;;;;OAQG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C;;;OAGG;IACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC"}

package/dist/core/config/RetrievalAugmentorConfiguration.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Defines configuration structures for the RetrievalAugmentor.
+ * This includes how different RAG memory categories are handled, default
+ * behaviors for ingestion and retrieval, and other operational parameters for
+ * the core RAG orchestration service.
+ *
+ * The configurations here rely on data contract types (like options and results
+ * for retrieval/ingestion) defined in `../rag/IRetrievalAugmentor.ts`.
+ *
+ * @module backend/agentos/config/RetrievalAugmentorConfiguration
+ * @see ../rag/IRetrievalAugmentor.ts for operational data contracts.
+ * @see ../rag/RetrievalAugmentor.ts for the concrete implementation using this config.
+ */
+export {};
+// Example of how categoryBehaviors might be configured:
+/*
+const exampleRetrievalAugmentorServiceConfig: RetrievalAugmentorServiceConfig = {
+  categoryBehaviors: [
+    {
+      category: RagMemoryCategory.SHARED_KNOWLEDGE_BASE,
+      targetDataSourceIds: ['global_wiki_main', 'global_faq_secondary'],
+      defaultRetrievalOptions: { topK: 5, strategyParams: { mmrLambda: 0.7 } },
+      defaultIngestionOptions: { chunkingStrategy: { type: 'recursive_character', chunkSize: 1000, chunkOverlap: 100 } },
+      queryPriority: 10,
+    },
+    {
+      category: RagMemoryCategory.USER_EXPLICIT_MEMORY,
+      targetDataSourceIds: ['user_private_notes_vector_store'],
+      isUserSpecific: true,
+      defaultRetrievalOptions: { topK: 3 },
+      queryPriority: 100, // High priority for personal user memory
+      retentionDays: 365, // User notes kept for a year by default
+    },
+    {
+      category: RagMemoryCategory.PERSONAL_LLM_EXPERIENCE,
+      targetDataSourceIds: ['gmi_self_learnings_collection'],
+      isPersonaSpecific: true, // Or combination of user & persona
+      defaultRetrievalOptions: { topK: 2, strategyParams: { mmrLambda: 0.5 } },
+      queryPriority: 50,
+    }
+  ],
+  globalDefaultRetrievalOptions: { topK: 3, strategy: 'similarity' },
+  maxCharsForAugmentedPrompt: 3000,
+  contextJoinSeparator: "\n\n[SOURCE]\n",
+};
+*/
+//# sourceMappingURL=RetrievalAugmentorConfiguration.js.map

package/dist/core/config/RetrievalAugmentorConfiguration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalAugmentorConfiguration.js","sourceRoot":"","sources":["../../../src/core/config/RetrievalAugmentorConfiguration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;;AAiHH,wDAAwD;AACxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BE"}

package/dist/core/config/ToolOrchestratorConfig.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Defines the configuration interface for the ToolOrchestrator.
+ * This configuration allows customization of various aspects of tool management,
+ * execution, and registry behavior within AgentOS, providing flexibility and control
+ * over the tool ecosystem.
+ *
+ * @module backend/agentos/config/ToolOrchestratorConfig
+ */
+/**
+ * @interface ToolRegistrySettings
+ * @description Defines settings specific to the tool registry behavior within the ToolOrchestrator.
+ * These settings control how tools are managed, whether they can be added dynamically,
+ * and conceptual aspects of persistence.
+ *
+ * @property {boolean} [allowDynamicRegistration=true] - If true (default), tools can be registered or
+ * unregistered with the orchestrator after its initial initialization. If false, the set of
+ * available tools is fixed once the orchestrator is initialized.
+ * @property {boolean} [persistRegistry=false] - If true (default: false), this conceptually indicates that the tool
+ * registry's state (e.g., list of dynamically registered tools, their versions) should be persisted
+ * to a durable store (e.g., database, configuration file). The actual persistence mechanism
+ * would be implemented within the ToolOrchestrator or a dedicated registry service.
+ * (Note: The current ToolOrchestrator uses an in-memory map).
+ * @property {string} [persistencePath] - Optional. If `persistRegistry` is true, this string could specify
+ * the path, URI, or identifier for the persisted storage location or configuration. (Conceptual).
+ */
+export interface ToolRegistrySettings {
+    allowDynamicRegistration?: boolean;
+    persistRegistry?: boolean;
+    persistencePath?: string;
+}
+export interface ToolOrchestratorHITLConfig {
+    /**
+     * Enable HITL gating inside the ToolOrchestrator.
+     * Default: false.
+     */
+    enabled?: boolean;
+    /**
+     * If true, tools with `tool.hasSideEffects === true` require an approval before execution.
+     * Default: true (when HITL is enabled).
+     */
+    requireApprovalForSideEffects?: boolean;
+    /**
+     * Default severity for side-effect tool approvals.
+     * Default: 'high'.
+     */
+    defaultSideEffectsSeverity?: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Optional per-approval timeout (ms). If omitted, the HITL manager's default timeout is used.
+     */
+    approvalTimeoutMs?: number;
+    /**
+     * If true, ToolOrchestrator will execute side-effect tools even if no HITL manager was provided.
+     * Default: false.
+     */
+    autoApproveWhenNoManager?: boolean;
+}
+/**
+ * @interface ToolOrchestratorConfig
+ * @description Configuration options for the ToolOrchestrator.
+ * This interface allows for fine-tuning its operational parameters, default behaviors,
+ * logging levels, and integration points with other system components.
+ *
+ * @property {string} [orchestratorId] - An optional unique identifier for this ToolOrchestrator instance.
+ * If not provided, one may be generated automatically (e.g., by the orchestrator's constructor).
+ * This ID is useful for logging, debugging, and potentially for managing multiple orchestrator instances
+ * in more complex or distributed setups.
+ * @property {number} [defaultToolCallTimeoutMs=30000] - Default timeout in milliseconds (default: 30 seconds)
+ * for a tool execution if the tool itself does not specify a more granular timeout or if the `ToolExecutor`
+ * needs a fallback. (Note: Actual timeout enforcement is typically handled by the `ToolExecutor` or the tool implementation).
+ * @property {number} [maxConcurrentToolCalls=10] - Maximum number of tool calls that the orchestrator, or more likely
+ * the underlying `ToolExecutor`, will attempt to process concurrently. This helps in managing system resources
+ * and preventing overload from too many simultaneous tool executions. (Conceptual for orchestrator, executor enforces).
+ * @property {boolean} [logToolCalls=true] - If true (default), detailed information about tool calls (including requests,
+ * arguments, results, and any errors) will be logged by the orchestrator. This is highly beneficial for
+ * debugging, auditing tool usage, and monitoring system behavior.
+ * @property {string[]} [globalDisabledTools] - An array of tool names (`ITool.name`) or tool IDs (`ITool.id`)
+ * that are globally disabled. These tools will not be registered or, if already present, will not be
+ * executed, irrespective of other permission settings. This provides a system-wide mechanism to quickly
+ * disable problematic or deprecated tools.
+ * @property {ToolRegistrySettings} [toolRegistrySettings] - Configuration settings that specifically govern
+ * the behavior of the internal tool registry, such as dynamic registration allowance.
+ * @property {Record<string, any>} [customParameters] - A flexible object to accommodate any other custom
+ * parameters or settings that specific `ToolOrchestrator` implementations or extensions might require.
+ * This allows for extensibility without modifying the core interface.
+ */
+export interface ToolOrchestratorConfig {
+    orchestratorId?: string;
+    defaultToolCallTimeoutMs?: number;
+    maxConcurrentToolCalls?: number;
+    logToolCalls?: boolean;
+    globalDisabledTools?: string[];
+    toolRegistrySettings?: ToolRegistrySettings;
+    hitl?: ToolOrchestratorHITLConfig;
+    customParameters?: Record<string, any>;
+}
+//# sourceMappingURL=ToolOrchestratorConfig.d.ts.map

package/dist/core/config/ToolOrchestratorConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolOrchestratorConfig.d.ts","sourceRoot":"","sources":["../../../src/core/config/ToolOrchestratorConfig.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,6BAA6B,CAAC,EAAE,OAAO,CAAC;IACxC;;;OAGG;IACH,0BAA0B,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACpE;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C,IAAI,CAAC,EAAE,0BAA0B,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACxC"}

package/dist/core/config/ToolOrchestratorConfig.js

@@ -0,0 +1,11 @@
+// File: backend/agentos/config/ToolOrchestratorConfig.ts
+/**
+ * @fileoverview Defines the configuration interface for the ToolOrchestrator.
+ * This configuration allows customization of various aspects of tool management,
+ * execution, and registry behavior within AgentOS, providing flexibility and control
+ * over the tool ecosystem.
+ *
+ * @module backend/agentos/config/ToolOrchestratorConfig
+ */
+export {};
+//# sourceMappingURL=ToolOrchestratorConfig.js.map

package/dist/core/config/ToolOrchestratorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolOrchestratorConfig.js","sourceRoot":"","sources":["../../../src/core/config/ToolOrchestratorConfig.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD;;;;;;;GAOG"}