@tractorscorch/clank 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to Clank will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+---
+
+## [1.1.0] — 2026-03-22
+
+### Security Hardening
+- **Bash tool:** expanded blocklist from 5 to 25 patterns — covers flag variations, shell-in-shell, encoded payloads, PowerShell, system damage commands
+- **Path traversal:** all file tools (read, write, edit, list, search, glob) now enforce workspace containment via `guardPath()` — blocks absolute paths and `../` traversal outside workspace
+- **Config redaction:** API keys, bot tokens, and auth tokens are stripped from config before exposing to LLM context or WebSocket clients
+- **Prototype pollution:** config.set RPC blocks `__proto__`, `constructor`, `prototype` keys
+- **SSRF protection:** web_fetch blocks localhost, cloud metadata endpoints (169.254.169.254), .internal/.local hostnames, file:// protocol
+- **Gateway auth:** auto-generates token on startup if mode is "token" but no token configured — prevents accidental open gateways
+- **Status endpoint:** /status now requires Bearer token authentication
+- **Tool confirmations:** gateway respects autoApprove config instead of blindly approving — 30s timeout defaults to deny
+- **.gitignore:** added config.json5, *.pem, *.key, credentials.json to prevent accidental secret commits
+
+### Bug Fixes
+- **Telegram bot not responding:** `bot.start()` was blocking (awaited) which prevented the gateway from finishing startup. Now runs non-blocking with `onStart` callback.
+- **Telegram allowFrom:** now matches both `@username` and numeric user IDs (was only matching numeric)
+- **grammY missing:** added as real dependency (was dynamic import that failed silently)
+- **Local server URL not saved:** setup wizard now saves detected server baseUrl for all local providers (was only saving Ollama)
+- **Port conflict:** default port changed to 18790 (was 18789, conflicted with OpenClaw/Claude Code)
+- **--web flag:** `clank chat --web` now auto-starts gateway and opens browser
+- **Gateway text/message param:** accepts both `message` and `text` fields from clients
+
+### Added
+- **TUI:** rich terminal UI with streaming, tool cards, thinking blocks, agent/session/model pickers, slash commands, shell integration (`!command`)
+- **Web Control UI:** 8-panel dashboard — Chat, Agents, Sessions, Config (JSON editor), Pipelines, Cron, Logs, Channels
+- **Telegram slash commands:** /help, /status, /agents, /agent, /sessions, /new, /reset, /model, /think
+- **CLI commands:** tui, dashboard, pipeline, cron, channels, uninstall
+- **Background gateway:** runs as detached process, Telegram/Discord stay alive while CLI/TUI/Web run on top
+- **Gateway singleton:** refuses to start if already running on the port
+- **Self-config tools (8):** config, manage_channel, manage_agent, manage_model, manage_session, manage_cron, gateway_status, send_message
+- **Google Gemini provider** with streaming and function calling
+- **Memory system:** TF-IDF cosine similarity with decay scoring, categorized storage
+- **Encryption:** AES-256-GCM for API keys, PIN hashing with timing-safe comparison
+- **Web search:** Brave Search API integration
+- **Config hot-reload:** watches config.json5 for changes
+- **`clank uninstall`:** removes all data, daemon, and npm package
+
+### Changed
+- Default command (`clank` with no args) starts gateway in background then launches TUI
+- `clank gateway start` now runs in background by default (`--foreground` for blocking mode)
+- `clank gateway restart` fully implemented (stop + start)
+- Protocol updated to v1 spec with 17 RPC methods and 11 event types
+
+---
+
+## [1.0.0] — 2026-03-22
+
+Initial release — Clank Gateway foundation.
+
+### Architecture
+- Single gateway daemon (HTTP + WebSocket on port 18789)
+- WebSocket JSON-RPC protocol v1 with 17 RPC methods and 11 event types
+- All interfaces are equal — CLI, TUI, Web UI, Telegram, Discord
+
+### Engine
+- AgentEngine with ReAct loop (stream → tool calls → execute → loop, max 50 iterations)
+- Pluggable ContextEngine with compaction optimized for local models (60% threshold vs 80% cloud)
+- Tool tiering: full/core/auto — reduces tool count for smaller models
+- PromptFallbackProvider for models without native function calling
+
+### Providers
+- Ollama (primary) — auto-detect, dynamic context window, tool support checking
+- Anthropic Claude — Messages API with SSE streaming
+- OpenAI — also covers LM Studio, vLLM, llama.cpp (OpenAI-compatible)
+- Google Gemini — streaming with function calling
+- Provider router with fallback chain and local server auto-detection
+- Reasoning/thinking content support (Qwen, DeepSeek, etc.)
+
+### Tools (18 total)
+- **Core (10):** read_file, write_file, edit_file, list_directory, search_files, glob_files, bash, git, web_search (Brave), web_fetch
+- **Self-config (8):** config, manage_channel, manage_agent, manage_model, manage_session, manage_cron, gateway_status, send_message
+
+### Interfaces
+- **CLI:** 12 commands — chat, gateway, setup, fix, models, agents, daemon, tui, dashboard, pipeline, cron, channels
+- **TUI:** Rich terminal UI with streaming, tool cards, thinking blocks, agent/session/model pickers, slash commands, shell integration
+- **Web Control UI:** 8-panel SPA — Chat, Agents, Sessions, Config (JSON editor), Pipelines, Cron, Logs, Channels
+- **Telegram:** Full adapter with slash commands, typing indicators, response chunking, permission allowlists, group mention checking
+- **Discord:** Full adapter with typing, reply threading, response chunking
+
+### Multi-Agent
+- Named agents with separate models, workspaces, and tool access
+- Config-driven routing with binding priority tiers (peer → guild → team → channel → default)
+- Normalized session keys for cross-channel continuity (dm:telegram:123, cli:main, etc.)
+
+### Systems
+- **Memory:** TF-IDF cosine similarity with decay scoring, categorized storage (identity/knowledge/lessons/context)
+- **Sessions:** JSON transcript persistence, prune/cap/reset, cross-channel shared sessions
+- **Config:** JSON5 with env var substitution, hot-reload watcher, defaults with deep merge
+- **Cron:** JSONL job store, 30s tick interval, run logging, retry tracking
+- **Pipelines:** Sequential step execution with agent handoffs, state persistence
+- **Plugins:** Discovery (~/.clank/plugins/ + node_modules/clank-plugin-*), 25+ hook types
+- **Heartbeat:** Periodic probes from HEARTBEAT.md, quiet hours
+- **Voice:** TTS (ElevenLabs + piper), STT (whisper.cpp)
+- **Daemon:** Cross-platform service — macOS (launchd), Windows (Task Scheduler), Linux (systemd)
+
+### Security
+- AES-256-GCM encryption for API keys (PBKDF2, 100K iterations)
+- PIN verification with timing-safe comparison
+- 3-tier tool safety system (low/medium/high) with auto-approve settings
+- Gateway binds to localhost by default, token-based auth
+
+### Onboarding
+- `clank setup` wizard — Quick Start (under 2 minutes) and Advanced flows
+- Auto-detects local model servers (Ollama, LM Studio, llama.cpp, vLLM)
+- Configures cloud providers, Telegram, Discord, Brave Search, voice, agents
+- `clank fix` diagnostics with auto-repair
+
+### Workspace
+- Bootstrap templates: SOUL.md, USER.md, IDENTITY.md, BOOTSTRAP.md, AGENTS.md, TOOLS.md, MEMORY.md, HEARTBEAT.md
+- System prompt builder loads workspace files + project context (.clank.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ItsTrag1c
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ItsTrag1c/Clank/main/docs/banner.png" alt="Clank" width="100%" />
+</p>
+
+<h1 align="center">Clank</h1>
+
+<p align="center">
+  <b>Local-first AI agent gateway.</b> Open-source alternative to OpenClaw, optimized for local models.
+</p>
+
+<p align="center">
+  <a href="https://github.com/ItsTrag1c/Clank/releases/latest"><img src="https://img.shields.io/badge/version-1.1.0-blue.svg" alt="Version" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License" /></a>
+  <a href="https://www.npmjs.com/package/clank"><img src="https://img.shields.io/npm/v/clank.svg" alt="npm" /></a>
+  <a href="https://github.com/ItsTrag1c/Clank/stargazers"><img src="https://img.shields.io/github/stars/ItsTrag1c/Clank.svg" alt="Stars" /></a>
+</p>
+
+<p align="center">
+  <a href="https://clanksuite.dev">Website</a> ·
+  <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/INSTALL.md">Install Guide</a> ·
+  <a href="https://github.com/ItsTrag1c/Clank/blob/main/docs/USER_GUIDE.md">User Guide</a> ·
+  <a href="https://github.com/ItsTrag1c/Clank/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://x.com/ClankSuite">Twitter</a> ·
+  <a href="https://reddit.com/u/ClankSuite">Reddit</a>
+</p>
+
+---
+
+## What is Clank?
+
+Clank is a personal AI gateway — **one daemon, many frontends**. It connects your preferred interfaces (CLI, TUI, browser, Telegram, Discord) to AI agents running local or cloud models. All interfaces share sessions, memory, and agent state.
+
+**Built for people who want the OpenClaw experience without the token costs.**
+
+```
+              ┌─────────────────────────────┐
+              │       Clank Gateway          │
+              │     (single daemon)          │
+              │                              │
+              │  Agent Pool + Routing        │
+              │  Sessions, Memory, Pipelines │
+              │  Cron, Tools, Plugins        │
+              └──────────────┬───────────────┘
+                             │
+                WebSocket + HTTP (port 18790)
+                             │
+      ┌──────────┬───────────┼───────────┬──────────┐
+      │          │           │           │          │
+     CLI      Web UI     Telegram    Discord      TUI
+  (direct)  (browser)    (bot)       (bot)     (terminal)
+```
+
+## Quick Start
+
+```bash
+npm install -g clank
+clank setup
+clank
+```
+
+That's it. Setup auto-detects your local models, configures the gateway, and gets you chatting in under 2 minutes. See the [full install guide](docs/INSTALL.md) for details.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Local-first** | Auto-detects Ollama, LM Studio, llama.cpp, vLLM. Cloud providers optional. |
+| **Multi-agent** | Named agents with separate models, workspaces, tools, and routing. |
+| **Multi-channel** | CLI, TUI, Web UI, Telegram, Discord — all equal, all share sessions. |
+| **Self-configuring** | After setup, configure everything through conversation. |
+| **18 tools** | File ops, bash, git, web search (Brave), plus 8 self-config tools. |
+| **Web Control UI** | 8-panel dashboard: Chat, Agents, Sessions, Config, Pipelines, Cron, Logs, Channels. |
+| **Pipeline orchestration** | Chain agents together for multi-step workflows. |
+| **Plugin system** | Extend with custom tools, channels, and providers. 25+ hook types. |
+| **Cron scheduler** | Recurring and one-shot scheduled agent tasks. |
+| **Voice** | Cloud (ElevenLabs) or fully local (whisper.cpp + piper). |
+| **Memory** | TF-IDF with decay scoring. Agent learns and remembers across sessions. |
+| **Security** | AES-256-GCM encryption, SSRF protection, path containment, config redaction. |
+
+## Commands
+
+```bash
+# Start — gateway + TUI (Telegram/Discord stay alive in background)
+clank
+
+# Chat interfaces
+clank chat                    # Direct mode (no gateway needed)
+clank chat --web              # Auto-start gateway + open Web UI
+clank tui                     # Rich TUI connected to gateway
+clank dashboard               # Open Web UI in browser
+
+# Gateway
+clank gateway start           # Start in background
+clank gateway stop            # Stop
+clank gateway status          # Show status, clients, sessions
+clank gateway restart         # Restart
+
+# Setup & diagnostics
+clank setup                   # Onboarding wizard
+clank fix                     # Diagnostics & auto-repair
+
+# Model & agent management
+clank models list             # Detect + list models
+clank models add              # Add a provider (Anthropic, OpenAI, Google, Brave)
+clank models test             # Test connectivity
+clank agents list             # List agents
+clank agents add              # Create an agent
+
+# Scheduled tasks
+clank cron list               # List jobs
+clank cron add                # Schedule a task
+
+# System
+clank daemon install          # Auto-start at login (Windows/macOS/Linux)
+clank channels                # Channel status
+clank uninstall               # Remove everything
+```
+
+## Providers
+
+| Provider | Type | How |
+|----------|------|-----|
+| **Ollama** | Local | Auto-detected at `localhost:11434` |
+| **LM Studio** | Local | Auto-detected at `localhost:1234` |
+| **llama.cpp** | Local | Auto-detected at `localhost:8080` |
+| **vLLM** | Local | Auto-detected at `localhost:8000` |
+| **Anthropic** | Cloud | API key via `clank setup` or config |
+| **OpenAI** | Cloud | API key via `clank setup` or config |
+| **Google Gemini** | Cloud | API key via `clank setup` or config |
+
+Models without native tool calling automatically use prompt-based fallback — tools are injected into the system prompt and parsed from text output.
+
+## Security
+
+Clank is designed to be safe by default:
+
+- **Workspace containment** — file tools blocked outside workspace
+- **Bash protection** — 25-pattern blocklist for destructive commands
+- **API key redaction** — keys never sent to LLM context
+- **SSRF protection** — web_fetch blocks localhost, cloud metadata, internal hosts
+- **Gateway auth** — token-based, auto-generated, localhost-only by default
+- **Encryption** — AES-256-GCM for API keys at rest
+
+See [SECURITY.md](SECURITY.md) for the full security model.
+
+## Documentation
+
+- **[Install Guide](docs/INSTALL.md)** — Detailed installation and setup instructions
+- **[User Guide](docs/USER_GUIDE.md)** — How to use Clank day-to-day
+- **[Changelog](CHANGELOG.md)** — Version history
+- **[Privacy Policy](PRIVACY_POLICY.md)** — Data handling
+- **[Security Policy](SECURITY.md)** — Security model and vulnerability reporting
+
+## Links
+
+| | |
+|--|--|
+| **Website** | [clanksuite.dev](https://clanksuite.dev) |
+| **GitHub** | [ItsTrag1c/Clank](https://github.com/ItsTrag1c/Clank) |
+| **npm** | [npmjs.com/package/clank](https://www.npmjs.com/package/clank) |
+| **Twitter/X** | [@ClankSuite](https://x.com/ClankSuite) |
+| **Reddit** | [u/ClankSuite](https://reddit.com/u/ClankSuite) |
+| **Legacy** | [Clank-Legacy](https://github.com/ItsTrag1c/Clank-Legacy) (archived CLI v2.7.0 + Desktop v2.6.1) |
+
+## Requirements
+
+- Node.js 20+
+- A local model server (Ollama recommended) or cloud API key
+
+## License
+
+MIT — see [LICENSE](LICENSE)