@sliday/tamp 0.8.0 → 0.8.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/README.md +52 -5
- package/index.js +44 -12
- package/package.json +4 -2
- package/providers.js +31 -5
- package/sidecar/requirements.txt +4 -0
- package/sidecar/server.py +41 -0
- package/stats.js +21 -1
package/README.md
CHANGED
|
@@ -6,16 +6,19 @@
|
|
|
6
6
|
npx @sliday/tamp
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
### Claude Code
|
|
10
|
-
|
|
11
|
-
Auto-start on every session:
|
|
9
|
+
### Claude Code
|
|
12
10
|
|
|
13
11
|
```bash
|
|
12
|
+
# Install the plugin (auto-starts Tamp each session)
|
|
14
13
|
claude plugin marketplace add sliday/claude-plugins
|
|
15
14
|
claude plugin install tamp@sliday
|
|
16
15
|
```
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
The plugin adds `/tamp:status` and `/tamp:config` commands. It auto-starts Tamp but does not route traffic. Point Claude Code at Tamp once by adding to `~/.claude/settings.json`:
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{ "env": { "ANTHROPIC_BASE_URL": "http://localhost:7778" } }
|
|
21
|
+
```
|
|
19
22
|
|
|
20
23
|
### 🦞 OpenClaw
|
|
21
24
|
|
|
@@ -51,6 +54,22 @@ Auto-detects API format, compresses tool output, forwards upstream. Error result
|
|
|
51
54
|
|
|
52
55
|
Opt-in stages: `strip-comments`, `textpress` (LLM semantic compression), `graph` (session-scoped dedup — works on any coding agent: Codex, Claude Code, Aider — anywhere the same file is read twice, up to -99% per repeat block)
|
|
53
56
|
|
|
57
|
+
### LLMLingua sidecar
|
|
58
|
+
|
|
59
|
+
The `llmlingua` stage is enabled by default but requires a Python sidecar running on port 8788.
|
|
60
|
+
|
|
61
|
+
Tamp auto-starts the sidecar when [`uv`](https://docs.astral.sh/uv/) is installed. Manual starts for all other cases:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
uv run --with fastapi --with uvicorn --with llmlingua \
|
|
65
|
+
uvicorn server:app --host 127.0.0.1 --port 8788 \
|
|
66
|
+
--app-dir "$(npm root -g)/@sliday/tamp/sidecar"
|
|
67
|
+
|
|
68
|
+
curl -s http://localhost:8788/health # Verify: {"status":"ok","model_loaded":true}
|
|
69
|
+
|
|
70
|
+
tamp stop && tamp -y # restart Tamp, health endpoint will show `sidecar: ok`
|
|
71
|
+
```
|
|
72
|
+
|
|
54
73
|
## Quick Start
|
|
55
74
|
|
|
56
75
|
```bash
|
|
@@ -232,7 +251,7 @@ Supported on all providers: Anthropic, OpenAI Chat, OpenAI Responses (Codex), Ge
|
|
|
232
251
|
| `TAMP_MIN_SIZE` | `200` | Min content size (chars) |
|
|
233
252
|
| `TAMP_LOG` | `true` | Enable logging |
|
|
234
253
|
| `TAMP_CACHE_SAFE` | `true` | Compress newest only (prompt-cache safe) |
|
|
235
|
-
| `TAMP_LLMLINGUA_URL` | *(none)* | LLMLingua sidecar URL |
|
|
254
|
+
| `TAMP_LLMLINGUA_URL` | *(none)* | LLMLingua sidecar URL. Set to `http://localhost:8788` to skip the auto-probe (avoids startup race if sidecar is still loading the model) |
|
|
236
255
|
|
|
237
256
|
**Recommended setups:**
|
|
238
257
|
|
|
@@ -293,6 +312,22 @@ tamp install-service
|
|
|
293
312
|
tamp status
|
|
294
313
|
```
|
|
295
314
|
|
|
315
|
+
## Monitoring
|
|
316
|
+
|
|
317
|
+
Check session stats any time via the health endpoint via browser or terminal:
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
curl -s 'http://localhost:7778/health?text' # Human-readable
|
|
321
|
+
# Tamp v0.5.9 | 7 stages active | sidecar: n/a
|
|
322
|
+
# Requests: 63 | Blocks: 2
|
|
323
|
+
# Tokens saved: 1136 | Chars: 3482/61528 (5.7%)
|
|
324
|
+
# Est. savings: $0.0034 (Sonnet $3/Mtok) | $0.0170 (Opus $15/Mtok)
|
|
325
|
+
|
|
326
|
+
curl -s http://localhost:7778/health # JSON (for scripts/dashboards)
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
Inside Claude Code, run `/tamp:status`.
|
|
330
|
+
|
|
296
331
|
## Token Savings
|
|
297
332
|
|
|
298
333
|
Claude Code sends full conversation history on every API call. Tool results accumulate — files, listings, outputs — all re-sent as input tokens.
|
|
@@ -318,6 +353,14 @@ Where v0.8 actually pays off is **session-scoped work**, which is what coding ag
|
|
|
318
353
|
|
|
319
354
|
The real win in v0.8 is **the level knob itself** — a zip-like 1–9 dial that lets you trade compression aggressiveness for risk without memorizing stage names. To reproduce the numbers above, run `node bench/runner.js --sweep` (set `OPENROUTER_API_KEY` for the live A/B pass).
|
|
320
355
|
|
|
356
|
+
## Security
|
|
357
|
+
|
|
358
|
+
Tamp runs on `localhost` and forwards to the upstream you configure. Most stages are local-only: `llmlingua` talks to a sidecar on `127.0.0.1`, `foundation-models` stays on-device. The one stage that sends content off-box is `textpress` (opt-in, level 7+), which posts to OpenRouter when `OPENROUTER_API_KEY` is set — leave it off if your tool output is sensitive.
|
|
359
|
+
|
|
360
|
+
**Secret redaction** is on the roadmap ([#6](https://github.com/sliday/tamp/issues/6)): a `redact` stage that masks API keys, tokens, and `.env` values before anything leaves the machine, running ahead of every other stage. Until it lands, Tamp forwards file contents verbatim — treat your upstream's data policy as the boundary.
|
|
361
|
+
|
|
362
|
+
This repo ships an agent harness (built with [harn.app](https://harn.app)): `AGENTS.md` plus PreToolUse / Stop hooks under `scripts/harness/` that block dangerous shell commands and gate completion on `npm test`. See `.claude/settings.json`.
|
|
363
|
+
|
|
321
364
|
## Development
|
|
322
365
|
|
|
323
366
|
```bash
|
|
@@ -325,6 +368,10 @@ npm test
|
|
|
325
368
|
node smoke.js
|
|
326
369
|
```
|
|
327
370
|
|
|
371
|
+
## Star History
|
|
372
|
+
|
|
373
|
+
[](https://star-history.com/#sliday/tamp&Date)
|
|
374
|
+
|
|
328
375
|
## License
|
|
329
376
|
|
|
330
377
|
MIT © [Stas Kulesh](https://sliday.com)
|
package/index.js
CHANGED
|
@@ -6,7 +6,7 @@ import * as fzstd from 'fzstd'
|
|
|
6
6
|
import { loadConfig } from './config.js'
|
|
7
7
|
import { compressRequest } from './compress.js'
|
|
8
8
|
import { detectProvider, detectOpenAIAuthMode, resolveOpenAIUpstream } from './providers.js'
|
|
9
|
-
import { createSession, formatRequestLog } from './stats.js'
|
|
9
|
+
import { createSession, formatRequestLog, redactUrl } from './stats.js'
|
|
10
10
|
import { createSessionStore, deriveSessionKey } from './session-graph.js'
|
|
11
11
|
import { createReadCache } from './lib/read-cache.js'
|
|
12
12
|
import { createBrCache } from './lib/br-cache.js'
|
|
@@ -95,6 +95,41 @@ export function createProxy(overrides = {}, loadOpts = {}) {
|
|
|
95
95
|
return { config, session, sessionStore, readCache, brCache, server: _createServer(config, session, sessionStore, readCache, brCache) }
|
|
96
96
|
}
|
|
97
97
|
|
|
98
|
+
// Stream-decompress a zstd body, aborting as soon as the running output size
|
|
99
|
+
// crosses `limit`. fzstd's one-shot decompress() inflates the entire frame
|
|
100
|
+
// into memory before any size check, so a small "bomb" frame could OOM the
|
|
101
|
+
// proxy; streaming bounds peak memory to ~limit + one block. Throws on excess.
|
|
102
|
+
export function decompressZstd(bytes, limit) {
|
|
103
|
+
const input = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
|
|
104
|
+
const parts = []
|
|
105
|
+
let total = 0
|
|
106
|
+
const dctx = new fzstd.Decompress((chunk) => {
|
|
107
|
+
total += chunk.length
|
|
108
|
+
if (total > limit) throw new Error('zstd decompression exceeded size limit')
|
|
109
|
+
parts.push(chunk)
|
|
110
|
+
})
|
|
111
|
+
dctx.push(input, true)
|
|
112
|
+
const out = Buffer.allocUnsafe(total)
|
|
113
|
+
let offset = 0
|
|
114
|
+
for (const p of parts) { out.set(p, offset); offset += p.length }
|
|
115
|
+
return out
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// Surface an upstream connection error to the client. Before any response
|
|
119
|
+
// bytes are sent we can emit a clean 502 JSON body. Once the response has
|
|
120
|
+
// started streaming (headersSent) or finished (writableEnded), appending JSON
|
|
121
|
+
// would corrupt the (possibly SSE) stream the client is reading, so we tear
|
|
122
|
+
// the socket down instead. Returns true if a JSON error body was written.
|
|
123
|
+
export function sendUpstreamError(res) {
|
|
124
|
+
if (res.headersSent || res.writableEnded) {
|
|
125
|
+
res.destroy()
|
|
126
|
+
return false
|
|
127
|
+
}
|
|
128
|
+
res.writeHead(502, { 'Content-Type': 'application/json' })
|
|
129
|
+
res.end(JSON.stringify({ error: 'upstream_error', message: 'failed to connect to upstream' }))
|
|
130
|
+
return true
|
|
131
|
+
}
|
|
132
|
+
|
|
98
133
|
function _createServer(config, session, sessionStore, readCache, brCache) {
|
|
99
134
|
const log = createRequestLogger(config)
|
|
100
135
|
const disclosureTotals = { rehydrated: 0, missed: 0, disclosed: 0 }
|
|
@@ -118,10 +153,7 @@ function openUpstream(method, upstreamUrl, headers, res) {
|
|
|
118
153
|
|
|
119
154
|
upstream.on('error', (err) => {
|
|
120
155
|
log(`[tamp] upstream error: ${err.code || ''} ${err.message}`)
|
|
121
|
-
|
|
122
|
-
res.writeHead(502, { 'Content-Type': 'application/json' })
|
|
123
|
-
}
|
|
124
|
-
res.end(JSON.stringify({ error: 'upstream_error', message: 'failed to connect to upstream' }))
|
|
156
|
+
sendUpstreamError(res)
|
|
125
157
|
})
|
|
126
158
|
|
|
127
159
|
res.on('error', (err) => {
|
|
@@ -209,7 +241,7 @@ return http.createServer(async (req, res) => {
|
|
|
209
241
|
const provider = detectProvider(req.method, req.url, req.headers)
|
|
210
242
|
|
|
211
243
|
if (!provider) {
|
|
212
|
-
log(`[tamp] ${req.method} ${req.url}`)
|
|
244
|
+
log(`[tamp] ${req.method} ${redactUrl(req.url)}`)
|
|
213
245
|
const upstreamUrl = buildUpstreamUrl(req.url, config.upstream)
|
|
214
246
|
return pipeRequest(req, res, upstreamUrl)
|
|
215
247
|
}
|
|
@@ -224,7 +256,11 @@ return http.createServer(async (req, res) => {
|
|
|
224
256
|
let size = 0
|
|
225
257
|
let overflow = false
|
|
226
258
|
|
|
227
|
-
|
|
259
|
+
// destroyOnReturn:false so breaking out on overflow does NOT destroy the
|
|
260
|
+
// request stream — pipeRequest() still needs to forward the unread remainder
|
|
261
|
+
// to the upstream. Without this, an over-maxBody body is truncated while its
|
|
262
|
+
// original content-length is preserved, hanging the upstream.
|
|
263
|
+
for await (const chunk of req.iterator({ destroyOnReturn: false })) {
|
|
228
264
|
size += chunk.length
|
|
229
265
|
chunks.push(chunk)
|
|
230
266
|
if (size > config.maxBody) {
|
|
@@ -263,11 +299,7 @@ return http.createServer(async (req, res) => {
|
|
|
263
299
|
textBody = zlib.brotliDecompressSync(rawBody, { maxOutputLength: MAX_DECOMPRESSED })
|
|
264
300
|
decompressed = true
|
|
265
301
|
} else if (encoding === 'zstd') {
|
|
266
|
-
|
|
267
|
-
if (decompressedBytes.length > MAX_DECOMPRESSED) {
|
|
268
|
-
throw new Error('zstd decompression exceeded size limit')
|
|
269
|
-
}
|
|
270
|
-
textBody = Buffer.from(decompressedBytes)
|
|
302
|
+
textBody = decompressZstd(rawBody, MAX_DECOMPRESSED)
|
|
271
303
|
decompressed = true
|
|
272
304
|
} else if (encoding && encoding !== 'identity') {
|
|
273
305
|
// Unknown encoding — can't decompress, passthrough as-is
|
package/package.json
CHANGED
|
@@ -10,9 +10,11 @@
|
|
|
10
10
|
"providers.js",
|
|
11
11
|
"session-graph.js",
|
|
12
12
|
"stats.js",
|
|
13
|
-
"lib/"
|
|
13
|
+
"lib/",
|
|
14
|
+
"sidecar/server.py",
|
|
15
|
+
"sidecar/requirements.txt"
|
|
14
16
|
],
|
|
15
|
-
"version": "0.8.
|
|
17
|
+
"version": "0.8.3",
|
|
16
18
|
"description": "Token compression proxy for coding agents. Works with Claude Code, Aider, Cursor, Cline, Windsurf. 60-70% combined input+output savings with Caveman-integrated presets and per-command rewriters.",
|
|
17
19
|
"type": "module",
|
|
18
20
|
"main": "index.js",
|
package/providers.js
CHANGED
|
@@ -184,12 +184,20 @@ function applyAnthropicRehydration(body, refs) {
|
|
|
184
184
|
if (typeof current !== 'string') continue
|
|
185
185
|
|
|
186
186
|
let updated = current
|
|
187
|
+
const seenMatch = new Set()
|
|
187
188
|
for (const ref of items) {
|
|
189
|
+
if (seenMatch.has(ref.match)) continue
|
|
190
|
+
seenMatch.add(ref.match)
|
|
188
191
|
const expandedSentinel = `<tamp-ref:v1:${ref.hash} expanded -`
|
|
189
|
-
if
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
192
|
+
// Idempotency across passes: skip if the INCOMING body already carried
|
|
193
|
+
// this expansion. Check `current` (the original), not `updated`, so an
|
|
194
|
+
// expansion we insert this pass cannot suppress a sibling marker that
|
|
195
|
+
// shares the same hash.
|
|
196
|
+
if (current.indexOf(expandedSentinel) !== -1) continue
|
|
197
|
+
if (current.indexOf(ref.match) === -1) continue
|
|
198
|
+
// Replace every occurrence: the model may quote the same marker more
|
|
199
|
+
// than once in one block.
|
|
200
|
+
updated = updated.split(ref.match).join(ref.expansion)
|
|
193
201
|
}
|
|
194
202
|
|
|
195
203
|
if (updated === current) continue
|
|
@@ -296,7 +304,14 @@ const openai = {
|
|
|
296
304
|
if (!body?.messages?.length) return null
|
|
297
305
|
for (let i = body.messages.length - 1; i >= 0; i--) {
|
|
298
306
|
const msg = body.messages[i]
|
|
299
|
-
if (msg?.role
|
|
307
|
+
if (msg?.role !== 'user') continue
|
|
308
|
+
if (typeof msg.content === 'string') return msg.content
|
|
309
|
+
// OpenAI chat allows array content parts (vision, structured input).
|
|
310
|
+
if (Array.isArray(msg.content)) {
|
|
311
|
+
for (const b of msg.content) {
|
|
312
|
+
if (b?.type === 'text' && typeof b.text === 'string') return b.text
|
|
313
|
+
}
|
|
314
|
+
}
|
|
300
315
|
}
|
|
301
316
|
return null
|
|
302
317
|
},
|
|
@@ -309,6 +324,17 @@ const openai = {
|
|
|
309
324
|
msg.content = msg.content + '\n\n' + text
|
|
310
325
|
return true
|
|
311
326
|
}
|
|
327
|
+
if (Array.isArray(msg.content)) {
|
|
328
|
+
for (let j = msg.content.length - 1; j >= 0; j--) {
|
|
329
|
+
const b = msg.content[j]
|
|
330
|
+
if (b?.type === 'text' && typeof b.text === 'string') {
|
|
331
|
+
b.text = b.text + '\n\n' + text
|
|
332
|
+
return true
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
msg.content.push({ type: 'text', text })
|
|
336
|
+
return true
|
|
337
|
+
}
|
|
312
338
|
return false
|
|
313
339
|
}
|
|
314
340
|
return false
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
from fastapi import FastAPI
|
|
2
|
+
from pydantic import BaseModel
|
|
3
|
+
|
|
4
|
+
app = FastAPI()
|
|
5
|
+
compressor = None
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class CompressRequest(BaseModel):
|
|
9
|
+
text: str
|
|
10
|
+
rate: float = 0.5
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@app.on_event("startup")
|
|
14
|
+
async def load_model():
|
|
15
|
+
global compressor
|
|
16
|
+
from llmlingua import PromptCompressor
|
|
17
|
+
|
|
18
|
+
compressor = PromptCompressor(
|
|
19
|
+
model_name="microsoft/llmlingua-2-xlm-roberta-large-meetingbank",
|
|
20
|
+
use_llmlingua2=True,
|
|
21
|
+
device_map="cpu",
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@app.get("/health")
|
|
26
|
+
async def health():
|
|
27
|
+
return {"status": "ok", "model_loaded": compressor is not None}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@app.post("/compress")
|
|
31
|
+
async def compress(payload: CompressRequest):
|
|
32
|
+
result = compressor.compress_prompt(
|
|
33
|
+
payload.text,
|
|
34
|
+
rate=payload.rate,
|
|
35
|
+
force_tokens=["\n", "?", "!", ".", ",", "'", '"'],
|
|
36
|
+
)
|
|
37
|
+
return {
|
|
38
|
+
"text": result["compressed_prompt"],
|
|
39
|
+
"original_tokens": result["origin_tokens"],
|
|
40
|
+
"compressed_tokens": result["compressed_tokens"],
|
|
41
|
+
}
|
package/stats.js
CHANGED
|
@@ -9,10 +9,30 @@ const c = {
|
|
|
9
9
|
red: '\x1b[31m',
|
|
10
10
|
}
|
|
11
11
|
|
|
12
|
+
// Strip secret values from a request URL before logging. Some providers
|
|
13
|
+
// (Gemini and OpenAI-compatible gateways) carry the API key in the query
|
|
14
|
+
// string (?key=, ?api_key=), which would otherwise land in stdout, log
|
|
15
|
+
// files, and the systemd journal. Path-relative URLs only — no base needed.
|
|
16
|
+
const SECRET_QUERY_PARAM = /^(key|api_key|apikey|access_token|token)$/i
|
|
17
|
+
export function redactUrl(url) {
|
|
18
|
+
if (typeof url !== 'string') return url
|
|
19
|
+
const q = url.indexOf('?')
|
|
20
|
+
if (q === -1) return url
|
|
21
|
+
const path = url.slice(0, q)
|
|
22
|
+
const query = url.slice(q + 1)
|
|
23
|
+
const redacted = query.split('&').map((pair) => {
|
|
24
|
+
const eq = pair.indexOf('=')
|
|
25
|
+
if (eq === -1) return pair
|
|
26
|
+
const name = pair.slice(0, eq)
|
|
27
|
+
return SECRET_QUERY_PARAM.test(name) ? `${name}=REDACTED` : pair
|
|
28
|
+
}).join('&')
|
|
29
|
+
return `${path}?${redacted}`
|
|
30
|
+
}
|
|
31
|
+
|
|
12
32
|
export function formatRequestLog(stats, session, providerName, url, bodySize, tokenCost, sessionBucket) {
|
|
13
33
|
const compressed = stats.filter(s => s.method)
|
|
14
34
|
const label = providerName || 'anthropic'
|
|
15
|
-
const path = url || '/v1/messages'
|
|
35
|
+
const path = redactUrl(url) || '/v1/messages'
|
|
16
36
|
const sizeInfo = bodySize ? ` ${c.dim}${fmtSize(bodySize)}${c.reset}` : ''
|
|
17
37
|
|
|
18
38
|
if (!compressed.length && !stats.length) {
|