skimpyclaw 0.1.0

package/dist/skills-types.d.ts

@@ -0,0 +1,65 @@
+/** YAML frontmatter fields in a SKILL.md file */
+export interface SkillFrontmatter {
+    /** Unique skill name (defaults to directory name) */
+    name: string;
+    /** Short description shown in skill listing */
+    description: string;
+    /** Whether the skill is active (default: true) */
+    enabled?: boolean;
+    /** Emoji identifier for the skill */
+    emoji?: string;
+    /** Freeform tags for filtering */
+    tags?: string[];
+    /** External requirements that must be met for eligibility */
+    requires?: SkillRequirements;
+    /** Context filters — when this skill should activate */
+    contexts?: SkillContext;
+    /** Sort priority — lower numbers appear first (default: 100) */
+    priority?: number;
+}
+/** External requirements for a skill to be eligible */
+export interface SkillRequirements {
+    /** Binary names that must be on PATH (checked via `which`) */
+    bins?: string[];
+    /** Environment variables that must be set */
+    env?: string[];
+    /** Tool names that must be available in the current ToolConfig */
+    tools?: string[];
+    /** File/directory paths that must exist */
+    paths?: string[];
+}
+/** Context filters for when a skill should be injected */
+export interface SkillContext {
+    /** Channel names where this skill applies (e.g. "telegram", "discord") */
+    channels?: string[];
+    /** Cron job IDs where this skill applies */
+    cronJobs?: string[];
+    /** Tag-based filters — skill activates when any tag matches */
+    tags?: string[];
+}
+/** A fully loaded skill after parsing and eligibility check */
+export interface LoadedSkill {
+    /** Skill name (from frontmatter or directory name) */
+    name: string;
+    /** Absolute path to the skill directory */
+    dirPath: string;
+    /** Parsed frontmatter */
+    frontmatter: SkillFrontmatter;
+    /** Markdown body (after frontmatter) */
+    body: string;
+    /** Whether the skill passed eligibility checks */
+    eligible: boolean;
+    /** Reason for ineligibility (undefined if eligible) */
+    reason?: string;
+}
+/** Config section for the skills system */
+export interface SkillConfig {
+    /** Master switch for the skills system (default: true) */
+    enabled?: boolean;
+    /** Skills directory path (default: ~/.skimpyclaw/skills/) */
+    directory?: string;
+    /** Override per-skill enabled state: { skillName: boolean } */
+    entries?: Record<string, boolean>;
+    /** Max approximate tokens for injected skills prompt (default: 4000) */
+    maxPromptTokens?: number;
+}

package/dist/skills-types.js

@@ -0,0 +1,2 @@
+// Skills System Type Definitions
+export {};

package/dist/skills.d.ts

@@ -0,0 +1,32 @@
+import type { SkillFrontmatter, LoadedSkill, SkillConfig } from './skills-types.js';
+import type { ToolConfig } from './types.js';
+/**
+ * Check whether a skill meets its external requirements.
+ * Returns { eligible: true } or { eligible: false, reason: string }.
+ */
+export declare function checkEligibility(skill: SkillFrontmatter, toolConfig?: ToolConfig): {
+    eligible: boolean;
+    reason?: string;
+};
+/**
+ * Scan the skills directory and load all valid skills.
+ * Returns skills sorted by priority (lower first).
+ * Results are cached for 60s to avoid repeated disk I/O and `which` calls.
+ */
+export declare function loadSkills(skillConfig?: SkillConfig, toolConfig?: ToolConfig): LoadedSkill[];
+export declare function clearSkillsCache(): void;
+/**
+ * Filter skills by context (channel, cron job ID, tags).
+ * Skills with no context filters pass through (always active).
+ * Skills with context filters must match at least one criterion.
+ */
+export declare function getSkillsForContext(skills: LoadedSkill[], context?: {
+    channel?: string;
+    cronJobId?: string;
+    tags?: string[];
+}): LoadedSkill[];
+/**
+ * Format eligible, context-filtered skills into a markdown prompt section.
+ * Respects maxPromptTokens budget (approximate).
+ */
+export declare function formatSkillsPrompt(skills: LoadedSkill[], maxTokens?: number): string;

package/dist/skills.js

