@matimo/core 0.1.3 → 0.1.4

package/tools/matimo_create_tool/matimo_create_tool.js

@@ -0,0 +1,89 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, validateToolContent, classifyRisk, getTierForTool, getGlobalMatimoLogger, } from '@matimo/core';
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+export default async function matimoCreateTool(params) {
+    const logger = getGlobalMatimoLogger();
+    const targetDir = params.target_dir || './matimo-tools';
+    // Step 1: Sanitize name
+    if (!params.name || params.name.trim().length === 0) {
+        return { success: false, message: 'Tool name is required' };
+    }
+    if (UNSAFE_NAME_PATTERN.test(params.name)) {
+        return { success: false, message: 'Tool name contains invalid characters (path traversal, backslash, or control characters)' };
+    }
+    if (params.name.startsWith('matimo_')) {
+        return { success: false, message: 'Tool name cannot start with reserved namespace "matimo_"' };
+    }
+    // Step 2: Parse YAML
+    let parsed;
+    try {
+        parsed = yaml.load(params.yaml_content);
+        if (!parsed || typeof parsed !== 'object') {
+            return { success: false, message: 'YAML must parse to an object' };
+        }
+    }
+    catch (err) {
+        return { success: false, message: `YAML parse error: ${err.message}` };
+    }
+    // Step 3: Force safety fields
+    parsed.name = params.name;
+    parsed.requires_approval = true;
+    parsed.status = 'draft';
+    // Step 4: Validate against schema
+    const yamlStr = yaml.dump(parsed);
+    try {
+        validateToolDefinition(yaml.load(yamlStr));
+    }
+    catch (err) {
+        return { success: false, message: `Schema validation failed: ${err.message}` };
+    }
+    // Step 5: Run content validator
+    const tool = validateToolDefinition(yaml.load(yamlStr));
+    const validation = validateToolContent(tool, { source: 'untrusted' });
+    const criticalOrHigh = validation.violations.filter((v) => v.severity === 'critical' || v.severity === 'high');
+    if (criticalOrHigh.length > 0) {
+        return {
+            success: false,
+            message: 'Tool failed policy validation',
+            errors: criticalOrHigh.map((v) => `[${v.severity}] ${v.rule}: ${v.message}`),
+        };
+    }
+    // Step 6: Classify risk + tier
+    const riskLevel = classifyRisk(tool);
+    const tier = getTierForTool(tool);
+    const approvalState = tier === 'auto' ? 'auto-approved' : 'pending';
+    // Step 7: Write to disk
+    const toolDirPath = path.resolve(targetDir, params.name);
+    fs.mkdirSync(toolDirPath, { recursive: true });
+    let header = '';
+    if (params.proposed_by) {
+        header += `# Proposed by: ${params.proposed_by}\n`;
+    }
+    if (params.justification) {
+        header += `# Justification: ${params.justification}\n`;
+    }
+    if (header) {
+        header += '\n';
+    }
+    const filePath = path.join(toolDirPath, 'definition.yaml');
+    fs.writeFileSync(filePath, header + yamlStr, 'utf-8');
+    logger.info('matimo_create_tool: tool created', {
+        name: params.name,
+        path: filePath,
+        riskLevel,
+        approvalState,
+    });
+    const message = approvalState === 'auto-approved'
+        ? 'Tool created and auto-approved (low-risk read-only). Ready for use.'
+        : 'Tool created as draft. Requires approval before execution. Use matimo_approve_tool to promote.';
+    return {
+        success: true,
+        path: filePath,
+        riskLevel,
+        status: 'draft',
+        approvalState,
+        message,
+    };
+}

package/tools/matimo_get_skill/definition.yaml

@@ -29,7 +29,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_get_skill.ts'
+  code: './matimo_get_skill.js'
 
 output_schema:
   type: object

package/tools/matimo_get_skill/matimo_get_skill.js

