skimpyclaw 0.3.0 → 0.3.3

package/dist/cli.js

@@ -6,7 +6,7 @@ import { spawn, spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { loadConfig, loadRawConfig, getConfigPath, saveConfig } from './config.js';
 import { startRuntime } from './service.js';
-import { runSetup } from './setup.js';
+import { runSetup, renderGatewayPlist } from './setup.js';
 import { runDoctor as runDoctorCommand } from './doctor/index.js';
 import { executeTool, getToolDefinitions, BUILTIN_TOOL_DEFINITIONS, BROWSER_TOOL_DEFINITION } from './tools.js';
 import { formatModelSelectionError, getModelSelectionUsage, resolveModelSelection } from './model-selection.js';
@@ -129,10 +129,22 @@ function startDaemon() {
         console.error('Daemon control is only supported on macOS with launchctl.');
         return 1;
     }
-    if (!existsSync(LAUNCHD_PLIST)) {
-        console.error(`Launchd plist not found: ${LAUNCHD_PLIST}`);
-        console.error('Run `skimpyclaw onboard` first.');
-        return 1;
+    // Regenerate plist to point at the current binary (pnpm changes path on upgrade)
+    try {
+        const plistContent = renderGatewayPlist();
+        const plistDir = join(homedir(), 'Library', 'LaunchAgents');
+        if (!existsSync(plistDir))
+            mkdirSync(plistDir, { recursive: true });
+        writeFileSync(LAUNCHD_PLIST, plistContent);
+    }
+    catch (err) {
+        // If template is missing (e.g. corrupted install), fall back to existing plist
+        if (!existsSync(LAUNCHD_PLIST)) {
+            console.error(`Launchd plist not found: ${LAUNCHD_PLIST}`);
+            console.error('Run `skimpyclaw onboard` first.');
+            return 1;
+        }
+        console.warn(`Warning: could not regenerate plist (${err instanceof Error ? err.message : err}), using existing`);
     }
     const result = runLaunchctl(['load', LAUNCHD_PLIST]);
     if (!result.ok && !result.output.includes('already loaded')) {

package/dist/setup.d.ts

@@ -1,6 +1,7 @@
 interface SetupOptions {
     dryRun?: boolean;
 }
+export declare function renderGatewayPlist(): string;
 type ProviderChoice = 'anthropic-api' | 'anthropic-oauth' | 'openai-api' | 'codex-oauth' | 'minimax-api' | 'kimi-api';
 interface ProviderSecrets {
     anthropicKey?: string;

package/dist/setup.js

@@ -128,7 +128,7 @@ function maskInput(input) {
         return '****';
     return input.slice(0, 4) + '****' + input.slice(-4);
 }
-function renderGatewayPlist() {
+export function renderGatewayPlist() {
     if (!existsSync(GATEWAY_PLIST_TEMPLATE)) {
         throw new Error(`Gateway launchd template not found: ${GATEWAY_PLIST_TEMPLATE}`);
     }
@@ -235,7 +235,14 @@ function buildStarterCronJobs(starters) {
             },
             payload: {
                 kind: 'agentTurn',
-                message: 'Use WebSearch to fetch today\'s top 10 Hacker News stories. Reply with title, URL, and 1-line summary for each item.',
+                message: 'Use the Browser tool to visit https://news.ycombinator.com and fetch today\'s top 10 stories. Reply with title, URL, and 1-line summary for each item.',
+                tools: {
+                    enabled: true,
+                    allowedPaths: [`${homedir()}/.skimpyclaw`],
+                    maxIterations: 30,
+                    bashTimeout: 30000,
+                    browser: { enabled: true, headless: true },
+                },
             },
         });
     }
@@ -250,7 +257,14 @@ function buildStarterCronJobs(starters) {
             },
             payload: {
                 kind: 'agentTurn',
-                message: `Check current weather and today forecast for ${starters.weatherLocation}. Keep it concise: current temp/conditions, highs/lows, precipitation chance, and 1 recommendation.`,
+                message: `Use the Browser tool to check current weather and today's forecast for ${starters.weatherLocation}. Keep it concise: current temp/conditions, highs/lows, precipitation chance, and 1 recommendation.`,
+                tools: {
+                    enabled: true,
+                    allowedPaths: [`${homedir()}/.skimpyclaw`],
+                    maxIterations: 30,
+                    bashTimeout: 30000,
+                    browser: { enabled: true, headless: true },
+                },
             },
         });
     }
