@agentpro/scroll 0.0.0-stage → 2.5.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/AGENTS.md +55 -0
- package/LICENSE +21 -0
- package/README.md +293 -2
- package/SPEC.md +1079 -0
- package/bin/scroll.js +8 -0
- package/docs/prompt-caching.md +128 -0
- package/index.js +33 -0
- package/lib/audit.js +358 -0
- package/lib/auth.js +849 -0
- package/lib/chat-sdk/admin-controller.js +289 -0
- package/lib/chat-sdk/debouncer.js +94 -0
- package/lib/chat-sdk/group-grants.js +150 -0
- package/lib/chat-sdk/index.js +222 -0
- package/lib/chat-sdk/long-task-runner.js +413 -0
- package/lib/chat-session.js +1788 -0
- package/lib/chat-telemetry.js +557 -0
- package/lib/codex-app-server.js +851 -0
- package/lib/digest.js +112 -0
- package/lib/effects.js +157 -0
- package/lib/eval.js +408 -0
- package/lib/grounding.js +356 -0
- package/lib/installers.js +176 -0
- package/lib/knowledge.js +335 -0
- package/lib/ledger.js +38 -0
- package/lib/loop.js +197 -0
- package/lib/mcp-client.js +926 -0
- package/lib/memory-cli.js +66 -0
- package/lib/memory-tracker.js +1472 -0
- package/lib/memory.js +1279 -0
- package/lib/people-cli.js +81 -0
- package/lib/people.js +534 -0
- package/lib/permissions.js +272 -0
- package/lib/providers.js +1572 -0
- package/lib/runtime.js +928 -0
- package/lib/sandbox.js +744 -0
- package/lib/scheduler.js +402 -0
- package/lib/scroll.js +1225 -0
- package/lib/skill-cli.js +120 -0
- package/lib/skill-eval.js +156 -0
- package/lib/skills.js +860 -0
- package/lib/style.js +126 -0
- package/lib/tool-retriever.js +489 -0
- package/lib/tools.js +1833 -0
- package/lib/user.js +711 -0
- package/lib/vault.js +151 -0
- package/package.json +88 -4
- package/templates/agent/IDENTITY.md +56 -0
- package/templates/agent/SOUL.md +23 -0
- package/templates/agent/TOOLS.md +25 -0
- package/templates/agent/evals/case-02-citation-discipline.md +29 -0
- package/templates/agent/evals/case-03-boundary.md +27 -0
- package/templates/agent/evals/case-example.md +43 -0
- package/templates/agent/hard-rules.md +11 -0
- package/templates/agent/memory/lessons.md +5 -0
- package/templates/agent/memory/log/.gitkeep +0 -0
- package/templates/external-safety-contract.md +5 -0
- package/templates/long-task-planner.md +17 -0
- package/templates/work/LOOP.md +37 -0
- package/templates/work/WORK.md +50 -0
- package/types/chat.d.ts +61 -0
- package/types/index.d.ts +112 -0
|
@@ -0,0 +1,557 @@
|
|
|
1
|
+
// SCROLL 2.5 -- §12 / §18 / §20.6 / §21 Chat Observability, Hash-Chained Audit,
|
|
2
|
+
// Budget & Loop Circuit Breakers, Single-Writer PID Lock, and Atomic Per-Call Approvals.
|
|
3
|
+
//
|
|
4
|
+
// Brings the governance guarantees of `lib/runtime.js` directly into `lib/chat-session.js`
|
|
5
|
+
// while keeping zero runtime dependencies and OpenTelemetry GenAI-aligned field names.
|
|
6
|
+
//
|
|
7
|
+
// Zero runtime dependencies. Node >= 20 built-ins only.
|
|
8
|
+
import fs from 'node:fs';
|
|
9
|
+
import os from 'node:os';
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
import crypto from 'node:crypto';
|
|
12
|
+
|
|
13
|
+
const SECRET_VALUE_RE = /\b(?:sk-[A-Za-z0-9_-]{16,}|sk-ant-[A-Za-z0-9_-]{16,}|AIza[A-Za-z0-9_-]{24,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{16,}|Bearer\s+[A-Za-z0-9._-]{20,})\b/g;
|
|
14
|
+
const SENSITIVE_KEY_RE = /(?:token|secret|password|passwd|api_?key|authorization|cookie|credential|private_?key|bearer)/i;
|
|
15
|
+
|
|
16
|
+
export function redactTelemetry(val) {
|
|
17
|
+
if (typeof val === 'string') return val.replace(SECRET_VALUE_RE, '[REDACTED]');
|
|
18
|
+
if (Array.isArray(val)) return val.map(redactTelemetry);
|
|
19
|
+
if (val && typeof val === 'object') {
|
|
20
|
+
const out = {};
|
|
21
|
+
for (const [k, v] of Object.entries(val)) {
|
|
22
|
+
// Redact sensitive keys regardless of value type (prevents `{ authorization: { value: "..." } }` leaks)
|
|
23
|
+
if (SENSITIVE_KEY_RE.test(k) && v !== undefined && v !== null) {
|
|
24
|
+
out[k] = '[REDACTED]';
|
|
25
|
+
} else {
|
|
26
|
+
out[k] = redactTelemetry(v);
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return out;
|
|
30
|
+
}
|
|
31
|
+
return val;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export function canonicalJson(val) {
|
|
35
|
+
if (val === null || typeof val !== 'object') return JSON.stringify(val);
|
|
36
|
+
if (Array.isArray(val)) return '[' + val.map(canonicalJson).join(',') + ']';
|
|
37
|
+
const keys = Object.keys(val).sort();
|
|
38
|
+
return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(val[k])).join(',') + '}';
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function hashArgs(args) {
|
|
42
|
+
return crypto.createHash('sha256').update(canonicalJson(args ?? {})).digest('hex').slice(0, 24);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
// ── Single-Writer PID Lockfile (enforces 1 active writer per state directory) ──
|
|
46
|
+
function isPidAlive(pid) {
|
|
47
|
+
const n = Number(pid);
|
|
48
|
+
if (!Number.isInteger(n) || n <= 0) return false;
|
|
49
|
+
try {
|
|
50
|
+
process.kill(n, 0);
|
|
51
|
+
return true;
|
|
52
|
+
} catch (err) {
|
|
53
|
+
return err?.code === 'EPERM';
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// Synchronous short-lived spin lock with owner token verification for multi-process JSON/JSONL appends.
|
|
58
|
+
function withShortFileLockSync(lockPath, fn, { maxWaitMs = 1500 } = {}) {
|
|
59
|
+
fs.mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
|
|
60
|
+
const token = `${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
|
|
61
|
+
const deadline = Date.now() + maxWaitMs;
|
|
62
|
+
let acquired = false;
|
|
63
|
+
|
|
64
|
+
while (!acquired) {
|
|
65
|
+
try {
|
|
66
|
+
const fd = fs.openSync(lockPath, 'wx', 0o600);
|
|
67
|
+
try { fs.writeSync(fd, JSON.stringify({ pid: process.pid, token, ts: Date.now() }) + '\n'); } finally { fs.closeSync(fd); }
|
|
68
|
+
acquired = true;
|
|
69
|
+
} catch (err) {
|
|
70
|
+
if (err?.code !== 'EEXIST') throw err;
|
|
71
|
+
try {
|
|
72
|
+
const cur = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
|
|
73
|
+
// Only reap when holder PID is dead (never steal from a live process!)
|
|
74
|
+
if (cur && cur.pid && !isPidAlive(cur.pid)) {
|
|
75
|
+
fs.rmSync(lockPath, { force: true });
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
} catch {
|
|
79
|
+
try {
|
|
80
|
+
const st = fs.statSync(lockPath);
|
|
81
|
+
if (Date.now() - st.mtimeMs > 10_000) {
|
|
82
|
+
fs.rmSync(lockPath, { force: true });
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
} catch { continue; }
|
|
86
|
+
}
|
|
87
|
+
if (Date.now() >= deadline) {
|
|
88
|
+
throw new Error(`short_file_lock_timeout:${lockPath}`);
|
|
89
|
+
}
|
|
90
|
+
// Bounded short wait using Atomics.wait (zero CPU busy spin)
|
|
91
|
+
try {
|
|
92
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 8);
|
|
93
|
+
} catch { /* ignore */ }
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
try {
|
|
98
|
+
return fn();
|
|
99
|
+
} finally {
|
|
100
|
+
try {
|
|
101
|
+
const cur = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
|
|
102
|
+
if (cur && cur.token === token) fs.rmSync(lockPath, { force: true });
|
|
103
|
+
} catch { /* ignore */ }
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function acquireWriterLock(stateDir, { lockName = '.writer.lock', owner = 'scroll-chat' } = {}) {
|
|
108
|
+
if (!stateDir) return { acquired: false, release() {} };
|
|
109
|
+
const absDir = path.resolve(stateDir);
|
|
110
|
+
fs.mkdirSync(absDir, { recursive: true, mode: 0o700 });
|
|
111
|
+
const lockPath = path.join(absDir, lockName);
|
|
112
|
+
const token = `${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
|
|
113
|
+
const payload = JSON.stringify({ pid: process.pid, token, owner, host: os.hostname(), startedAt: new Date().toISOString() }) + '\n';
|
|
114
|
+
|
|
115
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
116
|
+
try {
|
|
117
|
+
const fd = fs.openSync(lockPath, 'wx', 0o600);
|
|
118
|
+
try { fs.writeSync(fd, payload); } finally { fs.closeSync(fd); }
|
|
119
|
+
let released = false;
|
|
120
|
+
const release = () => {
|
|
121
|
+
if (released) return;
|
|
122
|
+
released = true;
|
|
123
|
+
try {
|
|
124
|
+
const cur = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
|
|
125
|
+
if (cur.token === token) fs.rmSync(lockPath, { force: true });
|
|
126
|
+
} catch { /* ignore */ }
|
|
127
|
+
};
|
|
128
|
+
return { acquired: true, lockPath, token, release };
|
|
129
|
+
} catch (err) {
|
|
130
|
+
if (err?.code !== 'EEXIST') throw err;
|
|
131
|
+
let existing = null;
|
|
132
|
+
try { existing = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { existing = null; }
|
|
133
|
+
if (existing && existing.pid && isPidAlive(existing.pid)) {
|
|
134
|
+
throw new Error(`writer_lock_held:pid=${existing.pid}:owner=${existing.owner || 'unknown'}:path=${lockPath}`);
|
|
135
|
+
}
|
|
136
|
+
try { fs.rmSync(lockPath, { force: true }); } catch { /* ignore */ }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
throw new Error(`writer_lock_contention:${lockPath}`);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// ── Append-Only OTel GenAI-Aligned Event Stream (`events.jsonl`) ───────────────
|
|
143
|
+
export function createEventLogger({ filePath = null, onEvent = null } = {}) {
|
|
144
|
+
function emit(type, data = {}) {
|
|
145
|
+
const rec = {
|
|
146
|
+
ts: new Date().toISOString(),
|
|
147
|
+
type: String(type || 'event'),
|
|
148
|
+
...redactTelemetry(data),
|
|
149
|
+
};
|
|
150
|
+
if (filePath) {
|
|
151
|
+
try {
|
|
152
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
|
|
153
|
+
fs.appendFileSync(filePath, JSON.stringify(rec) + '\n', { mode: 0o600 });
|
|
154
|
+
} catch { /* isolate disk telemetry error */ }
|
|
155
|
+
}
|
|
156
|
+
if (typeof onEvent === 'function') {
|
|
157
|
+
try { onEvent(rec); } catch { /* isolate callback */ }
|
|
158
|
+
}
|
|
159
|
+
return rec;
|
|
160
|
+
}
|
|
161
|
+
return { emit, filePath };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// ── Tamper-Evident Hash-Chained Audit Log (`audit.jsonl`, §20.6) ───────────────
|
|
165
|
+
function readTailHash(filePath) {
|
|
166
|
+
let seq = 0;
|
|
167
|
+
let prevHash = '0'.repeat(64);
|
|
168
|
+
if (!filePath || !fs.existsSync(filePath)) return { seq, prevHash };
|
|
169
|
+
const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter((l) => l.trim());
|
|
170
|
+
for (const line of lines) {
|
|
171
|
+
try {
|
|
172
|
+
const parsed = JSON.parse(line);
|
|
173
|
+
if (typeof parsed.hash === 'string' && parsed.hash.length === 64) {
|
|
174
|
+
prevHash = parsed.hash;
|
|
175
|
+
seq = Number(parsed.seq || seq + 1);
|
|
176
|
+
}
|
|
177
|
+
} catch { /* ignore torn line */ }
|
|
178
|
+
}
|
|
179
|
+
return { seq, prevHash };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function createAuditChain({ filePath = null, onAudit = null } = {}) {
|
|
183
|
+
let { seq, prevHash } = readTailHash(filePath);
|
|
184
|
+
const lockPath = filePath ? `${filePath}.lock` : null;
|
|
185
|
+
|
|
186
|
+
function append(entry) {
|
|
187
|
+
const doAppend = () => {
|
|
188
|
+
// Refresh tail from disk inside lock so multi-bot / multi-process writers NEVER break the chain
|
|
189
|
+
if (filePath) {
|
|
190
|
+
const tail = readTailHash(filePath);
|
|
191
|
+
seq = tail.seq;
|
|
192
|
+
prevHash = tail.prevHash;
|
|
193
|
+
}
|
|
194
|
+
seq++;
|
|
195
|
+
const body = {
|
|
196
|
+
seq,
|
|
197
|
+
ts: new Date().toISOString(),
|
|
198
|
+
...redactTelemetry(entry),
|
|
199
|
+
prevHash,
|
|
200
|
+
};
|
|
201
|
+
const hash = crypto.createHash('sha256').update(prevHash + '\n' + canonicalJson(body)).digest('hex');
|
|
202
|
+
const full = { ...body, hash };
|
|
203
|
+
prevHash = hash;
|
|
204
|
+
if (filePath) {
|
|
205
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
|
|
206
|
+
fs.appendFileSync(filePath, JSON.stringify(full) + '\n', { mode: 0o600 });
|
|
207
|
+
}
|
|
208
|
+
return full;
|
|
209
|
+
};
|
|
210
|
+
|
|
211
|
+
const full = lockPath ? withShortFileLockSync(lockPath, doAppend) : doAppend();
|
|
212
|
+
if (typeof onAudit === 'function') {
|
|
213
|
+
try { onAudit(full); } catch { /* isolate callback */ }
|
|
214
|
+
}
|
|
215
|
+
return full;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
return { append, filePath, get lastHash() { return prevHash; }, get count() { return seq; } };
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
export function verifyAuditChain(filePath) {
|
|
222
|
+
if (!filePath || !fs.existsSync(filePath)) {
|
|
223
|
+
return { ok: true, count: 0, errors: [] };
|
|
224
|
+
}
|
|
225
|
+
const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter((l) => l.trim());
|
|
226
|
+
let expectedPrev = '0'.repeat(64);
|
|
227
|
+
const errors = [];
|
|
228
|
+
for (let i = 0; i < lines.length; i++) {
|
|
229
|
+
let rec;
|
|
230
|
+
try { rec = JSON.parse(lines[i]); } catch {
|
|
231
|
+
errors.push({ line: i + 1, reason: 'invalid_json' });
|
|
232
|
+
continue;
|
|
233
|
+
}
|
|
234
|
+
if (rec.prevHash !== expectedPrev) {
|
|
235
|
+
errors.push({ line: i + 1, reason: 'prev_hash_mismatch', expected: expectedPrev, actual: rec.prevHash });
|
|
236
|
+
}
|
|
237
|
+
const { hash, ...body } = rec;
|
|
238
|
+
const recomputed = crypto.createHash('sha256').update(expectedPrev + '\n' + canonicalJson(body)).digest('hex');
|
|
239
|
+
if (hash !== recomputed) {
|
|
240
|
+
errors.push({ line: i + 1, reason: 'hash_mismatch', expected: recomputed, actual: hash });
|
|
241
|
+
}
|
|
242
|
+
expectedPrev = hash || expectedPrev;
|
|
243
|
+
}
|
|
244
|
+
return { ok: errors.length === 0, count: lines.length, errors };
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
// ── §12 Budget Governor & Runaway Loop Circuit Breaker ─────────────────────────
|
|
248
|
+
const DEFAULT_PRICING = { inputPerM: 3.0, cachedPerM: 0.3, outputPerM: 15.0 };
|
|
249
|
+
|
|
250
|
+
export function estimateUsageUsd(usage, pricing = DEFAULT_PRICING) {
|
|
251
|
+
const p = { ...DEFAULT_PRICING, ...(pricing || {}) };
|
|
252
|
+
const uncached = Number(usage?.uncachedInputTokens || 0);
|
|
253
|
+
const cached = Number(usage?.cachedInputTokens || 0);
|
|
254
|
+
const output = Number(usage?.outputTokens || 0);
|
|
255
|
+
return (uncached * p.inputPerM + cached * p.cachedPerM + output * p.outputPerM) / 1_000_000;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
export function createBudgetGovernor({
|
|
259
|
+
maxInputTokensPerTurn = null,
|
|
260
|
+
maxDailyUsd = null,
|
|
261
|
+
maxConversationDailyUsd = null,
|
|
262
|
+
maxToolCallsPerTurn = 24,
|
|
263
|
+
maxIdenticalToolRepeats = 3,
|
|
264
|
+
maxConsecutiveToolErrors = 4,
|
|
265
|
+
pricing = DEFAULT_PRICING,
|
|
266
|
+
stateFile = null,
|
|
267
|
+
} = {}) {
|
|
268
|
+
const daily = { day: new Date().toISOString().slice(0, 10), totalUsd: 0, byConv: {} };
|
|
269
|
+
const lockPath = stateFile ? `${stateFile}.lock` : null;
|
|
270
|
+
|
|
271
|
+
function loadFromDisk() {
|
|
272
|
+
const today = new Date().toISOString().slice(0, 10);
|
|
273
|
+
if (daily.day !== today) {
|
|
274
|
+
daily.day = today;
|
|
275
|
+
daily.totalUsd = 0;
|
|
276
|
+
daily.byConv = {};
|
|
277
|
+
}
|
|
278
|
+
if (stateFile && fs.existsSync(stateFile)) {
|
|
279
|
+
try {
|
|
280
|
+
const saved = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
|
|
281
|
+
if (saved && saved.day === today) {
|
|
282
|
+
daily.totalUsd = Number(saved.totalUsd || 0);
|
|
283
|
+
daily.byConv = saved.byConv && typeof saved.byConv === 'object' ? saved.byConv : {};
|
|
284
|
+
}
|
|
285
|
+
} catch { /* ignore */ }
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
loadFromDisk();
|
|
290
|
+
|
|
291
|
+
function persistUnlocked() {
|
|
292
|
+
if (!stateFile) return;
|
|
293
|
+
try {
|
|
294
|
+
fs.mkdirSync(path.dirname(stateFile), { recursive: true, mode: 0o700 });
|
|
295
|
+
const tmp = `${stateFile}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
|
|
296
|
+
fs.writeFileSync(tmp, JSON.stringify(daily, null, 2) + '\n', { mode: 0o600 });
|
|
297
|
+
fs.renameSync(tmp, stateFile);
|
|
298
|
+
} catch { /* ignore */ }
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
function checkBeforeCall({
|
|
302
|
+
conversationId = 'default',
|
|
303
|
+
estimatedInputTokens = 0,
|
|
304
|
+
estimatedOutputTokens = 0,
|
|
305
|
+
} = {}) {
|
|
306
|
+
loadFromDisk();
|
|
307
|
+
if (maxInputTokensPerTurn && estimatedInputTokens > maxInputTokensPerTurn) {
|
|
308
|
+
return { ok: false, reason: 'budget_input_tokens_per_turn_exceeded', limit: maxInputTokensPerTurn, actual: estimatedInputTokens };
|
|
309
|
+
}
|
|
310
|
+
const estUsd = estimateUsageUsd({
|
|
311
|
+
uncachedInputTokens: Number(estimatedInputTokens || 0),
|
|
312
|
+
cachedInputTokens: 0,
|
|
313
|
+
outputTokens: Number(estimatedOutputTokens || 0),
|
|
314
|
+
}, pricing);
|
|
315
|
+
|
|
316
|
+
if (maxDailyUsd != null && (daily.totalUsd >= maxDailyUsd || (estUsd > 0 && daily.totalUsd + estUsd > maxDailyUsd))) {
|
|
317
|
+
return { ok: false, reason: 'budget_daily_usd_exceeded', limit: maxDailyUsd, actual: daily.totalUsd, estimatedCallUsd: estUsd };
|
|
318
|
+
}
|
|
319
|
+
const convUsd = Number(daily.byConv[String(conversationId)] || 0);
|
|
320
|
+
if (maxConversationDailyUsd != null && (convUsd >= maxConversationDailyUsd || (estUsd > 0 && convUsd + estUsd > maxConversationDailyUsd))) {
|
|
321
|
+
return { ok: false, reason: 'budget_conversation_daily_usd_exceeded', limit: maxConversationDailyUsd, actual: convUsd, estimatedCallUsd: estUsd };
|
|
322
|
+
}
|
|
323
|
+
return { ok: true, estimatedCallUsd: estUsd };
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
function recordUsage({ conversationId = 'default', usage = null, fallbackInputTokens = 0 } = {}) {
|
|
327
|
+
const apply = () => {
|
|
328
|
+
loadFromDisk();
|
|
329
|
+
const effUsage = usage && (usage.uncachedInputTokens || usage.cachedInputTokens || usage.outputTokens)
|
|
330
|
+
? usage
|
|
331
|
+
: { uncachedInputTokens: fallbackInputTokens, cachedInputTokens: 0, outputTokens: 0 };
|
|
332
|
+
const usd = estimateUsageUsd(effUsage, pricing);
|
|
333
|
+
daily.totalUsd += usd;
|
|
334
|
+
const ck = String(conversationId);
|
|
335
|
+
daily.byConv[ck] = Number(daily.byConv[ck] || 0) + usd;
|
|
336
|
+
persistUnlocked();
|
|
337
|
+
return { usd, dailyTotalUsd: daily.totalUsd, convDailyUsd: daily.byConv[ck] };
|
|
338
|
+
};
|
|
339
|
+
return lockPath ? withShortFileLockSync(lockPath, apply) : apply();
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
function createTurnTracker() {
|
|
343
|
+
let toolCalls = 0;
|
|
344
|
+
let consecutiveErrors = 0;
|
|
345
|
+
const callSigCounts = new Map();
|
|
346
|
+
|
|
347
|
+
return {
|
|
348
|
+
beforeToolCall(name, args) {
|
|
349
|
+
toolCalls++;
|
|
350
|
+
if (maxToolCallsPerTurn && toolCalls > maxToolCallsPerTurn) {
|
|
351
|
+
return { ok: false, reason: 'circuit_breaker_max_tool_calls_per_turn', limit: maxToolCallsPerTurn, count: toolCalls };
|
|
352
|
+
}
|
|
353
|
+
const sig = `${name}:${hashArgs(args)}`;
|
|
354
|
+
const count = (callSigCounts.get(sig) || 0) + 1;
|
|
355
|
+
callSigCounts.set(sig, count);
|
|
356
|
+
if (maxIdenticalToolRepeats && count > maxIdenticalToolRepeats) {
|
|
357
|
+
return { ok: false, reason: 'circuit_breaker_identical_tool_repeat_loop', tool: name, repeats: count };
|
|
358
|
+
}
|
|
359
|
+
return { ok: true, count: toolCalls };
|
|
360
|
+
},
|
|
361
|
+
afterToolResult(ok) {
|
|
362
|
+
if (ok) {
|
|
363
|
+
consecutiveErrors = 0;
|
|
364
|
+
return { ok: true };
|
|
365
|
+
}
|
|
366
|
+
consecutiveErrors++;
|
|
367
|
+
if (maxConsecutiveToolErrors && consecutiveErrors >= maxConsecutiveToolErrors) {
|
|
368
|
+
return { ok: false, reason: 'circuit_breaker_consecutive_tool_errors', consecutiveErrors };
|
|
369
|
+
}
|
|
370
|
+
return { ok: true };
|
|
371
|
+
},
|
|
372
|
+
get toolCalls() { return toolCalls; },
|
|
373
|
+
get consecutiveErrors() { return consecutiveErrors; },
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
return {
|
|
378
|
+
checkBeforeCall,
|
|
379
|
+
recordUsage,
|
|
380
|
+
createTurnTracker,
|
|
381
|
+
getSnapshot: () => {
|
|
382
|
+
loadFromDisk();
|
|
383
|
+
return { day: daily.day, totalUsd: daily.totalUsd, byConv: { ...daily.byConv } };
|
|
384
|
+
},
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// ── Atomic POSIX Single-Use Approval Token Store (issued/ -> consumed/ via renameSync) ──
|
|
389
|
+
// Zero-dep, multi-process race-free: POSIX `rename()` guarantees at most ONE caller
|
|
390
|
+
// across any number of processes can transition a token from `issued/` to `consumed/`.
|
|
391
|
+
export function createApprovalStore({ dir = null, defaultTtlMs = 15 * 60_000 } = {}) {
|
|
392
|
+
const pendingMem = new Map();
|
|
393
|
+
const consumedMem = new Map();
|
|
394
|
+
const absDir = dir ? path.resolve(dir) : null;
|
|
395
|
+
const issuedDir = absDir ? path.join(absDir, 'issued') : null;
|
|
396
|
+
const consumedDir = absDir ? path.join(absDir, 'consumed') : null;
|
|
397
|
+
|
|
398
|
+
function safeId(id) {
|
|
399
|
+
return String(id || '').replace(/[^A-Za-z0-9_-]/g, '_');
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
function issuedPath(id) {
|
|
403
|
+
return issuedDir ? path.join(issuedDir, `${safeId(id)}.json`) : null;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
function consumedPath(id) {
|
|
407
|
+
return consumedDir ? path.join(consumedDir, `${safeId(id)}.json`) : null;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
function legacyPath(id) {
|
|
411
|
+
return absDir ? path.join(absDir, `${safeId(id)}.json`) : null;
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
function writeAtomic(filePath, rec) {
|
|
415
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
|
|
416
|
+
const tmp = `${filePath}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
|
|
417
|
+
fs.writeFileSync(tmp, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 });
|
|
418
|
+
fs.renameSync(tmp, filePath);
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
function readJsonSafe(p) {
|
|
422
|
+
if (!p || !fs.existsSync(p)) return null;
|
|
423
|
+
try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
function get(id) {
|
|
427
|
+
if (!id) return null;
|
|
428
|
+
if (absDir) {
|
|
429
|
+
return readJsonSafe(issuedPath(id))
|
|
430
|
+
|| readJsonSafe(consumedPath(id))
|
|
431
|
+
|| readJsonSafe(legacyPath(id));
|
|
432
|
+
}
|
|
433
|
+
return pendingMem.get(id) || consumedMem.get(id) || null;
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
function issue({
|
|
437
|
+
tool,
|
|
438
|
+
args = {},
|
|
439
|
+
approver = null,
|
|
440
|
+
tier = 'destructive',
|
|
441
|
+
amount = null,
|
|
442
|
+
conversationId = null,
|
|
443
|
+
turnId = null,
|
|
444
|
+
schemaHash = null,
|
|
445
|
+
ttlMs = defaultTtlMs,
|
|
446
|
+
} = {}) {
|
|
447
|
+
if (!tool) throw new Error('approval_issue: tool is required');
|
|
448
|
+
const id = `appr_${crypto.randomBytes(8).toString('hex')}`;
|
|
449
|
+
const now = Date.now();
|
|
450
|
+
const rec = {
|
|
451
|
+
id,
|
|
452
|
+
tool: String(tool),
|
|
453
|
+
argsHash: hashArgs(args),
|
|
454
|
+
approver: approver ? String(approver) : null,
|
|
455
|
+
tier: String(tier),
|
|
456
|
+
amount: amount != null && Number.isFinite(Number(amount)) ? Number(amount) : null,
|
|
457
|
+
conversationId: conversationId ? String(conversationId) : null,
|
|
458
|
+
turnId: turnId ? String(turnId) : null,
|
|
459
|
+
schemaHash: schemaHash ? String(schemaHash) : null,
|
|
460
|
+
createdAt: new Date(now).toISOString(),
|
|
461
|
+
expiresAt: new Date(now + Math.max(1000, Number(ttlMs || defaultTtlMs))).toISOString(),
|
|
462
|
+
used: false,
|
|
463
|
+
};
|
|
464
|
+
if (absDir) {
|
|
465
|
+
fs.mkdirSync(issuedDir, { recursive: true, mode: 0o700 });
|
|
466
|
+
fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
|
|
467
|
+
writeAtomic(issuedPath(id), rec);
|
|
468
|
+
} else {
|
|
469
|
+
pendingMem.set(id, rec);
|
|
470
|
+
}
|
|
471
|
+
return rec;
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
function validateRecord(rec, { tool, args, userDoc, tier, amount, conversationId, turnId, schemaHash }) {
|
|
475
|
+
if (rec.used) return { ok: false, reason: 'approval_token_already_used' };
|
|
476
|
+
if (Date.now() > Date.parse(rec.expiresAt)) return { ok: false, reason: 'approval_token_expired' };
|
|
477
|
+
if (rec.tool !== String(tool)) return { ok: false, reason: 'approval_tool_mismatch' };
|
|
478
|
+
const actualHash = hashArgs(args);
|
|
479
|
+
if (rec.argsHash !== actualHash) return { ok: false, reason: 'approval_args_hash_mismatch' };
|
|
480
|
+
// Strict binding: if token was issued with a conversationId/turnId/schemaHash, caller MUST supply the exact match!
|
|
481
|
+
if (rec.conversationId && String(conversationId || '') !== rec.conversationId) {
|
|
482
|
+
return { ok: false, reason: 'approval_conversation_mismatch' };
|
|
483
|
+
}
|
|
484
|
+
if (rec.turnId && String(turnId || '') !== rec.turnId) {
|
|
485
|
+
return { ok: false, reason: 'approval_turn_mismatch' };
|
|
486
|
+
}
|
|
487
|
+
if (rec.schemaHash && String(schemaHash || '') !== rec.schemaHash) {
|
|
488
|
+
return { ok: false, reason: 'approval_schema_hash_mismatch' };
|
|
489
|
+
}
|
|
490
|
+
if (userDoc && userDoc.active && typeof userDoc.canApprove === 'function') {
|
|
491
|
+
if (!rec.approver) return { ok: false, reason: 'approval_missing_approver' };
|
|
492
|
+
const checkAmt = amount != null ? Number(amount) : rec.amount;
|
|
493
|
+
const chk = userDoc.canApprove(rec.approver, { tier, amount: checkAmt });
|
|
494
|
+
if (chk && chk.ok === false) {
|
|
495
|
+
return { ok: false, reason: chk.reason || 'approver_not_authorized' };
|
|
496
|
+
}
|
|
497
|
+
}
|
|
498
|
+
return { ok: true };
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
function consume({
|
|
502
|
+
tokenId,
|
|
503
|
+
tool,
|
|
504
|
+
args = {},
|
|
505
|
+
userDoc = null,
|
|
506
|
+
tier = 'destructive',
|
|
507
|
+
amount = null,
|
|
508
|
+
conversationId = null,
|
|
509
|
+
turnId = null,
|
|
510
|
+
schemaHash = null,
|
|
511
|
+
} = {}) {
|
|
512
|
+
if (!tokenId || !/^[A-Za-z0-9_-]{8,128}$/.test(String(tokenId))) {
|
|
513
|
+
return { ok: false, reason: 'approval_token_not_found' };
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
if (absDir) {
|
|
517
|
+
const src = issuedPath(tokenId);
|
|
518
|
+
const dst = consumedPath(tokenId);
|
|
519
|
+
const rec = readJsonSafe(src);
|
|
520
|
+
if (!rec) {
|
|
521
|
+
if (fs.existsSync(dst)) return { ok: false, reason: 'approval_token_already_used' };
|
|
522
|
+
return { ok: false, reason: 'approval_token_not_found' };
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
const valid = validateRecord(rec, { tool, args, userDoc, tier, amount, conversationId, turnId, schemaHash });
|
|
526
|
+
if (!valid.ok) return valid;
|
|
527
|
+
|
|
528
|
+
// Atomic POSIX claim: only ONE process/call succeeds in moving `issued/<id>` -> `consumed/<id>`!
|
|
529
|
+
fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
|
|
530
|
+
try {
|
|
531
|
+
fs.renameSync(src, dst);
|
|
532
|
+
} catch (err) {
|
|
533
|
+
if (err?.code === 'ENOENT') return { ok: false, reason: 'approval_token_already_used' };
|
|
534
|
+
throw err;
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
const claimed = { ...rec, used: true, usedAt: new Date().toISOString() };
|
|
538
|
+
try { writeAtomic(dst, claimed); } catch { /* already moved atomically */ }
|
|
539
|
+
return { ok: true, token: claimed };
|
|
540
|
+
}
|
|
541
|
+
|
|
542
|
+
// In-memory atomic single-use transition
|
|
543
|
+
const rec = pendingMem.get(tokenId);
|
|
544
|
+
if (!rec) {
|
|
545
|
+
if (consumedMem.has(tokenId)) return { ok: false, reason: 'approval_token_already_used' };
|
|
546
|
+
return { ok: false, reason: 'approval_token_not_found' };
|
|
547
|
+
}
|
|
548
|
+
const valid = validateRecord(rec, { tool, args, userDoc, tier, amount, conversationId, turnId, schemaHash });
|
|
549
|
+
if (!valid.ok) return valid;
|
|
550
|
+
pendingMem.delete(tokenId);
|
|
551
|
+
const claimed = { ...rec, used: true, usedAt: new Date().toISOString() };
|
|
552
|
+
consumedMem.set(tokenId, claimed);
|
|
553
|
+
return { ok: true, token: claimed };
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
return { issue, consume, get, hashArgs };
|
|
557
|
+
}
|