skimpyclaw 0.1.0

package/dist/subagent.js

@@ -0,0 +1,376 @@
+// Subagent system: background task dispatch with concurrency control
+import { homedir } from 'os';
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, appendFileSync } from 'fs';
+import { runAgentTurn } from './agent.js';
+import { getCurrentModel } from './gateway.js';
+import { getAgentDir } from './config.js';
+import { releaseAllLocks } from './file-lock.js';
+import { resolveModel } from './providers/utils.js';
+const DEFAULT_MAX_CONCURRENT = 5;
+const DEFAULT_MAX_RETRIES = 2;
+const REGISTRY_PATH = join(homedir(), '.skimpyclaw', 'logs', 'subagent-runs.jsonl');
+const PRESETS = {
+    coding: {
+        agentId: 'coding',
+        defaultModel: 'claude-opus',
+        toolConfig: {
+            enabled: true,
+            allowedPaths: [join(homedir(), '.skimpyclaw')],
+            maxIterations: 50,
+            bashTimeout: 30000
+        },
+        description: 'Code tasks with broad file + bash access'
+    },
+    research: {
+        agentId: 'research',
+        defaultModel: 'claude-think',
+        toolConfig: {
+            enabled: true,
+            allowedPaths: [join(homedir(), '.skimpyclaw')],
+            maxIterations: 30,
+            bashTimeout: 15000
+        },
+        description: 'Research tasks with configurable file access'
+    },
+};
+// --- Starter Templates ---
+const STARTER_TEMPLATES = {
+    coding: {
+        identity: `# IDENTITY.md - Coding Subagent
+
+Name: Coding Agent
+Emoji: 🔧
+
+You are a coding subagent dispatched for a specific task. You have file and bash access
+within your allowed paths (provided at runtime).
+
+## Your Role
+- Execute coding tasks: write code, fix bugs, refactor, run commands
+- Act on instructions directly — don't narrate what you're going to do
+- Return concise results when done
+
+## Your Limitations
+- You are short-lived: complete the task and return the result
+- You have ONLY 4 tools: Read, Write, Glob, Bash
+- Do NOT invent or hallucinate tools that don't exist
+`,
+        tools: `# TOOLS.md - Coding Subagent Tools
+
+## CRITICAL: Act, Don't Narrate
+
+**NEVER say "let me write the code" or "now I'll update the file" — just call the tool.**
+You have a LIMITED number of tool iterations. Every message you spend talking about what
+you're going to do is one less chance to actually do it.
+
+## Your 4 Tools
+
+### Read
+Read the contents of a file. Parameter: \`file_path\` (string, required)
+
+### Write
+Write content to a file. Parameters: \`file_path\` (string, required), \`content\` (string, required)
+
+### Glob
+List files and directories at a path. Parameter: \`path\` (string, required)
+
+### Bash
+Execute a shell command. Parameters: \`command\` (string, required), \`cwd\` (string, optional)
+
+## Key Paths
+- Config: ~/.skimpyclaw/config.json
+- Agent templates: ~/.skimpyclaw/agents/
+`
+    },
+    research: {
+        identity: `# IDENTITY.md - Research Subagent
+
+Name: Research Agent
+Emoji: 🔍
+
+You are a research subagent dispatched for a specific task.
+
+## Your Role
+- Research questions using vault notes and files
+- Summarize findings concisely
+- Act on instructions directly — don't narrate what you're going to do
+
+## Your Limitations
+- You are short-lived: complete the task and return the result
+- You have ONLY 4 tools: Read, Write, Glob, Bash
+- Do NOT invent or hallucinate tools that don't exist
+`,
+        tools: `# TOOLS.md - Research Subagent Tools
+
+## CRITICAL: Act, Don't Narrate
+
+**NEVER say "let me check" or "I'll look into that" — just call the tool.**
+
+## Your 4 Tools
+
+### Read
+Read the contents of a file. Parameter: \`file_path\` (string, required)
+
+### Write
+Write content to a file. Parameters: \`file_path\` (string, required), \`content\` (string, required)
+
+### Glob
+List files and directories at a path. Parameter: \`path\` (string, required)
+
+### Bash
+Execute a shell command. Parameters: \`command\` (string, required), \`cwd\` (string, optional)
+
+## Key Paths
+- Config: ~/.skimpyclaw/config.json
+- Agent templates: ~/.skimpyclaw/agents/
+- Add your notes/vault paths to allowedPaths in config before using them
+`
+    },
+};
+// Agent identity metadata for in-memory registration
+const AGENT_IDENTITIES = {
+    coding: { name: 'Coding Agent', emoji: '🔧' },
+    research: { name: 'Research Agent', emoji: '🔍' }
+};
+/**
+ * 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 function ensureAgentSetup(type, config) {
+    const preset = PRESETS[type];
+    const agentDir = getAgentDir(preset.agentId);
+    // Create dir + starter templates if missing
+    if (!existsSync(agentDir)) {
+        mkdirSync(agentDir, { recursive: true });
+        const templates = STARTER_TEMPLATES[type];
+        writeFileSync(join(agentDir, 'IDENTITY.md'), templates.identity, 'utf-8');
+        writeFileSync(join(agentDir, 'TOOLS.md'), templates.tools, 'utf-8');
+        console.log(`[subagent] Created agent dir with templates: ${agentDir}`);
+    }
+    // Register in config.agents.list if not already there (in-memory only)
+    if (!config.agents.list[preset.agentId]) {
+        const identity = AGENT_IDENTITIES[type];
+        config.agents.list[preset.agentId] = {
+            identity,
+            model: resolveModel(preset.defaultModel || 'anthropic/claude-sonnet-4-5', config),
+            thinking: 'medium'
+        };
+        console.log(`[subagent] Registered agent in config: ${preset.agentId}`);
+    }
+}
+// Task tracking
+let taskCounter = 0;
+const tasks = new Map();
+let deliverMessage = null;
+export function initSubagentSystem(deliverFn) {
+    deliverMessage = deliverFn;
+    console.log('[subagent] System initialized');
+}
+export function getPresetDescriptions() {
+    return Object.entries(PRESETS)
+        .map(([type, preset]) => `  ${type} — ${preset.description} (default: ${preset.defaultModel || 'current model'})`)
+        .join('\n');
+}
+// --- Disk Registry ---
+function ensureRegistryDir() {
+    const dir = join(homedir(), '.skimpyclaw', 'logs');
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function appendRegistryEvent(event) {
+    try {
+        ensureRegistryDir();
+        const line = JSON.stringify({ ...event, timestamp: new Date().toISOString() }) + '\n';
+        appendFileSync(REGISTRY_PATH, line, 'utf-8');
+    }
+    catch (err) {
+        console.warn('[subagent] Failed to write registry event:', err instanceof Error ? err.message : err);
+    }
+}
+// --- Dispatch ---
+export function dispatchSubagent(type, prompt, chatId, config, modelOverride, history, options) {
+    const maxConcurrent = config.subagents?.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    const active = [...tasks.values()].filter((t) => t.status === 'running' || t.status === 'pending');
+    if (active.length >= maxConcurrent) {
+        throw new Error(`Max concurrent agents reached (${maxConcurrent}). Use /tasks to see running agents or /cancel to stop one.`);
+    }
+    const preset = PRESETS[type];
+    if (!preset) {
+        throw new Error(`Unknown agent type: ${type}. Use: ${Object.keys(PRESETS).join(', ')}`);
+    }
+    taskCounter++;
+    const id = `t${taskCounter}`;
+    const model = resolveModel(modelOverride || preset.defaultModel || getCurrentModel(), config);
+    const maxRetries = options?.maxRetries ?? config.subagents?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const task = {
+        id,
+        type,
+        prompt,
+        status: 'pending',
+        chatId,
+        model,
+        label: options?.label,
+        createdAt: new Date(),
+        retryCount: 0,
+        maxRetries,
+        abortController: new AbortController()
+    };
+    tasks.set(id, task);
+    // Log to disk registry
+    appendRegistryEvent({
+        type: 'task_created',
+        taskId: id,
+        agentType: type,
+        model,
+        label: options?.label,
+        prompt: prompt.slice(0, 500),
+    });
+    // Build tool config with merged paths
+    const toolConfig = {
+        ...preset.toolConfig,
+        allowedPaths: [
+            ...preset.toolConfig.allowedPaths,
+            ...(options?.allowedPaths || []),
+        ],
+    };
+    // Fire and forget — don't await
+    executeTask(task, config, toolConfig, history).catch((err) => {
+        console.error(`[subagent] Unhandled error in task ${id}:`, err);
+    });
+    return task;
+}
+async function executeTask(task, config, toolConfig, history) {
+    task.status = 'running';
+    task.startedAt = new Date();
+    const label = task.label ? ` "${task.label}"` : '';
+    console.log(`[subagent] Starting ${task.id}${label} (${task.type}, model: ${task.model})`);
+    try {
+        // Check cancellation before starting
+        if (task.abortController.signal.aborted) {
+            task.status = 'cancelled';
+            task.completedAt = new Date();
+            appendRegistryEvent({ type: 'task_cancelled', taskId: task.id });
+            return;
+        }
+        // Ensure agent dir + templates exist, register in config
+        ensureAgentSetup(task.type, config);
+        const response = await runAgentTurn(task.type, // agentId = preset.agentId = type name
+        task.prompt, config, task.model, toolConfig, history, {
+            channel: 'subagent',
+            sessionId: task.id,
+            metadata: {
+                type: task.type,
+                chatId: task.chatId,
+                label: task.label,
+            },
+            abortSignal: task.abortController.signal,
+        });
+        // Check cancellation after completion
+        if (task.abortController.signal.aborted) {
+            task.status = 'cancelled';
+            task.completedAt = new Date();
+            releaseAllLocks(task.id);
+            appendRegistryEvent({ type: 'task_cancelled', taskId: task.id });
+            return;
+        }
+        task.status = 'completed';
+        task.result = response;
+        task.completedAt = new Date();
+        // Release any file locks held by this task
+        releaseAllLocks(task.id);
+        const elapsed = Math.round((task.completedAt.getTime() - task.startedAt.getTime()) / 1000);
+        console.log(`[subagent] Completed ${task.id}${label} in ${elapsed}s`);
+        appendRegistryEvent({
+            type: 'task_completed',
+            taskId: task.id,
+            elapsed,
+            resultLength: response.length,
+        });
+        // Deliver result
+        if (deliverMessage) {
+            const labelStr = task.label ? ` (${task.label})` : '';
+            const header = `✅ Agent ${task.id}${labelStr} completed in ${elapsed}s:`;
+            await deliverMessage(task.chatId, `${header}\n\n${response}`);
+        }
+    }
+    catch (error) {
+        // Release any file locks on error
+        releaseAllLocks(task.id);
+        const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+        const retryCount = task.retryCount ?? 0;
+        const maxRetries = task.maxRetries ?? DEFAULT_MAX_RETRIES;
+        // Retry if under limit and not cancelled
+        if (retryCount < maxRetries && !task.abortController.signal.aborted) {
+            task.retryCount = retryCount + 1;
+            const elapsed = Math.round((Date.now() - (task.startedAt?.getTime() || task.createdAt.getTime())) / 1000);
+            console.log(`[subagent] Task ${task.id} failed after ${elapsed}s (attempt ${retryCount + 1}/${maxRetries + 1}), retrying: ${errorMsg}`);
+            appendRegistryEvent({
+                type: 'task_retry',
+                taskId: task.id,
+                attempt: task.retryCount,
+                error: errorMsg,
+            });
+            if (deliverMessage) {
+                await deliverMessage(task.chatId, `⚠️ Agent ${task.id} failed (attempt ${retryCount + 1}/${maxRetries + 1}), retrying...\n\nError: ${errorMsg}`);
+            }
+            // Modify prompt to include error context for retry (compressed to save tokens)
+            const taskSummary = task.prompt.length > 500 ? task.prompt.slice(0, 500) + '...' : task.prompt;
+            const retryPrompt = `Retry task (attempt ${(task.retryCount ?? 0) + 1}).\n\nTask: ${taskSummary}\n\nPrevious error: ${errorMsg}\n\nTry a different approach.`;
+            task.prompt = retryPrompt;
+            task.startedAt = new Date();
+            // Retry
+            return executeTask(task, config, {
+                ...PRESETS[task.type].toolConfig,
+            }, history);
+        }
+        task.status = 'failed';
+        task.error = errorMsg;
+        task.completedAt = new Date();
+        const elapsed = Math.round((task.completedAt.getTime() -
+            (task.startedAt?.getTime() || task.createdAt.getTime())) /
+            1000);
+        console.error(`[subagent] Failed ${task.id} after ${elapsed}s (all retries exhausted):`, task.error);
+        appendRegistryEvent({
+            type: 'task_failed',
+            taskId: task.id,
+            elapsed,
+            error: task.error,
+        });
+        if (deliverMessage) {
+            await deliverMessage(task.chatId, `❌ Agent ${task.id} (${task.type}) failed after ${elapsed}s:\n\n${task.error}`);
+        }
+    }
+}
+export function cancelTask(id) {
+    const task = tasks.get(id);
+    if (!task)
+        return null;
+    if (task.status !== 'pending' && task.status !== 'running')
+        return task;
+    task.abortController.abort();
+    task.status = 'cancelled';
+    task.completedAt = new Date();
+    releaseAllLocks(task.id);
+    appendRegistryEvent({ type: 'task_cancelled', taskId: task.id });
+    console.log(`[subagent] Cancelled ${task.id}`);
+    return task;
+}
+export function getActiveTasks() {
+    return [...tasks.values()].filter((t) => t.status === 'pending' || t.status === 'running');
+}
+export function getRecentTasks(n = 10) {
+    return [...tasks.values()]
+        .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
+        .slice(0, n);
+}
+export function getTask(id) {
+    return tasks.get(id) || null;
+}
+// For testing
+export function resetForTesting() {
+    taskCounter = 0;
+    tasks.clear();
+    deliverMessage = null;
+}

package/dist/telegram.d.ts

@@ -0,0 +1,2 @@
+export { initTelegram, startTelegram, stopTelegram, getBot, setSilenceUntil, getSilenceUntil, isSilenced, sendProactiveMessage, sendProactiveVoice, getHistory, addToHistory, clearHistory, getRunContext, getDefaultTelegramToolConfig, buildHelpText, getTelegramDefaultChatId, startTypingIndicator, sendLongMessage, sendLongMessageHtml, escapeHtml, markdownToTelegramHtml, state, BOT_COMMANDS, LAUNCHD_LABEL, commandHandlers, subscribeToApprovalEvents, } from './channels/telegram/index.js';
+export type { MemoryFileInfo, TelegramContext } from './channels/telegram/types.js';

package/dist/telegram.js

@@ -0,0 +1,11 @@
+// Telegram bot - Re-export from new location for backward compatibility
+// @deprecated Import from './channels/telegram/index.js' instead
+export { 
+// Core functions
+initTelegram, startTelegram, stopTelegram, getBot, setSilenceUntil, getSilenceUntil, isSilenced, sendProactiveMessage, sendProactiveVoice, 
+// Utilities
+getHistory, addToHistory, clearHistory, getRunContext, getDefaultTelegramToolConfig, buildHelpText, getTelegramDefaultChatId, startTypingIndicator, sendLongMessage, sendLongMessageHtml, escapeHtml, markdownToTelegramHtml, 
+// Constants
+state, BOT_COMMANDS, LAUNCHD_LABEL, 
+// Handlers
+commandHandlers, subscribeToApprovalEvents, } from './channels/telegram/index.js';

package/dist/tools/bash-tool.d.ts

@@ -0,0 +1,3 @@
+import type { ToolConfig } from '../types.js';
+import type { ExecuteToolContext } from './execute-context.js';
+export declare function executeBash(command: string, cwd: string | undefined, config: ToolConfig, context?: ExecuteToolContext): Promise<string>;

package/dist/tools/bash-tool.js

@@ -0,0 +1,59 @@
+import { exec } from 'child_process';
+import { isBashCommandSafe } from '../security.js';
+import { classifyCommandRisk, requiresApproval, createApprovalRequest, waitForApproval, } from '../exec-approval.js';
+import { isPathAllowed } from './path-utils.js';
+export async function executeBash(command, cwd, config, context) {
+    // Hard block: existing safety filter (always enforced)
+    if (!isBashCommandSafe(command)) {
+        return Promise.resolve('Error: Command blocked by safety filter.');
+    }
+    if (cwd && !isPathAllowed(cwd, config.allowedPaths)) {
+        return Promise.resolve('Error: Working directory not in allowed paths.');
+    }
+    // Exec approval gate: classify risk and check if approval is needed
+    const approvalConfig = config.execApproval;
+    if (approvalConfig?.enabled !== false) {
+        const classification = classifyCommandRisk(command);
+        if (requiresApproval(classification, approvalConfig)) {
+            // Build channel metadata from context for notification routing
+            const channelMeta = context?.channel
+                ? {
+                    channel: context.channel,
+                    chatId: context.channelTargetId ?? context.chatId,
+                    userId: context.approverUserId,
+                    username: context.approverUsername,
+                }
+                : context?.chatId
+                    ? {
+                        channel: 'telegram',
+                        chatId: context.chatId,
+                    }
+                    : undefined;
+            // Create a pending approval request and wait for resolution
+            const ttlMs = approvalConfig?.ttlMs ?? 5 * 60 * 1000;
+            const request = createApprovalRequest(command, cwd, classification, approvalConfig, channelMeta);
+            const resolved = await waitForApproval(request.id, ttlMs);
+            if (resolved.status !== 'approved') {
+                return `⛔ Command not executed — approval ${resolved.status} (tier ${classification.tier}: ${classification.reason}).`;
+            }
+            // Approved — fall through to execution below
+        }
+    }
+    const timeout = config.bashTimeout || 30_000;
+    return new Promise((res) => {
+        exec(command, {
+            cwd: cwd || undefined,
+            timeout,
+            env: { ...process.env },
+            maxBuffer: 5 * 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                const parts = [stdout, stderr, `Exit code: ${error.code ?? 'unknown'}`].filter(Boolean);
+                res(parts.join('\n').slice(0, 50_000));
+                return;
+            }
+            const output = [stdout, stderr].filter(Boolean).join('\n');
+            res(output.slice(0, 50_000) || '(no output)');
+        });
+    });
+}

package/dist/tools/browser-tool.d.ts

@@ -0,0 +1,3 @@
+import type { ToolConfig } from '../types.js';
+export declare function executeBrowser(input: Record<string, any>, config: ToolConfig): Promise<string>;
+export declare function cleanupBrowser(): Promise<void>;