@animus-labs/cortex 0.2.0

package/dist/skill-preprocessor.js

@@ -0,0 +1,237 @@
+/**
+ * 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';
+// ---------------------------------------------------------------------------
+// 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;
+function getShellConfig() {
+    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, config) {
+    // 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 = [];
+    const scriptReplacements = [];
+    // Find shell commands
+    let match;
+    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, variables) {
+    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) => {
+        return variables[num] ?? '';
+    });
+    // Replace ${VAR} references
+    result = result.replace(VARIABLE_PATTERN, (_match, varName) => {
+        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, cwd) {
+    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, stdout, _stderr) => {
+            if (error) {
+                if ('killed' in error && error.killed) {
+                    resolve('[Error: command timed out]');
+                }
+                else {
+                    const exitCode = 'code' in error && error['code'] != null
+                        ? error['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, extraArgsStr, config) {
+    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 = {};
+    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 = {
+        ...config.scriptContext,
+        skillDir: config.skillDir,
+        scriptArgs,
+    };
+    // Execute with timeout
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve('[Error: script timed out]'), COMMAND_TIMEOUT_MS);
+    });
+    const executionPromise = (async () => {
+        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]);
+}
+//# sourceMappingURL=skill-preprocessor.js.map

package/dist/skill-preprocessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-preprocessor.js","sourceRoot":"","sources":["../src/skill-preprocessor.ts"],"names":[],"mappings":"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"}

package/dist/skill-registry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 type { SkillConfig, SkillEntry } from './types.js';
+/**
+ * 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)
+ */
+declare function parseFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+export declare class SkillRegistry {
+    private readonly entries;
+    /** Consumer-provided variables for ${VAR} substitution. */
+    private preprocessorVariables;
+    /** Consumer-provided context for !{script:} executions. */
+    private scriptContext;
+    /**
+     * Callback fired when skills are added or removed.
+     * CortexAgent sets this to rebuild the load_skill tool description.
+     */
+    onChange: (() => void) | null;
+    constructor(configs?: SkillConfig[]);
+    /**
+     * 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;
+    /**
+     * Remove a skill by name.
+     */
+    removeSkill(name: string): void;
+    /**
+     * Get a skill entry by name.
+     */
+    getEntry(name: string): SkillEntry | null;
+    /**
+     * Get all registered skill entries.
+     */
+    getAll(): SkillEntry[];
+    /**
+     * Get the number of registered skills.
+     */
+    get size(): number;
+    /**
+     * 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): string;
+    /**
+     * 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
+     */
+    getSkillBody(name: string, callArgs: {
+        args: string[];
+        rawArgs: string;
+    }): Promise<string>;
+    /**
+     * Set consumer-provided variables for ${VAR} substitution.
+     * Called each tick during GATHER to update runtime values.
+     */
+    setPreprocessorVariables(variables: Record<string, string>): void;
+    /**
+     * Set consumer-provided context for !{script:} executions.
+     * Called each tick during GATHER to update runtime values.
+     */
+    setScriptContext(context: Record<string, unknown>): void;
+    /**
+     * Clear all entries. Called during destroy.
+     */
+    clear(): void;
+}
+export { parseFrontmatter };
+//# sourceMappingURL=skill-registry.d.ts.map

package/dist/skill-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-registry.d.ts","sourceRoot":"","sources":["../src/skill-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO1D;;;;;;;;;;GAUG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6FjG;AAMD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,2DAA2D;IAC3D,OAAO,CAAC,qBAAqB,CAA8B;IAE3D,2DAA2D;IAC3D,OAAO,CAAC,aAAa,CAA+B;IAEpD;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;gBAEzB,OAAO,CAAC,EAAE,WAAW,EAAE;IAQnC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAsCnC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO/B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIzC;;OAEG;IACH,MAAM,IAAI,UAAU,EAAE;IAItB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,yBAAyB,CAAC,SAAS,SAA2B,GAAG,MAAM;IA6CvE;;;;;;;;OAQG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,MAAM,CAAC;IAkDlB;;;OAGG;IACH,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAIjE;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxD;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAGD,OAAO,EAAE,gBAAgB,EAAE,CAAC"}