@tractorscorch/clank 1.4.0 → 1.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +214 -189
- package/README.md +189 -172
- package/dist/index.js +60 -23
- package/dist/index.js.map +1 -1
- package/package.json +58 -58
package/CHANGELOG.md
CHANGED
|
@@ -1,189 +1,214 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to Clank will be documented in this file.
|
|
4
|
-
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/).
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## [1.4.
|
|
10
|
-
|
|
11
|
-
###
|
|
12
|
-
- **Telegram streaming** —
|
|
13
|
-
- **
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
- **
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
- **
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
- **
|
|
50
|
-
- **
|
|
51
|
-
- **
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## [1.
|
|
62
|
-
|
|
63
|
-
### Fixed
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
- **
|
|
90
|
-
- **
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- **
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
- **
|
|
109
|
-
- **
|
|
110
|
-
- **
|
|
111
|
-
- **
|
|
112
|
-
- **
|
|
113
|
-
- **
|
|
114
|
-
- **
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
138
|
-
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
-
|
|
144
|
-
-
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
-
|
|
156
|
-
-
|
|
157
|
-
-
|
|
158
|
-
|
|
159
|
-
###
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
-
|
|
167
|
-
-
|
|
168
|
-
-
|
|
169
|
-
-
|
|
170
|
-
-
|
|
171
|
-
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
184
|
-
-
|
|
185
|
-
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to Clank will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## [1.4.3] — 2026-03-22
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
- **Telegram streaming stutter** — fixed race condition where multiple partial messages were sent instead of editing a single message; added synchronous guard flag to prevent duplicate `sendMessage` calls while the initial message promise is in-flight
|
|
13
|
+
- **Gateway killed by `clear` on Windows** — replaced `fork()` with `spawn()` + `windowsHide` for background gateway process; `fork` kept an IPC channel tied to the parent console, so clearing PowerShell killed the gateway
|
|
14
|
+
- **`clank update` fails on Windows** — added `--force` to the npm install command to overwrite locked shim files (`clank.ps1`, `clank.cmd`)
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## [1.4.1] — 2026-03-23
|
|
19
|
+
|
|
20
|
+
### Security
|
|
21
|
+
- **Config get redaction** — `config get` action now redacts sensitive keys (apiKey, token, botToken) before returning to LLM context
|
|
22
|
+
- **Config set protection** — config tool now blocks prototype pollution (`__proto__`, `constructor`, `prototype`)
|
|
23
|
+
- **Rate limit streaming path** — `handleInboundMessageStreaming` now enforced (was bypassing rate limiter)
|
|
24
|
+
- **SSRF private IPs** — web_fetch now blocks RFC 1918 ranges (10.x, 192.168.x, 172.16-31.x) and IPv4-mapped IPv6
|
|
25
|
+
- **STT workspace containment** — speech_to_text tool now uses guardPath() to prevent reading files outside workspace
|
|
26
|
+
|
|
27
|
+
### Audit Result
|
|
28
|
+
- 0 dependency vulnerabilities
|
|
29
|
+
- 14 PASS, 1 WARN (bash blocklist is defense-in-depth), 0 FAIL
|
|
30
|
+
- Grade: A
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## [1.4.0] — 2026-03-23
|
|
35
|
+
|
|
36
|
+
### Added
|
|
37
|
+
- **Telegram streaming** — responses edit in real-time as tokens arrive (800ms interval, respects rate limits)
|
|
38
|
+
- **Telegram image handling** — send photos to the bot, routed to agent with image URL
|
|
39
|
+
- **Telegram document handling** — send files to the bot, saved to temp with sanitized filenames, agent can read them
|
|
40
|
+
- **File share tool** — `share_file` lets the agent send workspace files through channels (workspace containment enforced)
|
|
41
|
+
- **Per-agent voice** — each agent can have its own ElevenLabs voice ID in config
|
|
42
|
+
- **Compact prompt mode** — `compactPrompt: true` strips workspace files for small model context optimization
|
|
43
|
+
- **Thinking control** — `thinking: "off"` suppresses extended reasoning for faster responses
|
|
44
|
+
- **Auto-memory persistence** — "remember X", preference statements, and corrections auto-saved to MEMORY.md
|
|
45
|
+
- **Web UI session history** — loads last 50 messages on connect and session switch
|
|
46
|
+
- **Rate limiting** — 20 messages per minute per session, prevents model flooding
|
|
47
|
+
|
|
48
|
+
### Improved
|
|
49
|
+
- **Model retry** — one retry with 2s backoff on transient connection failures
|
|
50
|
+
- **Session resume compaction** — auto-compacts on load if over context budget
|
|
51
|
+
- **Memory persistence instruction** — system prompt now encourages the agent to save learnings
|
|
52
|
+
|
|
53
|
+
### Security
|
|
54
|
+
- Telegram document uploads: filename sanitized (path traversal protection), 10MB size limit
|
|
55
|
+
- File share tool: workspace containment via guardPath
|
|
56
|
+
- Rate limiting prevents denial-of-service via message flooding
|
|
57
|
+
- Per-agent voice IDs read from config only (not from user input)
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## [1.3.1] — 2026-03-23
|
|
62
|
+
|
|
63
|
+
### Fixed
|
|
64
|
+
- **STT not working** — local whisper.cpp was selected by default but not installed. Added Groq as the recommended free STT provider (whisper-large-v3-turbo).
|
|
65
|
+
- **STT provider priority:** Groq (free, fast) → OpenAI Whisper → local whisper.cpp
|
|
66
|
+
- **Setup wizard:** STT now offers Groq as option 1 (recommended), OpenAI as option 2, local as option 3
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## [1.3.0] — 2026-03-23
|
|
71
|
+
|
|
72
|
+
### Added
|
|
73
|
+
- **ElevenLabs integration** — text-to-speech via ElevenLabs API, configurable during onboarding
|
|
74
|
+
- **Whisper integration** — speech-to-text via OpenAI Whisper API or local whisper.cpp
|
|
75
|
+
- **Voice tools (3):** `text_to_speech`, `speech_to_text`, `list_voices` — agent can generate and transcribe audio
|
|
76
|
+
- **Telegram voice messages** — send a voice message → auto-transcribed via Whisper → routed to agent → response as voice (ElevenLabs) or text
|
|
77
|
+
- **Integrations config section** — unified config for third-party API services (ElevenLabs, Whisper, image gen, extensible)
|
|
78
|
+
- **Setup wizard integrations step** — configure ElevenLabs, Whisper, and other API services during onboarding
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
- Tool count: 21 total (10 core + 11 self-config/voice)
|
|
82
|
+
- Setup wizard now asks about integrations for all users (not just advanced mode)
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## [1.2.1] — 2026-03-23
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
- **Gateway crash on restart** — stale Telegram messages queued while offline no longer flood the model. Messages older than 30s before startup are dropped.
|
|
90
|
+
- **Parallel model overload** — Telegram messages from the same chat are now processed sequentially (per-chat queue) instead of all at once.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## [1.2.0] — 2026-03-22
|
|
95
|
+
|
|
96
|
+
### Added
|
|
97
|
+
- **Two-tier context compaction** — critical for local model performance:
|
|
98
|
+
- Tier 1 (fast): system prompt budgeting, tool result dedup, message truncation, aggressive dropping
|
|
99
|
+
- Tier 2 (LLM-summarized): model generates conversation recap replacing oldest messages. Preserves meaning over long sessions.
|
|
100
|
+
- Token budgeting: reserves 25% for response, budgets system prompt separately from conversation
|
|
101
|
+
- **`clank update`** — update to latest npm version, preserves config/sessions/memory, restarts gateway
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## [1.1.0] — 2026-03-22
|
|
106
|
+
|
|
107
|
+
### Security Hardening
|
|
108
|
+
- **Bash tool:** expanded blocklist from 5 to 25 patterns — covers flag variations, shell-in-shell, encoded payloads, PowerShell, system damage commands
|
|
109
|
+
- **Path traversal:** all file tools (read, write, edit, list, search, glob) now enforce workspace containment via `guardPath()` — blocks absolute paths and `../` traversal outside workspace
|
|
110
|
+
- **Config redaction:** API keys, bot tokens, and auth tokens are stripped from config before exposing to LLM context or WebSocket clients
|
|
111
|
+
- **Prototype pollution:** config.set RPC blocks `__proto__`, `constructor`, `prototype` keys
|
|
112
|
+
- **SSRF protection:** web_fetch blocks localhost, cloud metadata endpoints (169.254.169.254), .internal/.local hostnames, file:// protocol
|
|
113
|
+
- **Gateway auth:** auto-generates token on startup if mode is "token" but no token configured — prevents accidental open gateways
|
|
114
|
+
- **Status endpoint:** /status now requires Bearer token authentication
|
|
115
|
+
- **Tool confirmations:** gateway respects autoApprove config instead of blindly approving — 30s timeout defaults to deny
|
|
116
|
+
- **.gitignore:** added config.json5, *.pem, *.key, credentials.json to prevent accidental secret commits
|
|
117
|
+
|
|
118
|
+
### Bug Fixes
|
|
119
|
+
- **Telegram bot not responding:** `bot.start()` was blocking (awaited) which prevented the gateway from finishing startup. Now runs non-blocking with `onStart` callback.
|
|
120
|
+
- **Telegram allowFrom:** now matches both `@username` and numeric user IDs (was only matching numeric)
|
|
121
|
+
- **grammY missing:** added as real dependency (was dynamic import that failed silently)
|
|
122
|
+
- **Local server URL not saved:** setup wizard now saves detected server baseUrl for all local providers (was only saving Ollama)
|
|
123
|
+
- **Port conflict:** default port changed to 18790 (was 18789, conflicted with OpenClaw/Claude Code)
|
|
124
|
+
- **--web flag:** `clank chat --web` now auto-starts gateway and opens browser
|
|
125
|
+
- **Gateway text/message param:** accepts both `message` and `text` fields from clients
|
|
126
|
+
|
|
127
|
+
### Added
|
|
128
|
+
- **TUI:** rich terminal UI with streaming, tool cards, thinking blocks, agent/session/model pickers, slash commands, shell integration (`!command`)
|
|
129
|
+
- **Web Control UI:** 8-panel dashboard — Chat, Agents, Sessions, Config (JSON editor), Pipelines, Cron, Logs, Channels
|
|
130
|
+
- **Telegram slash commands:** /help, /status, /agents, /agent, /sessions, /new, /reset, /model, /think
|
|
131
|
+
- **CLI commands:** tui, dashboard, pipeline, cron, channels, uninstall
|
|
132
|
+
- **Background gateway:** runs as detached process, Telegram/Discord stay alive while CLI/TUI/Web run on top
|
|
133
|
+
- **Gateway singleton:** refuses to start if already running on the port
|
|
134
|
+
- **Self-config tools (8):** config, manage_channel, manage_agent, manage_model, manage_session, manage_cron, gateway_status, send_message
|
|
135
|
+
- **Google Gemini provider** with streaming and function calling
|
|
136
|
+
- **Memory system:** TF-IDF cosine similarity with decay scoring, categorized storage
|
|
137
|
+
- **Encryption:** AES-256-GCM for API keys, PIN hashing with timing-safe comparison
|
|
138
|
+
- **Web search:** Brave Search API integration
|
|
139
|
+
- **Config hot-reload:** watches config.json5 for changes
|
|
140
|
+
- **`clank uninstall`:** removes all data, daemon, and npm package
|
|
141
|
+
|
|
142
|
+
### Changed
|
|
143
|
+
- Default command (`clank` with no args) starts gateway in background then launches TUI
|
|
144
|
+
- `clank gateway start` now runs in background by default (`--foreground` for blocking mode)
|
|
145
|
+
- `clank gateway restart` fully implemented (stop + start)
|
|
146
|
+
- Protocol updated to v1 spec with 17 RPC methods and 11 event types
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## [1.0.0] — 2026-03-22
|
|
151
|
+
|
|
152
|
+
Initial release — Clank Gateway foundation.
|
|
153
|
+
|
|
154
|
+
### Architecture
|
|
155
|
+
- Single gateway daemon (HTTP + WebSocket on port 18789)
|
|
156
|
+
- WebSocket JSON-RPC protocol v1 with 17 RPC methods and 11 event types
|
|
157
|
+
- All interfaces are equal — CLI, TUI, Web UI, Telegram, Discord
|
|
158
|
+
|
|
159
|
+
### Engine
|
|
160
|
+
- AgentEngine with ReAct loop (stream → tool calls → execute → loop, max 50 iterations)
|
|
161
|
+
- Pluggable ContextEngine with compaction optimized for local models (60% threshold vs 80% cloud)
|
|
162
|
+
- Tool tiering: full/core/auto — reduces tool count for smaller models
|
|
163
|
+
- PromptFallbackProvider for models without native function calling
|
|
164
|
+
|
|
165
|
+
### Providers
|
|
166
|
+
- Ollama (primary) — auto-detect, dynamic context window, tool support checking
|
|
167
|
+
- Anthropic Claude — Messages API with SSE streaming
|
|
168
|
+
- OpenAI — also covers LM Studio, vLLM, llama.cpp (OpenAI-compatible)
|
|
169
|
+
- Google Gemini — streaming with function calling
|
|
170
|
+
- Provider router with fallback chain and local server auto-detection
|
|
171
|
+
- Reasoning/thinking content support (Qwen, DeepSeek, etc.)
|
|
172
|
+
|
|
173
|
+
### Tools (18 total)
|
|
174
|
+
- **Core (10):** read_file, write_file, edit_file, list_directory, search_files, glob_files, bash, git, web_search (Brave), web_fetch
|
|
175
|
+
- **Self-config (8):** config, manage_channel, manage_agent, manage_model, manage_session, manage_cron, gateway_status, send_message
|
|
176
|
+
|
|
177
|
+
### Interfaces
|
|
178
|
+
- **CLI:** 12 commands — chat, gateway, setup, fix, models, agents, daemon, tui, dashboard, pipeline, cron, channels
|
|
179
|
+
- **TUI:** Rich terminal UI with streaming, tool cards, thinking blocks, agent/session/model pickers, slash commands, shell integration
|
|
180
|
+
- **Web Control UI:** 8-panel SPA — Chat, Agents, Sessions, Config (JSON editor), Pipelines, Cron, Logs, Channels
|
|
181
|
+
- **Telegram:** Full adapter with slash commands, typing indicators, response chunking, permission allowlists, group mention checking
|
|
182
|
+
- **Discord:** Full adapter with typing, reply threading, response chunking
|
|
183
|
+
|
|
184
|
+
### Multi-Agent
|
|
185
|
+
- Named agents with separate models, workspaces, and tool access
|
|
186
|
+
- Config-driven routing with binding priority tiers (peer → guild → team → channel → default)
|
|
187
|
+
- Normalized session keys for cross-channel continuity (dm:telegram:123, cli:main, etc.)
|
|
188
|
+
|
|
189
|
+
### Systems
|
|
190
|
+
- **Memory:** TF-IDF cosine similarity with decay scoring, categorized storage (identity/knowledge/lessons/context)
|
|
191
|
+
- **Sessions:** JSON transcript persistence, prune/cap/reset, cross-channel shared sessions
|
|
192
|
+
- **Config:** JSON5 with env var substitution, hot-reload watcher, defaults with deep merge
|
|
193
|
+
- **Cron:** JSONL job store, 30s tick interval, run logging, retry tracking
|
|
194
|
+
- **Pipelines:** Sequential step execution with agent handoffs, state persistence
|
|
195
|
+
- **Plugins:** Discovery (~/.clank/plugins/ + node_modules/clank-plugin-*), 25+ hook types
|
|
196
|
+
- **Heartbeat:** Periodic probes from HEARTBEAT.md, quiet hours
|
|
197
|
+
- **Voice:** TTS (ElevenLabs + piper), STT (whisper.cpp)
|
|
198
|
+
- **Daemon:** Cross-platform service — macOS (launchd), Windows (Task Scheduler), Linux (systemd)
|
|
199
|
+
|
|
200
|
+
### Security
|
|
201
|
+
- AES-256-GCM encryption for API keys (PBKDF2, 100K iterations)
|
|
202
|
+
- PIN verification with timing-safe comparison
|
|
203
|
+
- 3-tier tool safety system (low/medium/high) with auto-approve settings
|
|
204
|
+
- Gateway binds to localhost by default, token-based auth
|
|
205
|
+
|
|
206
|
+
### Onboarding
|
|
207
|
+
- `clank setup` wizard — Quick Start (under 2 minutes) and Advanced flows
|
|
208
|
+
- Auto-detects local model servers (Ollama, LM Studio, llama.cpp, vLLM)
|
|
209
|
+
- Configures cloud providers, Telegram, Discord, Brave Search, voice, agents
|
|
210
|
+
- `clank fix` diagnostics with auto-repair
|
|
211
|
+
|
|
212
|
+
### Workspace
|
|
213
|
+
- Bootstrap templates: SOUL.md, USER.md, IDENTITY.md, BOOTSTRAP.md, AGENTS.md, TOOLS.md, MEMORY.md, HEARTBEAT.md
|
|
214
|
+
- System prompt builder loads workspace files + project context (.clank.md)
|