@animus-labs/cortex 0.2.0

package/src/skill-preprocessor.ts

@@ -0,0 +1,314 @@
+/**
+ * Skill Preprocessor: processes SKILL.md body at load time.
+ *
+ * Three preprocessor types run in order:
+ * 1. Variable substitution: ${VAR}, $ARGUMENTS, $N
+ * 2. Shell commands: !`command` (parallel execution)
+ * 3. Script execution: !{script: path} (parallel execution)
+ *
+ * Shell commands use the same shell selection logic as the Bash tool
+ * (PowerShell on Windows, bash/zsh on Unix).
+ *
+ * References:
+ *   - docs/cortex/skill-system.md
+ *   - docs/cortex/cross-platform-considerations.md
+ */
+
+import { execFile } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PreprocessorConfig {
+  /** Variables for ${VAR} and $N substitution. */
+  variables: Record<string, string>;
+  /** Context object passed to script executions. */
+  scriptContext: Record<string, unknown>;
+  /** Absolute path to the skill directory. */
+  skillDir: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Timeout for each shell command or script execution. */
+const COMMAND_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Regex patterns
+// ---------------------------------------------------------------------------
+
+/** Match !`command` patterns (shell command markers). */
+const SHELL_COMMAND_PATTERN = /^!`([^`]+)`$/gm;
+
+/** Match !{script: path} or !{script: path, key: value, ...} patterns. */
+const SCRIPT_PATTERN = /^!\{script:\s*([^,}]+)(?:,\s*([^}]+))?\}$/gm;
+
+/** Match ${VAR} variable references. */
+const VARIABLE_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+/** Match $N positional argument references (1-9). */
+const POSITIONAL_PATTERN = /\$([1-9])/g;
+
+/** Match $ARGUMENTS reference. */
+const ARGUMENTS_PATTERN = /\$ARGUMENTS/g;
+
+// ---------------------------------------------------------------------------
+// Shell selection (mirrors bash tool logic)
+// ---------------------------------------------------------------------------
+
+interface ShellConfig {
+  shell: string;
+  args: string[];
+}
+
+function getShellConfig(): ShellConfig {
+  if (process.platform === 'win32') {
+    // PowerShell on Windows
+    const psCore = process.env['ProgramFiles'];
+    const psCorePath = psCore ? `${psCore}\\PowerShell\\7\\pwsh.exe` : null;
+
+    // Try pwsh (PowerShell 7+) first, fall back to Windows PowerShell
+    try {
+      if (psCorePath) {
+        fs.accessSync(psCorePath);
+        return { shell: psCorePath, args: ['-NoProfile', '-NonInteractive', '-Command'] };
+      }
+    } catch {
+      // Fall through
+    }
+
+    return {
+      shell: 'powershell.exe',
+      args: ['-NoProfile', '-NonInteractive', '-Command'],
+    };
+  }
+
+  // Unix: use $SHELL, falling back to /bin/bash or /bin/sh
+  const userShell = process.env['SHELL'];
+  if (userShell && !userShell.endsWith('/fish')) {
+    return { shell: userShell, args: ['-c'] };
+  }
+
+  // Fall back
+  try {
+    fs.accessSync('/bin/bash');
+    return { shell: '/bin/bash', args: ['-c'] };
+  } catch {
+    return { shell: '/bin/sh', args: ['-c'] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Preprocessor implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Preprocess a SKILL.md body. Runs all three stages:
+ * 1. Variable substitution
+ * 2. Shell commands and scripts (in parallel)
+ * 3. Assemble final content
+ */
+export async function preprocessSkillBody(
+  body: string,
+  config: PreprocessorConfig,
+): Promise<string> {
+  // Stage 1: Variable substitution (runs first so vars are available
+  // inside shell commands and script arguments)
+  let content = substituteVariables(body, config.variables);
+
+  // Stage 2: Collect shell command and script markers, execute in parallel
+  const shellReplacements: Array<{ marker: string; promise: Promise<string> }> = [];
+  const scriptReplacements: Array<{ marker: string; promise: Promise<string> }> = [];
+
+  // Find shell commands
+  let match: RegExpExecArray | null;
+  const shellRegex = new RegExp(SHELL_COMMAND_PATTERN.source, 'gm');
+  while ((match = shellRegex.exec(content)) !== null) {
+    const fullMatch = match[0]!;
+    const command = match[1]!;
+    shellReplacements.push({
+      marker: fullMatch,
+      promise: executeShellCommand(command, config.skillDir),
+    });
+  }
+
+  // Find scripts
+  const scriptRegex = new RegExp(SCRIPT_PATTERN.source, 'gm');
+  while ((match = scriptRegex.exec(content)) !== null) {
+    const fullMatch = match[0]!;
+    const scriptPath = match[1]!.trim();
+    const extraArgs = match[2]?.trim() ?? '';
+    scriptReplacements.push({
+      marker: fullMatch,
+      promise: executeScript(scriptPath, extraArgs, config),
+    });
+  }
+
+  // Execute all in parallel
+  const allReplacements = [...shellReplacements, ...scriptReplacements];
+  if (allReplacements.length > 0) {
+    const results = await Promise.allSettled(
+      allReplacements.map(r => r.promise),
+    );
+
+    for (let i = 0; i < allReplacements.length; i++) {
+      const replacement = allReplacements[i]!;
+      const result = results[i]!;
+      const output = result.status === 'fulfilled'
+        ? result.value
+        : `[Error: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}]`;
+      // Use callback to prevent $& and other replacement patterns in output
+      content = content.replace(replacement.marker, () => output);
+    }
+  }
+
+  return content;
+}
+
+/**
+ * Substitute ${VAR}, $ARGUMENTS, and $N references with their values.
+ */
+export function substituteVariables(
+  body: string,
+  variables: Record<string, string>,
+): string {
+  let result = body;
+
+  // Replace $ARGUMENTS first (before ${} to avoid partial matching)
+  result = result.replace(ARGUMENTS_PATTERN, () => variables['ARGUMENTS'] ?? '');
+
+  // Replace positional $1..$9
+  result = result.replace(POSITIONAL_PATTERN, (_match, num: string) => {
+    return variables[num] ?? '';
+  });
+
+  // Replace ${VAR} references
+  result = result.replace(VARIABLE_PATTERN, (_match, varName: string) => {
+    return variables[varName] ?? '';
+  });
+
+  return result;
+}
+
+/**
+ * Execute a shell command and return stdout.
+ * Uses the same shell selection as the Bash tool.
+ */
+export function executeShellCommand(
+  command: string,
+  cwd: string,
+): Promise<string> {
+  return new Promise((resolve) => {
+    const shellConfig = getShellConfig();
+
+    // Use execFile to invoke the shell directly with the command as an argument.
+    // This avoids double-shell invocation (exec spawns a shell around our shell).
+    const args = [...shellConfig.args, command];
+
+    const child = execFile(
+      shellConfig.shell,
+      args,
+      {
+        cwd,
+        timeout: COMMAND_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024, // 1MB
+        env: process.env,
+      },
+      (error: Error | null, stdout: string, _stderr: string) => {
+        if (error) {
+          if ('killed' in error && (error as { killed?: boolean }).killed) {
+            resolve('[Error: command timed out]');
+          } else {
+            const exitCode = 'code' in error && (error as Record<string, unknown>)['code'] != null
+              ? (error as Record<string, unknown>)['code']
+              : 'unknown';
+            resolve(`[Error: command failed with exit code ${exitCode}]`);
+          }
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+
+    child.on('error', () => {
+      resolve('[Error: failed to execute command]');
+    });
+  });
+}
+
+/**
+ * Execute a JavaScript script and return its output.
+ * Scripts are loaded via dynamic import() and must export a default
+ * async function.
+ */
+export async function executeScript(
+  scriptPath: string,
+  extraArgsStr: string,
+  config: PreprocessorConfig,
+): Promise<string> {
+  const absolutePath = path.isAbsolute(scriptPath)
+    ? scriptPath
+    : path.resolve(config.skillDir, scriptPath);
+
+  // Security: reject paths that escape the skill directory
+  const relative = path.relative(config.skillDir, absolutePath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    return '[Error: script path must be within the skill directory]';
+  }
+
+  // Parse extra args from "key: value, key2: value2" format
+  const scriptArgs: Record<string, string> = {};
+  if (extraArgsStr) {
+    const pairs = extraArgsStr.split(',');
+    for (const pair of pairs) {
+      const colonIdx = pair.indexOf(':');
+      if (colonIdx > 0) {
+        const key = pair.substring(0, colonIdx).trim();
+        const value = pair.substring(colonIdx + 1).trim();
+        scriptArgs[key] = value;
+      }
+    }
+  }
+
+  // Build context: consumer context spread first, then Cortex built-ins
+  // override (skillDir and scriptArgs are Cortex-owned and cannot be
+  // overridden by consumer). args/rawArgs come pre-merged in
+  // config.scriptContext from the registry with the same precedence.
+  const ctx: Record<string, unknown> = {
+    ...config.scriptContext,
+    skillDir: config.skillDir,
+    scriptArgs,
+  };
+
+  // Execute with timeout
+  const timeoutPromise = new Promise<string>((resolve) => {
+    setTimeout(() => resolve('[Error: script timed out]'), COMMAND_TIMEOUT_MS);
+  });
+
+  const executionPromise = (async (): Promise<string> => {
+    try {
+      // Dynamic import of the script file
+      const fileUrl = pathToFileURL(absolutePath).href;
+      const mod = await import(fileUrl);
+      const fn = mod.default ?? mod;
+
+      if (typeof fn !== 'function') {
+        return '[Error: script does not export a function]';
+      }
+
+      const result = await fn(ctx);
+      return typeof result === 'string' ? result : String(result ?? '');
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return `[Error: script failed: ${message}]`;
+    }
+  })();
+
+  return Promise.race([executionPromise, timeoutPromise]);
+}

package/src/skill-registry.ts

@@ -0,0 +1,378 @@
+/**
+ * SkillRegistry: manages all known skills for the Cortex agent.
+ *
+ * Config-driven: the consumer provides paths to SKILL.md files from any
+ * source (plugins, user directories, built-ins). The registry does not
+ * scan directories.
+ *
+ * Skills are parsed at registration time (frontmatter extracted, body
+ * deferred to load time). The registry produces a compact summary for
+ * the load_skill tool description.
+ *
+ * References:
+ *   - docs/cortex/skill-system.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { SkillConfig, SkillEntry } from './types.js';
+import { preprocessSkillBody } from './skill-preprocessor.js';
+
+// ---------------------------------------------------------------------------
+// Frontmatter parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ * Expects --- delimited frontmatter at the start of the file.
+ *
+ * This is a lightweight parser that handles the common SKILL.md patterns
+ * without requiring a full YAML library. It handles:
+ * - Simple key: value pairs
+ * - Multi-line strings (using > or |)
+ * - Nested metadata maps
+ * - Space-delimited lists (for allowed-tools)
+ */
+function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---')) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const endIdx = trimmed.indexOf('\n---', 3);
+  if (endIdx < 0) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const yamlBlock = trimmed.substring(3, endIdx).trim();
+  const body = trimmed.substring(endIdx + 4).trimStart();
+
+  const frontmatter: Record<string, unknown> = {};
+  const lines = yamlBlock.split('\n');
+  let currentKey = '';
+  let multilineValue = '';
+  let inMultiline = false;
+  let multilineType: '>' | '|' | '' = '';
+  let inMetadata = false;
+  const metadataMap: Record<string, string> = {};
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+
+    // Handle metadata block (indented key-value pairs)
+    if (inMetadata) {
+      const metaMatch = line.match(/^ {2}(\w[\w-]*)\s*:\s*(.*)$/);
+      if (metaMatch) {
+        metadataMap[metaMatch[1]!] = metaMatch[2]!.trim();
+        continue;
+      }
+      // End of metadata block
+      frontmatter['metadata'] = { ...metadataMap };
+      inMetadata = false;
+    }
+
+    // Handle multi-line folded/literal values
+    if (inMultiline) {
+      if (line.startsWith('  ') || line.trim() === '') {
+        if (multilineType === '>') {
+          multilineValue += (multilineValue ? ' ' : '') + line.trim();
+        } else {
+          multilineValue += (multilineValue ? '\n' : '') + line.trimStart();
+        }
+        continue;
+      }
+      // End of multi-line
+      frontmatter[currentKey] = multilineValue.trim();
+      inMultiline = false;
+      multilineValue = '';
+    }
+
+    // Parse key: value
+    const kvMatch = line.match(/^(\w[\w-]*)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      const key = kvMatch[1]!;
+      const rawValue = kvMatch[2]!.trim();
+
+      if (rawValue === '>' || rawValue === '|') {
+        currentKey = key;
+        multilineType = rawValue as '>' | '|';
+        multilineValue = '';
+        inMultiline = true;
+        continue;
+      }
+
+      if (key === 'metadata' && rawValue === '') {
+        inMetadata = true;
+        continue;
+      }
+
+      // Parse boolean values
+      if (rawValue === 'true') {
+        frontmatter[key] = true;
+      } else if (rawValue === 'false') {
+        frontmatter[key] = false;
+      } else {
+        frontmatter[key] = rawValue;
+      }
+    }
+  }
+
+  // Flush any remaining multi-line or metadata
+  if (inMultiline && currentKey) {
+    frontmatter[currentKey] = multilineValue.trim();
+  }
+  if (inMetadata && Object.keys(metadataMap).length > 0) {
+    frontmatter['metadata'] = { ...metadataMap };
+  }
+
+  return { frontmatter, body };
+}
+
+// ---------------------------------------------------------------------------
+// SkillRegistry
+// ---------------------------------------------------------------------------
+
+export class SkillRegistry {
+  private readonly entries = new Map<string, SkillEntry>();
+
+  /** Consumer-provided variables for ${VAR} substitution. */
+  private preprocessorVariables: Record<string, string> = {};
+
+  /** Consumer-provided context for !{script:} executions. */
+  private scriptContext: Record<string, unknown> = {};
+
+  /**
+   * Callback fired when skills are added or removed.
+   * CortexAgent sets this to rebuild the load_skill tool description.
+   */
+  onChange: (() => void) | null = null;
+
+  constructor(configs?: SkillConfig[]) {
+    if (configs) {
+      for (const config of configs) {
+        this.addSkill(config);
+      }
+    }
+  }
+
+  /**
+   * Add a skill from a SKILL.md file path.
+   * Reads and parses the frontmatter synchronously at registration time.
+   *
+   * If a skill with the same name already exists, the new one replaces it
+   * (last-registered wins).
+   */
+  addSkill(config: SkillConfig): void {
+    let content: string;
+    try {
+      content = fs.readFileSync(config.path, 'utf8');
+    } catch (err) {
+      // Skill file not readable; skip silently
+      return;
+    }
+
+    const { frontmatter } = parseFrontmatter(content);
+
+    const name = typeof frontmatter['name'] === 'string'
+      ? frontmatter['name']
+      : path.basename(path.dirname(config.path));
+
+    const description = typeof frontmatter['description'] === 'string'
+      ? frontmatter['description']
+      : '';
+
+    const disableModelInvocation = frontmatter['disable-model-invocation'] === true;
+
+    const entry: SkillEntry = {
+      name,
+      description,
+      path: config.path,
+      dir: path.dirname(config.path),
+      source: config.source,
+      frontmatter,
+      modelInvocable: !disableModelInvocation,
+    };
+    if (config.variables) {
+      entry.variables = config.variables;
+    }
+
+    this.entries.set(name, entry);
+    this.onChange?.();
+  }
+
+  /**
+   * Remove a skill by name.
+   */
+  removeSkill(name: string): void {
+    const existed = this.entries.delete(name);
+    if (existed) {
+      this.onChange?.();
+    }
+  }
+
+  /**
+   * Get a skill entry by name.
+   */
+  getEntry(name: string): SkillEntry | null {
+    return this.entries.get(name) ?? null;
+  }
+
+  /**
+   * Get all registered skill entries.
+   */
+  getAll(): SkillEntry[] {
+    return [...this.entries.values()];
+  }
+
+  /**
+   * Get the number of registered skills.
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * Generate the available skills summary for the load_skill tool description.
+   *
+   * Skills with disable-model-invocation: true (modelInvocable: false) are
+   * excluded from the summary. The agent cannot see or auto-load them.
+   *
+   * Format: XML listing with name, source, and description per skill.
+   * Each skill consumes approximately 100 tokens.
+   */
+  getAvailableSkillsSummary(maxTokens = Number.POSITIVE_INFINITY): string {
+    const invocableSkills = [...this.entries.values()]
+      .filter(e => e.modelInvocable)
+      .sort((a, b) => {
+        // Priority: builtin > user > plugin
+        const priority = (s: string): number => {
+          if (s === 'builtin') return 0;
+          if (s === 'user') return 1;
+          return 2; // plugin:*
+        };
+        const pa = priority(a.source);
+        const pb = priority(b.source);
+        if (pa !== pb) return pa - pb;
+        return a.name.localeCompare(b.name);
+      });
+
+    if (invocableSkills.length === 0) {
+      return '<available-skills>\n(No skills available)\n</available-skills>';
+    }
+
+    let usedTokens = 0;
+    const visibleSkills: SkillEntry[] = [];
+
+    for (const entry of invocableSkills) {
+      const approxTokens = Math.max(
+        32,
+        Math.ceil((entry.name.length + entry.description.trim().length) / 4),
+      );
+
+      if (visibleSkills.length > 0 && usedTokens + approxTokens > maxTokens) {
+        continue;
+      }
+
+      visibleSkills.push(entry);
+      usedTokens += approxTokens;
+    }
+
+    const skillXml = visibleSkills.map(e => {
+      const desc = e.description.trim();
+      return `<skill name="${e.name}" source="${e.source}">\n${desc}\n</skill>`;
+    }).join('\n');
+
+    return `<available-skills>\n${skillXml}\n</available-skills>`;
+  }
+
+  /**
+   * Read and preprocess a skill's full body content.
+   * Runs variable substitution, shell commands, and scripts.
+   *
+   * @param name - The skill name
+   * @param callArgs - Arguments from the load_skill tool call
+   * @returns The preprocessed skill body
+   * @throws Error if the skill is not found
+   */
+  async getSkillBody(
+    name: string,
+    callArgs: { args: string[]; rawArgs: string },
+  ): Promise<string> {
+    const entry = this.entries.get(name);
+    if (!entry) {
+      throw new Error(`Skill not found: "${name}"`);
+    }
+
+    // Read the file and extract the body (below frontmatter)
+    let content: string;
+    try {
+      content = fs.readFileSync(entry.path, 'utf8');
+    } catch (err) {
+      throw new Error(`Cannot read skill file: ${entry.path}`);
+    }
+
+    const { body } = parseFrontmatter(content);
+
+    // Build merged variables (consumer + built-ins, consumer wins on collision)
+    const variables: Record<string, string> = {
+      SKILL_DIR: entry.dir,
+      ARGUMENTS: callArgs.rawArgs,
+    };
+    // Add positional args
+    for (let i = 0; i < 9; i++) {
+      variables[String(i + 1)] = callArgs.args[i] ?? '';
+    }
+    // Merge per-skill variables (e.g., PLUGIN_ROOT for plugin skills)
+    if (entry.variables) {
+      Object.assign(variables, entry.variables);
+    }
+    // Merge consumer variables (consumer wins on collision)
+    Object.assign(variables, this.preprocessorVariables);
+
+    // Build merged script context (consumer first, Cortex built-ins last so
+    // they cannot be overridden — skillDir, args, rawArgs are Cortex-owned)
+    const mergedScriptContext: Record<string, unknown> = {
+      ...this.scriptContext,
+      skillDir: entry.dir,
+      args: callArgs.args,
+      rawArgs: callArgs.rawArgs,
+      scriptArgs: {},
+    };
+
+    // Run preprocessor
+    return preprocessSkillBody(body, {
+      variables,
+      scriptContext: mergedScriptContext,
+      skillDir: entry.dir,
+    });
+  }
+
+  /**
+   * Set consumer-provided variables for ${VAR} substitution.
+   * Called each tick during GATHER to update runtime values.
+   */
+  setPreprocessorVariables(variables: Record<string, string>): void {
+    this.preprocessorVariables = variables;
+  }
+
+  /**
+   * Set consumer-provided context for !{script:} executions.
+   * Called each tick during GATHER to update runtime values.
+   */
+  setScriptContext(context: Record<string, unknown>): void {
+    this.scriptContext = context;
+  }
+
+  /**
+   * Clear all entries. Called during destroy.
+   */
+  clear(): void {
+    this.entries.clear();
+    this.preprocessorVariables = {};
+    this.scriptContext = {};
+  }
+}
+
+// Export parseFrontmatter for testing
+export { parseFrontmatter };