@@ -0,0 +1,148 @@
+import fs from 'fs';
+import path from 'path';
+import { getGlobalMatimoLogger, getGlobalMatimoInstance, ToolLoader } from '@matimo/core';
+import { parseSkillContent, listBundledResources } from '../shared/skill-validation.js';
+/** Path traversal detection — defense-in-depth. */
+const UNSAFE_NAME_PATTERN = /[/\\]|\.\.|[\x00-\x1f]/;
+/**
+ * Helper: Find skill directory using auto-discovery (like matimo_list_skills)
+ */
+function findSkillDir(skillName, explicitSkillsDir) {
+    // Try explicit skills_dir first
+    if (explicitSkillsDir) {
+        const skillPath = path.join(explicitSkillsDir, skillName, 'SKILL.md');
+        if (fs.existsSync(skillPath)) {
+            return path.join(explicitSkillsDir, skillName);
+        }
+    }
+    // Try MatimoInstance
+    try {
+        const matimo = getGlobalMatimoInstance();
+        if (matimo) {
+            const skills = matimo.listSkills();
+            const found = skills?.find((s) => s.name === skillName);
+            if (found) {
+                const skillPath = found._path;
+                if (skillPath && fs.existsSync(path.join(skillPath, 'SKILL.md'))) {
+                    return skillPath;
+                }
+            }
+        }
+    }
+    catch {
+        // Fall through
+    }
+    // Auto-discover from @matimo/* packages
+    try {
+        const toolLoader = new ToolLoader();
+        const discoveredPaths = toolLoader.autoDiscoverPackages();
+        for (const toolPath of discoveredPaths) {
+            const pkgDir = path.dirname(toolPath);
+            const skillPath = path.join(pkgDir, 'skills', skillName, 'SKILL.md');
+            if (fs.existsSync(skillPath)) {
+                return path.join(pkgDir, 'skills', skillName);
+            }
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return null;
+}
+/**
+ * Read a skill's content by name — Level 2 activation (SKILL.md) or
+ * Level 3 resource access (bundled file).
+ *
+ * When called without `file`, returns SKILL.md content + metadata + resource listing.
+ * When called with `file`, returns the contents of that bundled resource file.
+ *
+ * Skills are discovered in this order (priority):
+ * 1. Explicit skills_dir if provided
+ * 2. Global MatimoInstance (if initialized)
+ * 3. Auto-discovered @matimo/* packages
+ *
+ * @see https://agentskills.io/specification
+ */
+export default async function matimoGetSkill(params) {
+    const logger = getGlobalMatimoLogger();
+    if (!params.name || params.name.trim().length === 0) {
+        return { success: false, message: 'Skill name is required' };
+    }
+    if (UNSAFE_NAME_PATTERN.test(params.name)) {
+        return { success: false, message: 'Skill name contains invalid characters' };
+    }
+    // Find skill directory using auto-discovery
+    const skillDir = findSkillDir(params.name, params.skills_dir);
+    if (!skillDir) {
+        return { success: false, message: `Skill "${params.name}" not found` };
+    }
+    const skillPath = path.join(skillDir, 'SKILL.md');
+    // Level 3: Read a specific bundled resource file
+    if (params.file) {
+        // For file paths, allow forward slashes but reject path traversal
+        if (/\.\.|\\/u.test(params.file) || /[\x00-\x1f]/.test(params.file)) {
+            return { success: false, message: 'File path contains invalid characters' };
+        }
+        const resourcePath = path.join(skillDir, params.file);
+        // Verify the resolved path stays within the skill directory
+        const resolvedPath = path.resolve(resourcePath);
+        const resolvedSkillDir = path.resolve(skillDir);
+        if (!resolvedPath.startsWith(resolvedSkillDir + path.sep) && resolvedPath !== resolvedSkillDir) {
+            return { success: false, message: 'File path escapes the skill directory' };
+        }
+        if (!fs.existsSync(resourcePath)) {
+            return { success: false, message: `Resource file "${params.file}" not found in skill "${params.name}"` };
+        }
+        try {
+            const fileContent = fs.readFileSync(resourcePath, 'utf-8');
+            return {
+                success: true,
+                name: params.name,
+                content: fileContent,
+                path: resourcePath,
+                message: `Resource file "${params.file}" retrieved successfully.`,
+            };
+        }
+        catch (err) {
+            return { success: false, message: `Failed to read resource file: ${err.message}` };
+        }
+    }
+    // Level 2: Read SKILL.md + metadata + resource listing
+    try {
+        const rawContent = fs.readFileSync(skillPath, 'utf-8');
+        const parseResult = parseSkillContent(rawContent);
+        const result = {
+            success: true,
+            name: params.name,
+            content: rawContent,
+            path: skillPath,
+            message: 'Skill retrieved successfully.',
+        };
+        if (parseResult.success && parseResult.parsed) {
+            const { frontmatter } = parseResult.parsed;
+            result.name = frontmatter.name || params.name;
+            result.description = frontmatter.description || '';
+            if (frontmatter.license)
+                result.license = frontmatter.license;
+            if (frontmatter.compatibility)
+                result.compatibility = frontmatter.compatibility;
+            if (frontmatter.metadata)
+                result.metadata = frontmatter.metadata;
+        }
+        // List bundled resources (Level 3 discovery)
+        result.resources = listBundledResources(skillDir);
+        logger.info('matimo_get_skill: skill retrieved', {
+            name: params.name,
+            path: skillPath,
+        });
+        return result;
+    }
+    catch (err) {
+        const errorMsg = err.message;
+        logger.error('matimo_get_skill: failed to read skill', {
+            name: params.name,
+            error: errorMsg,
+        });
+        return { success: false, message: `Failed to read skill: ${errorMsg}` };
+    }
+}

package/tools/matimo_get_tool/definition.yaml

@@ -19,7 +19,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_get_tool.ts'
+  code: './matimo_get_tool.js'
 
 output_schema:
   type: object

package/tools/matimo_get_tool/matimo_get_tool.js

@@ -0,0 +1,38 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, getGlobalMatimoLogger } from '@matimo/core';
+export default async function matimoGetTool(params) {
+    const logger = getGlobalMatimoLogger();
+    const toolDir = params.tool_dir ?? './matimo-tools';
+    const defPath = path.join(toolDir, params.name, 'definition.yaml');
+    if (!fs.existsSync(defPath)) {
+        logger.warn('matimo_get_tool: tool not found', { name: params.name, path: defPath });
+        return { found: false, message: `Tool "${params.name}" not found at ${defPath}` };
+    }
+    const yamlContent = fs.readFileSync(defPath, 'utf-8');
+    let definition;
+    try {
+        const parsed = yaml.load(yamlContent);
+        const validated = validateToolDefinition(parsed);
+        // Omit internal _definitionPath from the returned object
+        const { _definitionPath: _, ...rest } = validated;
+        definition = rest;
+    }
+    catch (err) {
+        return {
+            found: true,
+            name: params.name,
+            yaml_content: yamlContent,
+            message: `Tool YAML is invalid: ${err.message}`,
+        };
+    }
+    logger.debug('matimo_get_tool: retrieved', { name: params.name });
+    return {
+        found: true,
+        name: params.name,
+        yaml_content: yamlContent,
+        definition,
+        message: `Tool "${params.name}" retrieved successfully`,
+    };
+}

package/tools/matimo_get_tool_status/definition.yaml

@@ -19,7 +19,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_get_tool_status.ts'
+  code: './matimo_get_tool_status.js'
 
 output_schema:
   type: object

package/tools/matimo_get_tool_status/matimo_get_tool_status.js

@@ -0,0 +1,68 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, classifyRisk, getTierForTool, ApprovalManifest, getGlobalMatimoLogger, } from '@matimo/core';
+export default async function matimoGetToolStatus(params, context) {
+    const logger = getGlobalMatimoLogger();
+    const toolDir = params.tool_dir || './matimo-tools';
+    const defPath = path.join(toolDir, params.name, 'definition.yaml');
+    if (!fs.existsSync(defPath)) {
+        logger.warn('matimo_get_tool_status: tool not found', { name: params.name, path: defPath });
+        return { found: false, message: `Tool "${params.name}" not found at ${defPath}` };
+    }
+    const yamlContent = fs.readFileSync(defPath, 'utf-8');
+    let tool;
+    try {
+        const parsed = yaml.load(yamlContent);
+        tool = validateToolDefinition(parsed);
+    }
+    catch (err) {
+        return {
+            found: true,
+            name: params.name,
+            message: `Tool YAML is invalid: ${err.message}`,
+        };
+    }
+    const riskLevel = classifyRisk(tool);
+    const tier = getTierForTool(tool);
+    // Determine approval state from manifest
+    const approvalDir = path.resolve(toolDir);
+    const manifest = new ApprovalManifest(approvalDir, context?.credentials?.MATIMO_APPROVAL_SECRET);
+    const hash = manifest.computeHash(yamlContent);
+    const approvalRecord = manifest.getApproval(params.name);
+    const isApproved = approvalRecord ? manifest.isApproved(params.name, hash) : false;
+    const pendingTools = manifest.getPendingTools();
+    let approvalState;
+    if (tool.status === 'deprecated') {
+        approvalState = 'rejected';
+    }
+    else if (isApproved) {
+        approvalState = 'approved';
+    }
+    else if (tier === 'auto') {
+        approvalState = 'auto-approved';
+    }
+    else if (pendingTools.includes(params.name)) {
+        approvalState = 'pending';
+    }
+    else {
+        // Tool exists on disk but no pending record and not approved — treat as pending
+        approvalState = 'pending';
+    }
+    logger.debug('matimo_get_tool_status: status retrieved', {
+        name: params.name,
+        status: tool.status,
+        riskLevel,
+        approvalState,
+    });
+    return {
+        found: true,
+        name: params.name,
+        status: tool.status ?? 'draft',
+        riskLevel,
+        approvalState,
+        approvedAt: approvalRecord?.approvedAt,
+        approvedBy: approvalRecord?.approvedBy,
+        message: `Tool "${params.name}" is ${approvalState} (${riskLevel} risk)`,
+    };
+}

