@sliday/tamp 0.8.20 → 0.9.0

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.
@@ -0,0 +1,360 @@
1
+ // Passive token-usage telemetry for upstream responses.
2
+ //
3
+ // The proxy pipes upstream bytes to the client untouched. This tap sees the
4
+ // same chunks on a side path and pulls the provider's usage counters out of
5
+ // them, prompt-cache counters included, so a cache-breaking rewrite shows up as
6
+ // a falling hit rate instead of a silent bill. It never writes to, holds up, or
7
+ // alters what the client gets: write() copies only the bytes it must keep, and
8
+ // any internal failure turns the tap into a no-op.
9
+ //
10
+ // The format comes from the payload shape, not from a provider argument:
11
+ // Anthropic Messages message_start.message.usage + message_delta.usage, or top-level usage
12
+ // OpenAI Chat usage.prompt_tokens / prompt_tokens_details.cached_tokens
13
+ // OpenAI Responses response.*.response.usage, or top-level usage with input_tokens_details
14
+ // Gemini usageMetadata (last one wins)
15
+ //
16
+ // Normalized inputTokens means UNCACHED input: inputTokens + cacheReadTokens +
17
+ // cacheCreationTokens is the full prompt. Anthropic already reports it that
18
+ // way; OpenAI and Gemini include cached tokens in the prompt count, so we
19
+ // subtract.
20
+
21
+ import zlib from 'node:zlib'
22
+
23
+ const DEFAULT_MAX_BUFFER = 1024 * 1024
24
+
25
+ const num = v => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0)
26
+ const isObj = v => v !== null && typeof v === 'object' && !Array.isArray(v)
27
+
28
+ function normalized(provider, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens) {
29
+ return { provider, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens }
30
+ }
31
+
32
+ function fromOpenAIChat(u) {
33
+ const d = isObj(u.prompt_tokens_details) ? u.prompt_tokens_details : {}
34
+ const read = num(d.cached_tokens)
35
+ const write = num(d.cache_write_tokens)
36
+ return normalized('openai', Math.max(0, num(u.prompt_tokens) - read - write), num(u.completion_tokens), read, write)
37
+ }
38
+
39
+ function fromOpenAIResponses(u) {
40
+ const d = isObj(u.input_tokens_details) ? u.input_tokens_details : {}
41
+ const read = num(d.cached_tokens)
42
+ const write = num(d.cache_write_tokens)
43
+ return normalized('openai-responses', Math.max(0, num(u.input_tokens) - read - write), num(u.output_tokens), read, write)
44
+ }
45
+
46
+ function fromGemini(m) {
47
+ const read = num(m.cachedContentTokenCount)
48
+ // candidatesTokenCount excludes thinking; the other providers bill reasoning
49
+ // as output, so fold thoughtsTokenCount in to keep outputTokens comparable.
50
+ const output = num(m.candidatesTokenCount) + num(m.thoughtsTokenCount)
51
+ return normalized('gemini', Math.max(0, num(m.promptTokenCount) - read), output, read, 0)
52
+ }
53
+
54
+ function fromAnthropic(a) {
55
+ return normalized('anthropic', num(a.input_tokens), num(a.output_tokens),
56
+ num(a.cache_read_input_tokens), num(a.cache_creation_input_tokens))
57
+ }
58
+
59
+ const ANTHROPIC_FIELDS = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']
60
+
61
+ // Collects usage across a response. Later values win; Anthropic fields merge
62
+ // because message_start and message_delta each carry part of the picture.
63
+ function createExtractor() {
64
+ let result = null
65
+ let anthropic = null
66
+
67
+ function mergeAnthropic(u) {
68
+ if (!anthropic) anthropic = {}
69
+ for (const k of ANTHROPIC_FIELDS) if (u[k] != null) anthropic[k] = u[k]
70
+ result = fromAnthropic(anthropic)
71
+ }
72
+
73
+ function take(obj) {
74
+ if (Array.isArray(obj)) {
75
+ for (const item of obj) take(item)
76
+ return
77
+ }
78
+ if (!isObj(obj)) return
79
+ const type = typeof obj.type === 'string' ? obj.type : ''
80
+
81
+ if (type === 'message_start' && isObj(obj.message) && isObj(obj.message.usage)) return mergeAnthropic(obj.message.usage)
82
+ if (type === 'message_delta' && isObj(obj.usage)) return mergeAnthropic(obj.usage)
83
+ if (type.startsWith('response.') && isObj(obj.response) && isObj(obj.response.usage)) {
84
+ result = fromOpenAIResponses(obj.response.usage)
85
+ return
86
+ }
87
+ if (isObj(obj.usageMetadata)) {
88
+ result = fromGemini(obj.usageMetadata)
89
+ return
90
+ }
91
+ const u = obj.usage
92
+ if (!isObj(u)) return
93
+ if (u.prompt_tokens != null) {
94
+ result = fromOpenAIChat(u)
95
+ } else if (type === 'message' || u.cache_read_input_tokens != null || u.cache_creation_input_tokens != null) {
96
+ anthropic = null
97
+ mergeAnthropic(u)
98
+ } else if (obj.object === 'response' || isObj(u.input_tokens_details)) {
99
+ result = fromOpenAIResponses(u)
100
+ }
101
+ }
102
+
103
+ return { take, result: () => result }
104
+ }
105
+
106
+ // Incremental SSE reader. Splits on LF bytes (a UTF-8 multi-byte sequence never
107
+ // contains 0x0A, so decoding whole lines is safe), strips a trailing CR, joins
108
+ // data: lines per event, and hands each event's payload to onData. At most one
109
+ // partial line and one event's data stay in memory, each capped at max bytes;
110
+ // anything over the cap is dropped and parsing resumes at the next line/event.
111
+ function createSseReader(max, onData) {
112
+ let parts = []
113
+ let partLen = 0
114
+ let skipping = false
115
+ let data = []
116
+ let dataLen = 0
117
+ let dropEvent = false
118
+
119
+ const resetPartial = () => { parts = []; partLen = 0 }
120
+
121
+ function dispatch() {
122
+ if (!dropEvent && data.length) onData(data.join('\n'))
123
+ data = []
124
+ dataLen = 0
125
+ dropEvent = false
126
+ }
127
+
128
+ function line(str) {
129
+ if (str.endsWith('\r')) str = str.slice(0, -1)
130
+ if (str === '') return dispatch()
131
+ if (!str.startsWith('data:')) return
132
+ if (dropEvent) return
133
+ let v = str.slice(5)
134
+ if (v.startsWith(' ')) v = v.slice(1)
135
+ dataLen += v.length + 1
136
+ if (dataLen > max) {
137
+ data = []
138
+ dropEvent = true
139
+ return
140
+ }
141
+ data.push(v)
142
+ }
143
+
144
+ function endLine(seg) {
145
+ if (skipping) {
146
+ skipping = false
147
+ return
148
+ }
149
+ const total = partLen + seg.length
150
+ if (total > max) {
151
+ resetPartial()
152
+ return
153
+ }
154
+ if (partLen === 0) return line(seg.toString('utf8'))
155
+ parts.push(seg)
156
+ const full = Buffer.concat(parts, total)
157
+ resetPartial()
158
+ line(full.toString('utf8'))
159
+ }
160
+
161
+ function addPartial(seg) {
162
+ if (skipping || seg.length === 0) return
163
+ if (partLen + seg.length > max) {
164
+ resetPartial()
165
+ skipping = true
166
+ return
167
+ }
168
+ parts.push(Buffer.from(seg))
169
+ partLen += seg.length
170
+ }
171
+
172
+ return {
173
+ push(buf) {
174
+ let pos = 0
175
+ while (pos < buf.length) {
176
+ const nl = buf.indexOf(10, pos)
177
+ if (nl === -1) {
178
+ addPartial(buf.subarray(pos))
179
+ return
180
+ }
181
+ endLine(buf.subarray(pos, nl))
182
+ pos = nl + 1
183
+ }
184
+ },
185
+ end() {
186
+ if (!skipping && partLen) {
187
+ const full = Buffer.concat(parts, partLen)
188
+ resetPartial()
189
+ line(full.toString('utf8'))
190
+ }
191
+ dispatch()
192
+ },
193
+ }
194
+ }
195
+
196
+ // Bounded whole-body collector for non-streaming JSON. Over the cap it drops
197
+ // everything and reports overflow so the caller can give up.
198
+ function createJsonReader(max, onData) {
199
+ let parts = []
200
+ let len = 0
201
+ let over = false
202
+ return {
203
+ push(buf) {
204
+ if (over) return
205
+ if (len + buf.length > max) {
206
+ over = true
207
+ parts = []
208
+ return
209
+ }
210
+ parts.push(Buffer.from(buf))
211
+ len += buf.length
212
+ },
213
+ end() {
214
+ if (over || len === 0) return
215
+ const text = Buffer.concat(parts, len).toString('utf8')
216
+ parts = []
217
+ onData(text)
218
+ },
219
+ overflowed: () => over,
220
+ }
221
+ }
222
+
223
+ function pickDecoder(encoding, firstChunk) {
224
+ if (encoding === 'gzip' || encoding === 'x-gzip') return zlib.createGunzip()
225
+ if (encoding === 'br') return zlib.createBrotliDecompress()
226
+ if (encoding === 'deflate') {
227
+ // HTTP "deflate" is meant to be zlib-wrapped, but some servers send raw
228
+ // deflate. A zlib header has CM=8 and a header checksum divisible by 31.
229
+ const b0 = firstChunk[0]
230
+ const b1 = firstChunk.length > 1 ? firstChunk[1] : 0
231
+ const wrapped = (b0 & 0x0f) === 8 && ((b0 << 8) | b1) % 31 === 0
232
+ return wrapped ? zlib.createInflate() : zlib.createInflateRaw()
233
+ }
234
+ return null
235
+ }
236
+
237
+ function parseEncoding(value) {
238
+ if (value == null) return 'identity'
239
+ if (typeof value !== 'string') return null
240
+ const parts = value.split(',').map(s => s.trim().toLowerCase()).filter(Boolean)
241
+ if (parts.length === 0) return 'identity'
242
+ if (parts.length > 1) return null // stacked encodings: not worth the risk
243
+ return parts[0]
244
+ }
245
+
246
+ const NOOP = Object.freeze({ write() {}, end() {} })
247
+
248
+ export function createUsageTap({ contentType, contentEncoding, onUsage, maxBufferBytes } = {}) {
249
+ try {
250
+ if (typeof onUsage !== 'function' || typeof contentType !== 'string') return NOOP
251
+ const ct = contentType.toLowerCase()
252
+ const isSse = ct.includes('text/event-stream')
253
+ const isJson = !isSse && ct.includes('json')
254
+ if (!isSse && !isJson) return NOOP
255
+
256
+ const encoding = parseEncoding(contentEncoding)
257
+ if (encoding !== 'identity' && encoding !== 'gzip' && encoding !== 'x-gzip' && encoding !== 'br' && encoding !== 'deflate') return NOOP
258
+
259
+ const max = Number.isFinite(maxBufferBytes) && maxBufferBytes > 0 ? maxBufferBytes : DEFAULT_MAX_BUFFER
260
+ const extractor = createExtractor()
261
+ let dead = false
262
+ let finished = false
263
+ let decoder = null
264
+
265
+ const kill = () => {
266
+ dead = true
267
+ if (decoder) {
268
+ try { decoder.destroy() } catch {}
269
+ decoder = null
270
+ }
271
+ }
272
+
273
+ const parse = (text) => {
274
+ // Cheap filter: content deltas outnumber usage events by orders of magnitude.
275
+ if (!text.includes('"usage')) return
276
+ let obj
277
+ try { obj = JSON.parse(text) } catch { return }
278
+ extractor.take(obj)
279
+ }
280
+
281
+ const reader = isSse ? createSseReader(max, parse) : createJsonReader(max, parse)
282
+
283
+ const finish = () => {
284
+ if (dead || finished) return
285
+ finished = true
286
+ try {
287
+ reader.end()
288
+ const usage = extractor.result()
289
+ if (usage) onUsage(usage)
290
+ } catch {}
291
+ kill()
292
+ }
293
+
294
+ const feed = (buf) => {
295
+ if (dead) return
296
+ reader.push(buf)
297
+ if (reader.overflowed && reader.overflowed()) kill()
298
+ }
299
+
300
+ let decoderPicked = encoding === 'identity'
301
+
302
+ return {
303
+ write(chunk) {
304
+ if (dead || finished) return
305
+ try {
306
+ if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array)) return
307
+ if (chunk.length === 0) return
308
+ if (!decoderPicked) {
309
+ decoderPicked = true
310
+ decoder = pickDecoder(encoding, chunk)
311
+ if (!decoder) return kill()
312
+ decoder.on('data', (out) => { try { feed(out) } catch { kill() } })
313
+ decoder.on('error', kill)
314
+ decoder.on('end', finish)
315
+ }
316
+ if (decoder) {
317
+ // The decoder works off-thread; if compressed input piles up faster
318
+ // than it drains, stop rather than buffer the whole response.
319
+ if (decoder.writableLength + chunk.length > max) return kill()
320
+ decoder.write(Buffer.from(chunk))
321
+ } else {
322
+ feed(chunk)
323
+ }
324
+ } catch {
325
+ kill()
326
+ }
327
+ },
328
+ end() {
329
+ if (dead || finished) return
330
+ try {
331
+ if (decoder) decoder.end()
332
+ else if (decoderPicked) finish()
333
+ else kill() // encoded response with no body
334
+ } catch {
335
+ kill()
336
+ }
337
+ },
338
+ }
339
+ } catch {
340
+ return NOOP
341
+ }
342
+ }
343
+
344
+ export function createUsageTotals() {
345
+ const t = { requests: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 }
346
+ return {
347
+ record(usage) {
348
+ if (!isObj(usage)) return
349
+ t.requests++
350
+ t.inputTokens += num(usage.inputTokens)
351
+ t.outputTokens += num(usage.outputTokens)
352
+ t.cacheReadTokens += num(usage.cacheReadTokens)
353
+ t.cacheCreationTokens += num(usage.cacheCreationTokens)
354
+ },
355
+ snapshot() {
356
+ const denom = t.inputTokens + t.cacheReadTokens + t.cacheCreationTokens
357
+ return { ...t, cacheHitRate: denom > 0 ? t.cacheReadTokens / denom : null }
358
+ },
359
+ }
360
+ }
package/metadata.js CHANGED
@@ -25,6 +25,9 @@ export const EXTRA_STAGES = Object.freeze([
25
25
  'br-cache',
26
26
  'disclosure',
27
27
  'bm25-trim',
28
+ 'px-render',
29
+ 'stale-images',
30
+ 'stale-inputs',
28
31
  ])
