/**
 * 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
}
