@sliday/tamp 0.5.9 → 0.8.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.
package/index.js CHANGED
@@ -5,9 +5,36 @@ import zlib from 'node:zlib'
5
5
  import * as fzstd from 'fzstd'
6
6
  import { loadConfig } from './config.js'
7
7
  import { compressRequest } from './compress.js'
8
- import { detectProvider } from './providers.js'
8
+ import { detectProvider, detectOpenAIAuthMode, resolveOpenAIUpstream } from './providers.js'
9
9
  import { createSession, formatRequestLog } from './stats.js'
10
10
  import { createSessionStore, deriveSessionKey } from './session-graph.js'
11
+ import { createReadCache } from './lib/read-cache.js'
12
+ import { createBrCache } from './lib/br-cache.js'
13
+ import { generateOutputRules, PER_AGENT_OVERRIDES } from './lib/rules-generator.js'
14
+
15
+ // Regex source strings used by the task classifier — surfaced via
16
+ // /caveman-help so operators can see exactly how their inputs are scored.
17
+ const CLASSIFIER_PATTERNS = Object.freeze({
18
+ safe: [
19
+ '^(add|remove|update|set|unset)\\s+(env\\s+var|environment variable|config|configuration|\\w+=)',
20
+ '^fix\\s+typo',
21
+ '^update\\s+(README|readme|documentation|docs)',
22
+ '^(install|uninstall).*package',
23
+ '^add\\s+\\w+\\s+(as\\s+)?dependency',
24
+ '^update\\s+version',
25
+ '^(format|lint|fmt)|run linter',
26
+ ],
27
+ dangerous: [
28
+ 'security|vulnerability|exploit|attack',
29
+ 'debug|investigate|diagnose|troubleshoot',
30
+ 'memory leak|performance|optimization|optimize',
31
+ '^refactor|^architecture|^design',
32
+ '^fix\\s+bug',
33
+ '^explain|^why|^how\\s+(does|work)',
34
+ 'test|spec|coverage',
35
+ ],
36
+ complex: 'default when neither safe nor dangerous patterns match',
37
+ })
11
38
 
