@deimoscloud/coreai 0.1.14 → 0.1.16

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { dirname as dirname5, join as join8 } from "path";
 import { fileURLToPath } from "url";
 
@@ -149,6 +149,61 @@ var AgentError = class extends Error {
     this.name = "AgentError";
   }
 };
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new AgentError(
+      "No YAML frontmatter found. Agent MD files must start with YAML frontmatter (---)",
+      "PARSE_ERROR"
+    );
+  }
+  const frontmatterYaml = match[1];
+  const body = match[2] ?? "";
+  let frontmatter;
+  try {
+    frontmatter = parseYaml2(frontmatterYaml);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown parse error";
+    throw new AgentError(`Failed to parse YAML frontmatter: ${message}`, "PARSE_ERROR", error);
+  }
+  if (!frontmatter || typeof frontmatter !== "object") {
+    throw new AgentError("Invalid frontmatter: expected an object", "PARSE_ERROR");
+  }
+  return { frontmatter, body };
+}
+function loadAgentFromMdFile(filePath) {
+  if (!existsSync2(filePath)) {
+    throw new AgentError(`Agent file not found: ${filePath}`, "NOT_FOUND");
+  }
+  let content;
+  try {
+    content = readFileSync2(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 { frontmatter } = extractFrontmatter(content);
+  const role = frontmatter.name || getRoleFromFilename(filePath);
+  if (!role) {
+    throw new AgentError(
+      `Agent MD file must have a 'name' field in frontmatter or a valid filename: ${filePath}`,
+      "VALIDATION_ERROR"
+    );
+  }
+  const description = frontmatter.description || "";
+  const tools = typeof frontmatter.tools === "string" ? frontmatter.tools.split(",").map((t) => t.trim()).filter(Boolean) : void 0;
+  const definition = {
+    role,
+    type: "ic-engineer",
+    // Default, actual identity is in the MD content
+    display_name: role.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+    description
+  };
+  if (tools) {
+    definition.tools = tools;
+  }
+  return definition;
+}
 function parseAgentYaml(content, filePath) {
   try {
     return parseYaml2(content);
@@ -180,7 +235,7 @@ function validateAgentDefinition(agent) {
   }
   return agent;
 }
-function loadAgentFromFile(filePath) {
+function loadAgentFromYamlFile(filePath) {
   if (!existsSync2(filePath)) {
     throw new AgentError(`Agent file not found: ${filePath}`, "NOT_FOUND");
   }
@@ -194,18 +249,36 @@ function loadAgentFromFile(filePath) {
   const parsed = parseAgentYaml(content, filePath);
   return validateAgentDefinition(parsed);
 }
-function listYamlFiles(dir) {
+function loadAgentFromFile(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".md") {
+    return loadAgentFromMdFile(filePath);
+  }
+  if (ext === ".yaml" || ext === ".yml") {
+    console.warn(
+      `Warning: YAML agent definitions are deprecated and will be removed in a future version.
+  Please migrate ${basename(filePath)} to Markdown format.`
+    );
+    return loadAgentFromYamlFile(filePath);
+  }
+  throw new AgentError(
+    `Unsupported agent file format: ${ext}. Use .md (recommended) or .yaml/.yml (deprecated)`,
+    "PARSE_ERROR"
+  );
+}
+function listAgentFiles(dir) {
   if (!existsSync2(dir)) {
     return [];
   }
   return readdirSync(dir).filter((file) => {
+    if (file.startsWith("_")) return false;
     const ext = extname(file).toLowerCase();
-    return ext === ".yaml" || ext === ".yml";
+    return ext === ".md" || ext === ".yaml" || ext === ".yml";
   }).map((file) => join2(dir, file));
 }
 function loadAgentsFromDirectory(dir, source) {
   const agents = /* @__PURE__ */ new Map();
-  const files = listYamlFiles(dir);
+  const files = listAgentFiles(dir);
   for (const filePath of files) {
     try {
       const definition = loadAgentFromFile(filePath);
@@ -372,17 +445,46 @@ function resolveAgentDefinition(agent, config, options = {}) {
 }
 
 // src/agents/compiler.ts
-import { existsSync as existsSync3, mkdirSync, writeFileSync } from "fs";
-import { join as join3, dirname as dirname2 } from "path";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { join as join3, dirname as dirname2, extname as extname2 } from "path";
+import { parse as parseYaml3, stringify as stringifyYaml } from "yaml";
 function buildAgentTools(agent, mcpServers) {
   const tools = agent.tools ? [...agent.tools] : [...DEFAULT_AGENT_TOOLS];
   if (mcpServers && mcpServers.length > 0) {
     for (const server of mcpServers) {
-      tools.push(`mcp__${server}`);
+      const mcpTool = `mcp__${server}`;
+      if (!tools.includes(mcpTool)) {
+        tools.push(mcpTool);
+      }
     }
   }
   return tools.join(", ");
 }
+function processAgentTemplate(templatePath, agent, config, mcpServers) {
+  const template = readFileSync3(templatePath, "utf-8");
+  const context = { agent };
+  if (config) {
+    context.config = config;
+  }
+  const resolved = resolveString(template, context);
+  const frontmatterMatch = resolved.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!frontmatterMatch) {
+    throw new Error(`Invalid markdown format in ${templatePath}: no frontmatter found`);
+  }
+  const frontmatterYaml = frontmatterMatch[1];
+  const body = frontmatterMatch[2] ?? "";
+  const frontmatter = parseYaml3(frontmatterYaml);
+  const tools = buildAgentTools(agent, mcpServers);
+  frontmatter.tools = tools;
+  if (typeof frontmatter.description === "string") {
+    frontmatter.description = frontmatter.description.replace(/\n/g, " ").trim();
+  }
+  const updatedFrontmatter = stringifyYaml(frontmatter, { lineWidth: 0 }).trim();
+  return `---
+${updatedFrontmatter}
+---
+${body}`;
+}
 function generateAgentMarkdown(agent, mcpServers) {
   const lines = [];
   const tools = buildAgentTools(agent, mcpServers);
@@ -404,8 +506,8 @@ function generateAgentMarkdown(agent, mcpServers) {
   if (agent.responsibilities && agent.responsibilities.length > 0) {
     lines.push("## Responsibilities");
     lines.push("");
-    for (const responsibility of agent.responsibilities) {
-      lines.push(`- ${responsibility}`);
+    for (const r of agent.responsibilities) {
+      lines.push(`- ${r}`);
     }
     lines.push("");
   }
@@ -423,12 +525,12 @@ function generateAgentMarkdown(agent, mcpServers) {
     if (agent.expertise.tech_stack) {
       lines.push("### Tech Stack");
       lines.push("");
-      const techStack = agent.expertise.tech_stack;
-      if (typeof techStack === "string") {
-        lines.push(techStack);
-      } else if (typeof techStack === "object") {
+      const ts = agent.expertise.tech_stack;
+      if (typeof ts === "string") {
+        lines.push(ts);
+      } else if (typeof ts === "object") {
         lines.push("```json");
-        lines.push(JSON.stringify(techStack, null, 2));
+        lines.push(JSON.stringify(ts, null, 2));
         lines.push("```");
       }
       lines.push("");
@@ -447,7 +549,7 @@ function generateAgentMarkdown(agent, mcpServers) {
     lines.push("");
     for (const [category, items] of Object.entries(agent.principles)) {
       if (items && Array.isArray(items) && items.length > 0) {
-        const title = formatTitle(category);
+        const title = category.replace(/[_-]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
         lines.push(`### ${title}`);
         lines.push("");
         for (const item of items) {
@@ -478,47 +580,161 @@ function generateAgentMarkdown(agent, mcpServers) {
       lines.push("");
     }
   }
-  if (agent.context_sources) {
+  if (agent.knowledge_library) {
+    generateKnowledgeLibrarySection(agent, lines);
+  }
+  if (agent.communication) {
+    generateCommunicationSection(agent, lines);
+  }
+  if (agent.protocols?.startup) {
+    generateStartupProtocolSection(agent, lines);
+  }
+  if (agent.protocols?.completion) {
+    generateCompletionProtocolSection(agent, lines);
+  }
+  if (agent.context_sources && !agent.knowledge_library) {
     lines.push("## Context Sources");
     lines.push("");
-    if (agent.context_sources.shared && agent.context_sources.shared.length > 0) {
+    if (agent.context_sources.shared?.length) {
       lines.push("### Shared");
       lines.push("");
-      for (const source of agent.context_sources.shared) {
-        lines.push(`- ${source}`);
-      }
+      for (const s of agent.context_sources.shared) lines.push(`- ${s}`);
       lines.push("");
     }
-    if (agent.context_sources.personal && agent.context_sources.personal.length > 0) {
+    if (agent.context_sources.personal?.length) {
       lines.push("### Personal");
       lines.push("");
-      for (const source of agent.context_sources.personal) {
-        lines.push(`- ${source}`);
-      }
+      for (const p of agent.context_sources.personal) lines.push(`- ${p}`);
       lines.push("");
     }
   }
-  if (agent.communication) {
-    lines.push("## Communication");
+  lines.push("---");
+  lines.push("");
+  lines.push("*Generated by CoreAI*");
+  lines.push("");
+  return lines.join("\n");
+}
+function generateKnowledgeLibrarySection(agent, lines) {
+  const kl = agent.knowledge_library;
+  if (!kl) return;
+  lines.push("## Knowledge Library Structure");
+  lines.push("");
+  if (kl.shared) {
+    lines.push("### Shared Context (Root - All Agents)");
+    lines.push("```");
+    lines.push("/KnowledgeLibrary/");
+    if (kl.shared.context) lines.push(`\u251C\u2500\u2500 ${kl.shared.context.split("/").pop()}`);
+    if (kl.shared.architecture) lines.push(`\u251C\u2500\u2500 ${kl.shared.architecture.split("/").pop()}`);
+    if (kl.shared.prd) lines.push(`\u2514\u2500\u2500 ${kl.shared.prd.split("/").pop()}`);
+    lines.push("```");
+    if (kl.shared.remote?.length) {
+      lines.push("");
+      lines.push("**Remote Documentation:**");
+      for (const r of kl.shared.remote) lines.push(`- ${r}`);
+    }
     lines.push("");
-    if (agent.communication.inbox) {
-      lines.push(`**Inbox:** ${agent.communication.inbox}`);
+  }
+  if (kl.personal) {
+    lines.push(`### Personal Context (${agent.role})`);
+    lines.push("```");
+    lines.push(`/KnowledgeLibrary/${agent.role}/`);
+    if (kl.personal.context) {
+      lines.push("\u251C\u2500\u2500 context/");
+      lines.push("\u2502   \u2514\u2500\u2500 current.txt");
     }
-    if (agent.communication.outbox) {
-      lines.push(`**Outbox:** ${agent.communication.outbox}`);
+    if (kl.personal.history) {
+      lines.push("\u251C\u2500\u2500 history/");
     }
+    if (kl.personal.inbox) {
+      lines.push("\u251C\u2500\u2500 inbox/");
+    }
+    if (kl.personal.outbox) {
+      lines.push("\u251C\u2500\u2500 outbox/");
+    }
+    if (kl.personal.tech) {
+      lines.push("\u251C\u2500\u2500 tech/");
+    }
+    if (kl.personal.control) {
+      lines.push("\u2514\u2500\u2500 control/");
+      if (kl.personal.control.objectives) lines.push("    \u251C\u2500\u2500 objectives.txt");
+      if (kl.personal.control.decisions) lines.push("    \u251C\u2500\u2500 decisions.txt");
+      if (kl.personal.control.dependencies) lines.push("    \u251C\u2500\u2500 dependencies.txt");
+      if (kl.personal.control.index) lines.push("    \u2514\u2500\u2500 index.txt");
+    }
+    lines.push("```");
     lines.push("");
   }
   lines.push("---");
   lines.push("");
-  lines.push("*Generated by CoreAI*");
+}
+function generateCommunicationSection(agent, lines) {
+  const comm = agent.communication;
+  if (!comm) return;
+  lines.push("## Communication");
   lines.push("");
-  return lines.join("\n");
+  if (comm.inbox) lines.push(`**Inbox:** \`${comm.inbox}\``);
+  if (comm.outbox) lines.push(`**Outbox:** \`${comm.outbox}\``);
+  lines.push("");
+  if (comm.message_format || comm.outbox_format || comm.processed_dir) {
+    lines.push("### Message Conventions");
+    lines.push("");
+    if (comm.message_format) lines.push(`- **Inbox message naming:** \`${comm.message_format}\``);
+    if (comm.outbox_format) lines.push(`- **Outbox message naming:** \`${comm.outbox_format}\``);
+    if (comm.processed_dir) lines.push(`- **Processed messages:** Move handled inbox messages to \`${comm.processed_dir}\``);
+    lines.push("");
+  }
 }
-function formatTitle(str) {
-  return str.replace(/[_-]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+function generateStartupProtocolSection(agent, lines) {
+  const p = agent.protocols;
+  if (!p?.startup) return;
+  lines.push("## When Invoked");
+  lines.push("");
+  lines.push("> **MANDATORY STARTUP PROTOCOL** - Execute before proceeding with any task.");
+  lines.push("");
+  lines.push("### Session Context Check");
+  lines.push("");
+  if (p.startup.first_session?.length) {
+    lines.push("**If this is your FIRST invocation in this session:**");
+    lines.push("");
+    for (const s of p.startup.first_session) lines.push(`- [ ] ${s}`);
+    lines.push("");
+    lines.push('Acknowledge: "Startup protocol complete. Full context loaded."');
+    lines.push("");
+  }
+  if (p.startup.subsequent?.length) {
+    lines.push("**If you have ALREADY loaded context in this session:**");
+    lines.push("");
+    for (const s of p.startup.subsequent) lines.push(`- [ ] ${s}`);
+    lines.push("");
+    lines.push('Acknowledge: "Context already loaded. Checked inbox for new messages."');
+    lines.push("");
+  }
+  lines.push("Then proceed with the task.");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
 }
-function compileAgent(agent, config, mcpServers) {
+function generateCompletionProtocolSection(agent, lines) {
+  const p = agent.protocols;
+  if (!p?.completion?.length) return;
+  lines.push("## Before Finishing");
+  lines.push("");
+  lines.push("> **MANDATORY COMPLETION PROTOCOL** - Execute ALL steps before ending any task.");
+  lines.push("");
+  for (let i = 0; i < p.completion.length; i++) {
+    lines.push(`### ${i + 1}. ${p.completion[i]}`);
+    lines.push("");
+  }
+  lines.push('Acknowledge: "Completion protocol finished. Context updated."');
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+}
+function compileAgent(agent, filePath, config, mcpServers) {
+  const ext = extname2(filePath).toLowerCase();
+  if (ext === ".md") {
+    return processAgentTemplate(filePath, agent, config, mcpServers);
+  }
   const resolved = resolveAgentDefinition(agent, config);
   return generateAgentMarkdown(resolved, mcpServers);
 }
@@ -578,7 +794,12 @@ function compileAgents(config, options = {}) {
       continue;
     }
     try {
-      const markdown = compileAgent(metadata.definition, config, options.mcpServers);
+      const markdown = compileAgent(
+        metadata.definition,
+        metadata.filePath,
+        config,
+        options.mcpServers
+      );
       const outputPath = join3(outputDir, `${role}.md`);
       writeFileSync(outputPath, markdown, "utf-8");
       result.compiled.push({
@@ -2445,7 +2666,7 @@ var StepTracker = class {
 };
 
 // src/skills/generator.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, statSync } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync4, readdirSync as readdirSync2, statSync } from "fs";
 import { join as join6, basename as basename3 } from "path";
 
 // src/skills/templates.ts
@@ -3030,7 +3251,7 @@ function loadCustomTemplates(templatesDir) {
     const stat = statSync(filePath);
     if (!stat.isFile()) continue;
     try {
-      const content = readFileSync3(filePath, "utf-8");
+      const content = readFileSync4(filePath, "utf-8");
       const template = parseSkillTemplate(file, content);
       templates.push(template);
     } catch {
@@ -3243,7 +3464,7 @@ import {
   existsSync as existsSync5,
   mkdirSync as mkdirSync3,
   writeFileSync as writeFileSync3,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   readdirSync as readdirSync3,
   renameSync,
   statSync as statSync2
@@ -3498,7 +3719,7 @@ function getAgentKnowledgeState(agentName, options = {}) {
   let context;
   const currentContextPath = join7(dirs.context, "current.txt");
   if (existsSync5(currentContextPath)) {
-    const content = readFileSync4(currentContextPath, "utf-8");
+    const content = readFileSync5(currentContextPath, "utf-8");
     context = parseContextFile(content);
   }
   const state = {
@@ -3598,7 +3819,7 @@ function readInboxMessages(agentName, options = {}) {
     );
     for (const file of files) {
       const filePath = join7(dirs.inbox, file);
-      const rawContent = readFileSync4(filePath, "utf-8");
+      const rawContent = readFileSync5(filePath, "utf-8");
       const { metadata, body } = parseMessageFrontmatter(rawContent);
       if (options.type && metadata.type !== options.type) continue;
       if (options.from && metadata.from !== options.from) continue;
@@ -3618,7 +3839,7 @@ function readInboxMessages(agentName, options = {}) {
     );
     for (const file of files) {
       const filePath = join7(dirs.inboxProcessed, file);
-      const rawContent = readFileSync4(filePath, "utf-8");
+      const rawContent = readFileSync5(filePath, "utf-8");
       const { metadata, body } = parseMessageFrontmatter(rawContent);
       if (options.type && metadata.type !== options.type) continue;
       if (options.from && metadata.from !== options.from) continue;
@@ -3823,7 +4044,7 @@ function findPackageJson() {
   while (dir !== dirname5(dir)) {
     const pkgPath = join8(dir, "package.json");
     try {
-      const content = readFileSync5(pkgPath, "utf-8");
+      const content = readFileSync6(pkgPath, "utf-8");
       const pkg = JSON.parse(content);
       if (pkg.name === "@deimoscloud/coreai") {
         return content;