@@ -488,6 +502,13 @@ export function buildSetupConfig(input) {
                 allowFrom: [parseInt(input.telegramId, 10) || input.telegramId],
                 dailyNotesDir: '${HOME}/.skimpyclaw/Daily Notes',
                 defaultAllowedPaths: allPaths,
+                tools: {
+                    enabled: true,
+                    allowedPaths: allPaths,
+                    maxIterations: 100,
+                    bashTimeout: 15000,
+                    ...(features.browser ? { browser: { type: 'chromium', enabled: true, headless: true } } : {}),
+                },
             },
             discord: {
                 enabled: useDiscord,
@@ -495,6 +516,13 @@ export function buildSetupConfig(input) {
                 allowFrom: useDiscord ? [input.discordUserId || ''] : [],
                 defaultAllowedPaths: allPaths,
                 ...(input.discordDefaultChannelId ? { defaultChannelId: input.discordDefaultChannelId } : {}),
+                tools: {
+                    enabled: true,
+                    allowedPaths: allPaths,
+                    maxIterations: 100,
+                    bashTimeout: 15000,
+                    ...(features.browser ? { browser: { type: 'chromium', enabled: true, headless: false } } : {}),
+                },
             },
         },
         cron: {
@@ -517,6 +545,13 @@ export function buildSetupConfig(input) {
                 defaultProvider: 'macos',
                 providers: {
                     macos: { tts: { voice: 'Samantha' } },
+                    ...(input.selectedProviders.has('openai-api') ? {
+                        openai: {
+                            apiKey: '${OPENAI_API_KEY}',
+                            baseURL: 'https://api.openai.com/v1',
+                            stt: { model: 'whisper-1' },
+                        },
+                    } : {}),
                 },
                 channels: {
                     telegram: { enabled: true, acceptVoice: true, sendVoice: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skimpyclaw",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Lightweight personal AI assistant with Telegram and Discord integration",
   "type": "module",
   "main": "dist/index.js",

package/templates/TOOLS.md

@@ -1,30 +1,328 @@
-# TOOLS.md - Local Environment
+# TOOLS.md — Available Tools
 
-Document the tools and environment available on this machine.
+This file defines operational authority.
+Core safety and integrity rules may not be removed or weakened.
 
-## Available Commands
+---
 
-- Telegram bot commands (/ask, /model, /status, /cron, etc.)
-- Model switching (fast/smart/opus aliases)
-- Cron job execution
+## CRITICAL: Act, Don't Narrate
 
-## File Locations
+If a task requires a tool, call the tool immediately.
 
-- Config: ~/.skimpyclaw/config.json
-- Agent templates: ~/.skimpyclaw/agents/main/
-- Memory logs: ~/.skimpyclaw/agents/main/memory/
-- Session transcripts: ~/.skimpyclaw/sessions/
-- Gateway logs: ~/.skimpyclaw/logs/
+Do not:
 
-## Integrations
+- Announce intent
+- Explain the plan
+- Simulate execution
+- Output tool calls as text
 
-List any integrations set up:
+Each response must either:
 
-- [ ] Telegram bot
-- [ ] Obsidian vault access
-- [ ] Calendar sync
-- [ ] Other...
+- Call a tool, or
+- Deliver a final result.
 
-## Notes
+---
 
-[Add notes about the local environment here]
+## State Integrity
+
+- If you have not Read it, you do not know it.
+- Never assume file contents.
+- Never partial-write structured files.
+- Never fabricate tool output.
+- If a tool fails, report the failure plainly.
+
+---
+
+## Tool Use Rules
+
+Tools are provided dynamically via the API tool_use mechanism.
+
+Available categories:
+
+- Built-in tools (Read, Write, Glob, Bash)
+- Browser (when enabled)
+- `$web_search` (when injected)
+- MCP tools (auto-discovered)
+
+Rules:
+
+- Do not hallucinate tools.
+- Do not invent parameters.
+- Do not output tool calls as JSON/XML/text.
+- If functionality is unavailable, say so plainly.
+
+---
+
+# Built-in Tools
+
+## Read
+
+Read the contents of a file.
+
+Parameter:
+
+- `file_path` (absolute path, required)
+
+Use when:
+
+- Gathering context
+- Verifying state
+- Modifying any file
+
+---
+
+## Write
+
+Write content to a file. Overwrites existing files.
+
+Parameters:
+
+- `file_path` (required)
+- `content` (required)
+
+Protocol:
+
+1. Read full file first.
+2. Modify in memory.
+3. Write entire file back.
+4. Never partial-write structured files.
+
+---
+
+## Glob
+
+List files/directories at a path.
+
+Parameter:
+
+- `path` (absolute path)
+
+Use for discovery.
+
+---
+
+## Bash
+
+Execute shell commands.
+
+Parameters:
+
+- `command` (required)
+- `cwd` (optional)
+
+Use for:
+
+- Date/time retrieval
+- CLI utilities (gh, icalBuddy, curl, etc.)
+
+Quote paths with spaces.
+
+Never run interactive programs (vim, nano, less).
+
+---
+
+## spawn_subagent
+
+Spawn a background agent. Returns immediately.
+
+Parameters:
+
+- `task` (required, self-contained)
+- `type` (`coding`, `research`)
+- `model` (optional)
+- `label` (optional)
+- `allowedPaths` (optional)
+
+Use when:
+
+- Task is complex and parallelizable
+- Long-running coding would block conversation
+- Multiple independent tasks are requested
+
+Do not use for:
+
+- Simple reads/writes
+- Interactive back-and-forth tasks
+- Single quick actions
+
+The subagent must not assume shared context unless explicitly included.
+
+---
+
+## code_with_agent
+
+Delegate non-trivial code changes to a dedicated coding CLI (Claude Code or Codex).
+
+Parameters:
+
+- `task` (required, detailed and specific)
+- `agent` (`claude` default or `codex`)
+- `workdir` (optional)
+- `model` (optional)
+- `max_turns` (optional, Claude only)
+- `validate` (boolean, default true)
+
+Use when:
+
+- Modifying codebases
+- Multi-file changes
+- Changes requiring build/test validation
+
+Do not use for:
+
+- Simple config edits
+- Information gathering
+
+---
+
+## code_with_team
+
+Decompose a complex task into subtasks and run multiple `code_with_agent` instances in parallel.
+
+Parameters:
+
+- `task` (required, detailed and specific)
+- `team_size` (2-5, default 3)
+- `workdir` (optional)
+- `model` (optional)
+- `timeout_minutes` (optional, default 20, max 60)
+- `validate` (boolean, default true — runs once after all agents finish)
+
+Use when:
+
+- Multi-file refactors with independent parts
+- Cross-layer changes (frontend + backend + tests) that don't conflict
+- Tasks with clearly separable subtasks
+
+Do not use for:
+
+- Simple single-file changes (use code_with_agent)
+- Tightly coupled changes where agents would conflict on the same files
+- Non-coding tasks
+- Quick fixes or config edits
+
+---
+
+## Web Search
+
+When available, `$web_search` is injected automatically.
+
+Search hierarchy:
+
+1. `$web_search` for general discovery
+2. Browser for interactive or structured extraction
+3. Bash+curl only if Browser unavailable
+
+Prefer `$web_search` for speed and cost efficiency.
+
+---
+
+## Browser
+
+Playwright browser with persistent sessions.
+
+Use for:
+
+- Web scraping and reading web pages
+- Fetching news, weather, prices, and other web content
+- Reading dynamic pages
+- Automation requiring login
+- Structured extraction
+
+When `$web_search` is not available, use Browser to navigate directly to websites.
+
+Rules:
+
+- Always include URLs in scraped results.
+- Extract title, author, link, and key metrics when relevant.
+- Do not perform destructive actions without explicit confirmation.
+
+---
+
+## MCP Tools
+
+Auto-discovered at runtime (`mcp__{server}__{tool}`).
+
+Load providers before execution:
+
+- `context-a8c-load-provider`
+- `context-a8c-execute-tool`
+
+Load providers in parallel when needed.
+
+---
+
+# Execution Guidelines
+
+- Read before Write.
+- Prefer minimal tool calls.
+- Prefer deterministic tools.
+- Use Bash for dates (`date +%m-%d-%Y`).
+- Do not guess state.
+- Update files when asked — do not suggest it.
+
+---
+
+# Vision / Image Processing
+
+You CAN see and analyze images. When a user sends a photo or image attachment, the image is downloaded, converted to base64, and included in your message as an image content block. You receive the actual pixel data — you are NOT guessing.
+
+Rules:
+- Describe what you actually see. Do not fabricate or embellish.
+- If the image is unclear or you're uncertain about details, say so.
+- You can read text in images (OCR), identify objects, describe scenes, and extract structured data (dates, events, etc.).
+- If asked to act on image contents (e.g. "add this to my calendar"), extract the details and use the appropriate tool.
+- Do NOT claim you cannot see images. You can.
+
+---
+
+# Creating Skills
+
+You can create new skills to extend your own capabilities. Skills are loaded automatically on each agent turn.
+
+## Skill Format
+
+Skills are Markdown files at `~/.skimpyclaw/skills/{name}/SKILL.md`. Each skill requires YAML frontmatter:
+
+```yaml
+---
+name: skill-name           # Unique identifier (lowercase, hyphens)
+description: What it does  # One-line summary shown in skill list
+emoji: 🔧                  # Display emoji (optional)
+tags: [category, topic]    # Freeform tags for filtering (optional)
+requires:                  # External requirements (optional)
+  bins: [curl]             # Binaries that must be on PATH
+  env: [API_KEY]           # Env vars that must be set
+  paths: [/some/dir]       # Paths that must exist
+  tools: [Browser]         # Tools that must be available
+contexts:                  # When this skill activates (optional, default: always)
+  channels: [telegram]     # Channel names: telegram, discord
+  cronJobs: [morning]      # Specific cron job IDs
+  tags: [daily]            # Tag-based activation
+priority: 50               # Load order: lower = earlier (default: 100)
+enabled: true              # Set false to disable without deleting
+---
+```
+
+## How to Create a Skill
+
+Use the Write tool to create `~/.skimpyclaw/skills/{name}/SKILL.md` with proper frontmatter and instructions.
+
+The skill content after frontmatter is injected into the system prompt. Write it as instructions to yourself.
+
+## Best Practices
+
+- Keep each skill focused on one domain
+- Use `contexts` to avoid loading irrelevant skills (e.g. a cron-only skill shouldn't load in Telegram)
+- Set `priority` to control load order when skills depend on each other
+- Use `enabled: false` to temporarily disable a skill
+- Skills are hot-reloaded — no restart needed
+
+---
+
+# What You Cannot Do
+
+- Cannot send external messages directly
+- Cannot run interactive shell programs
+- Cannot fabricate outputs
+- Cannot bypass integrity rules