29
32
 
30
33
  export const ALL_STAGES = Object.freeze([
@@ -39,6 +42,8 @@ export const ALL_STAGES = Object.freeze([
39
42
  // `disclosure` IS lossy: it drops body content from the outgoing turn and
40
43
  // relies on the model quoting the marker to trigger rehydration next turn.
41
44
  // `bm25-trim` drops low-relevance lines from huge tool_results (lossy).
45
+ // `stale-images` drops base64 images from older turns (lossy — recoverable
46
+ // only by re-reading the file, not from any tamp cache).
42
47
  export const LOSSY_STAGES = Object.freeze(new Set([
43
48
  'llmlingua',
44
49
  'foundation-models',
@@ -46,6 +51,9 @@ export const LOSSY_STAGES = Object.freeze(new Set([
46
51
  'strip-comments',
47
52
  'disclosure',
48
53
  'bm25-trim',
54
+ 'px-render',
55
+ 'stale-images',
56
+ 'stale-inputs',
49
57
  ]))
50
58
 
51
59
  export function isLossy(stage) {
@@ -92,6 +100,18 @@ export const STAGE_HINTS = Object.freeze({
92
100
  summary: 'query-aware line ranking, preserves first+last, bypasses dangerous tasks',
93
101
  setup: 'TAMP_STAGES=...,bm25-trim',
94
102
  },
103
+ 'px-render': {
104
+ summary: 'image-render dense tool_results, ~3x chars/token on vision-legible models (lossy)',
105
+ setup: 'npm i pxpipe-proxy && TAMP_STAGES=...,px-render',
106
+ },
107
+ 'stale-images': {
108
+ summary: 'drop base64 images from older turns, keep the newest 2 (lossy, invalidates prompt cache)',
109
+ setup: 'TAMP_STAGES=...,stale-images',
110
+ },
111
+ 'stale-inputs': {
112
+ summary: 'drop payloads from older tool_use inputs, keep headers and the newest 2 turns (lossy)',
113
+ setup: 'TAMP_STAGES=...,stale-inputs',
114
+ },
95
115
  })
96
116
 
97
117
  export const STAGE_DESCRIPTIONS = Object.freeze({
@@ -112,6 +132,9 @@ export const STAGE_DESCRIPTIONS = Object.freeze({
112
132
  'br-cache': 'Disk-backed Brotli store for large tool_results (lossless, opt-in)',
113
133
  disclosure: '3-tier summary for huge tool_results with on-demand rehydration (lossy, aggressive-only)',
114
134
  'bm25-trim': 'Drop low-relevance lines from huge tool_results via BM25 (lossy, aggressive-only)',
135
+ 'px-render': 'Render dense tool_results as PNG image blocks via pxpipe (lossy, model-gated, opt-in)',
136
+ 'stale-images': 'Evict base64 images from older turns, keeping the newest 2 (lossy, opt-in)',
137
+ 'stale-inputs': 'Prune payloads from older tool_use inputs, keeping call headers (lossy, opt-in)',
115
138
  })
116
139
 
117
140
  export const COMPRESSION_PRESETS = Object.freeze({
package/package.json CHANGED
@@ -14,12 +14,12 @@
14
14
  "sidecar/server.py",
15
15
  "sidecar/requirements.txt"
16
16
  ],
17
- "version": "0.8.20",
17
+ "version": "0.9.0",
18
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.",
19
19
  "type": "module",
20
20
  "main": "index.js",
21
21
  "bin": {
22
- "tamp": "./bin/tamp.js"
22
+ "tamp": "bin/tamp.js"
23
23
  },
24
24
  "scripts": {
25
25
  "start": "node bin/tamp.js",
@@ -43,7 +43,7 @@
43
43
  "license": "MIT",
44
44
  "repository": {
45
45
  "type": "git",
46
- "url": "https://github.com/sliday/tamp"
46
+ "url": "git+https://github.com/sliday/tamp.git"
47
47
  },
48
48
  "homepage": "https://github.com/sliday/tamp",
49
49
  "dependencies": {
@@ -54,5 +54,8 @@
54
54
  "fzstd": "^0.1.1",
55
55
  "ink": "^5.2.0",
56
56
  "react": "^18.2.0"
57
+ },
58
+ "optionalDependencies": {
59
+ "pxpipe-proxy": "^0.16.0"
57
60
  }
58
61
  }
package/providers.js CHANGED
@@ -8,6 +8,13 @@ function applyTargets(body, targets) {
8
8
  }
9
9
  }
10
10
 
11
+ // Stable identity for a target so the replay memo can find it again in a
12
+ // later request. Sub-blocks of array content get `#j`. No id, no replay.
13
+ function targetId(id, j) {
14
+ if (typeof id !== 'string' || !id) return undefined
15
+ return j === undefined ? id : `${id}#${j}`
16
+ }
17
+
11
18
  function findLatestEligibleGroup(items, extractTargets) {
12
19
  let fallback = null
13
20
  for (let i = items.length - 1; i >= 0; i--) {
@@ -35,12 +42,12 @@ function extractAnthropicMessageTargets(msg, mi) {
35
42
  }
36
43
 
37
44
  if (typeof block.content === 'string') {
38
- targets.push({ path: ['messages', mi, 'content', i, 'content'], text: block.content, index: i })
45
+ targets.push({ path: ['messages', mi, 'content', i, 'content'], text: block.content, index: i, id: targetId(block.tool_use_id) })
39
46
  } else if (Array.isArray(block.content)) {
40
47
  for (let j = 0; j < block.content.length; j++) {
41
48
  const sub = block.content[j]
42
49
  if (sub && sub.type === 'text') {
43
- targets.push({ path: ['messages', mi, 'content', i, 'content', j, 'text'], text: sub.text, index: i })
50
+ targets.push({ path: ['messages', mi, 'content', i, 'content', j, 'text'], text: sub.text, index: i, id: targetId(block.tool_use_id, j) })
44
51
  }
45
52
  }
46
53
  }
@@ -260,14 +267,14 @@ function extractOpenAIChatTargets(msg, i) {
260
267
  if (!block || typeof block !== 'object') continue
261
268
  if (OPENAI_COMPAT_SKIP_BLOCK_TYPES.has(block.type)) continue
262
269
  if (block.type === 'text' && typeof block.text === 'string') {
263
- targets.push({ path: ['messages', i, 'content', j, 'text'], text: block.text, index: i })
270
+ targets.push({ path: ['messages', i, 'content', j, 'text'], text: block.text, index: i, id: targetId(msg.tool_call_id, j) })
264
271
  }
265
272
  }
266
273
  return targets
267
274
  }
268
275
  return []
269
276
  }
270
- return [{ path: ['messages', i, 'content'], text: msg.content, index: i }]
277
+ return [{ path: ['messages', i, 'content'], text: msg.content, index: i, id: targetId(msg.tool_call_id) }]
271
278
  }
272
279
 
273
280
  const openai = {
@@ -403,6 +410,7 @@ function extractGeminiContentTargets(content, ci) {
403
410
  text,
404
411
  index: pi,
405
412
  wasObject: typeof resp !== 'string',
413
+ id: targetId(part.functionResponse.id),
406
414
  })
407
415
  }
408
416
 
@@ -484,13 +492,13 @@ function isResponsesToolOutput(type) {
484
492
  function extractOpenAIResponsesTargets(item, i) {
485
493
  if (!isResponsesToolOutput(item?.type)) return []
486
494
  if (typeof item.output === 'string') {
487
- return [{ path: ['input', i, 'output'], text: item.output, index: i }]
495
+ return [{ path: ['input', i, 'output'], text: item.output, index: i, id: targetId(item.call_id) }]
488
496
  }
489
497
  if (Array.isArray(item.output)) {
490
498
  const targets = []
491
499
  for (const [j, part] of item.output.entries()) {
492
500
  if (part?.type === 'input_text' && typeof part.text === 'string') {
493
- targets.push({ path: ['input', i, 'output', j, 'text'], text: part.text, index: i })
501
+ targets.push({ path: ['input', i, 'output', j, 'text'], text: part.text, index: i, id: targetId(item.call_id, j) })
494
502
  }
495
503
  }
496
504
  return targets