12
39
  function buildUpstreamUrl(reqPath, base) {
13
40
  const parsed = new URL(base)
@@ -24,19 +51,53 @@ function buildUpstreamUrl(reqPath, base) {
24
51
  return parsed
25
52
  }
26
53
 
27
- export function createProxy(overrides = {}) {
28
- const base = loadConfig()
54
+ // Pick the upstream base + path transform for a resolved provider. For
55
+ // OpenAI-like providers we inspect auth headers to detect Codex CLI ChatGPT
56
+ // Plus mode (OAuth JWT + chatgpt-account-id), which must be routed to
57
+ // chatgpt.com/backend-api/codex instead of api.openai.com.
58
+ export function resolveUpstream(provider, headers, config) {
59
+ const defaultBase = config.upstreams?.[provider.name] || config.upstream
60
+ if (config.disableChatgptRoute) {
61
+ return { base: defaultBase, transformPath: (p) => p, mode: 'api-key' }
62
+ }
63
+ if (provider.name === 'openai' || provider.name === 'openai-responses') {
64
+ const mode = detectOpenAIAuthMode(headers)
65
+ if (mode === 'chatgpt-oauth') {
66
+ return resolveOpenAIUpstream({
67
+ mode,
68
+ base: config.chatgptUpstream || 'https://chatgpt.com',
69
+ providerName: provider.name,
70
+ })
71
+ }
72
+ }
73
+ return { base: defaultBase, transformPath: (p) => p, mode: 'api-key' }
74
+ }
75
+
76
+ export function createProxy(overrides = {}, loadOpts = {}) {
77
+ const base = loadConfig(process.env, loadOpts)
29
78
  const config = { ...base, ...overrides }
30
79
  if (overrides.upstream && !overrides.upstreams) {
31
- config.upstreams = { anthropic: overrides.upstream, openai: overrides.upstream, 'openai-responses': overrides.upstream, gemini: overrides.upstream }
80
+ config.upstreams = {
81
+ anthropic: overrides.upstream,
82
+ openai: overrides.upstream,
83
+ 'openai-responses': overrides.upstream,
84
+ gemini: overrides.upstream,
85
+ kimi: overrides.upstream,
86
+ moonshot: overrides.upstream,
87
+ }
32
88
  }
33
89
  const session = createSession()
34
- const sessionStore = createSessionStore()
35
- return { config, session, sessionStore, server: _createServer(config, session, sessionStore) }
90
+ const brCache = (config.stages?.includes('graph') || config.stages?.includes('br-cache') || config.stages?.includes('disclosure'))
91
+ ? createBrCache()
92
+ : null
93
+ const sessionStore = createSessionStore({ brCache })
94
+ const readCache = createReadCache()
95
+ return { config, session, sessionStore, readCache, brCache, server: _createServer(config, session, sessionStore, readCache, brCache) }
36
96
  }
37
97
 
38
- function _createServer(config, session, sessionStore) {
98
+ function _createServer(config, session, sessionStore, readCache, brCache) {
39
99
  const log = createRequestLogger(config)
100
+ const disclosureTotals = { rehydrated: 0, missed: 0, disclosed: 0 }
40
101
 
41
102
  function openUpstream(method, upstreamUrl, headers, res) {
42
103
  const mod = upstreamUrl.protocol === 'https:' ? https : http
@@ -120,12 +181,32 @@ return http.createServer(async (req, res) => {
120
181
  charsOriginal: totals.totalOriginal,
121
182
  blocksCompressed: totals.compressionCount,
122
183
  },
184
+ disclosure: disclosureTotals,
123
185
  })
124
186
  res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) })
125
187
  return res.end(req.method === 'HEAD' ? undefined : body)
126
188
  }
127
189
 
128
- const provider = detectProvider(req.method, req.url)
190
+ // Caveman Mode diagnostic endpoint (v1.5.0 parity)
191
+ if (req.url === '/caveman-help' && (req.method === 'GET' || req.method === 'HEAD')) {
192
+ const sampleSafe = generateOutputRules(config.outputMode, 'safe', config.agent)
193
+ const sampleDangerous = generateOutputRules(config.outputMode, 'dangerous', config.agent)
194
+ const body = JSON.stringify({
195
+ mode: config.outputMode,
196
+ defaultFromEnv: config.outputModeDefault || null,
197
+ agent: config.agent || null,
198
+ taskClassifierRules: CLASSIFIER_PATTERNS,
199
+ sampleInjection: {
200
+ safe: sampleSafe || null,
201
+ dangerous: sampleDangerous || null,
202
+ },
203
+ perAgent: Object.keys(PER_AGENT_OVERRIDES),
204
+ })
205
+ res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(body) })
206
+ return res.end(req.method === 'HEAD' ? undefined : body)
207
+ }
208
+
209
+ const provider = detectProvider(req.method, req.url, req.headers)
129
210
 
