profclaw 0.0.1-beta.1

package/dist/skills/compiler.js

@@ -0,0 +1,358 @@
+/**
+ * Skill Intelligence Compiler - Phase 19 Category 9
+ *
+ * 9.1 - Skill-to-workflow compiler: parses SKILL.md into WorkflowDefinition
+ * 9.2 - Model-adaptive injection: selects condensed vs full instructions by capability
+ * 9.3 - Skill effectiveness tracking: in-memory usage/success counters
+ */
+/** Lines that indicate a numbered step (1. text, Step 1: text) */
+const NUMBERED_STEP_RE = /^(?:\d+\.\s+|Step\s+\d+[:.]\s*)/i;
+/** Lines that are task-list items: - [ ] text */
+const TASK_ITEM_RE = /^-\s+\[[ x]\]\s+/i;
+/** Backtick-quoted tool or command names */
+const BACKTICK_TOOL_RE = /`([a-z_][a-z0-9_-]*)`/gi;
+/** Code fence opener */
+const CODE_FENCE_RE = /^```/;
+/** Heading line */
+const HEADING_RE = /^#{1,6}\s/;
+/** Example block markers (headings or lines containing "example") */
+const EXAMPLE_HEADING_RE = /^#{1,6}\s.*example/i;
+/**
+ * Map a plain-text step description to a best-guess tool name
+ */
+function inferToolFromText(text) {
+    const lower = text.toLowerCase();
+    if (/\b(run|execute|exec|bash|shell|command|cmd)\b/.test(lower))
+        return 'exec';
+    if (/\b(write|create|generate|output|save|produce)\b/.test(lower))
+        return 'write_file';
+    if (/\b(read|open|load|view|look at|check file|inspect file)\b/.test(lower))
+        return 'read_file';
+    if (/\b(search|find|grep|locate|look for)\b/.test(lower))
+        return 'search_files';
+    if (/\b(fetch|download|request|http|url|web)\b/.test(lower))
+        return 'web_fetch';
+    if (/\b(list|enumerate|dir|ls)\b/.test(lower))
+        return 'search_files';
+    if (/\b(check|verify|validate|test)\b/.test(lower))
+        return 'exec';
+    return 'exec';
+}
+/**
+ * Collect all backtick-quoted tool references from a block of text.
+ * Common prose words are filtered out to avoid noise.
+ */
+function extractToolRefs(text) {
+    const PROSE_WORDS = new Set([
+        'true', 'false', 'null', 'undefined', 'yes', 'no', 'ok',
+        'and', 'or', 'not', 'the', 'a', 'an', 'of', 'in', 'to', 'for',
+    ]);
+    const seen = new Set();
+    const result = [];
+    let match;
+    const re = new RegExp(BACKTICK_TOOL_RE.source, 'gi');
+    while ((match = re.exec(text)) !== null) {
+        const token = match[1].toLowerCase();
+        if (!PROSE_WORDS.has(token) && !seen.has(token)) {
+            seen.add(token);
+            result.push(token);
+        }
+    }
+    return result;
+}
+/**
+ * Extract action verbs from a block of text (first word of each sentence / step).
+ */
+function extractActions(steps) {
+    const seen = new Set();
+    const actions = [];
+    for (const step of steps) {
+        // Strip leading numbering / task markers
+        const clean = step
+            .replace(NUMBERED_STEP_RE, '')
+            .replace(TASK_ITEM_RE, '')
+            .trim();
+        const firstWord = clean.split(/\s+/)[0]?.replace(/[^a-zA-Z]/g, '').toLowerCase();
+        if (firstWord && firstWord.length > 2 && !seen.has(firstWord)) {
+            seen.add(firstWord);
+            actions.push(firstWord);
+        }
+    }
+    return actions;
+}
+/**
+ * Split the instructions into step lines by looking for numbered lists,
+ * task-list items, and "Step N:" patterns.
+ */
+function extractStepLines(instructions) {
+    const steps = [];
+    const lines = instructions.split('\n');
+    let inCodeBlock = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Track code blocks - skip their contents for step extraction
+        if (CODE_FENCE_RE.test(trimmed)) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        if (NUMBERED_STEP_RE.test(trimmed) || TASK_ITEM_RE.test(trimmed)) {
+            steps.push(trimmed);
+        }
+    }
+    return steps;
+}
+/**
+ * Build a WorkflowDefinition from a list of step lines.
+ * Only created when there are 2+ sequential steps.
+ */
+function buildWorkflow(skillId, skillName, stepLines, instructions) {
+    if (stepLines.length < 2)
+        return undefined;
+    const steps = stepLines.map((line, idx) => {
+        const clean = line
+            .replace(NUMBERED_STEP_RE, '')
+            .replace(TASK_ITEM_RE, '')
+            .trim();
+        // Pull any backtick tool override from the line
+        const toolMatch = /`([a-z_][a-z0-9_-]+)`/.exec(clean);
+        const toolName = toolMatch ? toolMatch[1] : inferToolFromText(clean);
+        return {
+            id: `step-${idx + 1}`,
+            name: clean.slice(0, 60),
+            tool: toolName,
+            params: { instruction: clean },
+            continueOnError: false,
+        };
+    });
+    // Derive triggers from skill name words + action verbs
+    const triggers = skillName.toLowerCase().split(/[\s_-]+/).filter(t => t.length > 2);
+    return {
+        id: `skill-${skillId}`,
+        name: skillName,
+        description: `Auto-compiled workflow for skill: ${skillName}`,
+        triggers,
+        steps,
+        variables: {
+            skillInstructions: instructions,
+        },
+    };
+}
+/**
+ * Strip example blocks and lengthy prose to produce a condensed prompt
+ * suitable for basic/small models. Target: ~500 chars.
+ */
+function buildCondensed(instructions) {
+    const lines = instructions.split('\n');
+    const kept = [];
+    let inExample = false;
+    let inCodeBlock = false;
+    let charCount = 0;
+    const LIMIT = 500;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Track code blocks
+        if (CODE_FENCE_RE.test(trimmed)) {
+            inCodeBlock = !inCodeBlock;
+            // Skip code block fences and contents in condensed mode
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        // Detect example sections - skip them
+        if (EXAMPLE_HEADING_RE.test(trimmed)) {
+            inExample = true;
+            continue;
+        }
+        // End example section on next non-empty heading
+        if (inExample && HEADING_RE.test(trimmed)) {
+            inExample = false;
+        }
+        if (inExample)
+            continue;
+        // Skip blank lines to save space
+        if (trimmed === '')
+            continue;
+        // Strip heading markdown for condensed
+        const content = trimmed.replace(/^#{1,6}\s+/, '');
+        if (charCount + content.length + 1 > LIMIT) {
+            if (kept.length > 0) {
+                kept.push('...');
+            }
+            break;
+        }
+        kept.push(content);
+        charCount += content.length + 1;
+    }
+    return kept.join(' ').trim();
+}
+/**
+ * Strip everything except the body text (remove metadata headings, keep instructions).
+ * Preserves full detail for large models.
+ */
+function buildFull(instructions) {
+    return instructions.trim();
+}
+/**
+ * Compile a SKILL.md instructions string into a CompiledSkill.
+ */
+export function compileSkill(skillId, skillName, markdown) {
+    const stepLines = extractStepLines(markdown);
+    const referencedTools = extractToolRefs(markdown);
+    const actions = extractActions(stepLines);
+    const workflow = buildWorkflow(skillId, skillName, stepLines, markdown);
+    const condensed = buildCondensed(markdown);
+    const full = buildFull(markdown);
+    return {
+        skillId,
+        skillName,
+        rawInstructions: markdown,
+        workflow,
+        condensed,
+        full,
+        actions,
+        referencedTools,
+    };
+}
+// 9.2 - Model-Adaptive Skill Injection
+/**
+ * Return the appropriate skill instructions for a given model capability level.
+ *
+ * - reasoning  -> full instructions, no preamble (model can self-direct)
+ * - instruction -> full instructions with explicit directive
+ * - basic      -> condensed instructions; optionally references compiled workflow
+ */
+export function getSkillForModel(compiled, capabilityLevel) {
+    switch (capabilityLevel) {
+        case 'reasoning':
+            return compiled.full;
+        case 'instruction':
+            return `Follow these steps exactly:\n\n${compiled.full}`;
+        case 'basic': {
+            let text = compiled.condensed;
+            if (compiled.workflow) {
+                text += ` Or use the workflow: {{${compiled.workflow.id}}}`;
+            }
+            return text;
+        }
+    }
+}
+/** In-memory tracking map keyed by "<skillId>:<modelId>" */
+const effectivenessMap = new Map();
+function effectivenessKey(skillId, modelId) {
+    return `${skillId}:${modelId}`;
+}
+/**
+ * Record the outcome of one skill execution.
+ */
+export function trackSkillUsage(skillId, modelId, success, durationMs) {
+    const key = effectivenessKey(skillId, modelId);
+    const existing = effectivenessMap.get(key);
+    if (existing) {
+        const newAttempts = existing.attempts + 1;
+        const newSuccesses = existing.successes + (success ? 1 : 0);
+        const newFailures = existing.failures + (success ? 0 : 1);
+        // Rolling average for duration
+        const newAvg = (existing.avgDurationMs * existing.attempts + durationMs) / newAttempts;
+        effectivenessMap.set(key, {
+            ...existing,
+            attempts: newAttempts,
+            successes: newSuccesses,
+            failures: newFailures,
+            avgDurationMs: newAvg,
+            successRate: newAttempts > 0 ? newSuccesses / newAttempts : 0,
+            lastUsed: Date.now(),
+        });
+    }
+    else {
+        effectivenessMap.set(key, {
+            skillId,
+            modelId,
+            attempts: 1,
+            successes: success ? 1 : 0,
+            failures: success ? 0 : 1,
+            avgDurationMs: durationMs,
+            successRate: success ? 1 : 0,
+            lastUsed: Date.now(),
+        });
+    }
+}
+/**
+ * Get effectiveness records for a skill.
+ * If `modelId` is provided, returns only that model's record (as a single-item array).
+ * If omitted, returns all model records for the skill.
+ */
+export function getSkillEffectiveness(skillId, modelId) {
+    if (modelId) {
+        const record = effectivenessMap.get(effectivenessKey(skillId, modelId));
+        return record ? [record] : [];
+    }
+    const results = [];
+    for (const record of effectivenessMap.values()) {
+        if (record.skillId === skillId) {
+            results.push(record);
+        }
+    }
+    return results;
+}
+/**
+ * Return the model with the highest success rate for a given skill.
+ * Returns null if no data exists.
+ */
+export function getBestModelForSkill(skillId) {
+    const records = getSkillEffectiveness(skillId);
+    if (records.length === 0)
+        return null;
+    let best = records[0];
+    for (const record of records) {
+        if (record.successRate > best.successRate) {
+            best = record;
+        }
+    }
+    return { modelId: best.modelId, successRate: best.successRate };
+}
+/**
+ * Return all skills ranked by total usage, with their overall success rate.
+ */
+export function getSkillRanking() {
+    // Aggregate per-skill across all models
+    const bySkill = new Map();
+    for (const record of effectivenessMap.values()) {
+        const agg = bySkill.get(record.skillId) ?? { successes: 0, attempts: 0 };
+        agg.successes += record.successes;
+        agg.attempts += record.attempts;
+        bySkill.set(record.skillId, agg);
+    }
+    const ranking = Array.from(bySkill.entries()).map(([skillId, agg]) => ({
+        skillId,
+        totalUses: agg.attempts,
+        overallSuccessRate: agg.attempts > 0 ? agg.successes / agg.attempts : 0,
+    }));
+    // Sort descending by total uses, then by success rate
+    ranking.sort((a, b) => {
+        if (b.totalUses !== a.totalUses)
+            return b.totalUses - a.totalUses;
+        return b.overallSuccessRate - a.overallSuccessRate;
+    });
+    return ranking;
+}
+/**
+ * Dump the full effectiveness map as a plain object (for persistence on shutdown).
+ */
+export function dumpEffectivenessData() {
+    const out = {};
+    for (const [key, value] of effectivenessMap.entries()) {
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Restore previously persisted effectiveness data (e.g. loaded from disk on startup).
+ */
+export function restoreEffectivenessData(data) {
+    for (const [key, value] of Object.entries(data)) {
+        effectivenessMap.set(key, value);
+    }
+}
+//# sourceMappingURL=compiler.js.map

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Skill Frontmatter Parser
+ *
+ * Parses YAML frontmatter from SKILL.md files.
+ * Following OpenClaw's patterns for compatibility.
+ */
+import type { SkillMetadata, SkillInvocationPolicy, SkillEntry, SkillSource } from './types.js';
+/**
+ * Raw parsed frontmatter (before type conversion)
+ */
+type ParsedFrontmatter = Record<string, string | undefined>;
+/**
+ * Parse YAML frontmatter from markdown content
+ */
+export declare function parseFrontmatter(content: string): ParsedFrontmatter;
+/**
+ * Get markdown content after frontmatter
+ */
+export declare function getMarkdownContent(content: string): string;
+/**
+ * Resolve extended metadata from frontmatter
+ */
+export declare function resolveMetadata(raw: ParsedFrontmatter): SkillMetadata | undefined;
+/**
+ * Resolve skill invocation policy from frontmatter
+ */
+export declare function resolveSkillInvocationPolicy(raw: ParsedFrontmatter): SkillInvocationPolicy;
+/**
+ * Parse a SKILL.md file into a SkillEntry
+ */
+export declare function parseSkillFile(content: string, filePath: string, baseDir: string, source: SkillSource): SkillEntry | null;
+export {};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/skills/frontmatter.js

@@ -0,0 +1,175 @@
+/**
+ * Skill Frontmatter Parser
+ *
+ * Parses YAML frontmatter from SKILL.md files.
+ * Following OpenClaw's patterns for compatibility.
+ */
+/**
+ * Parse YAML frontmatter from markdown content
+ */
+export function parseFrontmatter(content) {
+    const frontmatter = {};
+    // Match YAML frontmatter block
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        return frontmatter;
+    }
+    const yamlContent = match[1];
+    const lines = yamlContent.split(/\r?\n/);
+    for (const line of lines) {
+        // Skip empty lines and comments
+        if (!line.trim() || line.trim().startsWith('#')) {
+            continue;
+        }
+        // Parse key: value pairs (single-line only, following OpenClaw)
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1) {
+            continue;
+        }
+        const key = line.slice(0, colonIndex).trim();
+        let value = line.slice(colonIndex + 1).trim();
+        // Remove surrounding quotes if present
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        frontmatter[key] = value;
+    }
+    return frontmatter;
+}
+/**
+ * Get markdown content after frontmatter
+ */
+export function getMarkdownContent(content) {
+    const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n([\s\S]*)$/);
+    return match ? match[1].trim() : content.trim();
+}
+/**
+ * Normalize string list from various input formats
+ */
+function normalizeStringList(input) {
+    if (!input) {
+        return [];
+    }
+    if (Array.isArray(input)) {
+        return input.map((v) => String(v).trim()).filter(Boolean);
+    }
+    if (typeof input === 'string') {
+        return input.split(',').map((v) => v.trim()).filter(Boolean);
+    }
+    return [];
+}
+/**
+ * Parse boolean from string value
+ */
+function parseBooleanValue(value) {
+    if (!value)
+        return undefined;
+    const lower = value.toLowerCase().trim();
+    if (lower === 'true' || lower === '1' || lower === 'yes')
+        return true;
+    if (lower === 'false' || lower === '0' || lower === 'no')
+        return false;
+    return undefined;
+}
+/**
+ * Parse frontmatter boolean with fallback
+ */
+function parseFrontmatterBool(value, fallback) {
+    const parsed = parseBooleanValue(value);
+    return parsed === undefined ? fallback : parsed;
+}
+/**
+ * Convert raw frontmatter to typed SkillFrontmatter
+ */
+function toSkillFrontmatter(raw) {
+    return {
+        name: raw['name'] || '',
+        description: raw['description'] || '',
+        'user-invocable': parseBooleanValue(raw['user-invocable']),
+        'disable-model-invocation': parseBooleanValue(raw['disable-model-invocation']),
+        'command-dispatch': raw['command-dispatch'],
+        'command-tool': raw['command-tool'],
+        'command-arg-mode': raw['command-arg-mode'],
+        metadata: raw['metadata'],
+    };
+}
+/**
+ * Resolve extended metadata from frontmatter
+ */
+export function resolveMetadata(raw) {
+    const metadataStr = raw['metadata'];
+    if (!metadataStr) {
+        return undefined;
+    }
+    try {
+        // Parse JSON metadata
+        const parsed = JSON.parse(metadataStr);
+        if (!parsed || typeof parsed !== 'object') {
+            return undefined;
+        }
+        // Support nested profclaw/openclaw key or flat structure
+        const metadataObj = (parsed.profclaw || parsed.openclaw || parsed);
+        const requiresRaw = typeof metadataObj.requires === 'object' && metadataObj.requires !== null
+            ? metadataObj.requires
+            : undefined;
+        const osRaw = normalizeStringList(metadataObj.os);
+        return {
+            always: typeof metadataObj.always === 'boolean' ? metadataObj.always : undefined,
+            skillKey: typeof metadataObj.skillKey === 'string' ? metadataObj.skillKey : undefined,
+            primaryEnv: typeof metadataObj.primaryEnv === 'string' ? metadataObj.primaryEnv : undefined,
+            emoji: typeof metadataObj.emoji === 'string' ? metadataObj.emoji : undefined,
+            homepage: typeof metadataObj.homepage === 'string' ? metadataObj.homepage : undefined,
+            os: osRaw.length > 0 ? osRaw : undefined,
+            requires: requiresRaw ? {
+                bins: normalizeStringList(requiresRaw.bins),
+                anyBins: normalizeStringList(requiresRaw.anyBins),
+                env: normalizeStringList(requiresRaw.env),
+                config: normalizeStringList(requiresRaw.config),
+            } : undefined,
+            toolCategories: normalizeStringList(metadataObj.tools || metadataObj.toolCategories),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve skill invocation policy from frontmatter
+ */
+export function resolveSkillInvocationPolicy(raw) {
+    return {
+        userInvocable: parseFrontmatterBool(raw['user-invocable'], true),
+        modelInvocable: !parseFrontmatterBool(raw['disable-model-invocation'], false),
+    };
+}
+/**
+ * Parse a SKILL.md file into a SkillEntry
+ */
+export function parseSkillFile(content, filePath, baseDir, source) {
+    const raw = parseFrontmatter(content);
+    // Name is required
+    const name = raw['name'];
+    if (!name) {
+        return null;
+    }
+    const frontmatter = toSkillFrontmatter(raw);
+    const metadata = resolveMetadata(raw);
+    const invocation = resolveSkillInvocationPolicy(raw);
+    const instructions = getMarkdownContent(content);
+    return {
+        name,
+        description: frontmatter.description || name,
+        source,
+        dirPath: baseDir,
+        skillMdPath: filePath,
+        frontmatter,
+        metadata,
+        instructions,
+        invocation,
+        eligible: true, // Will be computed by loader
+        eligibilityErrors: [],
+        enabled: true, // Will be computed by config
+    };
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/skills/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Skills System
+ *
+ * Dynamic knowledge system for teaching AI about available capabilities.
+ * Following OpenClaw's proven patterns.
+ *
+ * Skills are Markdown files (SKILL.md) that teach the AI:
+ * - What tools are available
+ * - How to use them
+ * - Best practices and workflows
+ *
+ * This enables dynamic capability extension without hardcoding every tool.
+ */
+export * from './types.js';
+export { parseFrontmatter, getMarkdownContent, resolveMetadata, resolveSkillInvocationPolicy, parseSkillFile, } from './frontmatter.js';
+export { loadAllSkills, filterSkills, parseSkillMd, checkEligibility, hasBinary, clearBinaryCache, buildSkillSnapshotSync, buildSkillsStatus, applySkillEnvOverrides, } from './loader.js';
+export { formatSkillsForPrompt, buildSkillSnapshot, buildSkillsPrompt, resolveSkillsPromptForRun, getSkillFromSnapshot, estimateSkillsTokenCost, } from './prompt-builder.js';
+export { SkillsRegistry, getSkillsRegistry, initializeSkillsRegistry, type MCPServerInfo, } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.js

@@ -0,0 +1,24 @@
+/**
+ * Skills System
+ *
+ * Dynamic knowledge system for teaching AI about available capabilities.
+ * Following OpenClaw's proven patterns.
+ *
+ * Skills are Markdown files (SKILL.md) that teach the AI:
+ * - What tools are available
+ * - How to use them
+ * - Best practices and workflows
+ *
+ * This enables dynamic capability extension without hardcoding every tool.
+ */
+// Types
+export * from './types.js';
+// Frontmatter parsing
+export { parseFrontmatter, getMarkdownContent, resolveMetadata, resolveSkillInvocationPolicy, parseSkillFile, } from './frontmatter.js';
+// Skill loading
+export { loadAllSkills, filterSkills, parseSkillMd, checkEligibility, hasBinary, clearBinaryCache, buildSkillSnapshotSync, buildSkillsStatus, applySkillEnvOverrides, } from './loader.js';
+// Prompt building
+export { formatSkillsForPrompt, buildSkillSnapshot, buildSkillsPrompt, resolveSkillsPromptForRun, getSkillFromSnapshot, estimateSkillsTokenCost, } from './prompt-builder.js';
+// Registry
+export { SkillsRegistry, getSkillsRegistry, initializeSkillsRegistry, } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/skills/installer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Skills Installer
+ *
+ * Installs missing dependencies for skills (binaries, packages).
+ * Supports brew, npm/pnpm, go, pip, and direct downloads.
+ */
+import type { SkillInstallSpec, SkillsSystemConfig } from './types.js';
+export interface InstallResult {
+    success: boolean;
+    spec: SkillInstallSpec;
+    message: string;
+    duration: number;
+}
+/**
+ * Install a dependency from a spec
+ */
+export declare function installDependency(spec: SkillInstallSpec, config: SkillsSystemConfig, timeoutMs?: number): Promise<InstallResult>;
+/**
+ * Install all missing dependencies for a skill
+ */
+export declare function installSkillDependencies(installSpecs: SkillInstallSpec[], config: SkillsSystemConfig): Promise<InstallResult[]>;
+//# sourceMappingURL=installer.d.ts.map