skimpyclaw 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# SkimpyClaw 👙🦞
+
+Lightweight personal AI assistant (~20k LOC). Runs locally. Telegram/Discord chat, scheduled routines, a web dashboard, and a tool-enabled agent — all in one tiny service.
+
+## Why SkimpyClaw vs OpenClaw
+
+Both are personal AI assistants you run yourself. The difference is scope.
+
+|                     | SkimpyClaw (~20k LOC)                   | OpenClaw (~700k LOC)                                     |
+| ------------------- | --------------------------------------- | -------------------------------------------------------- |
+| **Channels**        | Telegram, Discord                       | WhatsApp, Signal, iMessage, Slack, Teams, Matrix, + more |
+| **Setup**           | `skimpyclaw onboard` → done             | Daemon + wizard + per-channel pairing                    |
+| **Codebase**        | Read it in an afternoon                 | Full platform with extensions, packages, native UI       |
+| **Model support**   | Anthropic, OpenAI, Kimi, MiniMax, Codex | Same + more                                              |
+| **Release cadence** | Move fast, no stability guarantees      | Stable / beta / dev channels                             |
+
+Use SkimpyClaw if you live in Telegram or Discord, want to read and own every line, and don't need 13 channels. Use OpenClaw if you need to support multiple channels like WhatsApp, Signal, iMessage, or Slack — or want a more polished, maintained platform.
+
+## Features
+
+- **Chat interface** — Telegram and Discord bots with persistent conversation history
+- **Tool-enabled agent** — file read/write, bash, browser (Playwright), MCP tools via mcporter
+- **Multi-modal support** — voice messages (STT/TTS), image analysis
+- **Subagents** — model autonomously spawns coding/research subagents with retry + concurrency control
+- **Code agents** — delegate coding tasks to Claude Code, Codex, or Kimi CLI with `code_with_agent` and `code_with_team`
+- **Cron scheduler** — run agent prompts or shell scripts on a schedule
+- **Web dashboard** — Preact/Vite SPA with status, cron, audit log, memory, templates, config editor, skills, approvals
+- **Heartbeat** — periodic keep-alive with Telegram/Discord alerts
+- **Skills** — domain-specific capabilities loaded from `~/.skimpyclaw/skills/`
+- **Exec approval** — human-in-the-loop approval for sensitive bash commands (tier 2-3 risks)
+- **Voice** — optional TTS/STT support (ElevenLabs, OpenAI, macOS `say`, local Whisper)
+- **Observability** — optional Langfuse tracing per agent turn
+- **Audit logging** — JSONL-based audit traces for all agent interactions
+- **Multiple model providers** — Anthropic, OpenAI, Kimi, MiniMax, Codex (ChatGPT backend), any OpenAI-compatible API
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph Channels
+    user["Telegram / Discord"]
+    browser["Browser"]
+  end
+
+  subgraph Gateway["Fastify :18790"]
+    dash["Dashboard"]
+    api["REST API"]
+  end
+
+  subgraph Core
+    agent["Agent Runtime"]
+    subagents["Subagent Pool"]
+    cron["Cron"]
+    hb["Heartbeat"]
+    audit["Audit Log"]
+    skills["Skills System"]
+    approvals["Exec Approval"]
+  end
+
+  user --> agent
+  browser --> dash --> api --> agent
+  cron --> agent
+  hb --> agent
+  agent --> subagents
+  agent --> audit
+  agent --> skills
+  agent --> approvals
+  agent --> models["Anthropic / OpenAI / Codex"]
+  agent --> mcp["MCP Servers"]
+  agent --> fs["~/.skimpyclaw"]
+```
+
+See [docs/architecture.md](docs/architecture.md) for runtime flow and startup sequence diagrams.
+
+## Quick Start
+
+**Install:**
+
+```bash
+npm install -g skimpyclaw
+```
+
+**Run onboarding:**
+
+```bash
+skimpyclaw onboard
+```
+
+Onboarding validates your Telegram token, provider auth, and creates:
+
+- `~/.skimpyclaw/config.json`
+- `~/.skimpyclaw/agents/main/*.md` (from templates)
+
+**Start:**
+
+```bash
+skimpyclaw start
+```
+
+**Verify:**
+
+```bash
+curl http://127.0.0.1:18790/health
+```
+
+**Open dashboard:**
+
+```
+http://127.0.0.1:18790/dashboard
+```
+
+Bearer token is shown in startup logs.
+
+## Tech Stack
+
+- **Backend:** TypeScript (ESM), Fastify, Vitest
+- **Frontend:** Preact, Vite, TypeScript
+- **Chat:** grammy (Telegram), discord.js (Discord)
+- **Scheduling:** Croner
+- **Browser:** Playwright
+- **AI SDKs:** Anthropic SDK, OpenAI SDK
+- **Observability:** Langfuse (optional)
+
+## Project Structure
+
+```
+src/
+  index.ts              # App entrypoint with logging setup
+  gateway.ts            # Fastify server + top-level routes
+  agent.ts              # Prompt assembly, model routing, tool loop, memory writes
+  tools.ts              # Tool registry + dispatch
+  tools/                # Tool executors (bash, browser, file tools, path utils, execute context)
+  providers/            # Provider routing + provider implementations (anthropic/openai/codex)
+  code-agents/          # Background coding-agent runtime (executor/parser/orchestrator/registry)
+  channels/             # Channel adapters/utilities (telegram/discord)
+  subagent.ts           # Background task dispatch: retry, concurrency, disk registry
+  file-lock.ts          # In-memory file lock for concurrent subagent writes
+  audit.ts              # Append-only audit log (trace/event model, JSONL storage)
+  cron.ts               # Job scheduling + execution + cron logging
+  heartbeat.ts          # Periodic health/attention checks
+  channels.ts           # Active channel selection + proactive routing
+  telegram.ts           # Telegram bot commands and message handling
+  discord.ts            # Discord bot commands and message handling
+  voice.ts              # Voice input/output (TTS/STT via providers)
+  digests.ts            # Daily digest generation for cron job outputs
+  skills.ts             # Skill loading, eligibility checks, and prompt injection
+  skills-types.ts       # TypeScript types for skills system
+  exec-approval.ts      # Human-in-the-loop exec approval flow with risk tiers
+  api.ts                # Dashboard REST API under /api/dashboard/*
+  dashboard-frontend.ts # Dashboard static asset serving
+  security.ts           # Auth, path validation, bash command blocklist, rate limiting
+  config.ts             # Config loading and validation
+  types.ts              # All TypeScript interfaces and types
+  setup.ts              # Interactive setup wizard
+  langfuse.ts           # Observability integration with cost tracking
+  usage.ts              # Token usage tracking and aggregation
+  service.ts            # Runtime service management
+  cli.ts                # CLI command definitions
+  cache.ts              # TTL cache utility
+  sessions.ts           # Session persistence for chat history
+  doctor/               # Health check system
+    index.ts
+    checks.ts
+    formatters.ts
+    runner.ts
+    types.ts
+
+web/dashboard/          # Preact/Vite dashboard frontend
+  src/
+    App.tsx
+    api/client.ts
+    components/
+    pages/              # Overview, Cron, Audit, Memory, Config, Skills, etc.
+
+templates/              # Default template markdown files
+  SOUL.md
+  IDENTITY.md
+  USER.md
+  TOOLS.md
+  BOOT.md
+  HEARTBEAT.md
+  MEMORY.md
+  AGENTS.md
+  BOOTSTRAP.md
+
+dist/                   # Compiled output + built dashboard assets
+```
+
+## Documentation
+
+| Doc                                            | Contents                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------- |
+| [docs/architecture.md](docs/architecture.md)   | Component diagram, runtime flow, startup sequence, source layout |
+| [docs/configuration.md](docs/configuration.md) | Full config reference, all sections with examples                |
+| [docs/tools.md](docs/tools.md)                 | Built-in tools, browser tool, MCP integration, code agents       |
+| [docs/subagents.md](docs/subagents.md)         | Subagent types, concurrency, file locking, flow diagram          |
+| [docs/dashboard.md](docs/dashboard.md)         | Web dashboard, all HTTP endpoints + API routes                   |
+| [docs/coding-agents.md](docs/coding-agents.md) | Coding-agent execution model and CLI backends                    |
+| [docs/cli.md](docs/cli.md)                     | CLI commands, service management                                 |
+| [docs/chat-commands.md](docs/chat-commands.md) | Telegram/Discord bot commands                                    |
+| [docs/skills.md](docs/skills.md)               | Skills system, built-in skills, creating custom skills           |
+| [docs/data-storage.md](docs/data-storage.md)   | File layout, audit log format, security notes                    |
+| [docs/setup-guide.md](docs/setup-guide.md)     | Step-by-step installation and setup guide                        |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Common issues and solutions                                  |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode (hot reload)
+pnpm dev
+
+# Build TypeScript and dashboard
+pnpm build
+
+# Run tests
+pnpm test
+
+# Run full CI gate
+pnpm ci
+
+# Run doctor checks
+pnpm run doctor
+```
+
+## License
+
+MIT

package/dist/__tests__/agent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/agent.test.js

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { toOpenAITools, buildSystemParam, addToolCacheBreakpoint, setUsingOAuth } from '../agent.js';
+describe('toOpenAITools', () => {
+    it('converts Anthropic tool format to OpenAI function format', () => {
+        const anthropicTools = [
+            {
+                name: 'Read',
+                description: 'Read a file',
+                input_schema: {
+                    type: 'object',
+                    properties: {
+                        file_path: { type: 'string', description: 'Path to file' },
+                    },
+                    required: ['file_path'],
+                },
+            },
+        ];
+        const result = toOpenAITools(anthropicTools);
+        expect(result).toHaveLength(1);
+        expect(result[0]).toEqual({
+            type: 'function',
+            function: {
+                name: 'Read',
+                description: 'Read a file',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        file_path: { type: 'string', description: 'Path to file' },
+                    },
+                    required: ['file_path'],
+                },
+            },
+        });
+    });
+    it('converts multiple tools', () => {
+        const tools = [
+            { name: 'Read', description: 'Read', input_schema: { type: 'object', properties: {} } },
+            { name: 'Write', description: 'Write', input_schema: { type: 'object', properties: {} } },
+            { name: 'Bash', description: 'Bash', input_schema: { type: 'object', properties: {} } },
+        ];
+        const result = toOpenAITools(tools);
+        expect(result).toHaveLength(3);
+        expect(result.every((t) => t.type === 'function')).toBe(true);
+        expect(result.map((t) => t.function.name)).toEqual(['Read', 'Write', 'Bash']);
+    });
+    it('preserves input_schema as parameters unchanged', () => {
+        const schema = {
+            type: 'object',
+            properties: {
+                command: { type: 'string' },
+                cwd: { type: 'string' },
+            },
+            required: ['command'],
+        };
+        const result = toOpenAITools([{ name: 'Bash', description: 'Run command', input_schema: schema }]);
+        expect(result[0].function.parameters).toBe(schema); // same reference, not deep-copied
+    });
+    it('handles empty array', () => {
+        expect(toOpenAITools([])).toEqual([]);
+    });
+});
+describe('buildSystemParam', () => {
+    beforeEach(() => {
+        setUsingOAuth(false);
+    });
+    it('returns undefined for empty content', () => {
+        expect(buildSystemParam(undefined)).toBeUndefined();
+        expect(buildSystemParam(undefined, true)).toBeUndefined();
+    });
+    it('returns plain string when caching disabled and not OAuth', () => {
+        const result = buildSystemParam('Hello system');
+        expect(result).toBe('Hello system');
+    });
+    it('returns plain string when caching explicitly disabled', () => {
+        const result = buildSystemParam('Hello system', false);
+        expect(result).toBe('Hello system');
+    });
+    it('returns array with cache_control when caching enabled (API key mode)', () => {
+        const result = buildSystemParam('Hello system', true);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(1);
+        expect(result[0]).toEqual({
+            type: 'text',
+            text: 'Hello system',
+            cache_control: { type: 'ephemeral' },
+        });
+    });
+    it('returns 3-block array with cache_control on last block (OAuth mode)', () => {
+        setUsingOAuth(true);
+        const result = buildSystemParam('My prompt', true);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(3);
+        // First two blocks: no cache_control
+        expect(result[0].cache_control).toBeUndefined();
+        expect(result[1].cache_control).toBeUndefined();
+        // Last block: has cache_control
+        expect(result[2].cache_control).toEqual({ type: 'ephemeral' });
+        expect(result[2].text).toBe('My prompt');
+    });
+    it('returns 3-block array without cache_control when caching disabled (OAuth mode)', () => {
+        setUsingOAuth(true);
+        const result = buildSystemParam('My prompt', false);
+        expect(Array.isArray(result)).toBe(true);
+        expect(result).toHaveLength(3);
+        expect(result[0].cache_control).toBeUndefined();
+        expect(result[1].cache_control).toBeUndefined();
+        expect(result[2].cache_control).toBeUndefined();
+    });
+});
+describe('addToolCacheBreakpoint', () => {
+    it('adds cache_control to the last tool definition', () => {
+        const tools = [
+            { name: 'Read', description: 'Read' },
+            { name: 'Write', description: 'Write' },
+            { name: 'Bash', description: 'Bash' },
+        ];
+        addToolCacheBreakpoint(tools);
+        expect(tools[0].cache_control).toBeUndefined();
+        expect(tools[1].cache_control).toBeUndefined();
+        expect(tools[2].cache_control).toEqual({ type: 'ephemeral' });
+    });
+    it('handles single tool', () => {
+        const tools = [{ name: 'Read', description: 'Read' }];
+        addToolCacheBreakpoint(tools);
+        expect(tools[0].cache_control).toEqual({ type: 'ephemeral' });
+    });
+    it('handles empty array without error', () => {
+        const tools = [];
+        expect(() => addToolCacheBreakpoint(tools)).not.toThrow();
+    });
+});

package/dist/__tests__/api.test.d.ts

@@ -0,0 +1 @@
+export {};