package/tools/matimo_list_skills/definition.yaml

@@ -37,7 +37,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_list_skills.ts'
+  code: './matimo_list_skills.js'
 
 output_schema:
   type: object

package/tools/matimo_list_skills/matimo_list_skills.js

@@ -0,0 +1,109 @@
+import path from 'path';
+import fs from 'fs';
+import { getGlobalMatimoLogger, getGlobalMatimoInstance, extractSkillMetadata, ToolLoader } from '@matimo/core';
+/**
+ * Helper: Load SKILL.md files from a directory and extract metadata.
+ */
+function loadSkillsFromPath(skillsPath, source, logger) {
+    const skills = [];
+    if (!fs.existsSync(skillsPath))
+        return skills;
+    try {
+        const entries = fs.readdirSync(skillsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillFilePath = path.join(skillsPath, entry.name, 'SKILL.md');
+            if (!fs.existsSync(skillFilePath))
+                continue;
+            try {
+                const content = fs.readFileSync(skillFilePath, 'utf-8');
+                const result = extractSkillMetadata(content, source);
+                if (result.success && result.metadata) {
+                    skills.push(result.metadata);
+                }
+            }
+            catch (err) {
+                logger.debug('matimo_list_skills: failed to extract metadata', {
+                    skill: entry.name,
+                    error: err.message,
+                });
+            }
+        }
+    }
+    catch (err) {
+        logger.debug('matimo_list_skills: failed to read directory', {
+            path: skillsPath,
+            error: err.message,
+        });
+    }
+    return skills;
+}
+/**
+ * List all skills available in the current Matimo instance.
+ *
+ * Skills are discovered in this order (priority):
+ * 1. Global MatimoInstance (if initialized) — includes auto-discovered @matimo/* skills
+ * 2. Auto-discover from @matimo/* packages in node_modules (like tools do)
+ * 3. Explicit skills_dir if provided
+ *
+ * Returns METADATA ONLY: name, description, license, version, metadata, source.
+ * Full body content is available via matimo_get_skill when explicitly requested.
+ *
+ * Uses lightweight YAML-only extraction (no body/sections parsing) for efficiency.
+ * This avoids the overhead of parsing skill markdown sections and keeps responses small.
+ */
+export default async function matimoListSkills(params) {
+    const logger = getGlobalMatimoLogger();
+    const allSkills = new Map();
+    try {
+        // Try global MatimoInstance first
+        try {
+            const matimo = getGlobalMatimoInstance();
+            if (matimo) {
+                const matimoSkills = matimo.listSkills();
+                if (matimoSkills?.length > 0) {
+                    logger.debug('matimo_list_skills: from MatimoInstance', { count: matimoSkills.length });
+                    matimoSkills.forEach((s) => allSkills.set(s.name, s));
+                    return { skills: Array.from(allSkills.values()), total: allSkills.size };
+                }
+            }
+        }
+        catch (err) {
+            logger.debug('matimo_list_skills: MatimoInstance unavailable', {
+                error: err.message,
+            });
+        }
+        // Auto-discover from @matimo/* packages
+        try {
+            const toolLoader = new ToolLoader();
+            const discoveredPaths = toolLoader.autoDiscoverPackages();
+            for (const toolPath of discoveredPaths) {
+                const pkgDir = path.dirname(toolPath);
+                const skillsPath = path.join(pkgDir, 'skills');
+                const discovered = loadSkillsFromPath(skillsPath, 'builtin', logger);
+                discovered.forEach((s) => allSkills.set(s.name, s));
+            }
+        }
+        catch (err) {
+            logger.debug('matimo_list_skills: auto-discovery failed', {
+                error: err.message,
+            });
+        }
+        // Load from explicit skills_dir if provided
+        if (params.skills_dir) {
+            const skillsDir = path.resolve(params.skills_dir);
+            const discovered = loadSkillsFromPath(skillsDir, 'user', logger);
+            discovered.forEach((s) => allSkills.set(s.name, s));
+        }
+        const results = Array.from(allSkills.values());
+        logger.debug('matimo_list_skills: complete', { total: results.length });
+        return { skills: results, total: results.length };
+    }
+    catch (err) {
+        logger.error('matimo_list_skills: failed', {
+            error: err.message,
+        });
+        return { skills: [], total: 0 };
+    }
+}

