arena-bridge 0.10.0 → 0.12.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/CHANGELOG.md CHANGED
@@ -4,6 +4,39 @@ All notable changes to this project are documented here.
4
4
  The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses
5
5
  [Semantic Versioning](https://semver.org/).
6
6
 
7
+ ## 0.12.0
8
+
9
+ ### Added
10
+ - Trust window events: open, extend, change, close and expire, each logged once; changes made by another writer (such as the app) are logged as external. The `trust` command takes `--source`.
11
+ - Bridge start and stop, and tunnel up and down, are logged with their origin.
12
+ - `GET /audit` pages with `before`, `after`, `tool`, `kind` and `level` filters; `GET /audit/entry?id=` returns the full record.
13
+ - `POST /log/event` accepts interface step events. `GET /v1/events` sends new audit records as they arrive.
14
+
15
+ ### Changed
16
+ - The audit log rotates into 5 MB segments; retention keeps 7 days and at most 20 MB of audit log (the newest archive is never removed) and 7 days and at most 200 MB of artifacts.
17
+ - `arena-bridge cleanup` removes artifacts older than 7 days by default (was 14).
18
+
19
+ ### Fixed
20
+ - The macOS release job uploads the app checksums with the release checksums file instead of failing.
21
+
22
+ ### CI
23
+ - npm publishing uses trusted publishing (OIDC) with Node 24; no npm token is used.
24
+
25
+ ## 0.11.0
26
+
27
+ ### Added
28
+ - Work log records every call with its full parameters (large payloads move to an `args.json` artifact), the caller (tunnel address, country, reverse-DNS host, client), and an alert level.
29
+ - Unauthorized requests are logged at alert level, limited to 5 per address per minute, with a suppressed count.
30
+ - `log_note` tool: adds an info entry to the work log (1–500 characters, one per second). Node only; the Python package does not receive new tools.
31
+ - Errors `INVALID_ARGS` and `RATE_LIMITED`; `INVALID_JSON` and `PAYLOAD_TOO_LARGE` responses for malformed or oversized HTTP bodies.
32
+
33
+ ### Changed
34
+ - Duplicate `chrome_screenshot` audit entry removed; the call is recorded once.
35
+ - Masking covers bearer tokens, AWS key ids, private key blocks, `env` values and secret-named keys.
36
+
37
+ ### Fixed
38
+ - `/files` GET, PUT and DELETE are all audited and authorized through the same path.
39
+
7
40
  ## 0.10.0
8
41
 
9
42
  ### Added
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "arena-bridge",
3
- "version": "0.10.0",
3
+ "version": "0.12.0",
4
4
  "description": "Give a cloud AI agent (Arena.ai Agent Mode, Claude, Cursor, ...) controlled access to your own machine over HTTP/MCP: files, shell, Chrome and the macOS desktop, with an approval gate, trust windows and an audit log.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -19,8 +19,8 @@
19
19
  "node": ">=18"
20
20
  },
21
21
  "scripts": {
22
- "test": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node --test test/test_security.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs",
23
- "test:node": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs",
22
+ "test": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node --test test/test_security.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs",
23
+ "test:node": "node --test test/approvals.test.mjs && node --test test/telegram.test.mjs && node test/smoke.mjs && node test/browser.test.mjs && node test/mac.test.mjs && node test/service.test.mjs && node --test test/log.test.mjs && node --test test/log-paging.test.mjs",
24
24
  "test:python": "python3 test/test_approvals.py && python3 test/test_bridge.py && python3 test/test_browser.py && python3 test/test_mac.py && python3 test/test_service.py && python3 test/test_telegram.py",
25
25
  "pack:check": "npm pack --dry-run"
26
26
  },
package/src/approvals.mjs CHANGED
@@ -3,7 +3,7 @@ import path from 'node:path';
3
3
  import crypto from 'node:crypto';
4
4
  import { APPROVALS_DIR, ensureDirs } from './config.mjs';
5
5
  import { sendTelegram, approvalKeyboard } from './telegram.mjs';
