@deimoscloud/coreai 0.1.0

package/src/agents/loader.ts

@@ -0,0 +1,143 @@
+/**
+ * Agent Loader
+ *
+ * Handles loading and validating agent YAML definitions.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { basename, extname, join } from 'path';
+import { parse as parseYaml } from 'yaml';
+import Ajv, { type ErrorObject } from 'ajv';
+import type { AgentDefinition, AgentMetadata, AgentSource } from './types.js';
+
+// Import schema as JSON
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const agentSchema = require('../../schemas/agent.schema.json') as object;
+
+export class AgentError extends Error {
+  constructor(
+    message: string,
+    public readonly code: AgentErrorCode,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'AgentError';
+  }
+}
+
+export type AgentErrorCode = 'NOT_FOUND' | 'PARSE_ERROR' | 'VALIDATION_ERROR' | 'READ_ERROR';
+
+/**
+ * Parse YAML content into an agent definition
+ */
+export function parseAgentYaml(content: string, filePath?: string): unknown {
+  try {
+    return parseYaml(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown parse error';
+    throw new AgentError(
+      `Failed to parse agent YAML${filePath ? ` in ${filePath}` : ''}: ${message}`,
+      'PARSE_ERROR',
+      error
+    );
+  }
+}
+
+/**
+ * Validate parsed YAML against agent schema
+ */
+export function validateAgentDefinition(agent: unknown): AgentDefinition {
+  const ajv = new Ajv.default({ allErrors: true, strict: false });
+  const validate = ajv.compile<AgentDefinition>(agentSchema);
+  const valid = validate(agent);
+
+  if (!valid) {
+    const errors: ErrorObject[] = validate.errors ?? [];
+    const errorMessages = errors.map((err: ErrorObject) => {
+      const path = err.instancePath || 'root';
+      return `${path}: ${err.message ?? 'unknown error'}`;
+    });
+
+    throw new AgentError(
+      `Agent validation failed:\n  - ${errorMessages.join('\n  - ')}`,
+      'VALIDATION_ERROR',
+      errors
+    );
+  }
+
+  return agent as AgentDefinition;
+}
+
+/**
+ * Load and validate an agent definition from a file
+ */
+export function loadAgentFromFile(filePath: string): AgentDefinition {
+  if (!existsSync(filePath)) {
+    throw new AgentError(`Agent file not found: ${filePath}`, 'NOT_FOUND');
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(filePath, 'utf-8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown read error';
+    throw new AgentError(`Failed to read agent file ${filePath}: ${message}`, 'READ_ERROR', error);
+  }
+
+  const parsed = parseAgentYaml(content, filePath);
+  return validateAgentDefinition(parsed);
+}
+
+/**
+ * List all YAML files in a directory
+ */
+function listYamlFiles(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir)
+    .filter((file) => {
+      const ext = extname(file).toLowerCase();
+      return ext === '.yaml' || ext === '.yml';
+    })
+    .map((file) => join(dir, file));
+}
+
+/**
+ * Load all agents from a directory
+ */
+export function loadAgentsFromDirectory(
+  dir: string,
+  source: AgentSource
+): Map<string, AgentMetadata> {
+  const agents = new Map<string, AgentMetadata>();
+  const files = listYamlFiles(dir);
+
+  for (const filePath of files) {
+    try {
+      const definition = loadAgentFromFile(filePath);
+      agents.set(definition.role, {
+        definition,
+        source,
+        filePath,
+      });
+    } catch (error) {
+      // Log warning but continue loading other agents
+      const fileName = basename(filePath);
+      console.warn(`Warning: Failed to load agent from ${fileName}: ${(error as Error).message}`);
+    }
+  }
+
+  return agents;
+}
+
+/**
+ * Get the agent role name from a filename
+ */
+export function getRoleFromFilename(filePath: string): string {
+  const fileName = basename(filePath);
+  const ext = extname(fileName);
+  return fileName.slice(0, -ext.length);
+}

package/src/agents/resolver.test.ts

@@ -0,0 +1,282 @@
+import {
+  resolveString,
+  resolveObject,
+  resolveAgentDefinition,
+  hasVariables,
+  extractVariables,
+  ResolutionError,
+} from './resolver.js';
+import type { CoreAIConfig } from '../config/types.js';
+import type { AgentDefinition } from './types.js';
+
+describe('Variable Resolver', () => {
+  const mockConfig: CoreAIConfig = {
+    version: '1.0',
+    project: {
+      name: 'test-project',
+      type: 'software',
+    },
+    team: {
+      agents: ['backend-engineer', 'frontend-engineer'],
+    },
+    integrations: {
+      documentation: {
+        provider: 'confluence',
+        config: {
+          base_url: 'https://docs.example.com',
+          space_key: 'TEAM',
+        },
+      },
+      issue_tracker: {
+        provider: 'jira',
+        config: {
+          base_url: 'https://jira.example.com',
+          project_key: 'PROJ',
+        },
+      },
+      git: {
+        provider: 'github',
+        config: {
+          repo: 'org/repo',
+          default_branch: 'main',
+        },
+      },
+    },
+    tech_stack: {
+      primary_language: 'TypeScript',
+      frameworks: ['React', 'Node.js'],
+      cloud: 'AWS',
+    },
+    quality_gates: {
+      lint: { command: 'npm run lint', required: true },
+      test: { command: 'npm test', required: true },
+    },
+  };
+
+  const mockAgent: AgentDefinition = {
+    role: 'backend-engineer',
+    type: 'ic-engineer',
+    display_name: 'Backend Engineer',
+    description: 'A backend engineer',
+  };
+
+  describe('resolveString', () => {
+    it('should resolve config variables', () => {
+      const result = resolveString('Project: ${config.project.name}', { config: mockConfig });
+      expect(result).toBe('Project: test-project');
+    });
+
+    it('should resolve nested config variables', () => {
+      const result = resolveString('Language: ${config.tech_stack.primary_language}', {
+        config: mockConfig,
+      });
+      expect(result).toBe('Language: TypeScript');
+    });
+
+    it('should resolve agent variables', () => {
+      const result = resolveString('Role: ${agent.role}', { agent: mockAgent });
+      expect(result).toBe('Role: backend-engineer');
+    });
+
+    it('should resolve remote.documentation shortcut', () => {
+      const result = resolveString('Docs: ${remote.documentation}', { config: mockConfig });
+      expect(result).toBe('Docs: https://docs.example.com');
+    });
+
+    it('should resolve remote.issues shortcut', () => {
+      const result = resolveString('Issues: ${remote.issues}', { config: mockConfig });
+      expect(result).toBe('Issues: https://jira.example.com');
+    });
+
+    it('should resolve remote.git shortcut', () => {
+      const result = resolveString('Repo: ${remote.git}', { config: mockConfig });
+      expect(result).toBe('Repo: org/repo');
+    });
+
+    it('should resolve multiple variables in one string', () => {
+      const result = resolveString('${agent.role} on ${config.project.name}', {
+        config: mockConfig,
+        agent: mockAgent,
+      });
+      expect(result).toBe('backend-engineer on test-project');
+    });
+
+    it('should leave unresolved variables as-is in non-strict mode', () => {
+      const result = resolveString('Value: ${config.nonexistent}', { config: mockConfig });
+      expect(result).toBe('Value: ${config.nonexistent}');
+    });
+
+    it('should throw in strict mode for unresolved variables', () => {
+      expect(() => {
+        resolveString('Value: ${config.nonexistent}', { config: mockConfig }, { strict: true });
+      }).toThrow(ResolutionError);
+    });
+
+    it('should throw in strict mode for missing context', () => {
+      expect(() => {
+        resolveString('Value: ${config.project.name}', {}, { strict: true });
+      }).toThrow(ResolutionError);
+    });
+
+    it('should resolve arrays as JSON', () => {
+      const result = resolveString('Frameworks: ${config.tech_stack.frameworks}', {
+        config: mockConfig,
+      });
+      expect(result).toBe('Frameworks: ["React","Node.js"]');
+    });
+
+    it('should resolve objects as JSON', () => {
+      const result = resolveString('Gate: ${config.quality_gates.lint}', { config: mockConfig });
+      expect(result).toBe('Gate: {"command":"npm run lint","required":true}');
+    });
+
+    it('should handle strings without variables', () => {
+      const result = resolveString('No variables here', { config: mockConfig });
+      expect(result).toBe('No variables here');
+    });
+  });
+
+  describe('hasVariables', () => {
+    it('should return true for strings with variables', () => {
+      expect(hasVariables('${config.project.name}')).toBe(true);
+      expect(hasVariables('Hello ${agent.role}')).toBe(true);
+    });
+
+    it('should return false for strings without variables', () => {
+      expect(hasVariables('No variables')).toBe(false);
+      expect(hasVariables('Just $ signs')).toBe(false);
+    });
+  });
+
+  describe('extractVariables', () => {
+    it('should extract single variable', () => {
+      const vars = extractVariables('${config.project.name}');
+      expect(vars).toEqual(['config.project.name']);
+    });
+
+    it('should extract multiple variables', () => {
+      const vars = extractVariables('${agent.role} on ${config.project.name}');
+      expect(vars).toEqual(['agent.role', 'config.project.name']);
+    });
+
+    it('should return empty array for no variables', () => {
+      const vars = extractVariables('No variables');
+      expect(vars).toEqual([]);
+    });
+  });
+
+  describe('resolveObject', () => {
+    it('should resolve variables in nested objects', () => {
+      const input = {
+        name: '${config.project.name}',
+        agent: {
+          role: '${agent.role}',
+          display: '${agent.display_name}',
+        },
+      };
+
+      const result = resolveObject(input, { config: mockConfig, agent: mockAgent });
+
+      expect(result).toEqual({
+        name: 'test-project',
+        agent: {
+          role: 'backend-engineer',
+          display: 'Backend Engineer',
+        },
+      });
+    });
+
+    it('should resolve variables in arrays', () => {
+      const input = {
+        sources: ['${remote.documentation}/architecture', '${remote.documentation}/api'],
+      };
+
+      const result = resolveObject(input, { config: mockConfig });
+
+      expect(result).toEqual({
+        sources: ['https://docs.example.com/architecture', 'https://docs.example.com/api'],
+      });
+    });
+
+    it('should handle null and undefined values', () => {
+      const input = {
+        value: null,
+        other: undefined,
+        name: '${config.project.name}',
+      };
+
+      const result = resolveObject(input, { config: mockConfig });
+
+      expect(result).toEqual({
+        value: null,
+        other: undefined,
+        name: 'test-project',
+      });
+    });
+
+    it('should preserve non-string primitives', () => {
+      const input = {
+        count: 42,
+        enabled: true,
+        name: '${config.project.name}',
+      };
+
+      const result = resolveObject(input, { config: mockConfig });
+
+      expect(result).toEqual({
+        count: 42,
+        enabled: true,
+        name: 'test-project',
+      });
+    });
+  });
+
+  describe('resolveAgentDefinition', () => {
+    it('should resolve all variables in an agent definition', () => {
+      const agent: AgentDefinition = {
+        role: 'backend-engineer',
+        type: 'ic-engineer',
+        display_name: 'Backend Engineer',
+        description: 'Backend engineer for ${config.project.name}',
+        expertise: {
+          primary: ['API design'],
+          tech_stack: '${config.tech_stack}',
+        },
+        behaviors: {
+          workflow: 'ticket-implementation',
+          quality_gates: '${config.quality_gates}',
+        },
+        context_sources: {
+          shared: ['${remote.documentation}/architecture'],
+          personal: ['KnowledgeLibrary/${agent.role}/context'],
+        },
+        communication: {
+          inbox: 'KnowledgeLibrary/${agent.role}/inbox',
+          outbox: 'KnowledgeLibrary/${agent.role}/outbox',
+        },
+      };
+
+      const resolved = resolveAgentDefinition(agent, mockConfig);
+
+      expect(resolved.description).toBe('Backend engineer for test-project');
+      expect(resolved.context_sources?.shared?.[0]).toBe('https://docs.example.com/architecture');
+      expect(resolved.context_sources?.personal?.[0]).toBe(
+        'KnowledgeLibrary/backend-engineer/context'
+      );
+      expect(resolved.communication?.inbox).toBe('KnowledgeLibrary/backend-engineer/inbox');
+    });
+
+    it('should work without config', () => {
+      const agent: AgentDefinition = {
+        role: 'test-agent',
+        type: 'ic-engineer',
+        display_name: 'Test Agent',
+        description: 'Agent role: ${agent.role}',
+      };
+
+      const resolved = resolveAgentDefinition(agent);
+
+      expect(resolved.description).toBe('Agent role: test-agent');
+    });
+  });
+});

package/src/agents/resolver.ts

@@ -0,0 +1,262 @@
+/**
+ * Variable Resolution System
+ *
+ * Resolves variable placeholders in agent definitions.
+ * Supports: ${config.*}, ${agent.*}, ${remote.*}
+ */
+
+import type { CoreAIConfig } from '../config/types.js';
+import type { AgentDefinition } from './types.js';
+
+/**
+ * Context for variable resolution
+ */
+export interface ResolutionContext {
+  config?: CoreAIConfig;
+  agent?: AgentDefinition;
+}
+
+/**
+ * Options for variable resolution
+ */
+export interface ResolutionOptions {
+  /**
+   * If true, throw an error for unresolved variables.
+   * If false, leave unresolved variables as-is.
+   * Default: false
+   */
+  strict?: boolean;
+}
+
+/**
+ * Error thrown when variable resolution fails
+ */
+export class ResolutionError extends Error {
+  constructor(
+    message: string,
+    public readonly variable: string,
+    public readonly path?: string
+  ) {
+    super(message);
+    this.name = 'ResolutionError';
+  }
+}
+
+/**
+ * Pattern to match variable placeholders: ${namespace.path.to.value}
+ */
+const VARIABLE_PATTERN = /\$\{([a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*)\}/gi;
+
+/**
+ * Get a nested value from an object using dot notation
+ */
+function getNestedValue(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Resolve a single variable reference
+ */
+function resolveVariable(
+  variable: string,
+  context: ResolutionContext,
+  options: ResolutionOptions
+): string | undefined {
+  const parts = variable.split('.');
+  const namespace = parts[0];
+  const path = parts.slice(1).join('.');
+
+  let value: unknown;
+
+  switch (namespace) {
+    case 'config':
+      if (!context.config) {
+        if (options.strict) {
+          throw new ResolutionError(
+            `Cannot resolve \${${variable}}: no config context provided`,
+            variable
+          );
+        }
+        return undefined;
+      }
+      value = getNestedValue(context.config, path);
+      break;
+
+    case 'agent':
+      if (!context.agent) {
+        if (options.strict) {
+          throw new ResolutionError(
+            `Cannot resolve \${${variable}}: no agent context provided`,
+            variable
+          );
+        }
+        return undefined;
+      }
+      value = getNestedValue(context.agent, path);
+      break;
+
+    case 'remote':
+      // Remote is a shortcut for integration URLs
+      value = resolveRemoteVariable(path, context, options);
+      break;
+
+    default:
+      if (options.strict) {
+        throw new ResolutionError(`Unknown variable namespace: ${namespace}`, variable);
+      }
+      return undefined;
+  }
+
+  if (value === undefined) {
+    if (options.strict) {
+      throw new ResolutionError(`Cannot resolve \${${variable}}: path not found`, variable, path);
+    }
+    return undefined;
+  }
+
+  // Convert value to string representation
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  // For objects/arrays, return JSON representation
+  return JSON.stringify(value);
+}
+
+/**
+ * Resolve remote.* variables (shortcuts to integration URLs)
+ */
+function resolveRemoteVariable(
+  path: string,
+  context: ResolutionContext,
+  options: ResolutionOptions
+): string | undefined {
+  if (!context.config?.integrations) {
+    if (options.strict) {
+      throw new ResolutionError(
+        `Cannot resolve \${remote.${path}}: no integrations configured`,
+        `remote.${path}`
+      );
+    }
+    return undefined;
+  }
+
+  const integrations = context.config.integrations;
+
+  // Map remote shortcuts to integration paths
+  switch (path) {
+    case 'documentation':
+      return (
+        integrations.documentation?.config?.base_url ??
+        integrations.documentation?.config?.base_path
+      );
+
+    case 'issues':
+      return integrations.issue_tracker?.config?.base_url;
+
+    case 'git':
+      return integrations.git?.config?.repo;
+
+    case 'state':
+      return integrations.state?.config?.base_path ?? integrations.state?.config?.bucket;
+
+    default:
+      // Try to resolve as nested path under integrations
+      return getNestedValue(integrations, path) as string | undefined;
+  }
+}
+
+/**
+ * Resolve all variables in a string
+ */
+export function resolveString(
+  input: string,
+  context: ResolutionContext,
+  options: ResolutionOptions = {}
+): string {
+  return input.replace(VARIABLE_PATTERN, (match, variable: string) => {
+    const resolved = resolveVariable(variable, context, options);
+    return resolved !== undefined ? resolved : match;
+  });
+}
+
+/**
+ * Check if a string contains variable placeholders
+ */
+export function hasVariables(input: string): boolean {
+  // Create new regex to avoid state issues with global flag
+  const pattern = /\$\{([a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*)\}/i;
+  return pattern.test(input);
+}
+
+/**
+ * Extract all variable references from a string
+ */
+export function extractVariables(input: string): string[] {
+  const matches = input.matchAll(VARIABLE_PATTERN);
+  return Array.from(matches, (m) => m[1]).filter((v): v is string => v !== undefined);
+}
+
+/**
+ * Recursively resolve all variables in an object
+ */
+export function resolveObject<T>(
+  obj: T,
+  context: ResolutionContext,
+  options: ResolutionOptions = {}
+): T {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (typeof obj === 'string') {
+    return resolveString(obj, context, options) as T;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => resolveObject(item, context, options)) as T;
+  }
+
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = resolveObject(value, context, options);
+    }
+    return result as T;
+  }
+
+  return obj;
+}
+
+/**
+ * Resolve all variables in an agent definition
+ */
+export function resolveAgentDefinition(
+  agent: AgentDefinition,
+  config?: CoreAIConfig,
+  options: ResolutionOptions = {}
+): AgentDefinition {
+  const context: ResolutionContext = {
+    agent,
+  };
+  if (config) {
+    context.config = config;
+  }
+
+  return resolveObject(agent, context, options);
+}