package/tools/matimo_list_user_tools/definition.yaml

@@ -19,7 +19,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_list_user_tools.ts'
+  code: './matimo_list_user_tools.js'
 
 output_schema:
   type: object

package/tools/matimo_list_user_tools/matimo_list_user_tools.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { validateToolDefinition, classifyRisk, getGlobalMatimoLogger, } from '@matimo/core';
+export default async function matimoListUserTools(params) {
+    const logger = getGlobalMatimoLogger();
+    const toolDir = params.tool_dir || './matimo-tools';
+    const includeDrafts = params.include_drafts !== false;
+    const tools = [];
+    if (!fs.existsSync(toolDir)) {
+        return { tools: [], total: 0 };
+    }
+    const entries = fs.readdirSync(toolDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const defPath = path.join(toolDir, entry.name, 'definition.yaml');
+        if (!fs.existsSync(defPath))
+            continue;
+        try {
+            const content = fs.readFileSync(defPath, 'utf-8');
+            const parsed = yaml.load(content);
+            const tool = validateToolDefinition(parsed);
+            const status = tool.status || 'approved';
+            if (!includeDrafts && status === 'draft')
+                continue;
+            tools.push({
+                name: tool.name,
+                description: tool.description,
+                version: tool.version,
+                status,
+                riskLevel: classifyRisk(tool),
+                tags: tool.tags || [],
+            });
+        }
+        catch (err) {
+            logger.warn('matimo_list_user_tools: failed to parse tool', {
+                dir: entry.name,
+                error: err.message,
+            });
+        }
+    }
+    return { tools, total: tools.length };
+}