6
- import { saveTrust } from './trust.mjs';
6
+ import { openTrust } from './trust.mjs';
7
7
 
8
8
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
9
9
 
@@ -64,13 +64,11 @@ export function decide(id, decision, by = 'cli') {
64
64
  export function settle(id, decision, by = 'cli', { trustSec = 0 } = {}) {
65
65
  const res = decide(id, decision, by);
66
66
  if (res.ok && trustSec > 0) {
67
- saveTrust({
68
- enabled: true,
67
+ openTrust({
69
68
  until: Date.now() + trustSec * 1000,
70
69
  tools: [], // blanket: all tools, any agent
71
70
  paths: [],
72
- createdAt: Date.now(),
73
- });
71
+ }, { via: 'approval' });
74
72
  }
75
73
  return res;
76
74
  }
package/src/audit.mjs CHANGED
@@ -1,5 +1,6 @@
1
1
  import fs from 'node:fs';
2
2
  import path from 'node:path';
3
+ import crypto from 'node:crypto';
3
4
  import { CONFIG_DIR } from './config.mjs';
4
5
 
5
6
  /** The config directory is resolved on every call so tests and relocations stay isolated. */
@@ -7,121 +8,399 @@ function configDir() {
7
8
  return process.env.ARENA_BRIDGE_HOME || CONFIG_DIR;
8
9
  }
9
10
 
11
+ const ACTIVE = 'audit.log';
12
+ const ARCHIVE = /^audit-\d{13}\.log$/;
13
+
10
14
  export function auditPath() {
11
- return path.join(configDir(), 'audit.log');
15
+ return path.join(configDir(), ACTIVE);
12
16
  }
13
17
 
18
+ export const LEVELS = ['info', 'notice', 'warning', 'alert'];
19
+ const ARGS_INLINE_BYTES = 64 * 1024;
20
+ const FIELD_CLIP = 4000;
21
+ const ROTATE_BYTES = 5 * 1024 * 1024;
22
+ const RETAIN_DAYS = 7;
23
+ const RETAIN_BYTES = 20 * 1024 * 1024;
24
+ const ART_RETAIN_DAYS = 7;
25
+ const ART_RETAIN_BYTES = 200 * 1024 * 1024;
26
+ const READ_CHUNK = 256 * 1024;
27
+ const SCAN_BUDGET = 8 * 1024 * 1024;
28
+ const LEAN_DROP = ['args', 'result', 'output', 'stdout', 'stderr', 'content', 'body', 'data'];
29
+ const LEAN_CLIP = 300;
30
+
14
31
  const SECRETS = [
15
32
  /(?<!\d)\d{6,12}:[A-Za-z0-9_-]{25,}/g, // telegram bot tokens
16
33
  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, // github tokens
17
34
  /\bnpm_[A-Za-z0-9]{20,}\b/g, // npm tokens
18
35
  /\bpypi-[A-Za-z0-9_-]{20,}\b/g, // pypi tokens
19
36
  /\bsk-[A-Za-z0-9]{20,}\b/g, // api keys
37
+ /\bBearer\s+[A-Za-z0-9._~+/=-]{16,}/gi, // bearer credentials
38
+ /\bAKIA[0-9A-Z]{16}\b/g, // aws access key ids
39
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
20
40
  ];
41
+ const SENSITIVE_KEY = /token|secret|passw|authorization|api[_-]?key|cookie|credential/i;
21
42
 
22
43
  /** Mask anything that looks like a credential, so the log never becomes a secret store. */
23
- export function scrub(value) {
44
+ export function scrub(value, key = '') {
24
45
  if (typeof value === 'string') {
46
+ if (SENSITIVE_KEY.test(key)) return '***';
25
47
  let out = value;
26
48
  for (const re of SECRETS) out = out.replace(re, '***');
27
49
  return out;
28
50
  }
29
- if (Array.isArray(value)) return value.map(scrub);
51
+ if (Array.isArray(value)) return value.map((v) => scrub(v, key));
52
+ if (value && typeof value === 'object') {
53
+ const out = {};
54
+ for (const [k, v] of Object.entries(value)) {
55
+ const masked = (key === 'env' || SENSITIVE_KEY.test(k)) && v !== null && typeof v !== 'object';
56
+ out[k] = masked ? '***' : scrub(v, k);
57
+ }
58
+ return out;
59
+ }
60
+ return value;
61
+ }
62
+
63
+ /** The alert level of an entry: explicit level wins, otherwise derived from kind and status. */
64
+ export function levelFor({ kind = 'call', status = '', level } = {}) {
65
+ if (level) return level;
66
+ if (kind === 'auth' || (kind === 'approval' && status === 'forbidden')) return 'alert';
67
+ if (kind === 'note') return status === 'ok' ? 'info' : 'warning';
68
+ if (status === 'ok') return 'info';
69
+ if (['trust', 'service', 'tunnel', 'log', 'approval', 'step'].includes(kind)) return 'notice';
70
+ return 'warning';
71
+ }
72
+
73
+ function newEntryId(tool) {
74
+ const stamp = new Date().toISOString().replace(/[:.]/g, '-');
75
+ const name = String(tool || 'event').replace(/[^\w.-]/g, '_');
76
+ return `${stamp}-${name}-${crypto.randomBytes(3).toString('hex')}`;
77
+ }
78
+
79
+ /** Long free-text fields other than the parameters are clipped; parameters are kept whole (see argsFor). */
80
+ function clipFields(value) {
81
+ if (typeof value === 'string') return value.length > FIELD_CLIP ? `[${value.length} chars truncated]` : value;
82
+ if (Array.isArray(value)) return value.map(clipFields);
30
83
  if (value && typeof value === 'object') {
31
84
  const out = {};
32
- for (const [k, v] of Object.entries(value)) out[k] = scrub(v);
85
+ for (const [k, v] of Object.entries(value)) out[k] = clipFields(v);
33
86
  return out;
34
87
  }
35
88
  return value;
36
89
  }
37
90
 
38
- export function audit(entry) {
91
+ /** Parameters are stored whole; the ones above the inline limit go to an artifact next to the entry. */
92
+ function argsFor(id, args) {
93
+ if (args === undefined) return { args: {}, truncated: false };
94
+ const clean = scrub(args);
95
+ const json = JSON.stringify(clean);
96
+ if (Buffer.byteLength(json) <= ARGS_INLINE_BYTES) return { args: clean, truncated: false };
97
+ const saved = saveArtifact(id, 'args', 'args.json', JSON.stringify(clean, null, 2));
98
+ return {
99
+ args: { preview: json.slice(0, 2000) },
100
+ truncated: true,
101
+ artifact: saved ? 'args.json' : undefined,
102
+ };
103
+ }
104
+
105
+ export function audit(entry = {}) {
39
106
  try {
40
- const dir = configDir();
41
- fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
42
- // auto-rotate if over 10 MB (cheap stat, keeps log bounded)
43
- try { const st = fs.statSync(auditPath()); if (st.size > 10*1024*1024) rotateAuditIfNeeded(); } catch {}
44
- // R2 fix: don't store huge bodies in audit log — store size instead
45
- function trunc(v, depth=0) {
46
- if (depth > 6) return '[max depth]';
47
- if (typeof v === 'string' && v.length > 4000) {
48
- return `[${v.length} chars truncated]`;
49
- }
50
- if (v && typeof v === 'object') {
51
- if (Array.isArray(v)) return v.map(x => trunc(x, depth+1));
52
- const out = {};
53
- for (const [k, val] of Object.entries(v)) {
54
- if ((k === 'content' || k === 'data_base64' || k === 'data' || k === 'text') && typeof val === 'string' && val.length > 1000) {
55
- out[k] = `[${val.length} chars truncated]`;
56
- out[k + '_bytes'] = Buffer.byteLength(val);
57
- } else {
58
- out[k] = trunc(val, depth+1);
59
- }
60
- }
61
- return out;
62
- }
63
- return v;
64
- }
65
- const rec = { ts: new Date().toISOString(), ...trunc(scrub(entry)) };
66
- fs.appendFileSync(auditPath(), JSON.stringify(rec) + '\n', { mode: 0o600 });
107
+ fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
108
+ const { id, args, ...fields } = entry;
109
+ const recId = String(id || newEntryId(fields.tool));
110
+ const params = argsFor(recId, args);
111
+ const body = clipFields(scrub({ kind: 'call', ...fields }));
112
+ const rec = {
113
+ id: recId,
114
+ ts: new Date().toISOString(),
115
+ ...body,
116
+ level: levelFor({ kind: body.kind, status: body.status, level: body.level }),
117
+ actor: body.actor || 'agent',
118
+ source: body.source ?? null,
119
+ args: params.args,
120
+ args_truncated: params.truncated,
121
+ ...(params.artifact ? { args_artifact: params.artifact } : {}),
122
+ };
123
+ const file = auditPath();
124
+ fs.appendFileSync(file, JSON.stringify(rec) + '\n', { mode: 0o600 });
125
+ if (fs.statSync(file).size > ROTATE_BYTES) rotateAudit();
67
126
  } catch {
68
127
  /* auditing must never break the request */
69
128
  }
70
129
  }
71
130
 
72
- export function tailAudit(n = 50) {
73
- const file = auditPath();
74
- if (!fs.existsSync(file)) return [];
75
- // R6 fix: read from end, not whole file, to handle large audit.log
131
+ /* ------------------------------------------------------------------ *
132
+ * segments: the active file plus closed archives, oldest first
133
+ * ------------------------------------------------------------------ */
134
+
135
+ /** Last rotation only: maps the active file's previous name to its archive name, so open cursors survive it. */
136
+ const renamed = new Map();
137
+ const resolveName = (n) => renamed.get(n) || n;
138
+ const fileOf = (n) => path.join(configDir(), n);
139
+ const sizeOf = (n) => {
140
+ try {
141
+ return fs.statSync(fileOf(n)).size;
142
+ } catch {
143
+ return 0;
144
+ }
145
+ };
146
+
147
+ export function segments() {
148
+ let names = [];
149
+ try {
150
+ names = fs.readdirSync(configDir()).filter((f) => ARCHIVE.test(f)).sort();
151
+ } catch {
152
+ /* no log yet */
153
+ }
154
+ return [...names, ACTIVE];
155
+ }
156
+
157
+ const encode = (c) => (c ? Buffer.from(`${c.name}:${c.off}`).toString('base64url') : null);
158
+
159
+ function decode(token) {
160
+ const m = /^(.+):(\d+)$/.exec(Buffer.from(String(token), 'base64url').toString('utf8'));
161
+ if (!m || !(ARCHIVE.test(m[1]) || m[1] === ACTIVE)) return null;
162
+ return { name: resolveName(m[1]), off: Number(m[2]) };
163
+ }
164
+
165
+ /** Cursor at the very beginning of the oldest segment. */
166
+ export function startCursor() {
167
+ return encode({ name: segments()[0], off: 0 });
168
+ }
169
+
170
+ /** Cursor at the current end of the active file: new records are after it. */
171
+ export function headCursor() {
172
+ return encode({ name: ACTIVE, off: sizeOf(ACTIVE) });
173
+ }
174
+
175
+ /** Complete lines of one file, from the end backwards: { text, start, end } with byte offsets. */
176
+ function* backLines(file, end) {
177
+ let fd;
76
178
  try {
77
- const stat = fs.statSync(file);
78
- // if file small (<1MB), use simple path
79
- if (stat.size < 1024*1024) {
80
- const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
81
- return lines.slice(-n).map((l) => { try { return JSON.parse(l); } catch { return { raw: l }; } });
179
+ fd = fs.openSync(file, 'r');
180
+ } catch {
181
+ return;
182
+ }
183
+ try {
184
+ let pos = end;
185
+ let carry = Buffer.alloc(0);
186
+ for (;;) {
187
+ const from = Math.max(0, pos - READ_CHUNK);
188
+ const chunk = Buffer.alloc(pos - from);
189
+ if (chunk.length) fs.readSync(fd, chunk, 0, chunk.length, from);
190
+ pos = from;
191
+ const buf = Buffer.concat([chunk, carry]);
192
+ let hi = buf.length;
193
+ let i = hi > 0 ? buf.lastIndexOf(0x0a, hi - 1) : -1;
194
+ while (i !== -1) {
195
+ const s = i + 1;
196
+ if (hi > s) yield { text: buf.toString('utf8', s, hi), start: from + s, end: from + hi + 1 };
197
+ hi = i;
198
+ i = hi > 0 ? buf.lastIndexOf(0x0a, hi - 1) : -1;
199
+ }
200
+ carry = buf.subarray(0, hi);
201
+ if (from === 0) {
202
+ if (carry.length) yield { text: carry.toString('utf8'), start: 0, end: carry.length };
203
+ return;
204
+ }
82
205
  }
83
- // For large files, read last 512KB and get needed lines (reverse-read approximation)
84
- const fd = fs.openSync(file, 'r');
85
- const chunkSize = 512*1024;
86
- const start = Math.max(0, stat.size - chunkSize);
87
- const buf = Buffer.alloc(stat.size - start);
88
- fs.readSync(fd, buf, 0, buf.length, start);
206
+ } finally {
89
207
  fs.closeSync(fd);
90
- const lines = buf.toString('utf8').trim().split('\n').filter(Boolean);
91
- // If we didn't get enough due to truncation, fallback to reading more
92
- if (lines.length < n && start > 0) {
93
- const moreStart = Math.max(0, stat.size - chunkSize*4);
94
- const buf2 = Buffer.alloc(stat.size - moreStart);
95
- const fd2 = fs.openSync(file, 'r');
96
- fs.readSync(fd2, buf2, 0, buf2.length, moreStart);
97
- fs.closeSync(fd2);
98
- const lines2 = buf2.toString('utf8').trim().split('\n').filter(Boolean);
99
- return lines2.slice(-n).map((l) => { try { return JSON.parse(l); } catch { return { raw: l }; } });
100
- }
101
- return lines.slice(-n).map((l) => { try { return JSON.parse(l); } catch { return { raw: l }; } });
208
+ }
209
+ }
210
+
211
+ /** Complete lines of one file, from an offset forwards, up to `budget` bytes. */
212
+ function forwardLines(name, off, budget) {
213
+ const out = [];
214
+ let fd;
215
+ try {
216
+ fd = fs.openSync(fileOf(name), 'r');
102
217
  } catch {
103
- // fallback to old method
104
- try {
105
- const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
106
- return lines.slice(-n).map((l) => { try { return JSON.parse(l); } catch { return { raw: l }; } });
107
- } catch { return []; }
218
+ return { lines: out, eof: true };
219
+ }
220
+ try {
221
+ const size = fs.fstatSync(fd).size;
222
+ let pos = off;
223
+ let used = 0;
224
+ while (pos < size && used < budget) {
225
+ let n = Math.min(READ_CHUNK, size - pos);
226
+ let buf;
227
+ let last;
228
+ for (;;) {
229
+ buf = Buffer.alloc(n);
230
+ fs.readSync(fd, buf, 0, n, pos);
231
+ last = buf.lastIndexOf(0x0a);
232
+ if (last !== -1 || pos + n >= size) break;
233
+ n = Math.min(n * 2, size - pos);
234
+ }
235
+ if (last === -1) break;
236
+ let s = 0;
237
+ while (s <= last && used < budget) {
238
+ const e = buf.indexOf(0x0a, s);
239
+ out.push({ text: buf.toString('utf8', s, e), end: pos + e + 1 });
240
+ used += e + 1 - s;
241
+ s = e + 1;
242
+ }
243
+ pos += s;
244
+ if (s <= last) break;
245
+ }
246
+ return { lines: out, eof: pos >= size };
247
+ } finally {
248
+ fs.closeSync(fd);
108
249
  }
109
250
  }
110
251
 
111
- export function rotateAuditIfNeeded(maxBytes = 10*1024*1024) {
112
- const file = auditPath();
113
- if (!fs.existsSync(file)) return;
252
+ function parse(text) {
114
253
  try {
115
- const stat = fs.statSync(file);
116
- if (stat.size > maxBytes) {
117
- const lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
118
- // keep last 50% of lines
119
- const keep = lines.slice(Math.floor(lines.length/2));
120
- const tmp = file + '.tmp';
121
- fs.writeFileSync(tmp, keep.join('\n') + '\n', { mode: 0o600 });
122
- fs.renameSync(tmp, file);
254
+ return JSON.parse(text);
255
+ } catch {
256
+ return null;
257
+ }
258
+ }
259
+
260
+ /**
261
+ * One page of the log. Default: the newest `limit` records, oldest first, with `next` (older page).
262
+ * `before` pages further back. `after` reads forward from a cursor (new records).
263
+ */
264
+ export function auditPage({ limit = 100, before, after, tool, kind, level } = {}) {
265
+ const minLevel = level ? LEVELS.indexOf(level) : -1;
266
+ if (level && minLevel < 0) return { error: 'invalid level', entries: [], next: null, has_more: false };
267
+ const want = (rec) =>
268
+ (!tool || rec.tool === tool) && (!kind || rec.kind === kind) && (minLevel < 0 || LEVELS.indexOf(rec.level) >= minLevel);
269
+ const names = segments();
270
+ const out = [];
271
+ let scanned = 0;
272
+
273
+ if (after) {
274
+ const c = decode(after);
275
+ if (!c) return { error: 'invalid cursor', entries: [], next: null, has_more: false };
276
+ let ci = names.indexOf(c.name);
277
+ if (ci < 0) return { entries: [], next: headCursor(), has_more: false, reset: true };
278
+ let off = c.off;
279
+ let cur = c;
280
+ for (;;) {
281
+ const f = forwardLines(names[ci], off, SCAN_BUDGET - scanned);
282
+ for (const ln of f.lines) {
283
+ scanned += ln.end - off;
284
+ off = ln.end;
285
+ cur = { name: names[ci], off };
286
+ const rec = parse(ln.text);
287
+ if (rec && want(rec)) {
288
+ out.push(rec);
289
+ if (out.length >= limit) break;
290
+ }
291
+ }
292
+ if (out.length >= limit || scanned >= SCAN_BUDGET) break;
293
+ if (f.eof && ci < names.length - 1) {
294
+ ci++;
295
+ off = 0;
296
+ cur = { name: names[ci], off: 0 };
297
+ continue;
298
+ }
299
+ break;
300
+ }
301
+ const more = !(names.indexOf(cur.name) === names.length - 1 && cur.off >= sizeOf(ACTIVE));
302
+ return { entries: out, next: encode(cur), has_more: more, reset: false };
303
+ }
304
+
305
+ let ci = names.length - 1;
306
+ let off = sizeOf(names[ci]);
307
+ if (before) {
308
+ const c = decode(before);
309
+ if (!c) return { error: 'invalid cursor', entries: [], next: null, has_more: false };
310
+ ci = names.indexOf(c.name);
311
+ if (ci < 0) return { entries: [], next: null, has_more: false, reset: true };
312
+ off = c.off;
313
+ }
314
+ let cur = null;
315
+ outer: while (ci >= 0) {
316
+ for (const ln of backLines(fileOf(names[ci]), off)) {
317
+ cur = { name: names[ci], off: ln.start };
318
+ scanned += ln.end - ln.start;
319
+ const rec = parse(ln.text);
320
+ if (rec && want(rec)) {
321
+ out.push(rec);
322
+ if (out.length >= limit) break outer;
323
+ }
324
+ if (scanned >= SCAN_BUDGET) break outer;
325
+ }
326
+ ci--;
327
+ if (ci >= 0) off = sizeOf(names[ci]);
328
+ }
329
+ const done = ci < 0;
330
+ const more = !done && !(cur && cur.name === names[0] && cur.off === 0);
331
+ return { entries: out.reverse(), next: more ? encode(cur) : null, has_more: more, reset: false };
332
+ }
333
+
334
+ export function tailAudit(n = 50) {
335
+ return auditPage({ limit: n }).entries;
336
+ }
337
+
338
+ /** The record with this id, searched newest first, or null. */
339
+ export function findEntry(id) {
340
+ const names = segments();
341
+ for (let ci = names.length - 1; ci >= 0; ci--) {
342
+ for (const ln of backLines(fileOf(names[ci]), sizeOf(names[ci]))) {
343
+ if (!ln.text.includes(id)) continue;
344
+ const rec = parse(ln.text);
345
+ if (rec && rec.id === id) return rec;
123
346
  }
124
- } catch {}
347
+ }
348
+ return null;
349
+ }
350
+
351
+ /** The API view of a record: no parameters or bulky output, long strings clipped, plus a short args preview. */
352
+ export function lean(rec) {
353
+ const out = {};
354
+ for (const [k, v] of Object.entries(rec)) {
355
+ if (LEAN_DROP.includes(k)) continue;
356
+ out[k] = typeof v === 'string' && v.length > LEAN_CLIP ? `${v.slice(0, LEAN_CLIP)}…` : v;
357
+ }
358
+ if (rec.args !== undefined) out.args_preview = JSON.stringify(rec.args).slice(0, 200);
359
+ return out;
360
+ }
361
+
362
+ /** Close the active file into an archive. The newest archive is never removed by retention. */
363
+ export function rotateAudit(now = Date.now()) {
364
+ const file = auditPath();
365
+ if (!fs.existsSync(file)) return null;
366
+ let ms = now;
367
+ let name;
368
+ do {
369
+ name = `audit-${String(ms).padStart(13, '0')}.log`;
370
+ ms++;
371
+ } while (fs.existsSync(fileOf(name)));
372
+ fs.renameSync(file, fileOf(name));
373
+ renamed.set(ACTIVE, name);
374
+ pruneAudit();
375
+ return name;
376
+ }
377
+
378
+ /** Delete archives older than `days`, then the oldest ones while the total is above `maxBytes`. */
379
+ export function pruneAudit({ days = RETAIN_DAYS, maxBytes = RETAIN_BYTES, now = Date.now() } = {}) {
380
+ const archives = segments()
381
+ .slice(0, -1)
382
+ .map((name) => {
383
+ try {
384
+ const st = fs.statSync(fileOf(name));
385
+ return { name, size: st.size, mtime: st.mtimeMs };
386
+ } catch {
387
+ return null;
388
+ }
389
+ })
390
+ .filter(Boolean);
391
+ let total = archives.reduce((s, f) => s + f.size, sizeOf(ACTIVE));
392
+ const cutoff = now - Number(days) * 86400000;
393
+ let removed = 0;
394
+ let freed = 0;
395
+ for (let i = 0; i < archives.length - 1; i++) {
396
+ const f = archives[i];
397
+ if (f.mtime >= cutoff && total <= maxBytes) break;
398
+ fs.rmSync(fileOf(f.name), { force: true });
399
+ total -= f.size;
400
+ freed += f.size;
401
+ removed++;
402
+ }
403
+ return { removed, freed_bytes: freed };
125
404
  }
126
405
 
127
406
  /* ------------------------------------------------------------------ *
@@ -180,24 +459,47 @@ export function listArtifacts() {
180
459
  return out;
181
460
  }
182
461
 
183
- export function pruneArtifacts(days = 14) {
462
+ function dirBytes(sub) {
463
+ let n = 0;
464
+ try {
465
+ for (const f of fs.readdirSync(sub)) {
466
+ try {
467
+ n += fs.statSync(path.join(sub, f)).size;
468
+ } catch {
469
+ /* ignore */
470
+ }
471
+ }
472
+ } catch {
473
+ /* ignore */
474
+ }
475
+ return n;
476
+ }
477
+
478
+ /** Remove artifact folders older than `days`, then the oldest while the total is above `maxBytes`. */
479
+ export function pruneArtifacts(days = ART_RETAIN_DAYS, maxBytes = ART_RETAIN_BYTES) {
184
480
  const dir = auditDir();
185
481
  if (!fs.existsSync(dir)) return { removed: 0, freed_bytes: 0 };
186
482
  const cutoff = Date.now() - Number(days) * 86400000;
187
- let removed = 0;
188
- let freed = 0;
483
+ const folders = [];
189
484
  for (const entry of fs.readdirSync(dir)) {
190
485
  const sub = path.join(dir, entry);
191
486
  try {
192
487
  const st = fs.statSync(sub);
193
- if (st.mtimeMs < cutoff) {
194
- freed += st.size;
195
- fs.rmSync(sub, { recursive: true, force: true });
196
- removed++;
197
- }
488
+ if (st.isDirectory()) folders.push({ sub, mtime: st.mtimeMs, size: dirBytes(sub) });
198
489
  } catch {
199
490
  /* ignore */
200
491
  }
201
492
  }
493
+ folders.sort((a, b) => a.mtime - b.mtime);
494
+ let total = folders.reduce((s, f) => s + f.size, 0);
495
+ let removed = 0;
496
+ let freed = 0;
497
+ for (const f of folders) {
498
+ if (f.mtime >= cutoff && total <= maxBytes) break;
499
+ fs.rmSync(f.sub, { recursive: true, force: true });
500
+ total -= f.size;
501
+ freed += f.size;
502
+ removed++;
503
+ }
202
504
  return { removed, freed_bytes: freed };
203
505
  }
package/src/browser.mjs CHANGED
@@ -1063,7 +1063,6 @@ export class BrowserManager {
1063
1063
  if (!chk.ok) return { ok: false, error: chk.error, reason: chk.reason };
1064
1064
  fs.mkdirSync(path.dirname(chk.abs), { recursive: true });
1065
1065
  fs.writeFileSync(chk.abs, Buffer.from(b64, 'base64'));
1066
- audit({ tool: 'chrome_screenshot', args, status: 'ok', path: chk.abs });
1067
1066
  return { ok: true, tab_id: tab.targetId, path: chk.abs, bytes: Math.round((b64.length * 3) / 4) };
1068
1067
  }
1069
1068
  return { ok: true, tab_id: tab.targetId, image_base64: b64, bytes: Math.round((b64.length * 3) / 4) };
package/src/catalog.mjs CHANGED
@@ -5,6 +5,9 @@ import path from 'node:path';
5
5
  import { checkPath, resolveTarget } from './policy.mjs';
6
6
  import { audit, saveArtifact, tailAudit, readArtifact, auditDir } from './audit.mjs';
7
7
  import { clip, runShell } from './engine_helpers.mjs';
8
+ import { errorResponse } from './errors.mjs';
9
+
10
+ let lastNoteAt = 0;
8
11
 
9
12
  const S = (o) => ({ type: 'object', properties: o, required: [], additionalProperties: false });
10
13
 
@@ -352,6 +355,24 @@ export function toolCatalog() {
352
355
  return { ok: true, count: entries.length, entries, artifacts_dir: auditDir() };
353
356
  },
354
357
  },
358
+ {
359
+ name: 'log_note',
360
+ description:
361
+ 'Write a short comment into the work log that the user reads, for example what you are about to do and why. It changes nothing else and needs no approval. Plain text, up to 500 characters, at most one note per second.',
362
+ approval: false,
363
+ schema: S({ text: { type: 'string', description: 'the comment, plain text, 1 to 500 characters' } }),
364
+ required: ['text'],
365
+ handler: async (args) => {
366
+ const text = typeof args.text === 'string' ? args.text.trim() : '';
367
+ if (!text || [...text].length > 500) {
368
+ return errorResponse('INVALID_ARGS', { message: 'text must be 1 to 500 characters' });
369
+ }
370
+ const now = Date.now();
371
+ if (now - lastNoteAt < 1000) return errorResponse('RATE_LIMITED');
372
+ lastNoteAt = now;
373
+ return { ok: true, noted: true, text };
374
+ },
375
+ },
355
376
  {
356
377
  name: 'audit_artifact',
357
378
  description: