@deimoscloud/coreai 0.1.0

package/src/knowledge-library/manager.ts

@@ -0,0 +1,804 @@
+/**
+ * KnowledgeLibrary Manager
+ *
+ * Manages the KnowledgeLibrary directory structure and agent state.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+} from 'fs';
+import { join, basename } from 'path';
+import type {
+  AgentDirectories,
+  AgentKnowledgeState,
+  InitKnowledgeLibraryOptions,
+  InitKnowledgeLibraryResult,
+  KnowledgeLibraryState,
+  Message,
+  MessageMetadata,
+  ReadMessagesOptions,
+  WriteMessageOptions,
+  AgentContext,
+} from './types.js';
+
+/**
+ * Default KnowledgeLibrary base path
+ */
+export const DEFAULT_KNOWLEDGE_LIBRARY_PATH = 'KnowledgeLibrary';
+
+/**
+ * Standard files in a KnowledgeLibrary
+ */
+export const STANDARD_FILES = {
+  context: 'context.txt',
+  architecture: 'architecture.txt',
+  prd: 'prd.txt',
+} as const;
+
+/**
+ * Standard directories for each agent
+ */
+export const AGENT_DIRECTORIES = [
+  'inbox',
+  'inbox/processed',
+  'outbox',
+  'context',
+  'control',
+  'history',
+  'tech',
+] as const;
+
+/**
+ * Standard files in an agent's control directory
+ */
+export const CONTROL_FILES = {
+  objectives: 'objectives.txt',
+  decisions: 'decisions.txt',
+  dependencies: 'dependencies.txt',
+} as const;
+
+/**
+ * Get the path to an agent's directories
+ */
+export function getAgentDirectories(basePath: string, agentName: string): AgentDirectories {
+  const root = join(basePath, agentName);
+  return {
+    root,
+    inbox: join(root, 'inbox'),
+    inboxProcessed: join(root, 'inbox', 'processed'),
+    outbox: join(root, 'outbox'),
+    context: join(root, 'context'),
+    control: join(root, 'control'),
+    history: join(root, 'history'),
+    tech: join(root, 'tech'),
+  };
+}
+
+/**
+ * Initialize the KnowledgeLibrary base structure
+ */
+export function initKnowledgeLibrary(
+  options: InitKnowledgeLibraryOptions = {}
+): InitKnowledgeLibraryResult {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const createDefaults = options.createDefaults ?? true;
+
+  const createdDirs: string[] = [];
+  const createdFiles: string[] = [];
+
+  try {
+    // Create base directory
+    if (!existsSync(basePath)) {
+      mkdirSync(basePath, { recursive: true });
+      createdDirs.push(basePath);
+    }
+
+    // Create default global files if requested
+    if (createDefaults) {
+      // context.txt
+      const contextPath = join(basePath, STANDARD_FILES.context);
+      if (!existsSync(contextPath)) {
+        writeFileSync(
+          contextPath,
+          `# Project Context
+
+## Current Sprint
+- Sprint: [Sprint name/number]
+- Goals: [Sprint goals]
+- Deadline: [Sprint deadline]
+
+## Priorities
+1. [Priority 1]
+2. [Priority 2]
+3. [Priority 3]
+
+## Notes
+[Project-wide notes and context]
+`,
+          'utf-8'
+        );
+        createdFiles.push(contextPath);
+      }
+
+      // architecture.txt
+      const architecturePath = join(basePath, STANDARD_FILES.architecture);
+      if (!existsSync(architecturePath)) {
+        writeFileSync(
+          architecturePath,
+          `# Architecture Notes
+
+## Technical Decisions
+[Record major technical decisions here]
+
+## System Overview
+[High-level system architecture]
+
+## Key Components
+[Important system components]
+`,
+          'utf-8'
+        );
+        createdFiles.push(architecturePath);
+      }
+
+      // prd.txt
+      const prdPath = join(basePath, STANDARD_FILES.prd);
+      if (!existsSync(prdPath)) {
+        writeFileSync(
+          prdPath,
+          `# Product Requirements Document
+
+## Overview
+[Product overview]
+
+## Goals
+[Product goals]
+
+## Features
+[Feature list]
+
+## Requirements
+[Detailed requirements]
+`,
+          'utf-8'
+        );
+        createdFiles.push(prdPath);
+      }
+    }
+
+    return {
+      success: true,
+      createdDirs,
+      createdFiles,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      createdDirs,
+      createdFiles,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Initialize an agent's KnowledgeLibrary directories
+ */
+export function initAgentKnowledgeLibrary(
+  agentName: string,
+  options: InitKnowledgeLibraryOptions = {}
+): InitKnowledgeLibraryResult {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const createDefaults = options.createDefaults ?? true;
+
+  const createdDirs: string[] = [];
+  const createdFiles: string[] = [];
+
+  try {
+    // Ensure base KnowledgeLibrary exists
+    if (!existsSync(basePath)) {
+      const baseResult = initKnowledgeLibrary(options);
+      if (!baseResult.success) {
+        return baseResult;
+      }
+      createdDirs.push(...baseResult.createdDirs);
+      createdFiles.push(...baseResult.createdFiles);
+    }
+
+    // Get agent directories
+    const dirs = getAgentDirectories(basePath, agentName);
+
+    // Create all agent directories
+    for (const dir of AGENT_DIRECTORIES) {
+      const dirPath = join(dirs.root, dir);
+      if (!existsSync(dirPath)) {
+        mkdirSync(dirPath, { recursive: true });
+        createdDirs.push(dirPath);
+      }
+    }
+
+    // Create default files if requested
+    if (createDefaults) {
+      // context/current.txt
+      const currentContextPath = join(dirs.context, 'current.txt');
+      if (!existsSync(currentContextPath)) {
+        writeFileSync(
+          currentContextPath,
+          `# ${agentName} Current Context
+
+## Status
+- State: idle
+- Current Task: None
+- Last Updated: ${new Date().toISOString()}
+
+## Notes
+[Agent-specific context notes]
+`,
+          'utf-8'
+        );
+        createdFiles.push(currentContextPath);
+      }
+
+      // control/objectives.txt
+      const objectivesPath = join(dirs.control, CONTROL_FILES.objectives);
+      if (!existsSync(objectivesPath)) {
+        writeFileSync(
+          objectivesPath,
+          `# ${agentName} Objectives
+
+## Current Objectives
+[None]
+
+## Success Criteria
+[Define success criteria for objectives]
+`,
+          'utf-8'
+        );
+        createdFiles.push(objectivesPath);
+      }
+
+      // control/decisions.txt
+      const decisionsPath = join(dirs.control, CONTROL_FILES.decisions);
+      if (!existsSync(decisionsPath)) {
+        writeFileSync(
+          decisionsPath,
+          `# ${agentName} Decision Log
+
+## Decisions
+[Record important decisions here]
+
+Format:
+- Date: YYYY-MM-DD
+- Decision: [What was decided]
+- Reasoning: [Why]
+- Related: [Ticket or task reference]
+`,
+          'utf-8'
+        );
+        createdFiles.push(decisionsPath);
+      }
+
+      // control/dependencies.txt
+      const dependenciesPath = join(dirs.control, CONTROL_FILES.dependencies);
+      if (!existsSync(dependenciesPath)) {
+        writeFileSync(
+          dependenciesPath,
+          `# ${agentName} Dependencies
+
+## Blocked By
+[Tasks/agents blocking this agent]
+
+## Blocking
+[Tasks/agents this agent is blocking]
+
+Last Updated: ${new Date().toISOString()}
+`,
+          'utf-8'
+        );
+        createdFiles.push(dependenciesPath);
+      }
+    }
+
+    return {
+      success: true,
+      createdDirs,
+      createdFiles,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      createdDirs,
+      createdFiles,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Check if a KnowledgeLibrary exists for an agent
+ */
+export function agentKnowledgeLibraryExists(
+  agentName: string,
+  options: { projectRoot?: string; basePath?: string } = {}
+): boolean {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const agentRoot = join(basePath, agentName);
+
+  return existsSync(agentRoot) && existsSync(join(agentRoot, 'inbox'));
+}
+
+/**
+ * Get the KnowledgeLibrary state for an agent
+ */
+export function getAgentKnowledgeState(
+  agentName: string,
+  options: { projectRoot?: string; basePath?: string } = {}
+): AgentKnowledgeState {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const dirs = getAgentDirectories(basePath, agentName);
+
+  const initialized = agentKnowledgeLibraryExists(agentName, options);
+
+  // Get pending messages
+  const pendingMessages = initialized ? readInboxMessages(agentName, options) : [];
+
+  // Get context
+  let context: AgentContext | undefined;
+  const currentContextPath = join(dirs.context, 'current.txt');
+  if (existsSync(currentContextPath)) {
+    const content = readFileSync(currentContextPath, 'utf-8');
+    context = parseContextFile(content);
+  }
+
+  const state: AgentKnowledgeState = {
+    agentName,
+    directories: dirs,
+    pendingMessages,
+    initialized,
+  };
+
+  if (context) {
+    state.context = context;
+  }
+
+  return state;
+}
+
+/**
+ * Parse a context file into AgentContext
+ */
+function parseContextFile(content: string): AgentContext {
+  const context: AgentContext = {
+    lastUpdated: new Date(),
+  };
+
+  // Simple parsing - look for key patterns
+  const statusMatch = content.match(/State:\s*(.+)/i);
+  if (statusMatch && statusMatch[1]) {
+    context.status = statusMatch[1].trim();
+  }
+
+  const taskMatch = content.match(/Current Task:\s*(.+)/i);
+  if (taskMatch && taskMatch[1] && taskMatch[1].trim() !== 'None') {
+    context.currentTask = taskMatch[1].trim();
+  }
+
+  const ticketMatch = content.match(/Current Ticket:\s*([A-Z]+-\d+)/i);
+  if (ticketMatch && ticketMatch[1]) {
+    context.currentTicket = ticketMatch[1];
+  }
+
+  const updatedMatch = content.match(/Last Updated:\s*(.+)/i);
+  if (updatedMatch) {
+    const dateStr = updatedMatch[1]?.trim();
+    if (dateStr) {
+      const parsed = new Date(dateStr);
+      if (!isNaN(parsed.getTime())) {
+        context.lastUpdated = parsed;
+      }
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Generate a message filename
+ */
+export function generateMessageFilename(from: string, subject: string): string {
+  const now = new Date();
+  const timestamp = now.toISOString().replace(/[-:T]/g, '').slice(0, 12); // YYYYMMDDHHMM
+  const sanitizedSubject = subject
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .slice(0, 30);
+  return `${timestamp}-${from}-${sanitizedSubject}.md`;
+}
+
+/**
+ * Parse message frontmatter
+ */
+function parseMessageFrontmatter(content: string): {
+  metadata: Partial<MessageMetadata>;
+  body: string;
+} {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+
+  if (!match) {
+    return { metadata: {}, body: content };
+  }
+
+  const frontmatter = match[1] ?? '';
+  const body = match[2] ?? '';
+  const metadata: Partial<MessageMetadata> = {};
+
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+
+    switch (key) {
+      case 'type':
+        metadata.type = value as MessageMetadata['type'];
+        break;
+      case 'from':
+        metadata.from = value;
+        break;
+      case 'to':
+        metadata.to = value;
+        break;
+      case 'date':
+        metadata.date = new Date(value);
+        break;
+      case 'ticket':
+        metadata.ticket = value;
+        break;
+      case 'priority':
+        if (value === 'P0' || value === 'P1' || value === 'P2' || value === 'P3') {
+          metadata.priority = value;
+        }
+        break;
+      case 'subject':
+        metadata.subject = value;
+        break;
+    }
+  }
+
+  return { metadata, body };
+}
+
+/**
+ * Read inbox messages for an agent
+ */
+export function readInboxMessages(
+  agentName: string,
+  options: { projectRoot?: string; basePath?: string } & ReadMessagesOptions = {}
+): Message[] {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const dirs = getAgentDirectories(basePath, agentName);
+
+  const messages: Message[] = [];
+
+  // Read inbox
+  if (existsSync(dirs.inbox)) {
+    const files = readdirSync(dirs.inbox).filter(
+      (f) => f.endsWith('.md') && statSync(join(dirs.inbox, f)).isFile()
+    );
+
+    for (const file of files) {
+      const filePath = join(dirs.inbox, file);
+      const rawContent = readFileSync(filePath, 'utf-8');
+      const { metadata, body } = parseMessageFrontmatter(rawContent);
+
+      // Apply filters
+      if (options.type && metadata.type !== options.type) continue;
+      if (options.from && metadata.from !== options.from) continue;
+      if (options.priority && metadata.priority !== options.priority) continue;
+
+      messages.push({
+        filename: file,
+        path: filePath,
+        metadata: metadata as MessageMetadata,
+        rawContent,
+        body,
+      });
+    }
+  }
+
+  // Include processed if requested
+  if (options.includeProcessed && existsSync(dirs.inboxProcessed)) {
+    const files = readdirSync(dirs.inboxProcessed).filter(
+      (f) => f.endsWith('.md') && statSync(join(dirs.inboxProcessed, f)).isFile()
+    );
+
+    for (const file of files) {
+      const filePath = join(dirs.inboxProcessed, file);
+      const rawContent = readFileSync(filePath, 'utf-8');
+      const { metadata, body } = parseMessageFrontmatter(rawContent);
+
+      // Apply filters
+      if (options.type && metadata.type !== options.type) continue;
+      if (options.from && metadata.from !== options.from) continue;
+      if (options.priority && metadata.priority !== options.priority) continue;
+
+      messages.push({
+        filename: file,
+        path: filePath,
+        metadata: metadata as MessageMetadata,
+        rawContent,
+        body,
+      });
+    }
+  }
+
+  // Sort by date (newest first)
+  messages.sort((a, b) => {
+    const dateA = a.metadata.date?.getTime() ?? 0;
+    const dateB = b.metadata.date?.getTime() ?? 0;
+    return dateB - dateA;
+  });
+
+  // Apply limit
+  if (options.limit && messages.length > options.limit) {
+    return messages.slice(0, options.limit);
+  }
+
+  return messages;
+}
+
+/**
+ * Write a message to an agent's inbox
+ */
+export function writeInboxMessage(
+  options: WriteMessageOptions & { projectRoot?: string; basePath?: string }
+): { success: boolean; path?: string; error?: string } {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const dirs = getAgentDirectories(basePath, options.to);
+
+  try {
+    // Ensure agent inbox exists
+    if (!existsSync(dirs.inbox)) {
+      mkdirSync(dirs.inbox, { recursive: true });
+    }
+
+    // Generate filename
+    const filename = generateMessageFilename(options.from, options.subject);
+    const filePath = join(dirs.inbox, filename);
+
+    // Format message
+    const now = new Date();
+    const content = formatMessage(options, now);
+
+    // Write file
+    writeFileSync(filePath, content, 'utf-8');
+
+    // Also copy to sender's outbox
+    const senderDirs = getAgentDirectories(basePath, options.from);
+    if (existsSync(senderDirs.outbox)) {
+      writeFileSync(join(senderDirs.outbox, filename), content, 'utf-8');
+    }
+
+    return { success: true, path: filePath };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Format a message with frontmatter
+ */
+function formatMessage(options: WriteMessageOptions, date: Date): string {
+  let frontmatter = `---
+type: ${options.type}
+from: ${options.from}
+to: ${options.to}
+date: ${date.toISOString().slice(0, 16).replace('T', ' ')}`;
+
+  if (options.ticket) {
+    frontmatter += `\nticket: ${options.ticket}`;
+  }
+
+  if (options.priority) {
+    frontmatter += `\npriority: ${options.priority}`;
+  }
+
+  frontmatter += `\nsubject: ${options.subject}`;
+
+  frontmatter += `\n---
+
+## ${options.subject}
+
+${options.body}`;
+
+  return frontmatter;
+}
+
+/**
+ * Mark a message as processed (move to processed folder)
+ */
+export function markMessageProcessed(
+  agentName: string,
+  messageFilename: string,
+  options: { projectRoot?: string; basePath?: string } = {}
+): { success: boolean; error?: string } {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const dirs = getAgentDirectories(basePath, agentName);
+
+  const sourcePath = join(dirs.inbox, messageFilename);
+  const destPath = join(dirs.inboxProcessed, messageFilename);
+
+  try {
+    if (!existsSync(sourcePath)) {
+      return { success: false, error: `Message not found: ${messageFilename}` };
+    }
+
+    if (!existsSync(dirs.inboxProcessed)) {
+      mkdirSync(dirs.inboxProcessed, { recursive: true });
+    }
+
+    renameSync(sourcePath, destPath);
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Get global KnowledgeLibrary state
+ */
+export function getKnowledgeLibraryState(
+  options: { projectRoot?: string; basePath?: string } = {}
+): KnowledgeLibraryState | null {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+
+  if (!existsSync(basePath)) {
+    return null;
+  }
+
+  // Get list of agents
+  const agents: string[] = [];
+  const entries = readdirSync(basePath);
+  for (const entry of entries) {
+    const entryPath = join(basePath, entry);
+    if (statSync(entryPath).isDirectory() && existsSync(join(entryPath, 'inbox'))) {
+      agents.push(entry);
+    }
+  }
+
+  return {
+    basePath,
+    contextPath: join(basePath, STANDARD_FILES.context),
+    architecturePath: join(basePath, STANDARD_FILES.architecture),
+    prdPath: join(basePath, STANDARD_FILES.prd),
+    agents,
+  };
+}
+
+/**
+ * Update agent context
+ */
+export function updateAgentContext(
+  agentName: string,
+  context: Partial<AgentContext>,
+  options: { projectRoot?: string; basePath?: string } = {}
+): { success: boolean; error?: string } {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const basePath = join(projectRoot, options.basePath ?? DEFAULT_KNOWLEDGE_LIBRARY_PATH);
+  const dirs = getAgentDirectories(basePath, agentName);
+  const contextPath = join(dirs.context, 'current.txt');
+
+  try {
+    const now = new Date();
+    const content = `# ${agentName} Current Context
+
+## Status
+- State: ${context.status ?? 'idle'}
+- Current Task: ${context.currentTask ?? 'None'}
+${context.currentTicket ? `- Current Ticket: ${context.currentTicket}` : ''}- Last Updated: ${now.toISOString()}
+
+## Notes
+${context.notes ?? '[Agent-specific context notes]'}
+`;
+
+    if (!existsSync(dirs.context)) {
+      mkdirSync(dirs.context, { recursive: true });
+    }
+
+    writeFileSync(contextPath, content, 'utf-8');
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Format KnowledgeLibrary state for display
+ */
+export function formatKnowledgeLibraryState(state: KnowledgeLibraryState | null): string {
+  if (!state) {
+    return 'KnowledgeLibrary not initialized.';
+  }
+
+  const lines: string[] = [];
+  lines.push(`KnowledgeLibrary: ${state.basePath}\n`);
+
+  lines.push('Global files:');
+  lines.push(`  - ${basename(state.contextPath)}`);
+  lines.push(`  - ${basename(state.architecturePath)}`);
+  lines.push(`  - ${basename(state.prdPath)}`);
+  lines.push('');
+
+  if (state.agents.length > 0) {
+    lines.push(`Agents (${state.agents.length}):`);
+    for (const agent of state.agents) {
+      lines.push(`  - ${agent}`);
+    }
+  } else {
+    lines.push('No agents initialized.');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format agent knowledge state for display
+ */
+export function formatAgentKnowledgeState(state: AgentKnowledgeState): string {
+  const lines: string[] = [];
+
+  lines.push(`Agent: ${state.agentName}`);
+  lines.push(`Status: ${state.initialized ? 'Initialized' : 'Not initialized'}`);
+  lines.push('');
+
+  if (state.context) {
+    lines.push('Context:');
+    lines.push(`  State: ${state.context.status ?? 'unknown'}`);
+    if (state.context.currentTask) {
+      lines.push(`  Current Task: ${state.context.currentTask}`);
+    }
+    if (state.context.currentTicket) {
+      lines.push(`  Current Ticket: ${state.context.currentTicket}`);
+    }
+    lines.push(`  Last Updated: ${state.context.lastUpdated.toISOString()}`);
+    lines.push('');
+  }
+
+  if (state.pendingMessages.length > 0) {
+    lines.push(`Pending Messages (${state.pendingMessages.length}):`);
+    for (const msg of state.pendingMessages) {
+      const type = msg.metadata.type ?? 'unknown';
+      const from = msg.metadata.from ?? 'unknown';
+      const subject = msg.metadata.subject ?? msg.filename;
+      lines.push(`  - [${type}] from ${from}: ${subject}`);
+    }
+  } else {
+    lines.push('No pending messages.');
+  }
+
+  return lines.join('\n');
+}