matimo 0.1.0-alpha.9 → 0.1.1

package/packages/core/dist/core/schema.js

@@ -15,11 +15,23 @@ export const ParameterSchema = z.object({
 });
 // Authentication configuration
 export const AuthConfigSchema = z.object({
-    type: z.enum(['api_key', 'basic', 'bearer', 'oauth2', 'custom']).optional(),
+    type: z.enum(['none', 'api_key', 'basic', 'bearer', 'oauth2', 'custom']).optional(),
     location: z.enum(['header', 'query', 'body']).optional(),
     name: z.string().optional(),
     provider: z.string().optional(),
     required: z.boolean().optional(),
+    /**
+     * For type: basic — name of the environment variable holding the HTTP Basic Auth username.
+     * HttpExecutor will read this env var and the password_env var, base64-encode them as
+     * "username:password", and inject `Authorization: Basic <encoded>` automatically.
+     * This eliminates the need for developers to pre-compute a base64 credential string.
+     */
+    username_env: z.string().optional(),
+    /**
+     * For type: basic — name of the environment variable holding the HTTP Basic Auth password.
+     * Used together with username_env to build the Authorization header automatically.
+     */
+    password_env: z.string().optional(),
 });
 // Execution configuration (command, HTTP, or function)
 export const ExecutionConfigSchema = z.discriminatedUnion('type', [
@@ -55,16 +67,38 @@ export const ExecutionConfigSchema = z.discriminatedUnion('type', [
     }),
 ]);
 // Output schema for validation
+// Aligned with TypeScript interface: type should be one of the known types (or unknown string for extensibility)
+// Recursive property schema — validates that each property value in output_schema.properties
+// is a valid schema object (not a raw primitive).
+const OutputPropertySchema = z.lazy(() => z.object({
+    type: z
+        .union([
+        z.enum(['string', 'number', 'integer', 'boolean', 'array', 'object', 'null']),
+        z.string(),
+        z.array(z.string()), // Allow nullable arrays: [string, "null"]
+    ])
+        .optional(),
+    description: z.string().optional(),
+    properties: z.record(z.string(), OutputPropertySchema).optional(),
+    items: OutputPropertySchema.optional(),
+    required: z.array(z.string()).optional(),
+    enum: z.array(z.unknown()).optional(),
+}));
 export const OutputSchemaSchema = z.object({
-    type: z.string().optional(),
-    properties: z.record(z.string(), z.unknown()).optional(),
+    type: z
+        .union([
+        z.enum(['string', 'number', 'boolean', 'array', 'object']),
+        z.string(), // Allow other custom types for extensibility
+    ])
+        .optional(),
+    properties: z.record(z.string(), OutputPropertySchema).optional(),
     required: z.array(z.string()).optional(),
     description: z.string().optional(),
 });
 // Error handling configuration
 export const ErrorHandlingSchema = z.object({
     retry: z.number().optional(),
-    backoff_type: z.enum(['linear', 'exponential']).optional(),
+    backoff_type: z.enum(['linear', 'exponential', 'fixed']).optional(),
     initial_delay_ms: z.number().optional(),
     max_delay_ms: z.number().optional(),
 });
