@elevasis/core 0.7.1 → 0.8.0

package/src/execution/engine/agent/knowledge-map/types.ts

@@ -1,106 +1,106 @@
-/**
- * Knowledge Map Types
- *
- * Enables agents to navigate organizational knowledge through a lightweight
- * graph that lazy-loads capabilities on-demand.
- *
- * @module agent/knowledge-map
- */
-
-import type { Tool } from '../../tools/types'
-import type { ExecutionContext } from '../../base/types'
-
-/**
- * Lightweight knowledge map (passed as agent property)
- *
- * Contains metadata about available knowledge nodes without loading
- * the full content upfront. Total size: ~300-500 tokens.
- *
- * Multi-tenancy is enforced via:
- * - File-scoped maps (organizations/{org-name}/knowledge/)
- * - ExecutionContext.organizationId passed to node.load()
- */
-export interface KnowledgeMap {
-  /** Available knowledge nodes indexed by ID */
-  nodes: Record<string, KnowledgeNode>
-}
-
-/**
- * Single knowledge source
- *
- * Represents a domain knowledge area (CRM, brand guidelines, Excel tools)
- * that can be lazy-loaded to provide instructions and tools to agents.
- */
-export interface KnowledgeNode {
-  /** Unique identifier for this node (e.g., "crm", "brand-guidelines") */
-  id: string
-
-  /**
-   * Description of when to use this knowledge
-   * Used for semantic matching against user intent
-   */
-  description: string
-
-  /**
-   * Load knowledge content on-demand
-   *
-   * @param context - Execution context with organizationId for multi-tenancy
-   * @returns Promise resolving to knowledge content (prompt + optional tools)
-   */
-  load(context: ExecutionContext): Promise<KnowledgeContent>
-
-  /**
-   * Loaded state flag
-   * Set to true after load() is called
-   */
-  loaded?: boolean
-
-  /**
-   * Cached prompt (for system prompt serialization)
-   * Only the prompt is cached - tools go to toolRegistry, children flattened to nodes
-   */
-  prompt?: string
-}
-
-/**
- * Content returned by knowledge node
- *
- * Separates instructions (prompt) from capabilities (tools).
- * Tools are optional - some nodes only provide context.
- *
- * Supports recursive navigation - nodes can contain child nodes
- * that are discovered when the parent node is loaded.
- */
-export interface KnowledgeContent {
-  /** Instructions and context (markdown format) */
-  prompt: string
-
-  /** Tool implementations (optional) */
-  tools?: Tool[]
-
-  /**
-   * Child knowledge nodes (optional, recursive)
-   *
-   * Enables hierarchical navigation: base → specialized → deep expertise.
-   * Child nodes are flattened into the main knowledge map when parent loads,
-   * making them available for subsequent navigate-knowledge actions.
-   *
-   * Example: CRM base node returns crm-customers and crm-deals as children
-   */
-  nodes?: Record<string, KnowledgeNode>
-}
-
-/**
- * Knowledge map state for cross-turn persistence
- *
- * Stored in sessionMemory['knowledge-map-state'] to track which nodes
- * have been loaded during the session. On subsequent turns, tools are
- * re-registered from source code using these IDs.
- */
-export interface KnowledgeMapState {
-  /** List of loaded node IDs (ordered by load time) */
-  loadedNodes: string[]
-
-  /** State version for future compatibility */
-  version: 1
-}
+/**
+ * Knowledge Map Types
+ *
+ * Enables agents to navigate organizational knowledge through a lightweight
+ * graph that lazy-loads capabilities on-demand.
+ *
+ * @module agent/knowledge-map
+ */
+
+import type { Tool } from '../../tools/types'
+import type { ExecutionContext } from '../../base/types'
+
+/**
+ * Lightweight knowledge map (passed as agent property)
+ *
+ * Contains metadata about available knowledge nodes without loading
+ * the full content upfront. Total size: ~300-500 tokens.
+ *
+ * Multi-tenancy is enforced via:
+ * - File-scoped maps (organizations/{org-name}/knowledge/)
+ * - ExecutionContext.organizationId passed to node.load()
+ */
+export interface KnowledgeMap {
+  /** Available knowledge nodes indexed by ID */
+  nodes: Record<string, KnowledgeNode>
+}
+
+/**
+ * Single knowledge source
+ *
+ * Represents a domain knowledge area (CRM, brand guidelines, Excel tools)
+ * that can be lazy-loaded to provide instructions and tools to agents.
+ */
+export interface KnowledgeNode {
+  /** Unique identifier for this node (e.g., "crm", "brand-guidelines") */
+  id: string
+
+  /**
+   * Description of when to use this knowledge
+   * Used for semantic matching against user intent
+   */
+  description: string
+
+  /**
+   * Load knowledge content on-demand
+   *
+   * @param context - Execution context with organizationId for multi-tenancy
+   * @returns Promise resolving to knowledge content (prompt + optional tools)
+   */
+  load(context: ExecutionContext): Promise<KnowledgeContent>
+
+  /**
+   * Loaded state flag
+   * Set to true after load() is called
+   */
+  loaded?: boolean
+
+  /**
+   * Cached prompt (for system prompt serialization)
+   * Only the prompt is cached - tools go to toolRegistry, children flattened to nodes
+   */
+  prompt?: string
+}
+
+/**
+ * Content returned by knowledge node
+ *
+ * Separates instructions (prompt) from capabilities (tools).
+ * Tools are optional - some nodes only provide context.
+ *
+ * Supports recursive navigation - nodes can contain child nodes
+ * that are discovered when the parent node is loaded.
+ */
+export interface KnowledgeContent {
+  /** Instructions and context (markdown format) */
+  prompt: string
+
+  /** Tool implementations (optional) */
+  tools?: Tool[]
+
+  /**
+   * Child knowledge nodes (optional, recursive)
+   *
+   * Enables hierarchical navigation: base → specialized → deep expertise.
+   * Child nodes are flattened into the main knowledge map when parent loads,
+   * making them available for subsequent navigate-knowledge actions.
+   *
+   * Example: CRM base node returns crm-customers and crm-deals as children
+   */
+  nodes?: Record<string, KnowledgeNode>
+}
+
+/**
+ * Knowledge map state for cross-turn persistence
+ *
+ * Stored in sessionMemory['knowledge-map-state'] to track which nodes
+ * have been loaded during the session. On subsequent turns, tools are
+ * re-registered from source code using these IDs.
+ */
+export interface KnowledgeMapState {
+  /** List of loaded node IDs (ordered by load time) */
+  loadedNodes: string[]
+
+  /** State version for future compatibility */
+  version: 1
+}

package/src/execution/engine/agent/knowledge-map/utils.ts

@@ -1,101 +1,101 @@
-/**
- * Knowledge Map Utilities
- *
- * Helper functions for knowledge map operations
- */
-
-import type { KnowledgeMap, KnowledgeMapState } from './types'
-import type { Tool } from '../../tools/types'
-import type { ExecutionContext } from '../../base/types'
-import type { AgentMemory } from '../memory/types'
-import { errorToString } from '../../../../platform/utils/error'
-
-/**
- * Reload tools from knowledge map state (cross-turn persistence)
- *
- * Reads the knowledge-map-state from sessionMemory and rebuilds the runtime
- * knowledge map by re-loading nodes and re-discovering their child nodes.
- *
- * This reconstructs the full map structure that existed at the end of the
- * previous turn, including both explicitly loaded nodes and discovered children.
- *
- * @param knowledgeMap - The agent's knowledge map (will be mutated to add child nodes)
- * @param memory - Agent memory with sessionMemory state
- * @param context - Execution context
- * @returns Array of tools to register with the agent
- *
- * @example
- * ```typescript
- * async function initializeMemoryManager(context: ExecutionContext) {
- *   const memory = await preloadMemory(context)
- *
- *   // Reload tools from loaded knowledge nodes
- *   if (knowledgeMap) {
- *     const tools = await reloadKnowledgeMapTools(knowledgeMap, memory, context)
- *     // Tools will be registered by caller
- *   }
- *
- *   return memory
- * }
- * ```
- */
-export async function reloadKnowledgeMapTools(
-  knowledgeMap: KnowledgeMap,
-  memory: AgentMemory,
-  context: ExecutionContext
-): Promise<Tool[]> {
-  const stateJson = memory.sessionMemory['knowledge-map-state']
-  if (!stateJson) {
-    return [] // No state to reload
-  }
-
-  try {
-    const state = JSON.parse(stateJson.content) as KnowledgeMapState
-    const tools: Tool[] = []
-
-    // Load each node and collect tools (BFS order - same as original load order)
-    for (const nodeId of state.loadedNodes) {
-      const node = knowledgeMap.nodes[nodeId]
-
-      if (!node) {
-        // Node no longer exists in knowledge map (definition changed)
-        context.logger.warn(`Knowledge node '${nodeId}' not found during reload (skipping)`)
-        continue
-      }
-
-      try {
-        // Re-load node content from source
-        const content = await node.load(context)
-
-        // Cache prompt and set loaded flag (minimal caching)
-        node.loaded = true
-        node.prompt = content.prompt
-
-        // Re-discover child nodes (rebuild runtime knowledge map)
-        if (content.nodes && Object.keys(content.nodes).length > 0) {
-          for (const [childId, childNode] of Object.entries(content.nodes)) {
-            if (!knowledgeMap.nodes[childId]) {
-              knowledgeMap.nodes[childId] = childNode
-            }
-          }
-        }
-
-        // Collect tools (if any)
-        if (content.tools && content.tools.length > 0) {
-          tools.push(...content.tools)
-        }
-      } catch (error) {
-        // Log error but continue with other nodes
-        const errorMessage = errorToString(error)
-        context.logger.error(`Failed to reload knowledge node '${nodeId}': ${errorMessage}`)
-      }
-    }
-
-    return tools
-  } catch (error) {
-    // Failed to parse state - return empty array
-    const errorMessage = errorToString(error)
-    context.logger.error(`Failed to parse knowledge-map-state: ${errorMessage}`)
-    return []
-  }
-}
+/**
+ * Knowledge Map Utilities
+ *
+ * Helper functions for knowledge map operations
+ */
+
+import type { KnowledgeMap, KnowledgeMapState } from './types'
+import type { Tool } from '../../tools/types'
+import type { ExecutionContext } from '../../base/types'
+import type { AgentMemory } from '../memory/types'
+import { errorToString } from '../../../../platform/utils/error'
+
+/**
+ * Reload tools from knowledge map state (cross-turn persistence)
+ *
+ * Reads the knowledge-map-state from sessionMemory and rebuilds the runtime
+ * knowledge map by re-loading nodes and re-discovering their child nodes.
+ *
+ * This reconstructs the full map structure that existed at the end of the
+ * previous turn, including both explicitly loaded nodes and discovered children.
+ *
+ * @param knowledgeMap - The agent's knowledge map (will be mutated to add child nodes)
+ * @param memory - Agent memory with sessionMemory state
+ * @param context - Execution context
+ * @returns Array of tools to register with the agent
+ *
+ * @example
+ * ```typescript
+ * async function initializeMemoryManager(context: ExecutionContext) {
+ *   const memory = await preloadMemory(context)
+ *
+ *   // Reload tools from loaded knowledge nodes
+ *   if (knowledgeMap) {
+ *     const tools = await reloadKnowledgeMapTools(knowledgeMap, memory, context)
+ *     // Tools will be registered by caller
+ *   }
+ *
+ *   return memory
+ * }
+ * ```
+ */
+export async function reloadKnowledgeMapTools(
+  knowledgeMap: KnowledgeMap,
+  memory: AgentMemory,
+  context: ExecutionContext
+): Promise<Tool[]> {
+  const stateJson = memory.sessionMemory['knowledge-map-state']
+  if (!stateJson) {
+    return [] // No state to reload
+  }
+
+  try {
+    const state = JSON.parse(stateJson.content) as KnowledgeMapState
+    const tools: Tool[] = []
+
+    // Load each node and collect tools (BFS order - same as original load order)
+    for (const nodeId of state.loadedNodes) {
+      const node = knowledgeMap.nodes[nodeId]
+
+      if (!node) {
+        // Node no longer exists in knowledge map (definition changed)
+        context.logger.warn(`Knowledge node '${nodeId}' not found during reload (skipping)`)
+        continue
+      }
+
+      try {
+        // Re-load node content from source
+        const content = await node.load(context)
+
+        // Cache prompt and set loaded flag (minimal caching)
+        node.loaded = true
+        node.prompt = content.prompt
+
+        // Re-discover child nodes (rebuild runtime knowledge map)
+        if (content.nodes && Object.keys(content.nodes).length > 0) {
+          for (const [childId, childNode] of Object.entries(content.nodes)) {
+            if (!knowledgeMap.nodes[childId]) {
+              knowledgeMap.nodes[childId] = childNode
+            }
+          }
+        }
+
+        // Collect tools (if any)
+        if (content.tools && content.tools.length > 0) {
+          tools.push(...content.tools)
+        }
+      } catch (error) {
+        // Log error but continue with other nodes
+        const errorMessage = errorToString(error)
+        context.logger.error(`Failed to reload knowledge node '${nodeId}': ${errorMessage}`)
+      }
+    }
+
+    return tools
+  } catch (error) {
+    // Failed to parse state - return empty array
+    const errorMessage = errorToString(error)
+    context.logger.error(`Failed to parse knowledge-map-state: ${errorMessage}`)
+    return []
+  }
+}