@probelabs/probe 0.6.0-rc201 → 0.6.0-rc202

package/src/agent/index.js

@@ -120,6 +120,7 @@ function parseArgs() {
     allowedFolders: null,
     prompt: null,
     systemPrompt: null,
+    architectureFileName: null,
     schema: null,
     provider: null,
     model: null,
@@ -137,6 +138,8 @@ function parseArgs() {
     noMermaidValidation: false, // New flag to disable mermaid validation
     allowedTools: null, // Tool filtering: ['*'] = all, [] = none, ['tool1', 'tool2'] = specific
     disableTools: false, // Convenience flag to disable all tools
+    disableSkills: false, // Disable skill discovery and activation
+    skillDirs: null, // Comma-separated list of repo-relative skill directories
     // Bash tool configuration
     enableBash: false,
     bashAllow: null,
@@ -172,6 +175,8 @@ function parseArgs() {
       config.prompt = args[++i];
     } else if (arg === '--system-prompt' && i + 1 < args.length) {
       config.systemPrompt = args[++i];
+    } else if (arg === '--architecture-file' && i + 1 < args.length) {
+      config.architectureFileName = args[++i];
     } else if (arg === '--schema' && i + 1 < args.length) {
       config.schema = args[++i];
     } else if (arg === '--provider' && i + 1 < args.length) {
@@ -205,6 +210,10 @@ function parseArgs() {
     } else if (arg === '--disable-tools') {
       // Convenience flag to disable all tools (raw AI mode)
       config.disableTools = true;
+    } else if (arg === '--no-skills') {
+      config.disableSkills = true;
+    } else if (arg === '--skills-dir' && i + 1 < args.length) {
+      config.skillDirs = args[++i].split(',').map(dir => dir.trim()).filter(Boolean);
     } else if (arg === '--enable-bash') {
       config.enableBash = true;
     } else if (arg === '--bash-allow' && i + 1 < args.length) {
@@ -254,6 +263,7 @@ Options:
   --allowed-folders <dirs>         Comma-separated list of allowed directories for file operations
   --prompt <type>                  Persona: code-explorer, engineer, code-review, support, architect
   --system-prompt <text|file>      Custom system prompt (text or file path)
+  --architecture-file <name>       Architecture context filename in repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present)
   --schema <schema|file>           Output schema (JSON, XML, any format - text or file path)
   --provider <name>                Force AI provider: anthropic, openai, google
   --model <name>                   Override model name
@@ -262,10 +272,12 @@ Options:
   --allowed-tools <tools>          Filter available tools (comma-separated list)
                                    Use '*' or 'all' for all tools (default)
                                    Use 'none' or '' for no tools (raw AI mode)
-                                   Specific tools: search,query,extract,listFiles,searchFiles
+                                   Specific tools: search,query,extract,listFiles,searchFiles,listSkills,useSkill
                                    Supports exclusion: '*,!bash' (all except bash)
   --disable-tools                  Disable all tools (raw AI mode, no code analysis)
                                    Convenience flag equivalent to --allowed-tools none
+  --skills-dir <dirs>              Comma-separated list of repo-relative skill directories to scan
+  --no-skills                      Disable skill discovery and activation
   --verbose                        Enable verbose output
   --outline                        Use outline-xml format for code search results
   --mcp                           Run as MCP server
@@ -391,6 +403,10 @@ class ProbeAgentMcpServer {
               system_prompt: {
                 type: 'string',
                 description: 'Optional custom system prompt (text or file path).',
+              },
+              architecture_file: {
+                type: 'string',
+                description: 'Optional architecture context filename in repo root (defaults to AGENTS.md with CLAUDE.md fallback; ARCHITECTURE.md is always included when present).',
               }
             },
             required: ['query']
@@ -511,6 +527,7 @@ class ProbeAgentMcpServer {
             path: args.path || (args.allowed_folders && args.allowed_folders[0]) || process.cwd(),
             promptType: args.prompt || 'code-explorer',
             customPrompt: systemPrompt,
+            architectureFileName: args.architecture_file,
             provider: args.provider,
             model: args.model,
             allowEdit: !!args.allow_edit,
@@ -803,6 +820,7 @@ async function main() {
       allowedFolders: config.allowedFolders,
       promptType: config.prompt,
       customPrompt: systemPrompt,
+      architectureFileName: config.architectureFileName,
       allowEdit: config.allowEdit,
       enableDelegate: config.enableDelegate,
       debug: config.verbose,
@@ -812,6 +830,8 @@ async function main() {
       disableMermaidValidation: config.noMermaidValidation,
       allowedTools: config.allowedTools,
       disableTools: config.disableTools,
+      enableSkills: !config.disableSkills,
+      skillDirs: config.skillDirs,
       enableBash: config.enableBash,
       bashConfig: bashConfig
     };

package/src/agent/probeTool.js

@@ -59,7 +59,7 @@ export function clearToolExecutionData(sessionId) {
 }
 
 // Wrap the tools to emit events and handle cancellation
-const wrapToolWithEmitter = (tool, toolName, baseExecute) => {
+export const wrapToolWithEmitter = (tool, toolName, baseExecute) => {
   return {
     ...tool, // Spread schema, description etc.
     execute: async (params) => { // The execute function now receives parsed params
@@ -407,4 +407,4 @@ export const searchFilesTool = {
 
 // Wrap the additional tools
 export const listFilesToolInstance = wrapToolWithEmitter(listFilesTool, 'listFiles', listFilesTool.execute);
-export const searchFilesToolInstance = wrapToolWithEmitter(searchFilesTool, 'searchFiles', searchFilesTool.execute);
+export const searchFilesToolInstance = wrapToolWithEmitter(searchFilesTool, 'searchFiles', searchFilesTool.execute);

package/src/agent/schemaUtils.js

@@ -1143,6 +1143,28 @@ export function replaceMermaidDiagramsInMarkdown(originalResponse, correctedDiag
   return modifiedResponse;
 }
 
+function replaceSingleMermaidDiagramInResponse(response, originalDiagram, newContent) {
+  if (!originalDiagram) {
+    return response;
+  }
+
+  const attributesStr = originalDiagram.attributes ? ` ${originalDiagram.attributes}` : '';
+  const newCodeBlock = `\`\`\`mermaid${attributesStr}\n${newContent}\n\`\`\``;
+
+  if (originalDiagram.isInJson) {
+    return replaceMermaidDiagramsInJson(response, [
+      {
+        ...originalDiagram,
+        content: newContent
+      }
+    ]);
+  }
+
+  return response.slice(0, originalDiagram.startIndex) +
+    newCodeBlock +
+    response.slice(originalDiagram.endIndex);
+}
+
 /**
  * Validate a single Mermaid diagram
  * @param {string} diagram - Mermaid diagram code
@@ -1849,12 +1871,11 @@ export async function validateAndFixMermaidResponse(response, options = {}) {
       if (maidResult.errors.length === 0) {
         // Maid fixed it completely
         const originalDiagram = diagrams[invalidDiagram.originalIndex];
-        const attributesStr = originalDiagram.attributes ? ` ${originalDiagram.attributes}` : '';
-        const newCodeBlock = `\`\`\`mermaid${attributesStr}\n${maidResult.fixed}\n\`\`\``;
-
-        fixedResponse = fixedResponse.slice(0, originalDiagram.startIndex) +
-                       newCodeBlock +
-                       fixedResponse.slice(originalDiagram.endIndex);
+        fixedResponse = replaceSingleMermaidDiagramInResponse(
+          fixedResponse,
+          originalDiagram,
+          maidResult.fixed
+        );
 
         fixingResults.push({
           diagramIndex: invalidDiagram.originalIndex,
@@ -1874,12 +1895,11 @@ export async function validateAndFixMermaidResponse(response, options = {}) {
       } else if (maidResult.wasFixed) {
         // Maid improved it but didn't fix everything - update content for AI fixing
         const originalDiagram = diagrams[invalidDiagram.originalIndex];
-        const attributesStr = originalDiagram.attributes ? ` ${originalDiagram.attributes}` : '';
-        const newCodeBlock = `\`\`\`mermaid${attributesStr}\n${maidResult.fixed}\n\`\`\``;
-
-        fixedResponse = fixedResponse.slice(0, originalDiagram.startIndex) +
-                       newCodeBlock +
-                       fixedResponse.slice(originalDiagram.endIndex);
+        fixedResponse = replaceSingleMermaidDiagramInResponse(
+          fixedResponse,
+          originalDiagram,
+          maidResult.fixed
+        );
 
         fixingResults.push({
           diagramIndex: invalidDiagram.originalIndex,
@@ -1987,12 +2007,11 @@ export async function validateAndFixMermaidResponse(response, options = {}) {
         if (fixedContent && fixedContent !== invalidDiagram.content) {
           // Replace the diagram in the response
           const originalDiagram = updatedDiagrams[invalidDiagram.originalIndex];
-          const attributesStr = originalDiagram.attributes ? ` ${originalDiagram.attributes}` : '';
-          const newCodeBlock = `\`\`\`mermaid${attributesStr}\n${fixedContent}\n\`\`\``;
-
-          fixedResponse = fixedResponse.slice(0, originalDiagram.startIndex) +
-                         newCodeBlock +
-                         fixedResponse.slice(originalDiagram.endIndex);
+          fixedResponse = replaceSingleMermaidDiagramInResponse(
+            fixedResponse,
+            originalDiagram,
+            fixedContent
+          );
 
           // Find existing result or create new one
           const existingResultIndex = fixingResults.findIndex(r => r.diagramIndex === invalidDiagram.originalIndex);

package/src/agent/shared/prompts.js

@@ -20,6 +20,23 @@ When providing answers:
 - Group references by file when multiple locations are from the same file
 - Include brief descriptions of what each reference contains`,
 
+  'code-searcher': `You are ProbeChat Code Searcher, a specialized AI assistant focused ONLY on locating relevant code. Your sole job is to find and return ALL relevant code locations. Do NOT answer questions or explain anything.
+
+When searching:
+- Use only the search tool
+- Run additional searches only if needed to capture all relevant locations
+- Prefer specific, focused queries
+
+Output format (MANDATORY):
+- Return ONLY valid JSON with a single top-level key: "targets"
+- "targets" must be an array of strings
+- Each string must be a file target in one of these formats:
+  - "path/to/file.ext#SymbolName"
+  - "path/to/file.ext:line"
+  - "path/to/file.ext:start-end"
+- Prefer #SymbolName when a function/class name is clear; otherwise use line numbers
+- Deduplicate targets and keep them concise`,
+
   'architect': `You are ProbeChat Architect, a specialized AI assistant focused on software architecture and design. Your primary function is to help users understand, analyze, and design software systems using the provided code analysis tools.
 
 When analyzing code:

package/src/agent/skills/formatting.js

@@ -0,0 +1,23 @@
+function escapeXml(value) {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+export function formatAvailableSkillsXml(skills) {
+  if (!skills || skills.length === 0) return '';
+
+  const lines = ['<available_skills>'];
+  for (const skill of skills) {
+    lines.push('  <skill>');
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+    lines.push(`    <description>${escapeXml(skill.description || '')}</description>`);
+    lines.push('  </skill>');
+  }
+  lines.push('</available_skills>');
+
+  return lines.join('\n');
+}

package/src/agent/skills/parser.js

@@ -0,0 +1,162 @@
+import { readFile } from 'fs/promises';
+import { dirname } from 'path';
+import YAML from 'yaml';
+
+const SKILL_NAME_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_SKILL_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_CHARS = 400;
+
+function isValidSkillName(name) {
+  if (!name || typeof name !== 'string') return false;
+  if (name.length > MAX_SKILL_NAME_LENGTH) return false;
+  return SKILL_NAME_REGEX.test(name);
+}
+
+function getFirstParagraph(text) {
+  const lines = text.split(/\r?\n/);
+  const paragraphLines = [];
+
+  for (const line of lines) {
+    if (line.trim() === '') {
+      if (paragraphLines.length > 0) {
+        break;
+      }
+      continue;
+    }
+
+    paragraphLines.push(line.trim());
+  }
+
+  return paragraphLines.join(' ').trim();
+}
+
+function extractFrontmatter(content) {
+  const trimmed = content.replace(/^\uFEFF/, '');
+  const lines = trimmed.split(/\r?\n/);
+
+  if (lines.length === 0 || lines[0].trim() !== '---') {
+    return { hasFrontmatter: false, frontmatterText: '', body: trimmed };
+  }
+
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      endIndex = i;
+      break;
+    }
+  }
+
+  if (endIndex === -1) {
+    return { hasFrontmatter: true, invalid: true, frontmatterText: '', body: '' };
+  }
+
+  const frontmatterText = lines.slice(1, endIndex).join('\n');
+  const body = lines.slice(endIndex + 1).join('\n');
+
+  return { hasFrontmatter: true, frontmatterText, body };
+}
+
+function truncateDescription(text) {
+  if (!text) return '';
+  const trimmed = text.trim();
+  if (trimmed.length <= MAX_DESCRIPTION_CHARS) return trimmed;
+  return `${trimmed.slice(0, MAX_DESCRIPTION_CHARS - 3)}...`;
+}
+
+function normalizeFrontmatter(data) {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return {};
+  return data;
+}
+
+function deriveSkillName(rawName, directoryName, { debug, skillFilePath }) {
+  const candidate = rawName || directoryName;
+  if (isValidSkillName(candidate)) return candidate;
+
+  if (rawName && debug) {
+    console.warn(`[skills] Invalid skill name '${rawName}' in ${skillFilePath}; falling back to directory name`);
+  }
+
+  if (isValidSkillName(directoryName)) {
+    return directoryName;
+  }
+
+  if (debug) {
+    console.warn(`[skills] Invalid directory name '${directoryName}' for skill at ${skillFilePath}; skipping`);
+  }
+
+  return null;
+}
+
+function deriveDescription(rawDescription, body) {
+  let description = rawDescription || '';
+  if (!description) {
+    description = getFirstParagraph(body);
+  }
+  return truncateDescription(description);
+}
+
+export function stripFrontmatter(content) {
+  const { body } = extractFrontmatter(content);
+  return body.trim();
+}
+
+function createError(code, message) {
+  return { code, message };
+}
+
+export async function parseSkillFile(skillFilePath, directoryName) {
+  let content;
+  try {
+    content = await readFile(skillFilePath, 'utf8');
+  } catch (error) {
+    return {
+      skill: null,
+      error: createError('read_failed', error.message)
+    };
+  }
+
+  const { hasFrontmatter, frontmatterText, body, invalid } = extractFrontmatter(content);
+  if (invalid) {
+    return {
+      skill: null,
+      error: createError('invalid_frontmatter', 'Missing closing frontmatter delimiter')
+    };
+  }
+
+  let data = {};
+  if (hasFrontmatter) {
+    try {
+      data = YAML.parse(frontmatterText, { schema: 'failsafe' }) || {};
+    } catch (error) {
+      return {
+        skill: null,
+        error: createError('invalid_yaml', error.message)
+      };
+    }
+  }
+
+  data = normalizeFrontmatter(data);
+
+  const rawName = typeof data.name === 'string' ? data.name.trim() : '';
+  const name = deriveSkillName(rawName, directoryName, { debug: false, skillFilePath });
+  if (!name) {
+    return {
+      skill: null,
+      error: createError('invalid_name', 'Skill name is invalid')
+    };
+  }
+
+  const rawDescription = typeof data.description === 'string' ? data.description.trim() : '';
+  const description = deriveDescription(rawDescription, body);
+
+  return {
+    skill: {
+      name,
+      description,
+      skillFilePath,
+      directoryName,
+      sourceDir: dirname(skillFilePath)
+    },
+    error: null
+  };
+}

package/src/agent/skills/registry.js

@@ -0,0 +1,185 @@
+import { existsSync } from 'fs';
+import { readdir, readFile, realpath, lstat } from 'fs/promises';
+import { resolve, join, isAbsolute, sep, relative } from 'path';
+import { parseSkillFile, stripFrontmatter } from './parser.js';
+
+const DEFAULT_SKILL_DIRS = ['.claude/skills', '.codex/skills', 'skills', '.skills'];
+const SKILL_FILE_NAME = 'SKILL.md';
+
+function isPathInside(basePath, targetPath) {
+  const base = resolve(basePath);
+  const target = resolve(targetPath);
+  const rel = relative(base, target);
+  if (rel === '') return true;
+  if (rel === '..' || rel.startsWith(`..${sep}`)) return false;
+  if (isAbsolute(rel)) return false;
+  return true;
+}
+
+function isSafeEntryName(name) {
+  if (!name || name === '.' || name === '..') return false;
+  if (name.includes('\0')) return false;
+  return !name.includes('/') && !name.includes('\\');
+}
+
+export class SkillRegistry {
+  constructor({ repoRoot, skillDirs = DEFAULT_SKILL_DIRS, debug = false } = {}) {
+    this.repoRoot = repoRoot ? resolve(repoRoot) : process.cwd();
+    this.repoRootReal = null;
+    this.skillDirs = Array.isArray(skillDirs) && skillDirs.length > 0 ? skillDirs : DEFAULT_SKILL_DIRS;
+    this.debug = debug;
+    this.skills = [];
+    this.skillsByName = new Map();
+    this.loadErrors = [];
+    this.loaded = false;
+  }
+
+  async loadSkills() {
+    if (this.loaded) return this.skills;
+
+    this.loadErrors = [];
+    this.repoRootReal = await this._resolveRealPath(this.repoRoot);
+    if (!this.repoRootReal) {
+      if (this.debug) {
+        console.warn(`[skills] Failed to resolve repo root: ${this.repoRoot}`);
+      }
+      this.loaded = true;
+      return this.skills;
+    }
+
+    const discovered = [];
+    for (const skillDir of this.skillDirs) {
+      const resolvedDir = await this._resolveSkillDir(skillDir);
+      if (!resolvedDir) continue;
+      const skillsInDir = await this._scanSkillDir(resolvedDir);
+      discovered.push(...skillsInDir);
+    }
+
+    this.skills = discovered;
+    this.loaded = true;
+    return this.skills;
+  }
+
+  getSkills() {
+    return this.skills;
+  }
+
+  getLoadErrors() {
+    return this.loadErrors;
+  }
+
+  getSkill(name) {
+    return this.skillsByName.get(name);
+  }
+
+  async loadSkillInstructions(name) {
+    const skill = this.skillsByName.get(name);
+    if (!skill) return null;
+
+    const content = await readFile(skill.skillFilePath, 'utf8');
+    return stripFrontmatter(content);
+  }
+
+  async _resolveRealPath(target) {
+    try {
+      return await realpath(target);
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  async _resolveSkillDir(skillDir) {
+    const resolved = isAbsolute(skillDir) ? resolve(skillDir) : resolve(this.repoRoot, skillDir);
+    const repoRoot = this.repoRootReal || resolve(this.repoRoot);
+    const resolvedReal = await this._resolveRealPath(resolved);
+    if (!resolvedReal) return null;
+
+    if (!isPathInside(repoRoot, resolvedReal)) {
+      if (this.debug) {
+        console.warn(`[skills] Skipping skill dir outside repo: ${resolvedReal}`);
+      }
+      return null;
+    }
+
+    return resolvedReal;
+  }
+
+  async _scanSkillDir(dirPath) {
+    if (!existsSync(dirPath)) return [];
+
+    let entries;
+    try {
+      entries = await readdir(dirPath, { withFileTypes: true });
+    } catch (error) {
+      if (this.debug) {
+        console.warn(`[skills] Failed to read skill dir ${dirPath}: ${error.message}`);
+      }
+      return [];
+    }
+
+    const results = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (!isSafeEntryName(entry.name)) {
+        if (this.debug) {
+          console.warn(`[skills] Skipping unsafe skill directory name: ${entry.name}`);
+        }
+        continue;
+      }
+
+      const skillFolder = join(dirPath, entry.name);
+      const skillFilePath = join(skillFolder, SKILL_FILE_NAME);
+      let skillStat;
+      try {
+        skillStat = await lstat(skillFilePath);
+      } catch (_error) {
+        continue;
+      }
+
+      if (skillStat.isSymbolicLink()) {
+        if (this.debug) {
+          console.warn(`[skills] Skipping symlinked SKILL.md: ${skillFilePath}`);
+        }
+        continue;
+      }
+
+      const resolvedSkillPath = await this._resolveRealPath(skillFilePath);
+      if (!resolvedSkillPath || !isPathInside(dirPath, resolvedSkillPath)) {
+        if (this.debug) {
+          console.warn(`[skills] Skipping skill path outside directory: ${resolvedSkillPath || skillFilePath}`);
+        }
+        continue;
+      }
+      if (!existsSync(skillFilePath)) continue;
+
+      const { skill, error } = await parseSkillFile(skillFilePath, entry.name);
+      if (!skill) {
+        if (error) {
+          this.loadErrors.push({
+            path: skillFilePath,
+            code: error.code,
+            message: error.message
+          });
+        }
+        if (this.debug && error) {
+          console.warn(`[skills] Skipping ${skillFilePath}: ${error.code} (${error.message})`);
+        }
+        continue;
+      }
+
+      if (this.skillsByName.has(skill.name)) {
+        if (this.debug) {
+          console.warn(`[skills] Duplicate skill name '${skill.name}' at ${skillFolder}, skipping`);
+        }
+        continue;
+      }
+
+      this.skillsByName.set(skill.name, skill);
+      results.push(skill);
+    }
+
+    return results;
+  }
+}
+
+export { DEFAULT_SKILL_DIRS };

package/src/agent/skills/tools.js

@@ -0,0 +1,65 @@
+import { wrapToolWithEmitter } from '../probeTool.js';
+
+function normalizeSkillName(name) {
+  return typeof name === 'string' ? name.trim() : '';
+}
+
+export function createSkillToolInstances({ registry, activeSkills }) {
+  const listSkillsTool = {
+    execute: async (params = {}) => {
+      const filter = typeof params.filter === 'string' ? params.filter.trim().toLowerCase() : '';
+      const skills = await registry.loadSkills();
+      const filtered = filter
+        ? skills.filter(skill =>
+            skill.name.toLowerCase().includes(filter) ||
+            (skill.description || '').toLowerCase().includes(filter)
+          )
+        : skills;
+
+      return {
+        skills: filtered.map(skill => ({
+          name: skill.name,
+          description: skill.description
+        }))
+      };
+    }
+  };
+
+  const useSkillTool = {
+    execute: async (params = {}) => {
+      const rawName = normalizeSkillName(params.name);
+      if (!rawName) {
+        throw new Error('Skill name is required');
+      }
+
+      await registry.loadSkills();
+      let skill = registry.getSkill(rawName);
+      if (!skill) {
+        skill = registry.getSkill(rawName.toLowerCase());
+      }
+
+      if (!skill) {
+        const available = registry.getSkills().map(s => s.name).join(', ') || 'None';
+        throw new Error(`Skill '${rawName}' not found. Available skills: ${available}`);
+      }
+
+      const instructions = await registry.loadSkillInstructions(skill.name);
+      if (!instructions) {
+        throw new Error(`Skill '${skill.name}' has no instructions`);
+      }
+
+      activeSkills.set(skill.name, { ...skill, instructions });
+
+      return {
+        name: skill.name,
+        description: skill.description,
+        instructions
+      };
+    }
+  };
+
+  return {
+    listSkillsToolInstance: wrapToolWithEmitter(listSkillsTool, 'listSkills', listSkillsTool.execute),
+    useSkillToolInstance: wrapToolWithEmitter(useSkillTool, 'useSkill', useSkillTool.execute)
+  };
+}