@@ -87,6 +121,7 @@ export const ToolDefinitionSchema = z.object({
     error_handling: ErrorHandlingSchema.optional(),
     rate_limiting: RateLimitingSchema.optional(),
     requires_approval: z.boolean().optional(),
+    risk: z.enum(['low', 'medium', 'high', 'critical']).optional(),
     examples: z
         .array(z.object({
         name: z.string(),
@@ -97,6 +132,7 @@ export const ToolDefinitionSchema = z.object({
     deprecated: z.boolean().optional(),
     tags: z.array(z.string()).optional(),
     deprecation_message: z.string().optional(),
+    status: z.enum(['draft', 'approved', 'deprecated']).optional(),
     // _definitionPath: z.string().optional(), // Internal use for tracking source file path
 });
 // export type ToolDefinition = z.infer<typeof ToolDefinitionSchema>;

package/packages/core/dist/core/schema.js.map

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

package/packages/core/dist/core/skill-content-parser.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Skill Content Parser — Markdown AST-based section chunking
+ *
+ * Breaks skill bodies into structured sections so agents load only the parts
+ * they need instead of dumping the entire SKILL.md into context.
+ *
+ * Uses lightweight heading-based parsing (no external Markdown AST library
+ * needed) to produce a tree of sections with token-count estimates.
+ */
+/**
+ * A single section of a skill body, parsed from Markdown headings.
+ */
+export interface SkillSection {
+    /** Heading text (e.g., "Error Handling") */
+    heading: string;
+    /** Heading level (1-6) */
+    level: number;
+    /** Raw Markdown content under this heading (excluding sub-headings) */
+    content: string;
+    /** Approximate token count (words ÷ 0.75 — conservative estimate) */
+    tokenEstimate: number;
+    /** Nested sub-sections */
+    children: SkillSection[];
+    /** Dot-path for addressing (e.g., "Error Handling.Rate Limits") */
+    path: string;
+}
+/**
+ * Result of parsing a skill body into sections.
+ */
+export interface ParsedSkillContent {
+    /** Top-level intro content before any heading */
+    preamble: string;
+    /** Token estimate for preamble */
+    preambleTokens: number;
+    /** All top-level sections (with nested children) */
+    sections: SkillSection[];
+    /** Total token estimate for the entire body */
+    totalTokens: number;
+    /** Flat index: heading path → section reference (for fast lookup) */
+    index: Map<string, SkillSection>;
+}
+/**
+ * Options for retrieving skill content with selective loading.
+ */
+export interface SkillContentOptions {
+    /** Only return sections matching these heading paths (case-insensitive partial match) */
+    sections?: string[];
+    /** Maximum total tokens to return (truncates from the end) */
+    maxTokens?: number;
+    /** Include the preamble (default: true) */
+    includePreamble?: boolean;
+    /** Depth limit for section inclusion (1 = top-level only, 2 = include children, etc.) */
+    maxDepth?: number;
+}
+/**
+ * Parse a Markdown skill body into a tree of sections.
+ *
+ * This is a lightweight parser that splits on ATX headings (lines starting
+ * with #). It does NOT handle:
+ * - Setext headings (underline style)
+ * - Headings inside code blocks (these are treated as content)
+ *
+ * For SKILL.md files (which follow a consistent format), this is sufficient.
+ */
+export declare function parseSkillSections(body: string): ParsedSkillContent;
+/**
+ * Selectively extract content from a parsed skill body.
+ *
+ * This is the key function for context management — instead of dumping the
+ * entire SKILL.md into the LLM's context window, agents call this to get
+ * only the sections they need.
+ *
+ * @example
+ * // Get only the error handling section
+ * extractSkillContent(parsed, { sections: ['Error Handling'] })
+ *
+ * @example
+ * // Get top-level overview only (no sub-sections), max 500 tokens
+ * extractSkillContent(parsed, { maxDepth: 1, maxTokens: 500 })
+ */
+export declare function extractSkillContent(parsed: ParsedSkillContent, options?: SkillContentOptions): string;
+/**
+ * Get a flat list of all section headings with their token costs.
+ * Useful for agents to decide which sections to load.
+ */
+export declare function listSkillSections(parsed: ParsedSkillContent): Array<{
+    path: string;
+    level: number;
+    tokenEstimate: number;
+}>;
+//# sourceMappingURL=skill-content-parser.d.ts.map

package/packages/core/dist/core/skill-content-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-content-parser.d.ts","sourceRoot":"","sources":["../../src/core/skill-content-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAkCD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CA6GnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4ER;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,GACzB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB/D"}

package/packages/core/dist/core/skill-content-parser.js

@@ -0,0 +1,248 @@
+/**
+ * Skill Content Parser — Markdown AST-based section chunking
+ *
+ * Breaks skill bodies into structured sections so agents load only the parts
+ * they need instead of dumping the entire SKILL.md into context.
+ *
+ * Uses lightweight heading-based parsing (no external Markdown AST library
+ * needed) to produce a tree of sections with token-count estimates.
+ */
+// ─── Helper: Check if line is a Markdown heading using safe string operations ─────────
+// Avoids regex to prevent ReDoS on malicious input with many spaces
+function parseHeading(line) {
+    if (!line.startsWith('#'))
+        return null;
+    let level = 0;
+    for (let i = 0; i < Math.min(6, line.length); i++) {
+        if (line[i] === '#')
+            level++;
+        else
+            break;
+    }
+    if (level === 0 || level > 6)
+        return null;
+    // Check that after the hashes, there's whitespace
+    if (level >= line.length || !/\s/.test(line[level]))
+        return null;
+    // Extract heading text after the hashes and skip leading whitespace
+    const heading = line.substring(level).trimStart();
+    return { level, heading };
+}
+/**
+ * Estimate token count from text.
+ * Rough heuristic: 1 token ≈ 0.75 words for English text.
+ * Conservative to avoid under-counting.
+ */
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+    return Math.ceil(wordCount / 0.75);
+}
+/**
+ * Parse a Markdown skill body into a tree of sections.
+ *
+ * This is a lightweight parser that splits on ATX headings (lines starting
+ * with #). It does NOT handle:
+ * - Setext headings (underline style)
+ * - Headings inside code blocks (these are treated as content)
+ *
+ * For SKILL.md files (which follow a consistent format), this is sufficient.
+ */
+export function parseSkillSections(body) {
+    if (!body || body.trim().length === 0) {
+        return {
+            preamble: '',
+            preambleTokens: 0,
+            sections: [],
+            totalTokens: 0,
+            index: new Map(),
+        };
+    }
+    const lines = body.split('\n');
+    const index = new Map();
+    const segments = [];
+    let currentSegment = null;
+    const preambleLines = [];
+    let inCodeBlock = false;
+    for (const line of lines) {
+        // Track fenced code blocks to avoid treating # inside them as headings
+        if (line.trimStart().startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+        }
+        if (!inCodeBlock) {
+            const headingMatch = parseHeading(line);
+            if (headingMatch) {
+                // Flush previous segment
+                if (currentSegment) {
+                    segments.push(currentSegment);
+                }
+                currentSegment = {
+                    heading: headingMatch.heading,
+                    level: headingMatch.level,
+                    contentLines: [],
+                };
+                continue;
+            }
+        }
+        if (currentSegment) {
+            currentSegment.contentLines.push(line);
+        }
+        else {
+            preambleLines.push(line);
+        }
+    }
+    // Flush last segment
+    if (currentSegment) {
+        segments.push(currentSegment);
+    }
+    const preamble = preambleLines.join('\n').trim();
+    const preambleTokens = estimateTokens(preamble);
+    // Build tree from flat list of segments using a stack
+    const topSections = [];
+    const stack = [];
+    for (const seg of segments) {
+        const content = seg.contentLines.join('\n').trim();
+        const section = {
+            heading: seg.heading,
+            level: seg.level,
+            content,
+            tokenEstimate: estimateTokens(content) + estimateTokens(seg.heading),
+            children: [],
+            path: seg.heading,
+        };
+        // Pop stack until we find a parent with a lower level
+        while (stack.length > 0 && stack[stack.length - 1].level >= seg.level) {
+            stack.pop();
+        }
+        if (stack.length > 0) {
+            const parent = stack[stack.length - 1];
+            section.path = `${parent.path}.${seg.heading}`;
+            parent.children.push(section);
+        }
+        else {
+            topSections.push(section);
+        }
+        index.set(section.path.toLowerCase(), section);
+        stack.push(section);
+    }
+    // Calculate total tokens (recursive)
+    function totalTokensOf(section) {
+        return section.tokenEstimate + section.children.reduce((sum, c) => sum + totalTokensOf(c), 0);
+    }
+    const totalTokens = preambleTokens + topSections.reduce((sum, s) => sum + totalTokensOf(s), 0);
+    return {
+        preamble,
+        preambleTokens,
+        sections: topSections,
+        totalTokens,
+        index,
+    };
+}
+/**
+ * Selectively extract content from a parsed skill body.
+ *
+ * This is the key function for context management — instead of dumping the
+ * entire SKILL.md into the LLM's context window, agents call this to get
+ * only the sections they need.
+ *
+ * @example
+ * // Get only the error handling section
+ * extractSkillContent(parsed, { sections: ['Error Handling'] })
+ *
+ * @example
+ * // Get top-level overview only (no sub-sections), max 500 tokens
+ * extractSkillContent(parsed, { maxDepth: 1, maxTokens: 500 })
+ */
+export function extractSkillContent(parsed, options = {}) {
+    const { sections: requestedSections, maxTokens, includePreamble = true, maxDepth } = options;
+    const parts = [];
+    let currentTokens = 0;
+    // Helper: check if we've exceeded the token budget
+    function withinBudget(additional) {
+        if (maxTokens === undefined)
+            return true;
+        return currentTokens + additional <= maxTokens;
+    }
+    // Helper: render a section to Markdown
+    function renderSection(section, depth) {
+        const hashes = '#'.repeat(section.level);
+        let result = `${hashes} ${section.heading}\n\n${section.content}`;
+        if (maxDepth === undefined || depth < maxDepth) {
+            for (const child of section.children) {
+                result += '\n\n' + renderSection(child, depth + 1);
+            }
+        }
+        return result;
+    }
+    // Add preamble
+    if (includePreamble && parsed.preamble) {
+        const tokens = parsed.preambleTokens;
+        if (withinBudget(tokens)) {
+            parts.push(parsed.preamble);
+            currentTokens += tokens;
+        }
+    }
+    // If specific sections requested, find and include only those
+    if (requestedSections && requestedSections.length > 0) {
+        for (const requested of requestedSections) {
+            const lower = requested.toLowerCase();
+            // Try exact match first, then partial match
+            let found = parsed.index.get(lower);
+            if (!found) {
+                // Partial match: find first section whose path contains the query
+                for (const [key, section] of parsed.index) {
+                    if (key.includes(lower)) {
+                        found = section;
+                        break;
+                    }
+                }
+            }
+            if (found) {
+                const rendered = renderSection(found, 1);
+                const tokens = estimateTokens(rendered);
+                if (withinBudget(tokens)) {
+                    parts.push(rendered);
+                    currentTokens += tokens;
+                }
+            }
+        }
+    }
+    else {
+        // Include all sections (respecting maxDepth and maxTokens)
+        for (const section of parsed.sections) {
+            const rendered = renderSection(section, 1);
+            const tokens = estimateTokens(rendered);
+            if (withinBudget(tokens)) {
+                parts.push(rendered);
+                currentTokens += tokens;
+            }
+            else {
+                break; // Stop adding sections once we exceed budget
+            }
+        }
+    }
+    return parts.join('\n\n');
+}
+/**
+ * Get a flat list of all section headings with their token costs.
+ * Useful for agents to decide which sections to load.
+ */
+export function listSkillSections(parsed) {
+    const result = [];
+    function walk(section) {
+        result.push({
+            path: section.path,
+            level: section.level,
+            tokenEstimate: section.tokenEstimate,
+        });
+        for (const child of section.children) {
+            walk(child);
+        }
+    }
+    for (const section of parsed.sections) {
+        walk(section);
+    }
+    return result;
+}
+//# sourceMappingURL=skill-content-parser.js.map

package/packages/core/dist/core/skill-content-parser.js.map

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

package/packages/core/dist/core/skill-loader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Skill Loader — loads and validates skills from multiple sources
+ *
+ * Implements agentskills.io specification with proper YAML parsing and Zod validation.
+ *
+ * @see https://agentskills.io/specification
+ */
+import { SkillDefinition, ParsedSkill, SkillSummary } from './types';
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ */
+export declare function parseSkillContent(content: string): ParsedSkill & {
+    error?: string;
+};
+/**
+ * Extract ONLY metadata from SKILL.md without parsing body/sections.
+ *
+ * Optimized for matimo_list_skills — reads YAML frontmatter only.
+ * This avoids the overhead of parsing sections and body content.
+ *
+ * Returns SkillSummary: name, description, version, license, metadata, source.
+ */
+export declare function extractSkillMetadata(content: string, source?: 'builtin' | 'user' | 'catalog'): {
+    success: boolean;
+    metadata?: SkillSummary;
+    error?: string;
+};
+/**
+ * SkillLoader reads and validates skills from directories
+ */
+export declare class SkillLoader {
+    private logger;
+    /**
+     * Load all skills from a directory
+     */
+    loadSkillsFromDirectory(skillsDir: string, source?: 'builtin' | 'user' | 'catalog'): SkillDefinition[];
+    /**
+     * Load a single skill by name
+     */
+    loadSkill(name: string, skillsDir: string, source?: 'builtin' | 'user' | 'catalog'): SkillDefinition | null;
+    /**
+     * Load a skill resource file (scripts/, references/, assets/)
+     */
+    loadSkillResource(skillName: string, skillsDir: string, resourcePath: string): string;
+}
+//# sourceMappingURL=skill-loader.d.ts.map

package/packages/core/dist/core/skill-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.d.ts","sourceRoot":"","sources":["../../src/core/skill-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EACL,eAAe,EAEf,WAAW,EAEX,YAAY,EACb,MAAM,SAAS,CAAC;AA4GjB;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAsBnF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,SAAS,GAAG,MAAM,GAAG,SAAkB,GAC9C;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAmB/D;AAiDD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA2B;IAEzC;;OAEG;IACH,uBAAuB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,SAAS,GAAG,MAAM,GAAG,SAAkB,GAC9C,eAAe,EAAE;IA2CpB;;OAEG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,SAAS,GAAG,MAAM,GAAG,SAAkB,GAC9C,eAAe,GAAG,IAAI;IAuDzB;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;CAgCtF"}