package/tools/matimo_reload_tools/definition.yaml

@@ -16,7 +16,7 @@ parameters: {}
 
 execution:
   type: function
-  code: './matimo_reload_tools.ts'
+  code: './matimo_reload_tools.js'
 
 output_schema:
   type: object

package/tools/matimo_reload_tools/matimo_reload_tools.js

@@ -0,0 +1,21 @@
+import { getGlobalMatimoLogger } from '@matimo/core';
+/**
+ * matimo_reload_tools — Hot-reload all tools from configured toolPaths.
+ *
+ * NOTE: This function is a placeholder. The actual reload logic is intercepted
+ * and handled directly by MatimoInstance.execute() because reloadTools() is a
+ * method on the instance itself (it clears the registry, re-reads YAML from
+ * disk, re-validates untrusted tools, etc.). The function executor cannot do
+ * this because it doesn't have a reference to the MatimoInstance.
+ *
+ * If this file is ever reached (e.g., in tests without the interception),
+ * it returns an error instructing the caller to use matimo.reloadTools() directly.
+ */
+export default async function matimoReloadTools() {
+    const logger = getGlobalMatimoLogger();
+    logger.warn('matimo_reload_tools: reached fallback implementation — this should be intercepted by MatimoInstance.execute()');
+    return {
+        success: false,
+        message: 'Reload must be handled by MatimoInstance. If you see this, the interception in execute() is not active.',
+    };
+}

package/tools/matimo_search_tools/definition.yaml

@@ -19,7 +19,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_search_tools.ts'
+  code: './matimo_search_tools.js'
 
 output_schema:
   type: object

package/tools/matimo_search_tools/matimo_search_tools.js

@@ -0,0 +1,59 @@
+import { getGlobalMatimoInstance, getGlobalMatimoLogger, validateToolDefinition, classifyRisk } from '@matimo/core';
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+export default async function matimoSearchTools(params) {
+    const logger = getGlobalMatimoLogger();
+    const query = params.query ?? '';
+    const limit = params.limit ?? 20;
+    const toSummary = (tool) => ({
+        name: tool.name,
+        description: tool.description,
+        version: tool.version,
+        tags: tool.tags ?? [],
+        riskLevel: classifyRisk(tool),
+    });
+    // Prefer registry search via the global instance (has all loaded tools)
+    try {
+        const instance = getGlobalMatimoInstance();
+        const found = instance.searchTools(query).slice(0, limit);
+        logger.debug('matimo_search_tools: registry search', { query, count: found.length });
+        return {
+            results: found.map(toSummary),
+            total: found.length,
+            query,
+        };
+    }
+    catch {
+        // Global instance not set — fall through to disk-based scan below
+        logger.debug('matimo_search_tools: no global instance, falling back to disk scan');
+    }
+    // Fallback: scan the default tools directory
+    const toolDir = './matimo-tools';
+    if (!fs.existsSync(toolDir)) {
+        return { results: [], total: 0, query };
+    }
+    const lowerQuery = query.toLowerCase();
+    const results = [];
+    for (const entry of fs.readdirSync(toolDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const defPath = path.join(toolDir, entry.name, 'definition.yaml');
+        if (!fs.existsSync(defPath))
+            continue;
+        try {
+            const tool = validateToolDefinition(yaml.load(fs.readFileSync(defPath, 'utf-8')));
+            const matches = tool.name.toLowerCase().includes(lowerQuery) ||
+                tool.description.toLowerCase().includes(lowerQuery) ||
+                (tool.tags ?? []).some((t) => t.toLowerCase().includes(lowerQuery));
+            if (matches)
+                results.push(toSummary(tool));
+        }
+        catch {
+            // Skip invalid definitions silently
+        }
+        if (results.length >= limit)
+            break;
+    }
+    return { results, total: results.length, query };
+}

package/tools/matimo_validate_skill/definition.yaml

@@ -23,7 +23,7 @@ parameters:
 
 execution:
   type: function
-  code: './matimo_validate_skill.ts'
+  code: './matimo_validate_skill.js'
 
 output_schema:
   type: object