@@ -0,0 +1,260 @@
+// Skills System: Load, filter, and format skill prompts from ~/.skimpyclaw/skills/
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import matter from 'gray-matter';
+import { TTLCache } from './cache.js';
+const DEFAULT_SKILLS_DIR = join(homedir(), '.skimpyclaw', 'skills');
+const DEFAULT_PRIORITY = 100;
+const DEFAULT_MAX_PROMPT_TOKENS = 4000;
+// Rough chars-per-token estimate for prompt budgeting
+const CHARS_PER_TOKEN = 4;
+/**
+ * Check if a binary exists on PATH.
+ * Returns true if found, false otherwise.
+ */
+function binExists(name) {
+    try {
+        execSync(`which ${name}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check whether a skill meets its external requirements.
+ * Returns { eligible: true } or { eligible: false, reason: string }.
+ */
+export function checkEligibility(skill, toolConfig) {
+    const reqs = skill.requires;
+    if (!reqs)
+        return { eligible: true };
+    // Check binary dependencies
+    if (reqs.bins) {
+        for (const bin of reqs.bins) {
+            if (!binExists(bin)) {
+                return { eligible: false, reason: `Missing binary: ${bin}` };
+            }
+        }
+    }
+    // Check environment variables
+    if (reqs.env) {
+        for (const envVar of reqs.env) {
+            if (!process.env[envVar]) {
+                return { eligible: false, reason: `Missing env var: ${envVar}` };
+            }
+        }
+    }
+    // Check file/directory paths
+    if (reqs.paths) {
+        for (const p of reqs.paths) {
+            if (!existsSync(p)) {
+                return { eligible: false, reason: `Missing path: ${p}` };
+            }
+        }
+    }
+    // Check tool availability against the active ToolConfig
+    if (reqs.tools && reqs.tools.length > 0) {
+        if (!toolConfig?.enabled) {
+            return { eligible: false, reason: `Tools not enabled (needs: ${reqs.tools.join(', ')})` };
+        }
+        const missing = [];
+        for (const tool of reqs.tools) {
+            const t = tool.toLowerCase();
+            if (t === 'browser') {
+                if (!toolConfig.browser?.enabled)
+                    missing.push(tool);
+            }
+            // spawn_subagent and other built-ins are available whenever tools.enabled is true
+        }
+        if (missing.length > 0) {
+            return { eligible: false, reason: `Tools not enabled (needs: ${missing.join(', ')})` };
+        }
+    }
+    return { eligible: true };
+}
+/**
+ * Parse a single SKILL.md file from a skill directory.
+ * Returns a LoadedSkill or null if the file doesn't exist or is malformed.
+ */
+function parseSkillFile(dirPath, dirName, skillConfig, toolConfig) {
+    const skillPath = join(dirPath, 'SKILL.md');
+    if (!existsSync(skillPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(skillPath, 'utf-8');
+        const { data, content } = matter(raw);
+        const frontmatter = {
+            name: data.name || dirName,
+            description: data.description || '',
+            enabled: data.enabled !== false, // default true
+            emoji: data.emoji,
+            tags: data.tags,
+            requires: data.requires,
+            contexts: data.contexts,
+            priority: typeof data.priority === 'number' ? data.priority : DEFAULT_PRIORITY,
+        };
+        // Check config-level override for this skill
+        if (skillConfig?.entries?.[frontmatter.name] === false) {
+            return {
+                name: frontmatter.name,
+                dirPath,
+                frontmatter,
+                body: content.trim(),
+                eligible: false,
+                reason: 'Disabled in config',
+            };
+        }
+        // Check frontmatter-level enabled flag
+        if (frontmatter.enabled === false) {
+            return {
+                name: frontmatter.name,
+                dirPath,
+                frontmatter,
+                body: content.trim(),
+                eligible: false,
+                reason: 'Disabled in frontmatter',
+            };
+        }
+        // Check external requirements
+        const eligibility = checkEligibility(frontmatter, toolConfig);
+        return {
+            name: frontmatter.name,
+            dirPath,
+            frontmatter,
+            body: content.trim(),
+            eligible: eligibility.eligible,
+            reason: eligibility.reason,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[skills] Failed to parse ${skillPath}: ${msg}`);
+        return null;
+    }
+}
+const skillsCache = new TTLCache(60_000);
+/**
+ * Scan the skills directory and load all valid skills.
+ * Returns skills sorted by priority (lower first).
+ * Results are cached for 60s to avoid repeated disk I/O and `which` calls.
+ */
+export function loadSkills(skillConfig, toolConfig) {
+    // Master switch
+    if (skillConfig?.enabled === false) {
+        return [];
+    }
+    const cacheKey = JSON.stringify({
+        dir: skillConfig?.directory,
+        entries: skillConfig?.entries,
+        enabled: skillConfig?.enabled,
+        toolEnabled: toolConfig?.enabled,
+        browserEnabled: toolConfig?.browser?.enabled,
+    });
+    const cached = skillsCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const dir = skillConfig?.directory || DEFAULT_SKILLS_DIR;
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const dirEntries = readdirSync(dir);
+    const skills = [];
+    for (const entry of dirEntries) {
+        const entryPath = join(dir, entry);
+        // Only process directories
+        try {
+            if (!statSync(entryPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const skill = parseSkillFile(entryPath, entry, skillConfig, toolConfig);
+        if (skill) {
+            skills.push(skill);
+        }
+    }
+    // Sort by priority (lower = first), then alphabetically by name
+    skills.sort((a, b) => {
+        const pa = a.frontmatter.priority ?? DEFAULT_PRIORITY;
+        const pb = b.frontmatter.priority ?? DEFAULT_PRIORITY;
+        if (pa !== pb)
+            return pa - pb;
+        return a.name.localeCompare(b.name);
+    });
+    skillsCache.set(cacheKey, skills);
+    return skills;
+}
+export function clearSkillsCache() {
+    skillsCache.clear();
+}
+/**
+ * Filter skills by context (channel, cron job ID, tags).
+ * Skills with no context filters pass through (always active).
+ * Skills with context filters must match at least one criterion.
+ */
+export function getSkillsForContext(skills, context) {
+    return skills.filter(skill => {
+        // Only include eligible skills
+        if (!skill.eligible)
+            return false;
+        const ctx = skill.frontmatter.contexts;
+        // No context filters = always active
+        if (!ctx)
+            return true;
+        const hasFilters = (ctx.channels && ctx.channels.length > 0) ||
+            (ctx.cronJobs && ctx.cronJobs.length > 0) ||
+            (ctx.tags && ctx.tags.length > 0);
+        // No actual filter values = always active
+        if (!hasFilters)
+            return true;
+        // Check channel match
+        if (ctx.channels?.length && context?.channel) {
+            if (ctx.channels.includes(context.channel))
+                return true;
+        }
+        // Check cron job match
+        if (ctx.cronJobs?.length && context?.cronJobId) {
+            if (ctx.cronJobs.includes(context.cronJobId))
+                return true;
+        }
+        // Check tag match (any overlap)
+        if (ctx.tags?.length && context?.tags?.length) {
+            if (ctx.tags.some(t => context.tags.includes(t)))
+                return true;
+        }
+        // Has filters but none matched
+        return false;
+    });
+}
+/**
+ * Format eligible, context-filtered skills into a markdown prompt section.
+ * Respects maxPromptTokens budget (approximate).
+ */
+export function formatSkillsPrompt(skills, maxTokens) {
+    if (skills.length === 0)
+        return '';
+    const budget = (maxTokens ?? DEFAULT_MAX_PROMPT_TOKENS) * CHARS_PER_TOKEN;
+    const sections = [];
+    let totalChars = 0;
+    // Header
+    const header = '## Active Skills\n';
+    totalChars += header.length;
+    for (const skill of skills) {
+        const emoji = skill.frontmatter.emoji ? `${skill.frontmatter.emoji} ` : '';
+        const section = `### ${emoji}${skill.name}\n\n${skill.body}`;
+        if (totalChars + section.length > budget) {
+            console.warn(`[skills] Token budget exceeded, skipping remaining skills (included ${sections.length}/${skills.length})`);
+            break;
+        }
+        sections.push(section);
+        totalChars += section.length;
+    }
+    if (sections.length === 0)
+        return '';
+    return header + sections.join('\n\n---\n\n');
+}

package/dist/subagent.d.ts

@@ -0,0 +1,19 @@
+import type { Config, SubagentType, SubagentTask, ChatMessage } from './types.js';
+/**
+ * Ensure agent directory and templates exist for a subagent type.
+ * Creates the dir + starter IDENTITY.md + TOOLS.md if missing.
+ * Registers the agent in config.agents.list (in-memory only).
+ */
+export declare function ensureAgentSetup(type: SubagentType, config: Config): void;
+export declare function initSubagentSystem(deliverFn: (chatId: number, message: string) => Promise<void>): void;
+export declare function getPresetDescriptions(): string;
+export declare function dispatchSubagent(type: SubagentType, prompt: string, chatId: number, config: Config, modelOverride?: string, history?: ChatMessage[], options?: {
+    label?: string;
+    allowedPaths?: string[];
+    maxRetries?: number;
+}): SubagentTask;
+export declare function cancelTask(id: string): SubagentTask | null;
+export declare function getActiveTasks(): SubagentTask[];
+export declare function getRecentTasks(n?: number): SubagentTask[];
+export declare function getTask(id: string): SubagentTask | null;
+export declare function resetForTesting(): void;