130
211
  if (!provider) {
131
212
  log(`[tamp] ${req.method} ${req.url}`)
@@ -133,8 +214,10 @@ return http.createServer(async (req, res) => {
133
214
  return pipeRequest(req, res, upstreamUrl)
134
215
  }
135
216
 
136
- const upstream = config.upstreams?.[provider.name] || config.upstream
137
- const reqUrl = provider.normalizeUrl ? provider.normalizeUrl(req.url) : req.url
217
+ const route = resolveUpstream(provider, req.headers, config)
218
+ const upstream = route.base
219
+ const normalizedUrl = provider.normalizeUrl ? provider.normalizeUrl(req.url) : req.url
220
+ const reqUrl = route.transformPath(normalizedUrl)
138
221
  const upstreamUrl = buildUpstreamUrl(reqUrl, upstream)
139
222
 
140
223
  const chunks = []
@@ -211,16 +294,24 @@ return http.createServer(async (req, res) => {
211
294
  try {
212
295
  const parsed = JSON.parse(textBody.toString('utf-8'))
213
296
 
214
- const sessionBucket = config.stages?.includes('graph')
215
- ? sessionStore.getBucket(deriveSessionKey(req.headers))
297
+ const sessionKey = (config.stages?.includes('graph') || config.stages?.includes('read-diff'))
298
+ ? deriveSessionKey(req.headers)
299
+ : null
300
+ const sessionBucket = config.stages?.includes('graph') && sessionKey
301
+ ? sessionStore.getBucket(sessionKey)
216
302
  : null
217
- const { body, stats } = await compressRequest(parsed, { ...config, sessionBucket }, provider)
303
+ const { body, stats, disclosure } = await compressRequest(parsed, { ...config, sessionBucket, sessionKey, readCache, brCache }, provider)
218
304
  finalBody = Buffer.from(JSON.stringify(body), 'utf-8')
219
305
  // Send uncompressed — simpler and content-length is accurate
220
306
  if (decompressed) delete headers['content-encoding']
221
307
 
222
308
  session.record(stats)
223
- log(formatRequestLog(stats, session, provider.name, req.url, textBody.length, config.tokenCost))
309
+ if (disclosure) {
310
+ disclosureTotals.rehydrated += disclosure.rehydrated || 0
311
+ disclosureTotals.missed += disclosure.missed || 0
312
+ disclosureTotals.disclosed += disclosure.disclosed || 0
313
+ }
314
+ log(formatRequestLog(stats, session, provider.name, req.url, textBody.length, config.tokenCost, sessionBucket))
224
315
  config.onCompress?.(stats, session.getTotals(), { provider: provider.name, url: req.url, bodySize: textBody.length })
225
316
  } catch (err) {
226
317
  log(`[tamp] passthrough (parse error): ${err.message}`)
package/lib/bm25.js ADDED
@@ -0,0 +1,194 @@
1
+ // Query-aware line ranker for huge tool_result bodies (Phase 6).
2
+ //
3
+ // Pure-JS BM25 scorer, zero deps. Given a query (last user message) and a
4
+ // large body, score each line against the query using Okapi BM25 and keep
5
+ // the highest-scoring lines until a token budget is satisfied. First and
6
+ // last lines are always preserved as context anchors, and collapsed ranges
7
+ // are replaced by a "[... N lines omitted, N chars ...]" marker so the
8
+ // model can reason about the elision.
9
+ //
10
+ // This primitive is reusable: any future stage that wants "keep the most
11
+ // relevant N lines" can import tokenize/bm25Scores directly.
12
+
13
+ import { countTokens } from '@anthropic-ai/tokenizer'
14
+
15
+ // --- Tokenizer ---
16
+ // Preserve identifiers with dots/underscores/dashes (e.g. `user.email`,
17
+ // `max_tokens`, `read-diff`) as single tokens. We collapse intra-word
18
+ // separators to underscore before splitting on non-word characters. Single
19
+ // character tokens are dropped (too noisy for BM25 on short queries).
20
+ const INTRA_WORD_RE = /([A-Za-z0-9])[._\-]+([A-Za-z0-9])/g
21
+ const SPLIT_RE = /[^A-Za-z0-9_]+/
22
+
23
+ export function tokenize(text) {
24
+ if (typeof text !== 'string' || text.length === 0) return []
25
+ let normalized = text.toLowerCase()
26
+ // Collapse intra-word separators. Run twice so chains like `a.b.c` fully
27
+ // collapse (first pass joins a.b, second joins a_b.c -> a_b_c).
28
+ normalized = normalized.replace(INTRA_WORD_RE, '$1_$2')
29
+ normalized = normalized.replace(INTRA_WORD_RE, '$1_$2')
30
+ const raw = normalized.split(SPLIT_RE)
31
+ const out = []
32
+ for (const tok of raw) {
33
+ if (tok.length < 2) continue
34
+ out.push(tok)
35
+ }
36
+ return out
37
+ }
38
+
39
+ // --- BM25 ---
40
+ // Standard Okapi BM25. Each document is a line; query is the user's last
41
+ // message. Returns Float64Array of scores aligned with the documents array.
42
+ export function bm25Scores(documents, query, { k1 = 1.5, b = 0.75 } = {}) {
43
+ const N = documents.length
44
+ const scores = new Float64Array(N)
45
+ if (N === 0) return scores
46
+
47
+ const qTokens = tokenize(query)
48
+ if (qTokens.length === 0) return scores
49
+
50
+ // Tokenize docs + build doc stats.
51
+ const docTokens = new Array(N)
52
+ const docLens = new Float64Array(N)
53
+ let totalLen = 0
54
+ for (let i = 0; i < N; i++) {
55
+ const toks = tokenize(documents[i])
56
+ docTokens[i] = toks
57
+ docLens[i] = toks.length
58
+ totalLen += toks.length
59
+ }
60
+ const avgdl = N > 0 ? totalLen / N : 0
61
+ if (avgdl === 0) return scores
62
+
63
+ // Document-frequency per unique query term.
64
+ const uniqQ = Array.from(new Set(qTokens))
65
+ const df = new Map()
66
+ for (const term of uniqQ) {
67
+ let count = 0
68
+ for (let i = 0; i < N; i++) {
69
+ if (docTokens[i].includes(term)) count += 1
70
+ }
71
+ df.set(term, count)
72
+ }
73
+
74
+ // Precompute IDF per term (Okapi BM25 variant with +1 smoothing).
75
+ const idf = new Map()
76
+ for (const term of uniqQ) {
77
+ const n = df.get(term) || 0
78
+ const v = Math.log(1 + (N - n + 0.5) / (n + 0.5))
79
+ idf.set(term, v)
80
+ }
81
+
82
+ for (let i = 0; i < N; i++) {
83
+ const dl = docLens[i]
84
+ if (dl === 0) continue
85
+ // Term-frequency table for this doc (only for query terms we care about).
86
+ const tf = new Map()
87
+ const toks = docTokens[i]
88
+ for (const t of toks) {
89
+ if (!idf.has(t)) continue
90
+ tf.set(t, (tf.get(t) || 0) + 1)
91
+ }
92
+ let s = 0
93
+ for (const term of uniqQ) {
94
+ const f = tf.get(term) || 0
95
+ if (f === 0) continue
96
+ const num = f * (k1 + 1)
97
+ const den = f + k1 * (1 - b + b * (dl / avgdl))
98
+ s += idf.get(term) * (num / den)
99
+ }
100
+ scores[i] = s
101
+ }
102
+ return scores
103
+ }
104
+
105
+ // --- Line trimmer ---
106
+ // Keep top-K highest-scoring lines until `targetTokens` is consumed. First
107
+ // and last line are always preserved. Returns null when text is already
108
+ // under budget, has fewer than `minLines` lines, or trimming didn't help.
109
+ //
110
+ // Output shape:
111
+ // { text, keptLines, droppedLines, originalTokens, trimmedTokens, originalLines }
112
+ export function trimLinesByRelevance(text, query, { targetTokens = 4096, minLines = 10 } = {}) {
113
+ if (typeof text !== 'string' || text.length === 0) return null
114
+
115
+ const originalTokens = countTokens(text)
116
+ if (originalTokens <= targetTokens) return null
117
+
118
+ const lines = text.split('\n')
119
+ const N = lines.length
120
+ if (N < minLines) return null
121
+
122
+ // Per-line token costs (includes the trailing newline for all but the last
123
+ // line; we approximate by counting each line once and adding N-1 tokens).
124
+ const lineTokens = new Array(N)
125
+ for (let i = 0; i < N; i++) {
126
+ lineTokens[i] = countTokens(lines[i])
127
+ }
128
+ const newlineCost = Math.max(0, N - 1)
129
+
130
+ const scores = bm25Scores(lines, query)
131
+
132
+ // Always-keep set: first + last as anchors.
133
+ const keep = new Uint8Array(N)
134
+ keep[0] = 1
135
+ keep[N - 1] = 1
136
+ let budgetUsed = lineTokens[0] + (N > 1 ? lineTokens[N - 1] : 0)
137
+ // Rough marker cost reserved per collapsed gap; we'll reconcile below.
138
+ const MARKER_RESERVE = 16
139
+
140
+ // Sort remaining lines by score desc, then by position asc (stable earlier
141
+ // context preferred on ties). We pick greedily until budget is hit.
142
+ const candidates = []
143
+ for (let i = 1; i < N - 1; i++) {
144
+ candidates.push({ i, score: scores[i], len: lineTokens[i] })
145
+ }
146
+ candidates.sort((a, b) => (b.score - a.score) || (a.i - b.i))
147
+
148
+ for (const c of candidates) {
149
+ if (budgetUsed + c.len > targetTokens) continue
150
+ keep[c.i] = 1
151
+ budgetUsed += c.len
152
+ }
153
+
154
+ // If even the anchors + marker exceed budget, still proceed — we need to
155
+ // produce SOME trim. But if nothing was dropped at all, bail.
156
+ let keptLines = 0
157
+ for (let i = 0; i < N; i++) keptLines += keep[i]
158
+ const droppedLines = N - keptLines
159
+ if (droppedLines === 0) return null
160
+
161
+ // Assemble output, collapsing contiguous dropped runs into drop markers.
162
+ const out = []
163
+ let i = 0
164
+ while (i < N) {
165
+ if (keep[i]) {
166
+ out.push(lines[i])
167
+ i += 1
168
+ continue
169
+ }
170
+ let j = i
171
+ let chars = 0
172
+ while (j < N && !keep[j]) { chars += lines[j].length + 1; j += 1 }
173
+ const runLen = j - i
174
+ out.push(`[... ${runLen} lines omitted, ${chars} chars ...]`)
175
+ i = j
176
+ }
177
+
178
+ const trimmedText = out.join('\n')
179
+ const trimmedTokens = countTokens(trimmedText)
180
+ // Defensive: if trimming somehow grew the text, don't return a trim.
181
+ if (trimmedTokens >= originalTokens) return null
182
+
183
+ return {
184
+ text: trimmedText,
185
+ keptLines,
186
+ droppedLines,
187
+ originalTokens,
188
+ trimmedTokens,
189
+ originalLines: N,
190
+ budgetUsed,
191
+ newlineCost,
192
+ markerReserve: MARKER_RESERVE,
193
+ }
194
+ }
@@ -0,0 +1,157 @@
1
+ // Disk-backed, content-addressable Brotli store for large bodies.
2
+ // Hash = SHA-256(text).digest('hex'); file path = <cacheDir>/<hash[0:2]>/<hash>.br
3
+ //
4
+ // Intended as the storage substrate for Phase 5 progressive disclosure. In
5
+ // Phase 3 we just offload large referenced bodies out of RAM and surface
6
+ // counters in the banner — we do NOT emit new markers upstream yet.
7
+
8
+ import { createHash } from 'node:crypto'
9
+ import { brotliCompressSync, brotliDecompressSync, constants as zlibConstants } from 'node:zlib'
10
+ import {
11
+ mkdirSync,
12
+ writeFileSync,
13
+ readFileSync,
14
+ renameSync,
15
+ unlinkSync,
16
+ readdirSync,
17
+ statSync,
18
+ utimesSync,
19
+ existsSync,
20
+ } from 'node:fs'
21
+ import { join } from 'node:path'
22
+ import { homedir, tmpdir } from 'node:os'
23
+
24
+ const DEFAULT_MAX_BYTES = 512 * 1024 * 1024
25
+ const DEFAULT_MIN_SIZE = 8 * 1024
26
+ const BROTLI_QUALITY = 4
27
+
28
+ function defaultCacheDir() {
29
+ const home = homedir() || tmpdir()
30
+ return join(home, '.cache', 'tamp', 'br')
31
+ }
32
+
33
+ function hashText(text) {
34
+ return createHash('sha256').update(text).digest('hex')
35
+ }
36
+
37
+ function filePathFor(cacheDir, hash) {
38
+ return join(cacheDir, hash.slice(0, 2), `${hash}.br`)
39
+ }
40
+
41
+ export function createBrCache({ cacheDir = defaultCacheDir(), maxBytes = DEFAULT_MAX_BYTES, minSize = DEFAULT_MIN_SIZE } = {}) {
42
+ try { mkdirSync(cacheDir, { recursive: true }) } catch { /* ignore */ }
43
+
44
+ let hits = 0
45
+ let misses = 0
46
+ let evictions = 0
47
+
48
+ function scan() {
49
+ const files = []
50
+ let totalBytes = 0
51
+ let shards
52
+ try { shards = readdirSync(cacheDir) } catch { return { files, totalBytes } }
53
+ for (const shard of shards) {
54
+ const shardPath = join(cacheDir, shard)
55
+ let entries
56
+ try { entries = readdirSync(shardPath) } catch { continue }
57
+ for (const name of entries) {
58
+ if (!name.endsWith('.br')) continue
59
+ const p = join(shardPath, name)
60
+ try {
61
+ const st = statSync(p)
62
+ if (!st.isFile()) continue
63
+ files.push({ path: p, size: st.size, atimeMs: st.atimeMs })
64
+ totalBytes += st.size
65
+ } catch { /* skip unreadable */ }
66
+ }
67
+ }
68
+ return { files, totalBytes }
69
+ }
70
+
71
+ function pruneInternal() {
72
+ const { files, totalBytes } = scan()
73
+ if (totalBytes <= maxBytes) return { totalBytes, evicted: 0 }
74
+ files.sort((a, b) => a.atimeMs - b.atimeMs) // oldest access first
75
+ let current = totalBytes
76
+ let evicted = 0
77
+ for (const f of files) {
78
+ if (current <= maxBytes) break
79
+ try { unlinkSync(f.path); current -= f.size; evicted += 1; evictions += 1 } catch { /* ignore */ }
80
+ }
81
+ return { totalBytes: current, evicted }
82
+ }
83
+
84
+ function put(text) {
85
+ if (typeof text !== 'string') return null
86
+ const byteLen = Buffer.byteLength(text, 'utf8')
87
+ if (byteLen < minSize) return null
88
+
89
+ const hash = hashText(text)
90
+ const finalPath = filePathFor(cacheDir, hash)
91
+ const shardDir = join(cacheDir, hash.slice(0, 2))
92
+
93
+ let brotliBytes
94
+ if (existsSync(finalPath)) {
95
+ try {
96
+ brotliBytes = statSync(finalPath).size
97
+ // Refresh access time for LRU.
98
+ const now = new Date()
99
+ try { utimesSync(finalPath, now, now) } catch { /* ignore */ }
100
+ return { hash, storedBytes: byteLen, brotliBytes }
101
+ } catch { /* fall through and rewrite */ }
102
+ }
103
+
104
+ try { mkdirSync(shardDir, { recursive: true }) } catch { /* ignore */ }
105
+
106
+ let compressed
107
+ try {
108
+ compressed = brotliCompressSync(Buffer.from(text, 'utf8'), {
109
+ params: { [zlibConstants.BROTLI_PARAM_QUALITY]: BROTLI_QUALITY },
110
+ })
111
+ } catch {
112
+ return null
113
+ }
114
+
115
+ const tmpPath = `${finalPath}.tmp`
116
+ try {
117
+ writeFileSync(tmpPath, compressed)
118
+ renameSync(tmpPath, finalPath)
119
+ brotliBytes = compressed.length
120
+ } catch {
121
+ try { unlinkSync(tmpPath) } catch { /* ignore */ }
122
+ return null
123
+ }
124
+
125
+ pruneInternal()
126
+ return { hash, storedBytes: byteLen, brotliBytes }
127
+ }
128
+
129
+ function get(hash) {
130
+ if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) { misses += 1; return null }
131
+ const p = filePathFor(cacheDir, hash)
132
+ let buf
133
+ try { buf = readFileSync(p) } catch { misses += 1; return null }
134
+ let decoded
135
+ try { decoded = brotliDecompressSync(buf) } catch { misses += 1; return null }
136
+ const now = new Date()
137
+ try { utimesSync(p, now, now) } catch { /* ignore */ }
138
+ hits += 1
139
+ return decoded.toString('utf8')
140
+ }
141
+
142
+ function has(hash) {
143
+ if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) return false
144
+ return existsSync(filePathFor(cacheDir, hash))
145
+ }
146
+
147
+ function stats() {
148
+ const { files, totalBytes } = scan()
149
+ return { entries: files.length, totalBytes, hits, misses, evictions }
150
+ }
151
+
152
+ function prune() {
153
+ return pruneInternal()
154
+ }
155
+
156
+ return { put, get, has, stats, prune, minSize, cacheDir }
157
+ }
@@ -0,0 +1,124 @@
1
+ // Progressive disclosure for huge tool_result bodies (Phase 5).
2
+ //
3
+ // Given a tool_result text body >= 32 KB, emit a 3-tier summary in the
4
+ // outgoing turn (signature + head excerpt + ellipsis + tail excerpt + marker),
5
+ // and retain the full body in the br-cache (built in Phase 3). If the model
6
+ // later quotes the marker in a follow-up request, `rehydrateReferences`
7
+ // injects the full body back in before we forward upstream.
8
+ //
9
+ // Marker format - strict, regex-extractable, non-ambiguous:
10
+ // <tamp-ref:v1:HEXHASH:BYTES>
11
+ // v1 = format version. BYTES = original body byte length.
12
+
13
+ import { createHash } from 'node:crypto'
14
+
15
+ export const REF_MARKER = /<tamp-ref:v1:([a-f0-9]{64}):(\d+)>/g
16
+
17
+ function sha256(text) {
18
+ return createHash('sha256').update(text).digest('hex')
19
+ }
20
+
21
+ function utf8Bytes(text) {
22
+ return Buffer.byteLength(text, 'utf8')
23
+ }
24
+
25
+ // Slice by UTF-8 byte count without splitting a codepoint mid-sequence.
26
+ function sliceHeadBytes(text, bytes) {
27
+ const buf = Buffer.from(text, 'utf8')
28
+ if (buf.length <= bytes) return text
29
+ let cut = bytes
30
+ while (cut > 0 && (buf[cut] & 0xC0) === 0x80) cut -= 1
31
+ return buf.slice(0, cut).toString('utf8')
32
+ }
33
+
34
+ function sliceTailBytes(text, bytes) {
35
+ const buf = Buffer.from(text, 'utf8')
36
+ if (buf.length <= bytes) return text
37
+ let cut = buf.length - bytes
38
+ while (cut < buf.length && (buf[cut] & 0xC0) === 0x80) cut += 1
39
+ return buf.slice(cut).toString('utf8')
40
+ }
41
+
42
+ function formatSize(bytes) {
43
+ if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
44
+ if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`
45
+ return `${bytes} B`
46
+ }
47
+
48
+ /**
49
+ * Build a 3-tier summary block for a large tool_result body.
50
+ * Returns null if the body is smaller than minSize.
51
+ * Shape: { summary, hash, originalBytes, summaryBytes }.
52
+ */
53
+ export function summarize(text, { hash, minSize = 32 * 1024, headBytes = 2048, tailBytes = 1024 } = {}) {
54
+ if (typeof text !== 'string') return null
55
+ const originalBytes = utf8Bytes(text)
56
+ if (originalBytes < minSize) return null
57
+
58
+ const fullHash = hash || sha256(text)
59
+ const head = sliceHeadBytes(text, headBytes)
60
+ const tail = sliceTailBytes(text, tailBytes)
61
+ const omitted = originalBytes - utf8Bytes(head) - utf8Bytes(tail)
62
+
63
+ const signature = `[tamp-disclosure v1] ${formatSize(originalBytes)}, sha256:${fullHash.slice(0, 12)}... - quote <tamp-ref:v1:${fullHash}:${originalBytes}> to expand`
64
+ const ellipsis = `\n[... ${formatSize(Math.max(0, omitted))} omitted ...]\n`
65
+ const marker = `<tamp-ref:v1:${fullHash}:${originalBytes}>`
66
+
67
+ const summary = `${signature}\n${head}${ellipsis}${tail}\n${marker}`
68
+ return { summary, hash: fullHash, originalBytes, summaryBytes: utf8Bytes(summary) }
69
+ }
70
+
71
+ function freshMarkerRegex() {
72
+ return new RegExp(REF_MARKER.source, REF_MARKER.flags)
73
+ }
74
+
75
+ /**
76
+ * Scan a provider request body for <tamp-ref:v1:HASH:BYTES> markers that
77
+ * the model quoted back. Returns an array of { hash, bytes, path, match }.
78
+ * Path and shape are defined by the provider's findReferences method.
79
+ */
80
+ export function findReferenceQuotes(body, provider) {
81
+ if (typeof provider?.findReferences === 'function') {
82
+ return provider.findReferences(body)
83
+ }
84
+ return []
85
+ }
86
+
87
+ /**
88
+ * Rehydrate the previous turn's full body into the outgoing request.
89
+ * For each reference quote found, look up the hash in brCache and replace
90
+ * the marker with an expanded block. Safe no-op on cache miss.
91
+ */
92
+ export function rehydrateReferences(body, provider, brCache) {
93
+ if (!provider || !brCache || typeof brCache.get !== 'function') return { rehydrated: 0, missed: 0 }
94
+ const refs = findReferenceQuotes(body, provider)
95
+ if (!refs.length) return { rehydrated: 0, missed: 0 }
96
+
97
+ const seen = new Map()
98
+ let rehydrated = 0
99
+ let missed = 0
100
+
101
+ for (const ref of refs) {
102
+ let entry = seen.get(ref.hash)
103
+ if (!entry) {
104
+ const full = brCache.get(ref.hash)
105
+ if (full == null) {
106
+ entry = { full: null }
107
+ } else {
108
+ const header = `<tamp-ref:v1:${ref.hash} expanded - ${utf8Bytes(full)} bytes follow>`
109
+ entry = { full: `${header}\n${full}\n</tamp-ref expanded>` }
110
+ }
111
+ seen.set(ref.hash, entry)
112
+ }
113
+ if (entry.full == null) { missed += 1; ref.missed = true }
114
+ else { rehydrated += 1; ref.expansion = entry.full }
115
+ }
116
+
117
+ if (rehydrated === 0) return { rehydrated: 0, missed }
118
+ if (typeof provider.applyRehydration === 'function') {
119
+ provider.applyRehydration(body, refs)
120
+ }
121
+ return { rehydrated, missed }
122
+ }
123
+
124
+ export const _internal = { sliceHeadBytes, sliceTailBytes, utf8Bytes, freshMarkerRegex, sha256 }