@crewhaus/tool-state 0.7.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/dist/index.js ADDED
@@ -0,0 +1,1858 @@
1
+ /**
2
+ * @crewhaus/tool-state — durable harness state, and lexical retrieval over it.
3
+ *
4
+ * A long-running crew needs somewhere to put the things a context window
5
+ * cannot hold: what it has already handled, how many attempts are left, where
6
+ * it got to before it was interrupted, what one agent wants another to know.
7
+ * This package is that somewhere. It is a directory of small files under the
8
+ * workspace (`.crewhaus/state` by default) — no database, no server, no
9
+ * network, nothing to run alongside the harness.
10
+ *
11
+ * Four properties hold across every tool here:
12
+ *
13
+ * 1. CONTAINMENT. The state directory and every file path a caller supplies
14
+ * go through `resolveSafe`, which refuses anything resolving outside
15
+ * `process.cwd()`, including via a symlink inside the workspace. Every
16
+ * path BENEATH the state directory is checked the same way, because the
17
+ * escape that works in practice is an innocuous-looking `kv/cache` that
18
+ * is a symlink to somewhere else.
19
+ * 2. DETERMINISM. Same inputs against the same state, same bytes out.
20
+ * Listings are sorted with plain code-unit comparison (never
21
+ * `localeCompare`), nothing samples a random source, an instant with no
22
+ * offset is read as UTC rather than in the machine's zone, and NO TOOL
23
+ * READS THE CLOCK — expiry and timestamps come from a caller-supplied
24
+ * `now`.
25
+ * 3. TOLERANCE. A corrupt or half-written file is reported, with its path
26
+ * and the reason, as a normal result. Nothing throws out of `execute`
27
+ * because a previous run was killed mid-write.
28
+ * 4. SAFETY FLAGS THAT MEAN SOMETHING. Reads are `readOnly`; anything that
29
+ * writes is `destructive`. Every tool in `STATE_TOOLS` is
30
+ * `scope: "internal"` with no declared io capability, because nothing in
31
+ * that list opens a socket or spawns a process — files under the
32
+ * workspace are all they touch.
33
+ *
34
+ * The one exception is `VectorDelete` (`vector.ts`), which deletes from a
35
+ * vector store the host registers and may therefore reach a remote
36
+ * collection. It is labelled `scope: "external"` + `ioCapability: "network"`
37
+ * and listed in `VECTOR_TOOLS`, NOT in `STATE_TOOLS`, so the promise the
38
+ * twenty make stays exactly as strong as it was.
39
+ *
40
+ * Concurrency is taken seriously but not magically: compare-and-set, counter
41
+ * increments and sequence allocation run under a machine-local lock file with
42
+ * a deadline, journal appends use `O_APPEND`, and de-duplication rides on an
43
+ * exclusive create. Two agents in one workspace are safe. Two machines sharing
44
+ * a directory over a network filesystem are not, and the README says so.
45
+ */
46
+ import { readdirSync, statSync } from "node:fs";
47
+ import * as path from "node:path";
48
+ import { buildTool } from "@crewhaus/tool-builder";
49
+ import { z } from "zod";
50
+ import { DEFAULT_B, DEFAULT_K1, buildIndex, isInvertedIndex, searchIndex, snippet, } from "./lib/bm25";
51
+ import { filterRecords, highestSeq, parseJsonl, toJsonlLine, } from "./lib/jsonl";
52
+ import { MAX_KEY_LENGTH, compareStrings, decodeSegment, encodeSegment, validateKey, validateName, } from "./lib/names";
53
+ import { byteLength, casConflict, expiryFrom, formatInstant, isExpired, isPlainObject, isStoredRecord, parseInstant, } from "./lib/records";
54
+ import { ToolPermissionError, entryNameEscapes, resolveSafe, workspaceRoot, } from "./paths";
55
+ import { DEFAULT_STATE_DIR, MAX_FILE_BYTES, appendLine, createExclusive, describeIoError, errorCode, fileSize, listNames, readBytes, readJsonFile, readTextFile, relativeToRoot, removeFile, removeTree, sha256, statePath, stateRoot, walkFiles, withLock, writeBuffer, writeJsonAtomic, } from "./store";
56
+ import { MAX_VECTOR_IDS, applyVectorDeletes, capList, checkCollection, countIsIndicative, describeBackend, getVectorTarget, observeCount, readVectorToolConfig, selectVectorIds, unionProtected, } from "./vector";
57
+ /** Compact JSON — the reader is a model, and every byte is context. */
58
+ const json = (value) => JSON.stringify(value);
59
+ // --- limits -----------------------------------------------------------------
60
+ /** Largest single stored value: a KV value, checkpoint, note or journal entry. */
61
+ const MAX_VALUE_BYTES = 4 * 1024 * 1024;
62
+ /** Largest journal or blackboard log this package will read in one call. */
63
+ const MAX_LOG_BYTES = 32 * 1024 * 1024;
64
+ /** Largest file `IndexBuild` will index, and `IndexSearch` will re-read. */
65
+ const MAX_INDEXED_FILE_BYTES = 4 * 1024 * 1024;
66
+ /** Total text `IndexBuild` will hold in memory across every file. */
67
+ const MAX_INDEXED_TOTAL_BYTES = 128 * 1024 * 1024;
68
+ /** Most records one listing will scan, so a runaway store cannot hang a call. */
69
+ const MAX_SCAN = 5_000;
70
+ /** Most files `StateExport` will carry, and `StateImport` will accept. */
71
+ const MAX_EXPORT_FILES = 5_000;
72
+ /** Largest export, measured on the bytes exported. */
73
+ const MAX_EXPORT_BYTES = 64 * 1024 * 1024;
74
+ /** Small metadata files (counters, sequence hints, dedupe marks). */
75
+ const SMALL_FILE_BYTES = 64 * 1024;
76
+ // --- directory layout -------------------------------------------------------
77
+ const KV_DIR = "kv";
78
+ const COUNTER_DIR = "counters";
79
+ const CHECKPOINT_DIR = "checkpoints";
80
+ const JOURNAL_DIR = "journal";
81
+ const BLACKBOARD_DIR = "blackboard";
82
+ const NOTE_DIR = "notes";
83
+ const INDEX_DIR = "indexes";
84
+ const DEDUPE_DIR = "dedupe";
85
+ /** Every top-level directory this package creates inside a state directory. */
86
+ const STATE_DIRS = new Set([
87
+ KV_DIR,
88
+ COUNTER_DIR,
89
+ CHECKPOINT_DIR,
90
+ JOURNAL_DIR,
91
+ BLACKBOARD_DIR,
92
+ NOTE_DIR,
93
+ INDEX_DIR,
94
+ DEDUPE_DIR,
95
+ ]);
96
+ // --- shared schema fragments ------------------------------------------------
97
+ const stateDirField = z
98
+ .string()
99
+ .min(1)
100
+ .optional()
101
+ .describe(`state directory, relative to the workspace (default '${DEFAULT_STATE_DIR}')`);
102
+ const nowField = z
103
+ .string()
104
+ .optional()
105
+ .describe("ISO-8601 instant to record as the time of this call; nothing here reads the system clock, so omitting it simply stores no timestamp");
106
+ // --- shared helpers ---------------------------------------------------------
107
+ /**
108
+ * `buildTool`, plus the two failures every tool in this package shares: a path
109
+ * that escapes the workspace, and an I/O error the caller can act on. Both
110
+ * come back as a readable sentence. Anything else is a bug and still throws,
111
+ * because a crash the runtime can see beats a lie the caller cannot.
112
+ */
113
+ function stateTool(def) {
114
+ const inner = def.execute;
115
+ return buildTool({
116
+ ...def,
117
+ execute: async (input, ctx) => {
118
+ try {
119
+ return await inner(input, ctx);
120
+ }
121
+ catch (err) {
122
+ if (err instanceof ToolPermissionError)
123
+ return err.message;
124
+ const io = describeIoError(err);
125
+ if (io !== undefined)
126
+ return `${def.name} could not complete: ${io}`;
127
+ throw err;
128
+ }
129
+ },
130
+ });
131
+ }
132
+ function parseNow(value) {
133
+ if (value === undefined)
134
+ return {};
135
+ const ms = parseInstant(value);
136
+ if (ms === undefined)
137
+ return { error: `now is not an ISO-8601 instant I can read: ${value}` };
138
+ return { ms };
139
+ }
140
+ /** A corrupt read, rendered for the caller with the path that is broken. */
141
+ function corruptMessage(rel, reason) {
142
+ return `${rel} is unusable: ${reason} — delete or repair the file, then retry`;
143
+ }
144
+ function sizeGuard(field, value) {
145
+ const bytes = byteLength(JSON.stringify(value ?? null));
146
+ if (bytes > MAX_VALUE_BYTES) {
147
+ return `${field} is ${bytes} bytes, over the ${MAX_VALUE_BYTES} limit — store it as a file and keep a path here instead`;
148
+ }
149
+ return undefined;
150
+ }
151
+ function loadRecord(abs, rel) {
152
+ const outcome = readJsonFile(abs, MAX_VALUE_BYTES * 2);
153
+ if (outcome.kind === "missing")
154
+ return { kind: "missing" };
155
+ if (outcome.kind === "corrupt") {
156
+ return { kind: "broken", message: corruptMessage(rel, outcome.reason) };
157
+ }
158
+ if (!isStoredRecord(outcome.value)) {
159
+ return { kind: "broken", message: corruptMessage(rel, "not a state record") };
160
+ }
161
+ return { kind: "ok", record: outcome.value };
162
+ }
163
+ /** The `next` hint beside a log, or `undefined` when it is absent or unusable. */
164
+ function readSequenceHint(seqAbs) {
165
+ const outcome = readJsonFile(seqAbs, SMALL_FILE_BYTES);
166
+ if (outcome.kind !== "ok" || !isPlainObject(outcome.value))
167
+ return undefined;
168
+ const next = outcome.value["next"];
169
+ return typeof next === "number" && Number.isFinite(next) && next >= 1 ? next : undefined;
170
+ }
171
+ /**
172
+ * Append a record to a `.jsonl` log with a monotonic sequence number.
173
+ *
174
+ * The number is allocated under a lock, so two writers never take the same
175
+ * one; the line itself is written with `O_APPEND`, so even a writer that
176
+ * ignored the lock cannot split somebody else's line. If the sequence hint is
177
+ * missing or unusable it is rebuilt from the log's own highest sequence and
178
+ * the caller is told. Sequences are monotonic but not gapless: an append that
179
+ * fails after its number was allocated leaves a hole, so a sequence is an
180
+ * ordering, not a count.
181
+ */
182
+ async function appendSequenced(toolName, root, dir, name, build) {
183
+ const encoded = encodeSegment(name);
184
+ const logAbs = statePath(toolName, root, dir, `${encoded}.jsonl`);
185
+ const seqAbs = `${logAbs}.seq`;
186
+ const logRel = relativeToRoot(root, logAbs);
187
+ const locked = await withLock(`${logAbs}.lock`, () => {
188
+ const hint = readSequenceHint(seqAbs);
189
+ let next = hint;
190
+ let rebuilt = false;
191
+ if (next === undefined) {
192
+ const log = readTextFile(logAbs, MAX_LOG_BYTES);
193
+ if (log.kind === "corrupt")
194
+ return { ok: false, message: corruptMessage(logRel, log.reason) };
195
+ next = log.kind === "ok" ? highestSeq(parseJsonl(log.value).records) + 1 : 1;
196
+ // Only call it a rebuild when there was something to rebuild FROM.
197
+ rebuilt = next > 1;
198
+ }
199
+ const line = toJsonlLine(build(next));
200
+ appendLine(logAbs, line);
201
+ writeJsonAtomic(seqAbs, { next: next + 1 });
202
+ return { ok: true, seq: next, bytes: byteLength(line), rebuiltSequence: rebuilt };
203
+ });
204
+ return locked.ok ? locked.value : { ok: false, message: locked.reason };
205
+ }
206
+ /** Every `.jsonl` log in `dir`, sorted by name, with its high-water sequence. */
207
+ function listLogs(toolName, root, dir) {
208
+ const base = statePath(toolName, root, dir);
209
+ const streams = [];
210
+ const undecodable = [];
211
+ for (const file of listNames(base, "file")) {
212
+ if (!file.endsWith(".jsonl"))
213
+ continue;
214
+ const name = decodeSegment(file.slice(0, -".jsonl".length));
215
+ if (name === undefined) {
216
+ undecodable.push(file);
217
+ continue;
218
+ }
219
+ const abs = statePath(toolName, root, dir, file);
220
+ const hint = readSequenceHint(`${abs}.seq`);
221
+ // No hint, or an unusable one, does not mean an empty stream: the hint is
222
+ // a cache of the log's own high-water mark and can be lost on its own.
223
+ // Reporting `lastSeq: 0` for a stream with a thousand entries would send
224
+ // a resuming reader back to the beginning, so it is recomputed instead.
225
+ const lastSeq = hint !== undefined ? hint - 1 : highestSeqOf(toolName, root, dir, name);
226
+ streams.push({ name, lastSeq, bytes: fileSize(abs) ?? 0 });
227
+ }
228
+ streams.sort((a, b) => compareStrings(a.name, b.name));
229
+ return { streams, undecodable };
230
+ }
231
+ /** The high-water sequence read out of the log itself, or 0 if unreadable. */
232
+ function highestSeqOf(toolName, root, dir, name) {
233
+ const log = readLog(toolName, root, dir, name);
234
+ return log.ok ? highestSeq(log.records) : 0;
235
+ }
236
+ function readLog(toolName, root, dir, name) {
237
+ const abs = statePath(toolName, root, dir, `${encodeSegment(name)}.jsonl`);
238
+ const outcome = readTextFile(abs, MAX_LOG_BYTES);
239
+ if (outcome.kind === "missing")
240
+ return { ok: true, records: [], corrupt: [] };
241
+ if (outcome.kind === "corrupt") {
242
+ return { ok: false, message: corruptMessage(relativeToRoot(root, abs), outcome.reason) };
243
+ }
244
+ const parsed = parseJsonl(outcome.value);
245
+ return { ok: true, records: parsed.records, corrupt: parsed.corrupt };
246
+ }
247
+ // ---------------------------------------------------------------------------
248
+ // key-value store
249
+ // ---------------------------------------------------------------------------
250
+ export const kvSet = stateTool({
251
+ name: "KvSet",
252
+ description: "Store a JSON value under a key in a namespace, with an optional TTL and an optional compare-and-set on the current version. Use it to remember something across turns, runs or agents; pass `expectedVersion` when another agent might be writing the same key and the write is refused rather than clobbering theirs.",
253
+ inputSchema: z.object({
254
+ namespace: z.string().min(1).describe("a group of keys, e.g. 'orders' or 'session'"),
255
+ key: z.string().min(1).describe("any printable string, e.g. an id or a URL"),
256
+ value: z.unknown().describe("any JSON value"),
257
+ ttlSeconds: z
258
+ .number()
259
+ .int()
260
+ .positive()
261
+ .max(31_536_000)
262
+ .optional()
263
+ .describe("expiry, counted from `now`; requires `now`"),
264
+ expectedVersion: z
265
+ .number()
266
+ .int()
267
+ .min(0)
268
+ .optional()
269
+ .describe("compare-and-set: the version you last read, or 0 to require the key be absent"),
270
+ now: nowField,
271
+ stateDir: stateDirField,
272
+ }),
273
+ destructive: true,
274
+ execute: async (input) => {
275
+ const badNamespace = validateName("namespace", input.namespace);
276
+ if (badNamespace !== undefined)
277
+ return badNamespace;
278
+ const badKey = validateKey("key", input.key);
279
+ if (badKey !== undefined)
280
+ return badKey;
281
+ if (input.value === undefined)
282
+ return "value is required — pass null if you mean an empty value";
283
+ const tooBig = sizeGuard("value", input.value);
284
+ if (tooBig !== undefined)
285
+ return tooBig;
286
+ const now = parseNow(input.now);
287
+ if (now.error !== undefined)
288
+ return now.error;
289
+ if (input.ttlSeconds !== undefined && now.ms === undefined) {
290
+ return "ttlSeconds needs `now`: expiry is computed from the instant you supply, never from the system clock";
291
+ }
292
+ const root = stateRoot("KvSet", input.stateDir);
293
+ const abs = statePath("KvSet", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
294
+ const rel = relativeToRoot(root, abs);
295
+ const locked = await withLock(`${abs}.lock`, () => {
296
+ const existing = loadRecord(abs, rel);
297
+ if (existing.kind === "broken")
298
+ return existing.message;
299
+ const current = existing.kind === "missing" ? undefined : existing.record.version;
300
+ const conflict = casConflict(current, input.expectedVersion);
301
+ if (conflict !== undefined) {
302
+ return json({
303
+ stored: false,
304
+ conflict: true,
305
+ reason: conflict,
306
+ currentVersion: current ?? null,
307
+ });
308
+ }
309
+ const record = {
310
+ key: input.key,
311
+ value: input.value,
312
+ version: (current ?? 0) + 1,
313
+ ...(input.ttlSeconds !== undefined && now.ms !== undefined
314
+ ? { expiresAt: expiryFrom(now.ms, input.ttlSeconds) }
315
+ : {}),
316
+ ...(now.ms !== undefined ? { updatedAt: formatInstant(now.ms) } : {}),
317
+ };
318
+ const bytes = writeJsonAtomic(abs, record);
319
+ return json({
320
+ stored: true,
321
+ namespace: input.namespace,
322
+ key: input.key,
323
+ version: record.version,
324
+ created: current === undefined,
325
+ bytes,
326
+ ...(record.expiresAt !== undefined ? { expiresAt: record.expiresAt } : {}),
327
+ });
328
+ });
329
+ return locked.ok ? locked.value : locked.reason;
330
+ },
331
+ });
332
+ export const kvGet = stateTool({
333
+ name: "KvGet",
334
+ description: "Read one key back, with its version and expiry. Use it before a compare-and-set write, or to recover a value a previous turn stored; expiry is evaluated only when you pass `now`, and the result says whether it was checked.",
335
+ inputSchema: z.object({
336
+ namespace: z.string().min(1),
337
+ key: z.string().min(1),
338
+ now: z
339
+ .string()
340
+ .optional()
341
+ .describe("ISO-8601 instant to evaluate expiry against; omit and expiry is not checked"),
342
+ includeExpired: z.boolean().optional().describe("return the value even when it has expired"),
343
+ stateDir: stateDirField,
344
+ }),
345
+ readOnly: true,
346
+ concurrencySafe: true,
347
+ execute: async (input) => {
348
+ const badNamespace = validateName("namespace", input.namespace);
349
+ if (badNamespace !== undefined)
350
+ return badNamespace;
351
+ const badKey = validateKey("key", input.key);
352
+ if (badKey !== undefined)
353
+ return badKey;
354
+ const now = parseNow(input.now);
355
+ if (now.error !== undefined)
356
+ return now.error;
357
+ const root = stateRoot("KvGet", input.stateDir);
358
+ const abs = statePath("KvGet", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
359
+ const loaded = loadRecord(abs, relativeToRoot(root, abs));
360
+ if (loaded.kind === "broken")
361
+ return loaded.message;
362
+ if (loaded.kind === "missing") {
363
+ return json({ found: false, namespace: input.namespace, key: input.key });
364
+ }
365
+ const record = loaded.record;
366
+ const expired = isExpired(record.expiresAt, now.ms);
367
+ if (expired && input.includeExpired !== true) {
368
+ return json({
369
+ found: false,
370
+ expired: true,
371
+ namespace: input.namespace,
372
+ key: input.key,
373
+ version: record.version,
374
+ expiresAt: record.expiresAt,
375
+ });
376
+ }
377
+ return json({
378
+ found: true,
379
+ namespace: input.namespace,
380
+ key: input.key,
381
+ value: record.value,
382
+ version: record.version,
383
+ expired,
384
+ expiryChecked: record.expiresAt === undefined || now.ms !== undefined,
385
+ ...(record.expiresAt !== undefined ? { expiresAt: record.expiresAt } : {}),
386
+ ...(record.updatedAt !== undefined ? { updatedAt: record.updatedAt } : {}),
387
+ });
388
+ },
389
+ });
390
+ export const kvDelete = stateTool({
391
+ name: "KvDelete",
392
+ description: "Delete a key, optionally only while it is still at the version you read. Use it to release a claim or drop state you are finished with; deleting a key that is not there is reported, not an error.",
393
+ inputSchema: z.object({
394
+ namespace: z.string().min(1),
395
+ key: z.string().min(1),
396
+ expectedVersion: z
397
+ .number()
398
+ .int()
399
+ .min(1)
400
+ .optional()
401
+ .describe("compare-and-set: delete only if the key is still at this version"),
402
+ stateDir: stateDirField,
403
+ }),
404
+ destructive: true,
405
+ execute: async (input) => {
406
+ const badNamespace = validateName("namespace", input.namespace);
407
+ if (badNamespace !== undefined)
408
+ return badNamespace;
409
+ const badKey = validateKey("key", input.key);
410
+ if (badKey !== undefined)
411
+ return badKey;
412
+ const root = stateRoot("KvDelete", input.stateDir);
413
+ const abs = statePath("KvDelete", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
414
+ const rel = relativeToRoot(root, abs);
415
+ const locked = await withLock(`${abs}.lock`, () => {
416
+ const existing = loadRecord(abs, rel);
417
+ if (existing.kind === "broken") {
418
+ // A corrupt record can still be deleted — that is half the point of a
419
+ // delete — but not under a version check it cannot satisfy.
420
+ if (input.expectedVersion !== undefined)
421
+ return existing.message;
422
+ return json({ deleted: removeFile(abs), existed: true, corrupt: true });
423
+ }
424
+ if (existing.kind === "missing") {
425
+ const conflict = casConflict(undefined, input.expectedVersion);
426
+ if (conflict !== undefined)
427
+ return json({ deleted: false, conflict: true, reason: conflict });
428
+ return json({ deleted: false, existed: false });
429
+ }
430
+ const version = existing.record.version;
431
+ const conflict = casConflict(version, input.expectedVersion);
432
+ if (conflict !== undefined) {
433
+ return json({ deleted: false, conflict: true, reason: conflict, currentVersion: version });
434
+ }
435
+ return json({ deleted: removeFile(abs), existed: true, version });
436
+ });
437
+ return locked.ok ? locked.value : locked.reason;
438
+ },
439
+ });
440
+ export const kvList = stateTool({
441
+ name: "KvList",
442
+ description: "List the keys in a namespace, sorted, with their versions and optionally their values. Use it to see what a previous run left behind; records whose files are corrupt are listed separately instead of failing the whole call.",
443
+ inputSchema: z.object({
444
+ namespace: z.string().min(1),
445
+ prefix: z.string().optional().describe("only keys starting with this"),
446
+ includeValues: z.boolean().optional().describe("include each value (default false)"),
447
+ now: z.string().optional().describe("ISO-8601 instant to evaluate expiry against"),
448
+ includeExpired: z.boolean().optional(),
449
+ limit: z.number().int().positive().max(MAX_SCAN).optional().describe("default 200"),
450
+ stateDir: stateDirField,
451
+ }),
452
+ readOnly: true,
453
+ concurrencySafe: true,
454
+ execute: async (input) => {
455
+ const badNamespace = validateName("namespace", input.namespace);
456
+ if (badNamespace !== undefined)
457
+ return badNamespace;
458
+ const now = parseNow(input.now);
459
+ if (now.error !== undefined)
460
+ return now.error;
461
+ const limit = input.limit ?? 200;
462
+ const root = stateRoot("KvList", input.stateDir);
463
+ const namespaceDir = encodeSegment(input.namespace);
464
+ const dir = statePath("KvList", root, KV_DIR, namespaceDir);
465
+ const entries = [];
466
+ const corrupt = [];
467
+ let expiredCount = 0;
468
+ let scanned = 0;
469
+ for (const file of listNames(dir, "file")) {
470
+ if (!file.endsWith(".json"))
471
+ continue;
472
+ if (scanned >= MAX_SCAN)
473
+ break;
474
+ scanned += 1;
475
+ const loaded = loadRecord(statePath("KvList", root, KV_DIR, namespaceDir, file), file);
476
+ if (loaded.kind === "broken") {
477
+ corrupt.push({ file, reason: loaded.message });
478
+ continue;
479
+ }
480
+ if (loaded.kind === "missing")
481
+ continue;
482
+ const record = loaded.record;
483
+ if (input.prefix !== undefined && !record.key.startsWith(input.prefix))
484
+ continue;
485
+ const expired = isExpired(record.expiresAt, now.ms);
486
+ if (expired) {
487
+ expiredCount += 1;
488
+ if (input.includeExpired !== true)
489
+ continue;
490
+ }
491
+ entries.push({
492
+ key: record.key,
493
+ version: record.version,
494
+ expired,
495
+ ...(record.expiresAt !== undefined ? { expiresAt: record.expiresAt } : {}),
496
+ ...(record.updatedAt !== undefined ? { updatedAt: record.updatedAt } : {}),
497
+ ...(input.includeValues === true ? { value: record.value } : {}),
498
+ });
499
+ }
500
+ entries.sort((a, b) => compareStrings(String(a["key"]), String(b["key"])));
501
+ return json({
502
+ namespace: input.namespace,
503
+ total: entries.length,
504
+ returned: Math.min(entries.length, limit),
505
+ truncated: entries.length > limit || scanned >= MAX_SCAN,
506
+ expiredSkipped: input.includeExpired === true ? 0 : expiredCount,
507
+ expiryChecked: now.ms !== undefined,
508
+ keys: entries.slice(0, limit),
509
+ ...(corrupt.length > 0 ? { corrupt } : {}),
510
+ });
511
+ },
512
+ });
513
+ function isCounter(value) {
514
+ return (isPlainObject(value) &&
515
+ typeof value["name"] === "string" &&
516
+ typeof value["value"] === "number" &&
517
+ typeof value["version"] === "number");
518
+ }
519
+ export const counterIncrement = stateTool({
520
+ name: "CounterIncrement",
521
+ description: "Add to a durable named counter and return the new value, optionally refusing to cross a limit. Use it for attempt counts, quotas and budgets that must survive a restart; the read-modify-write runs under a lock, so two agents incrementing at once both count.",
522
+ inputSchema: z.object({
523
+ name: z.string().min(1).describe("counter name, e.g. 'retries.orders'"),
524
+ by: z
525
+ .number()
526
+ .int()
527
+ .min(-1_000_000_000)
528
+ .max(1_000_000_000)
529
+ .optional()
530
+ .describe("default 1; may be negative"),
531
+ limit: z
532
+ .number()
533
+ .int()
534
+ .optional()
535
+ .describe("refuse the increment, leaving the counter untouched, if it would take the value above this"),
536
+ now: nowField,
537
+ stateDir: stateDirField,
538
+ }),
539
+ destructive: true,
540
+ execute: async (input) => {
541
+ const badName = validateName("name", input.name);
542
+ if (badName !== undefined)
543
+ return badName;
544
+ const now = parseNow(input.now);
545
+ if (now.error !== undefined)
546
+ return now.error;
547
+ const by = input.by ?? 1;
548
+ const root = stateRoot("CounterIncrement", input.stateDir);
549
+ const abs = statePath("CounterIncrement", root, COUNTER_DIR, `${encodeSegment(input.name)}.json`);
550
+ const rel = relativeToRoot(root, abs);
551
+ const locked = await withLock(`${abs}.lock`, () => {
552
+ const outcome = readJsonFile(abs, SMALL_FILE_BYTES);
553
+ if (outcome.kind === "corrupt")
554
+ return corruptMessage(rel, outcome.reason);
555
+ let previous = 0;
556
+ let version = 0;
557
+ if (outcome.kind === "ok") {
558
+ if (!isCounter(outcome.value))
559
+ return corruptMessage(rel, "not a counter record");
560
+ previous = outcome.value.value;
561
+ version = outcome.value.version;
562
+ }
563
+ const next = previous + by;
564
+ if (input.limit !== undefined && next > input.limit) {
565
+ return json({
566
+ applied: false,
567
+ limited: true,
568
+ name: input.name,
569
+ value: previous,
570
+ limit: input.limit,
571
+ reason: `${previous} + ${by} would exceed the limit of ${input.limit}`,
572
+ });
573
+ }
574
+ const record = {
575
+ name: input.name,
576
+ value: next,
577
+ version: version + 1,
578
+ ...(now.ms !== undefined ? { updatedAt: formatInstant(now.ms) } : {}),
579
+ };
580
+ writeJsonAtomic(abs, record);
581
+ return json({
582
+ applied: true,
583
+ name: input.name,
584
+ value: next,
585
+ previous,
586
+ by,
587
+ version: record.version,
588
+ });
589
+ });
590
+ return locked.ok ? locked.value : locked.reason;
591
+ },
592
+ });
593
+ export const counterGet = stateTool({
594
+ name: "CounterGet",
595
+ description: "Read one counter, or every counter when you name none. Use it to check a budget before spending it; a counter that has never been incremented reads as 0 rather than as an error.",
596
+ inputSchema: z.object({
597
+ name: z.string().min(1).optional().describe("omit to list every counter, sorted by name"),
598
+ prefix: z.string().optional().describe("when listing, only counters starting with this"),
599
+ stateDir: stateDirField,
600
+ }),
601
+ readOnly: true,
602
+ concurrencySafe: true,
603
+ execute: async (input) => {
604
+ const root = stateRoot("CounterGet", input.stateDir);
605
+ if (input.name !== undefined) {
606
+ const badName = validateName("name", input.name);
607
+ if (badName !== undefined)
608
+ return badName;
609
+ const abs = statePath("CounterGet", root, COUNTER_DIR, `${encodeSegment(input.name)}.json`);
610
+ const rel = relativeToRoot(root, abs);
611
+ const outcome = readJsonFile(abs, SMALL_FILE_BYTES);
612
+ if (outcome.kind === "corrupt")
613
+ return corruptMessage(rel, outcome.reason);
614
+ if (outcome.kind === "missing") {
615
+ return json({ name: input.name, value: 0, exists: false, version: 0 });
616
+ }
617
+ if (!isCounter(outcome.value))
618
+ return corruptMessage(rel, "not a counter record");
619
+ return json({
620
+ name: input.name,
621
+ value: outcome.value.value,
622
+ exists: true,
623
+ version: outcome.value.version,
624
+ ...(outcome.value.updatedAt !== undefined ? { updatedAt: outcome.value.updatedAt } : {}),
625
+ });
626
+ }
627
+ const dir = statePath("CounterGet", root, COUNTER_DIR);
628
+ const counters = [];
629
+ const corrupt = [];
630
+ for (const file of listNames(dir, "file")) {
631
+ if (!file.endsWith(".json"))
632
+ continue;
633
+ const outcome = readJsonFile(statePath("CounterGet", root, COUNTER_DIR, file), SMALL_FILE_BYTES);
634
+ if (outcome.kind !== "ok" || !isCounter(outcome.value)) {
635
+ corrupt.push({
636
+ file,
637
+ reason: outcome.kind === "corrupt" ? outcome.reason : "not a counter record",
638
+ });
639
+ continue;
640
+ }
641
+ if (input.prefix !== undefined && !outcome.value.name.startsWith(input.prefix))
642
+ continue;
643
+ counters.push({
644
+ name: outcome.value.name,
645
+ value: outcome.value.value,
646
+ version: outcome.value.version,
647
+ });
648
+ }
649
+ counters.sort((a, b) => compareStrings(String(a["name"]), String(b["name"])));
650
+ return json({ count: counters.length, counters, ...(corrupt.length > 0 ? { corrupt } : {}) });
651
+ },
652
+ });
653
+ // ---------------------------------------------------------------------------
654
+ // checkpoints
655
+ // ---------------------------------------------------------------------------
656
+ const VERSION_FILE = /^v(\d{7})\.json$/;
657
+ function checkpointVersions(dirAbs) {
658
+ const versions = [];
659
+ for (const file of listNames(dirAbs, "file")) {
660
+ const match = VERSION_FILE.exec(file);
661
+ const digits = match?.[1];
662
+ if (digits !== undefined)
663
+ versions.push(Number.parseInt(digits, 10));
664
+ }
665
+ return versions.sort((a, b) => a - b);
666
+ }
667
+ function versionFileName(version) {
668
+ return `v${String(version).padStart(7, "0")}.json`;
669
+ }
670
+ export const checkpointSave = stateTool({
671
+ name: "CheckpointSave",
672
+ description: "Save a named JSON checkpoint as a new numbered version, so a long flow can be resumed after a crash or a restart. Use it at each stage boundary; earlier versions are kept unless you set `keep`, and `expectedVersion` refuses the save when somebody else checkpointed in the meantime.",
673
+ inputSchema: z.object({
674
+ name: z.string().min(1).describe("checkpoint name, e.g. 'migration' or 'crawl.batch-3'"),
675
+ data: z.unknown().describe("any JSON value — the state you want back later"),
676
+ label: z.string().max(200).optional().describe("a short human note about this version"),
677
+ expectedVersion: z
678
+ .number()
679
+ .int()
680
+ .min(0)
681
+ .optional()
682
+ .describe("the latest version you saw; 0 requires that no checkpoint exists yet"),
683
+ keep: z
684
+ .number()
685
+ .int()
686
+ .positive()
687
+ .max(1000)
688
+ .optional()
689
+ .describe("keep only this many most recent versions, deleting older ones"),
690
+ now: nowField,
691
+ stateDir: stateDirField,
692
+ }),
693
+ destructive: true,
694
+ execute: async (input) => {
695
+ const badName = validateName("name", input.name);
696
+ if (badName !== undefined)
697
+ return badName;
698
+ if (input.data === undefined) {
699
+ return "data is required — pass null if you mean an empty checkpoint";
700
+ }
701
+ const tooBig = sizeGuard("data", input.data);
702
+ if (tooBig !== undefined)
703
+ return tooBig;
704
+ const now = parseNow(input.now);
705
+ if (now.error !== undefined)
706
+ return now.error;
707
+ const root = stateRoot("CheckpointSave", input.stateDir);
708
+ const folder = encodeSegment(input.name);
709
+ const dir = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder);
710
+ const locked = await withLock(`${dir}.lock`, () => {
711
+ const versions = checkpointVersions(dir);
712
+ const latest = versions.length === 0 ? undefined : versions[versions.length - 1];
713
+ const conflict = casConflict(latest, input.expectedVersion);
714
+ if (conflict !== undefined) {
715
+ return json({ saved: false, conflict: true, reason: conflict, latestVersion: latest ?? 0 });
716
+ }
717
+ const version = (latest ?? 0) + 1;
718
+ const abs = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder, versionFileName(version));
719
+ const line = `${JSON.stringify({
720
+ name: input.name,
721
+ version,
722
+ ...(input.label !== undefined ? { label: input.label } : {}),
723
+ ...(now.ms !== undefined ? { savedAt: formatInstant(now.ms) } : {}),
724
+ data: input.data,
725
+ })}\n`;
726
+ if (!createExclusive(abs, line)) {
727
+ return `checkpoint "${input.name}" version ${version} already exists — another writer got there first; re-read with CheckpointList and retry`;
728
+ }
729
+ const pruned = [];
730
+ if (input.keep !== undefined) {
731
+ const all = [...versions, version];
732
+ for (const old of all.slice(0, Math.max(0, all.length - input.keep))) {
733
+ const oldAbs = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder, versionFileName(old));
734
+ if (removeFile(oldAbs))
735
+ pruned.push(old);
736
+ }
737
+ }
738
+ return json({
739
+ saved: true,
740
+ name: input.name,
741
+ version,
742
+ bytes: byteLength(line),
743
+ ...(pruned.length > 0 ? { pruned } : {}),
744
+ });
745
+ });
746
+ return locked.ok ? locked.value : locked.reason;
747
+ },
748
+ });
749
+ export const checkpointLoad = stateTool({
750
+ name: "CheckpointLoad",
751
+ description: "Load a checkpoint back — the newest version, or an earlier one by number. Use it when resuming: load, see how far the last run got, and carry on from there instead of starting again.",
752
+ inputSchema: z.object({
753
+ name: z.string().min(1),
754
+ version: z.number().int().positive().optional().describe("default: the most recent version"),
755
+ stateDir: stateDirField,
756
+ }),
757
+ readOnly: true,
758
+ concurrencySafe: true,
759
+ execute: async (input) => {
760
+ const badName = validateName("name", input.name);
761
+ if (badName !== undefined)
762
+ return badName;
763
+ const root = stateRoot("CheckpointLoad", input.stateDir);
764
+ const folder = encodeSegment(input.name);
765
+ const versions = checkpointVersions(statePath("CheckpointLoad", root, CHECKPOINT_DIR, folder));
766
+ if (versions.length === 0)
767
+ return json({ found: false, name: input.name, versions: 0 });
768
+ const latest = versions[versions.length - 1];
769
+ const wanted = input.version ?? latest;
770
+ if (wanted === undefined || !versions.includes(wanted)) {
771
+ return json({
772
+ found: false,
773
+ name: input.name,
774
+ requestedVersion: wanted ?? null,
775
+ availableVersions: versions,
776
+ });
777
+ }
778
+ const abs = statePath("CheckpointLoad", root, CHECKPOINT_DIR, folder, versionFileName(wanted));
779
+ const rel = relativeToRoot(root, abs);
780
+ const outcome = readJsonFile(abs, MAX_VALUE_BYTES * 2);
781
+ if (outcome.kind === "corrupt")
782
+ return corruptMessage(rel, outcome.reason);
783
+ if (outcome.kind === "missing") {
784
+ return json({ found: false, name: input.name, requestedVersion: wanted });
785
+ }
786
+ if (!isPlainObject(outcome.value))
787
+ return corruptMessage(rel, "not a checkpoint record");
788
+ const label = outcome.value["label"];
789
+ const savedAt = outcome.value["savedAt"];
790
+ return json({
791
+ found: true,
792
+ name: input.name,
793
+ version: wanted,
794
+ latestVersion: latest,
795
+ ...(typeof label === "string" ? { label } : {}),
796
+ ...(typeof savedAt === "string" ? { savedAt } : {}),
797
+ data: outcome.value["data"],
798
+ });
799
+ },
800
+ });
801
+ export const checkpointList = stateTool({
802
+ name: "CheckpointList",
803
+ description: "List the saved checkpoints with their version counts and newest label. Use it to find out what a previous run left to resume from before loading anything.",
804
+ inputSchema: z.object({
805
+ name: z.string().min(1).optional().describe("only this checkpoint"),
806
+ stateDir: stateDirField,
807
+ }),
808
+ readOnly: true,
809
+ concurrencySafe: true,
810
+ execute: async (input) => {
811
+ const root = stateRoot("CheckpointList", input.stateDir);
812
+ const base = statePath("CheckpointList", root, CHECKPOINT_DIR);
813
+ const out = [];
814
+ const undecodable = [];
815
+ for (const entry of listNames(base, "dir")) {
816
+ const name = decodeSegment(entry);
817
+ if (name === undefined) {
818
+ undecodable.push(entry);
819
+ continue;
820
+ }
821
+ if (input.name !== undefined && name !== input.name)
822
+ continue;
823
+ const versions = checkpointVersions(statePath("CheckpointList", root, CHECKPOINT_DIR, entry));
824
+ const latest = versions[versions.length - 1];
825
+ if (latest === undefined)
826
+ continue;
827
+ const abs = statePath("CheckpointList", root, CHECKPOINT_DIR, entry, versionFileName(latest));
828
+ const bytes = fileSize(abs);
829
+ const outcome = readJsonFile(abs, MAX_VALUE_BYTES * 2);
830
+ const head = outcome.kind === "ok" && isPlainObject(outcome.value) ? outcome.value : undefined;
831
+ const label = head?.["label"];
832
+ const savedAt = head?.["savedAt"];
833
+ out.push({
834
+ name,
835
+ versions: versions.length,
836
+ latestVersion: latest,
837
+ oldestVersion: versions[0],
838
+ ...(bytes !== undefined ? { bytes } : {}),
839
+ ...(typeof label === "string" ? { label } : {}),
840
+ ...(typeof savedAt === "string" ? { savedAt } : {}),
841
+ ...(outcome.kind === "corrupt" ? { corrupt: outcome.reason } : {}),
842
+ });
843
+ }
844
+ out.sort((a, b) => compareStrings(String(a["name"]), String(b["name"])));
845
+ return json({
846
+ count: out.length,
847
+ checkpoints: out,
848
+ ...(undecodable.length > 0 ? { unreadableNames: undecodable } : {}),
849
+ });
850
+ },
851
+ });
852
+ // ---------------------------------------------------------------------------
853
+ // journal
854
+ // ---------------------------------------------------------------------------
855
+ export const journalAppend = stateTool({
856
+ name: "JournalAppend",
857
+ description: "Append one entry to an append-only JSONL stream and return its monotonic sequence number. Use it to record what happened, in order, so a later run or a reviewer can replay it; the sequence is allocated under a lock and the line written with O_APPEND, so concurrent writers never interleave.",
858
+ inputSchema: z.object({
859
+ stream: z.string().min(1).describe("stream name, e.g. 'runs' or 'orders.processed'"),
860
+ entry: z.record(z.unknown()).describe("the JSON object to record"),
861
+ kind: z
862
+ .string()
863
+ .min(1)
864
+ .max(64)
865
+ .optional()
866
+ .describe("a label to filter on later, e.g. 'error' or 'sent'"),
867
+ now: nowField,
868
+ stateDir: stateDirField,
869
+ }),
870
+ destructive: true,
871
+ execute: async (input) => {
872
+ const badName = validateName("stream", input.stream);
873
+ if (badName !== undefined)
874
+ return badName;
875
+ const tooBig = sizeGuard("entry", input.entry);
876
+ if (tooBig !== undefined)
877
+ return tooBig;
878
+ const now = parseNow(input.now);
879
+ if (now.error !== undefined)
880
+ return now.error;
881
+ const root = stateRoot("JournalAppend", input.stateDir);
882
+ const result = await appendSequenced("JournalAppend", root, JOURNAL_DIR, input.stream, (seq) => ({
883
+ seq,
884
+ ...(input.kind !== undefined ? { kind: input.kind } : {}),
885
+ ...(now.ms !== undefined ? { at: formatInstant(now.ms) } : {}),
886
+ data: input.entry,
887
+ }));
888
+ if (!result.ok)
889
+ return result.message;
890
+ return json({
891
+ stream: input.stream,
892
+ seq: result.seq,
893
+ bytes: result.bytes,
894
+ ...(result.rebuiltSequence ? { rebuiltSequence: true } : {}),
895
+ });
896
+ },
897
+ });
898
+ export const journalRead = stateTool({
899
+ name: "JournalRead",
900
+ description: "Read a journal stream back, filtered by sequence range, kind or substring — or list the streams when you name none. Use `sinceSeq` with the last sequence you handled to read only what is new; corrupt lines are reported with their line numbers and the rest of the stream is still returned.",
901
+ inputSchema: z.object({
902
+ stream: z
903
+ .string()
904
+ .min(1)
905
+ .optional()
906
+ .describe("omit to list every stream with its last sequence"),
907
+ sinceSeq: z.number().int().min(0).optional().describe("exclusive: entries after this sequence"),
908
+ untilSeq: z.number().int().min(0).optional().describe("inclusive: entries up to this sequence"),
909
+ kind: z.string().min(1).optional(),
910
+ contains: z.string().min(1).optional().describe("case-sensitive substring of the entry's JSON"),
911
+ limit: z.number().int().positive().max(MAX_SCAN).optional().describe("default 100"),
912
+ order: z
913
+ .enum(["asc", "desc"])
914
+ .optional()
915
+ .describe("'desc' returns the newest first (default 'asc')"),
916
+ stateDir: stateDirField,
917
+ }),
918
+ readOnly: true,
919
+ concurrencySafe: true,
920
+ execute: async (input) => {
921
+ const root = stateRoot("JournalRead", input.stateDir);
922
+ if (input.stream === undefined) {
923
+ const { streams, undecodable } = listLogs("JournalRead", root, JOURNAL_DIR);
924
+ return json({
925
+ count: streams.length,
926
+ streams,
927
+ ...(undecodable.length > 0 ? { unreadableNames: undecodable } : {}),
928
+ });
929
+ }
930
+ const badName = validateName("stream", input.stream);
931
+ if (badName !== undefined)
932
+ return badName;
933
+ const log = readLog("JournalRead", root, JOURNAL_DIR, input.stream);
934
+ if (!log.ok)
935
+ return log.message;
936
+ const filtered = filterRecords(log.records, {
937
+ ...(input.sinceSeq !== undefined ? { sinceSeq: input.sinceSeq } : {}),
938
+ ...(input.untilSeq !== undefined ? { untilSeq: input.untilSeq } : {}),
939
+ ...(input.kind !== undefined ? { kind: input.kind } : {}),
940
+ ...(input.contains !== undefined ? { contains: input.contains } : {}),
941
+ limit: input.limit ?? 100,
942
+ order: input.order ?? "asc",
943
+ });
944
+ return json({
945
+ stream: input.stream,
946
+ total: log.records.length,
947
+ matched: filtered.matched,
948
+ returned: filtered.selected.length,
949
+ truncated: filtered.truncated,
950
+ lastSeq: highestSeq(log.records),
951
+ entries: filtered.selected,
952
+ ...(log.corrupt.length > 0 ? { corruptLines: log.corrupt } : {}),
953
+ });
954
+ },
955
+ });
956
+ // ---------------------------------------------------------------------------
957
+ // blackboard
958
+ // ---------------------------------------------------------------------------
959
+ export const blackboardPost = stateTool({
960
+ name: "BlackboardPost",
961
+ description: "Post a note to a shared topic that other crew members can read. Use it to leave findings, claims or warnings for agents working the same problem — it is a durable pinboard, not a delivery mechanism, so nobody is notified and nobody is guaranteed to read it.",
962
+ inputSchema: z.object({
963
+ topic: z.string().min(1).describe("topic name, e.g. 'incident-421'"),
964
+ author: z.string().min(1).max(64).describe("who is posting, e.g. the agent's name"),
965
+ text: z.string().min(1).max(32_000).describe("the note itself"),
966
+ tags: z.array(z.string().min(1).max(64)).max(32).optional(),
967
+ replyToSeq: z.number().int().positive().optional().describe("the post this one answers"),
968
+ now: nowField,
969
+ stateDir: stateDirField,
970
+ }),
971
+ destructive: true,
972
+ execute: async (input) => {
973
+ const badTopic = validateName("topic", input.topic);
974
+ if (badTopic !== undefined)
975
+ return badTopic;
976
+ const badAuthor = validateKey("author", input.author, 64);
977
+ if (badAuthor !== undefined)
978
+ return badAuthor;
979
+ const now = parseNow(input.now);
980
+ if (now.error !== undefined)
981
+ return now.error;
982
+ const root = stateRoot("BlackboardPost", input.stateDir);
983
+ const result = await appendSequenced("BlackboardPost", root, BLACKBOARD_DIR, input.topic, (seq) => ({
984
+ seq,
985
+ author: input.author,
986
+ text: input.text,
987
+ ...(input.tags !== undefined ? { tags: [...input.tags].sort(compareStrings) } : {}),
988
+ ...(input.replyToSeq !== undefined ? { replyToSeq: input.replyToSeq } : {}),
989
+ ...(now.ms !== undefined ? { at: formatInstant(now.ms) } : {}),
990
+ }));
991
+ if (!result.ok)
992
+ return result.message;
993
+ return json({
994
+ topic: input.topic,
995
+ seq: result.seq,
996
+ author: input.author,
997
+ bytes: result.bytes,
998
+ ...(result.rebuiltSequence ? { rebuiltSequence: true } : {}),
999
+ });
1000
+ },
1001
+ });
1002
+ export const blackboardRead = stateTool({
1003
+ name: "BlackboardRead",
1004
+ description: "Read a topic's posts, filtered by author, tag or sequence — or list the topics when you name none. Use `latestPerAuthor` to get each crew member's most recent word without wading through the whole thread.",
1005
+ inputSchema: z.object({
1006
+ topic: z.string().min(1).optional().describe("omit to list every topic"),
1007
+ author: z.string().min(1).optional(),
1008
+ tag: z.string().min(1).optional(),
1009
+ sinceSeq: z.number().int().min(0).optional().describe("exclusive: posts after this sequence"),
1010
+ latestPerAuthor: z.boolean().optional().describe("keep only each author's most recent post"),
1011
+ limit: z.number().int().positive().max(MAX_SCAN).optional().describe("default 50"),
1012
+ order: z.enum(["asc", "desc"]).optional().describe("default 'asc'"),
1013
+ stateDir: stateDirField,
1014
+ }),
1015
+ readOnly: true,
1016
+ concurrencySafe: true,
1017
+ execute: async (input) => {
1018
+ const root = stateRoot("BlackboardRead", input.stateDir);
1019
+ if (input.topic === undefined) {
1020
+ const { streams, undecodable } = listLogs("BlackboardRead", root, BLACKBOARD_DIR);
1021
+ return json({
1022
+ count: streams.length,
1023
+ topics: streams.map((s) => ({ topic: s.name, lastSeq: s.lastSeq, bytes: s.bytes })),
1024
+ ...(undecodable.length > 0 ? { unreadableNames: undecodable } : {}),
1025
+ });
1026
+ }
1027
+ const badTopic = validateName("topic", input.topic);
1028
+ if (badTopic !== undefined)
1029
+ return badTopic;
1030
+ const log = readLog("BlackboardRead", root, BLACKBOARD_DIR, input.topic);
1031
+ if (!log.ok)
1032
+ return log.message;
1033
+ let records = log.records;
1034
+ if (input.tag !== undefined) {
1035
+ const wanted = input.tag;
1036
+ records = records.filter((record) => {
1037
+ const tags = record["tags"];
1038
+ return Array.isArray(tags) && tags.includes(wanted);
1039
+ });
1040
+ }
1041
+ if (input.latestPerAuthor === true) {
1042
+ const byAuthor = new Map();
1043
+ for (const record of records) {
1044
+ const author = record["author"];
1045
+ if (typeof author === "string")
1046
+ byAuthor.set(author, record);
1047
+ }
1048
+ records = [...byAuthor.values()].sort((a, b) => Number(a["seq"] ?? 0) - Number(b["seq"] ?? 0));
1049
+ }
1050
+ const filtered = filterRecords(records, {
1051
+ ...(input.sinceSeq !== undefined ? { sinceSeq: input.sinceSeq } : {}),
1052
+ ...(input.author !== undefined ? { author: input.author } : {}),
1053
+ limit: input.limit ?? 50,
1054
+ order: input.order ?? "asc",
1055
+ });
1056
+ const authors = [
1057
+ ...new Set(log.records.map((r) => r["author"]).filter((a) => typeof a === "string")),
1058
+ ].sort(compareStrings);
1059
+ return json({
1060
+ topic: input.topic,
1061
+ total: log.records.length,
1062
+ matched: filtered.matched,
1063
+ returned: filtered.selected.length,
1064
+ truncated: filtered.truncated,
1065
+ authors,
1066
+ posts: filtered.selected,
1067
+ ...(log.corrupt.length > 0 ? { corruptLines: log.corrupt } : {}),
1068
+ });
1069
+ },
1070
+ });
1071
+ function isNote(value) {
1072
+ return (isPlainObject(value) &&
1073
+ typeof value["id"] === "string" &&
1074
+ typeof value["text"] === "string" &&
1075
+ typeof value["version"] === "number");
1076
+ }
1077
+ export const noteWrite = stateTool({
1078
+ name: "NoteWrite",
1079
+ description: "Write or overwrite a durable note under an id, with an optional title and tags. Use it to keep what the crew learned — a convention, a workaround, an answer worth not deriving twice — somewhere NoteSearch can find it again.",
1080
+ inputSchema: z.object({
1081
+ id: z.string().min(1).describe("note id; writing the same id again replaces the note"),
1082
+ text: z.string().min(1).max(MAX_VALUE_BYTES).describe("the note body"),
1083
+ title: z.string().max(200).optional(),
1084
+ tags: z.array(z.string().min(1).max(64)).max(32).optional(),
1085
+ ifAbsent: z.boolean().optional().describe("refuse to overwrite an existing note"),
1086
+ now: nowField,
1087
+ stateDir: stateDirField,
1088
+ }),
1089
+ destructive: true,
1090
+ execute: async (input) => {
1091
+ const badId = validateKey("id", input.id, 200);
1092
+ if (badId !== undefined)
1093
+ return badId;
1094
+ const now = parseNow(input.now);
1095
+ if (now.error !== undefined)
1096
+ return now.error;
1097
+ const root = stateRoot("NoteWrite", input.stateDir);
1098
+ const abs = statePath("NoteWrite", root, NOTE_DIR, `${encodeSegment(input.id)}.json`);
1099
+ const rel = relativeToRoot(root, abs);
1100
+ const locked = await withLock(`${abs}.lock`, () => {
1101
+ const outcome = readJsonFile(abs, MAX_VALUE_BYTES * 2);
1102
+ if (outcome.kind === "corrupt" && input.ifAbsent === true) {
1103
+ return corruptMessage(rel, outcome.reason);
1104
+ }
1105
+ const previous = outcome.kind === "ok" && isNote(outcome.value) ? outcome.value : undefined;
1106
+ if (previous !== undefined && input.ifAbsent === true) {
1107
+ return json({ written: false, exists: true, id: input.id, version: previous.version });
1108
+ }
1109
+ const record = {
1110
+ id: input.id,
1111
+ ...(input.title !== undefined ? { title: input.title } : {}),
1112
+ text: input.text,
1113
+ ...(input.tags !== undefined ? { tags: [...input.tags].sort(compareStrings) } : {}),
1114
+ version: (previous?.version ?? 0) + 1,
1115
+ ...(now.ms !== undefined ? { updatedAt: formatInstant(now.ms) } : {}),
1116
+ };
1117
+ // The schema's `max` counts CHARACTERS; what has to fit is BYTES, and
1118
+ // the read cap is what the note must fit under or it comes back as
1119
+ // corrupt. A note of 4M astral characters is 16MB on disk — writing it
1120
+ // would produce a file this package could never read again.
1121
+ const tooLarge = sizeGuard("text", record);
1122
+ if (tooLarge !== undefined)
1123
+ return tooLarge;
1124
+ const bytes = writeJsonAtomic(abs, record);
1125
+ return json({
1126
+ written: true,
1127
+ id: input.id,
1128
+ version: record.version,
1129
+ replaced: previous !== undefined,
1130
+ bytes,
1131
+ });
1132
+ });
1133
+ return locked.ok ? locked.value : locked.reason;
1134
+ },
1135
+ });
1136
+ export const noteSearch = stateTool({
1137
+ name: "NoteSearch",
1138
+ description: "Search the stored notes with BM25 ranking over their titles, tags and text. Use it to recall what the crew already worked out; the matching is LEXICAL ONLY — no embeddings, no synonyms, no stemming — so a note about 'automobiles' will not answer a query about 'cars'.",
1139
+ inputSchema: z.object({
1140
+ query: z.string().min(1).describe("the words to look for"),
1141
+ tags: z
1142
+ .array(z.string().min(1))
1143
+ .max(16)
1144
+ .optional()
1145
+ .describe("only notes carrying all of these"),
1146
+ limit: z.number().int().positive().max(100).optional().describe("default 10"),
1147
+ snippetChars: z
1148
+ .number()
1149
+ .int()
1150
+ .min(0)
1151
+ .max(2000)
1152
+ .optional()
1153
+ .describe("default 240; 0 for no snippet"),
1154
+ minScore: z.number().min(0).optional(),
1155
+ k1: z
1156
+ .number()
1157
+ .min(0)
1158
+ .max(10)
1159
+ .optional()
1160
+ .describe(`BM25 term-frequency saturation (default ${DEFAULT_K1})`),
1161
+ b: z
1162
+ .number()
1163
+ .min(0)
1164
+ .max(1)
1165
+ .optional()
1166
+ .describe(`BM25 length normalisation (default ${DEFAULT_B})`),
1167
+ stateDir: stateDirField,
1168
+ }),
1169
+ readOnly: true,
1170
+ concurrencySafe: true,
1171
+ execute: async (input) => {
1172
+ const root = stateRoot("NoteSearch", input.stateDir);
1173
+ const dir = statePath("NoteSearch", root, NOTE_DIR);
1174
+ const corrupt = [];
1175
+ const notes = [];
1176
+ let scanned = 0;
1177
+ for (const file of listNames(dir, "file")) {
1178
+ if (!file.endsWith(".json"))
1179
+ continue;
1180
+ if (scanned >= MAX_SCAN)
1181
+ break;
1182
+ scanned += 1;
1183
+ const outcome = readJsonFile(statePath("NoteSearch", root, NOTE_DIR, file), MAX_VALUE_BYTES * 2);
1184
+ if (outcome.kind === "missing")
1185
+ continue;
1186
+ if (outcome.kind === "corrupt" || !isNote(outcome.value)) {
1187
+ corrupt.push({
1188
+ file,
1189
+ reason: outcome.kind === "corrupt" ? outcome.reason : "not a note record",
1190
+ });
1191
+ continue;
1192
+ }
1193
+ notes.push(outcome.value);
1194
+ }
1195
+ const wantedTags = input.tags ?? [];
1196
+ const eligible = notes
1197
+ .filter((note) => wantedTags.every((tag) => (note.tags ?? []).includes(tag)))
1198
+ .sort((a, b) => compareStrings(a.id, b.id));
1199
+ const docs = eligible.map((note) => ({
1200
+ id: note.id,
1201
+ text: [note.title ?? "", (note.tags ?? []).join(" "), note.text].join("\n"),
1202
+ ...(note.title !== undefined ? { title: note.title } : {}),
1203
+ }));
1204
+ const k1 = input.k1 ?? DEFAULT_K1;
1205
+ const b = input.b ?? DEFAULT_B;
1206
+ const result = searchIndex(buildIndex(docs), input.query, {
1207
+ k1,
1208
+ b,
1209
+ limit: input.limit ?? 10,
1210
+ ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
1211
+ });
1212
+ const byId = new Map(eligible.map((note) => [note.id, note]));
1213
+ const snippetChars = input.snippetChars ?? 240;
1214
+ return json({
1215
+ query: input.query,
1216
+ terms: result.terms,
1217
+ unknownTerms: result.unknownTerms,
1218
+ searched: eligible.length,
1219
+ matched: result.matched,
1220
+ parameters: { algorithm: "bm25", k1, b, lexicalOnly: true },
1221
+ hits: result.hits.map((hit) => {
1222
+ const note = byId.get(hit.id);
1223
+ const text = snippet(note?.text ?? "", result.terms, snippetChars);
1224
+ return {
1225
+ id: hit.id,
1226
+ score: hit.score,
1227
+ matchedTerms: hit.matchedTerms,
1228
+ ...(note?.title !== undefined ? { title: note.title } : {}),
1229
+ ...(note?.tags !== undefined ? { tags: note.tags } : {}),
1230
+ ...(note?.updatedAt !== undefined ? { updatedAt: note.updatedAt } : {}),
1231
+ ...(text !== undefined ? { snippet: text } : {}),
1232
+ };
1233
+ }),
1234
+ ...(corrupt.length > 0 ? { corrupt } : {}),
1235
+ });
1236
+ },
1237
+ });
1238
+ // ---------------------------------------------------------------------------
1239
+ // file index
1240
+ // ---------------------------------------------------------------------------
1241
+ export const indexBuild = stateTool({
1242
+ name: "IndexBuild",
1243
+ description: "Build a named inverted index over a list of workspace text files, so they can be searched without a model reading them. Use it once per corpus and re-run it when the files change — the index is a snapshot and watches nothing; binary and over-large files are skipped and reported rather than mangled.",
1244
+ inputSchema: z.object({
1245
+ name: z.string().min(1).describe("index name, used later by IndexSearch"),
1246
+ paths: z
1247
+ .array(z.string().min(1))
1248
+ .min(1)
1249
+ .max(MAX_SCAN)
1250
+ .describe("workspace-relative file paths; pair with Glob or FindFiles to produce the list"),
1251
+ now: nowField,
1252
+ stateDir: stateDirField,
1253
+ }),
1254
+ destructive: true,
1255
+ execute: async (input) => {
1256
+ const badName = validateName("name", input.name);
1257
+ if (badName !== undefined)
1258
+ return badName;
1259
+ const now = parseNow(input.now);
1260
+ if (now.error !== undefined)
1261
+ return now.error;
1262
+ const docs = [];
1263
+ const skipped = [];
1264
+ let totalBytes = 0;
1265
+ const seen = new Set();
1266
+ for (const given of [...input.paths].sort(compareStrings)) {
1267
+ let safe;
1268
+ try {
1269
+ safe = resolveSafe("IndexBuild", given);
1270
+ }
1271
+ catch (err) {
1272
+ if (err instanceof ToolPermissionError) {
1273
+ skipped.push({ path: given, reason: "resolves outside the workspace" });
1274
+ continue;
1275
+ }
1276
+ throw err;
1277
+ }
1278
+ if (seen.has(safe.rel))
1279
+ continue;
1280
+ seen.add(safe.rel);
1281
+ const outcome = readTextFile(safe.abs, MAX_INDEXED_FILE_BYTES);
1282
+ if (outcome.kind === "missing") {
1283
+ skipped.push({ path: safe.rel, reason: "no such file" });
1284
+ continue;
1285
+ }
1286
+ if (outcome.kind === "corrupt") {
1287
+ skipped.push({ path: safe.rel, reason: outcome.reason });
1288
+ continue;
1289
+ }
1290
+ if (totalBytes + outcome.stats.size > MAX_INDEXED_TOTAL_BYTES) {
1291
+ skipped.push({ path: safe.rel, reason: "would exceed the total index budget" });
1292
+ continue;
1293
+ }
1294
+ totalBytes += outcome.stats.size;
1295
+ docs.push({
1296
+ id: safe.rel,
1297
+ text: outcome.value,
1298
+ bytes: outcome.stats.size,
1299
+ mtimeMs: Math.round(outcome.stats.mtimeMs),
1300
+ });
1301
+ }
1302
+ const index = buildIndex(docs);
1303
+ const root = stateRoot("IndexBuild", input.stateDir);
1304
+ const abs = statePath("IndexBuild", root, INDEX_DIR, `${encodeSegment(input.name)}.json`);
1305
+ // Serialise first and check the size: `IndexSearch` reads with a cap, so
1306
+ // an index written over it would be built successfully and then be
1307
+ // unreadable forever. Better to refuse the build and say how to shrink it.
1308
+ const body = `${JSON.stringify({
1309
+ ...index,
1310
+ name: input.name,
1311
+ ...(now.ms !== undefined ? { builtAt: formatInstant(now.ms) } : {}),
1312
+ })}\n`;
1313
+ const buffer = Buffer.from(body, "utf8");
1314
+ if (buffer.byteLength > MAX_FILE_BYTES) {
1315
+ return `the index would be ${buffer.byteLength} bytes, over the ${MAX_FILE_BYTES} limit IndexSearch can read — build it over fewer or smaller files, or split it into several named indexes`;
1316
+ }
1317
+ const bytes = writeBuffer(abs, buffer);
1318
+ return json({
1319
+ name: input.name,
1320
+ documents: index.docs.length,
1321
+ terms: Object.keys(index.postings).length,
1322
+ totalTerms: index.totalTerms,
1323
+ bytesIndexed: totalBytes,
1324
+ indexBytes: bytes,
1325
+ ...(skipped.length > 0 ? { skipped } : {}),
1326
+ });
1327
+ },
1328
+ });
1329
+ export const indexSearch = stateTool({
1330
+ name: "IndexSearch",
1331
+ description: "Query an index built by IndexBuild and get the ranked files back, with optional snippets. Use it to narrow a large corpus to the two or three files worth reading; ranking is BM25 over literal terms, and a file whose size or mtime no longer matches the index is flagged stale rather than silently trusted.",
1332
+ inputSchema: z.object({
1333
+ name: z.string().min(1),
1334
+ query: z.string().min(1),
1335
+ limit: z.number().int().positive().max(100).optional().describe("default 10"),
1336
+ snippetChars: z
1337
+ .number()
1338
+ .int()
1339
+ .min(0)
1340
+ .max(2000)
1341
+ .optional()
1342
+ .describe("re-read each hit to quote a matching line; 0, the default, skips the re-read"),
1343
+ minScore: z.number().min(0).optional(),
1344
+ k1: z
1345
+ .number()
1346
+ .min(0)
1347
+ .max(10)
1348
+ .optional()
1349
+ .describe(`BM25 term-frequency saturation (default ${DEFAULT_K1})`),
1350
+ b: z
1351
+ .number()
1352
+ .min(0)
1353
+ .max(1)
1354
+ .optional()
1355
+ .describe(`BM25 length normalisation (default ${DEFAULT_B})`),
1356
+ stateDir: stateDirField,
1357
+ }),
1358
+ readOnly: true,
1359
+ concurrencySafe: true,
1360
+ execute: async (input) => {
1361
+ const badName = validateName("name", input.name);
1362
+ if (badName !== undefined)
1363
+ return badName;
1364
+ const root = stateRoot("IndexSearch", input.stateDir);
1365
+ const abs = statePath("IndexSearch", root, INDEX_DIR, `${encodeSegment(input.name)}.json`);
1366
+ const rel = relativeToRoot(root, abs);
1367
+ const outcome = readJsonFile(abs);
1368
+ if (outcome.kind === "missing") {
1369
+ return `no index named "${input.name}" — build one with IndexBuild first`;
1370
+ }
1371
+ if (outcome.kind === "corrupt")
1372
+ return corruptMessage(rel, outcome.reason);
1373
+ if (!isInvertedIndex(outcome.value))
1374
+ return corruptMessage(rel, "not an inverted index");
1375
+ const index = outcome.value;
1376
+ const k1 = input.k1 ?? DEFAULT_K1;
1377
+ const b = input.b ?? DEFAULT_B;
1378
+ const result = searchIndex(index, input.query, {
1379
+ k1,
1380
+ b,
1381
+ limit: input.limit ?? 10,
1382
+ ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
1383
+ });
1384
+ const snippetChars = input.snippetChars ?? 0;
1385
+ const hits = result.hits.map((hit) => {
1386
+ let state = "current";
1387
+ let text;
1388
+ try {
1389
+ const safe = resolveSafe("IndexSearch", hit.id);
1390
+ const stats = statSync(safe.abs);
1391
+ const sizeChanged = hit.entry.bytes !== undefined && hit.entry.bytes !== stats.size;
1392
+ const timeChanged = hit.entry.mtimeMs !== undefined && hit.entry.mtimeMs !== Math.round(stats.mtimeMs);
1393
+ if (sizeChanged || timeChanged)
1394
+ state = "changed";
1395
+ if (snippetChars > 0) {
1396
+ const read = readTextFile(safe.abs, MAX_INDEXED_FILE_BYTES);
1397
+ if (read.kind === "ok")
1398
+ text = snippet(read.value, result.terms, snippetChars);
1399
+ }
1400
+ }
1401
+ catch {
1402
+ // The file has been moved, deleted or put outside the workspace since
1403
+ // the index was built; the hit still ranks, but say it cannot be read.
1404
+ state = "missing";
1405
+ }
1406
+ return {
1407
+ path: hit.id,
1408
+ score: hit.score,
1409
+ matchedTerms: hit.matchedTerms,
1410
+ file: state,
1411
+ ...(text !== undefined ? { snippet: text } : {}),
1412
+ };
1413
+ });
1414
+ return json({
1415
+ name: input.name,
1416
+ query: input.query,
1417
+ terms: result.terms,
1418
+ unknownTerms: result.unknownTerms,
1419
+ documents: index.docs.length,
1420
+ matched: result.matched,
1421
+ parameters: { algorithm: "bm25", k1, b, lexicalOnly: true },
1422
+ hits,
1423
+ stale: hits.filter((hit) => hit.file !== "current").map((hit) => hit.path),
1424
+ });
1425
+ },
1426
+ });
1427
+ // ---------------------------------------------------------------------------
1428
+ // export / import
1429
+ // ---------------------------------------------------------------------------
1430
+ /**
1431
+ * Why `StateImport` in `replace` mode may not empty this directory.
1432
+ *
1433
+ * `replace` is a recursive delete of a caller-named directory, and `stateDir`
1434
+ * is a caller-named directory anywhere in the workspace — so `stateDir: "."`
1435
+ * would have deleted the workspace, source tree and all, and `stateDir: "src"`
1436
+ * the source. A directory may be emptied only when it still looks like one of
1437
+ * ours: absent, empty, or holding nothing but the eight folders this package
1438
+ * creates. Anything else — a foreign folder, a loose file this package never
1439
+ * writes at the top level — is the signal that it is somebody's working
1440
+ * directory, and the import is refused rather than allowed to delete it.
1441
+ */
1442
+ function replaceRefusal(root) {
1443
+ if (root.abs === workspaceRoot()) {
1444
+ return "StateImport will not replace the workspace root — point `stateDir` at a state directory (the default is '.crewhaus/state')";
1445
+ }
1446
+ let entries;
1447
+ try {
1448
+ entries = readdirSync(root.abs, { withFileTypes: true })
1449
+ .filter((entry) => !(entry.isDirectory() && STATE_DIRS.has(entry.name)))
1450
+ .map((entry) => entry.name);
1451
+ }
1452
+ catch (err) {
1453
+ if (errorCode(err) === "ENOENT" || errorCode(err) === "ENOTDIR")
1454
+ return undefined;
1455
+ throw err;
1456
+ }
1457
+ if (entries.length === 0)
1458
+ return undefined;
1459
+ const foreign = entries.sort(compareStrings);
1460
+ return `StateImport will not replace "${root.rel}": it holds ${foreign.length} entr${foreign.length === 1 ? "y" : "ies"} this package did not put there (${foreign.slice(0, 5).join(", ")}), and replacing means deleting them — use mode 'merge', or point \`stateDir\` at a real state directory`;
1461
+ }
1462
+ export const stateExport = stateTool({
1463
+ name: "StateExport",
1464
+ description: "Dump the whole state directory as one JSON document, with a digest per file. Use it to back state up, move it to another machine, or attach it to a bug report; text files are carried as text and anything else as base64, and symlinks are skipped rather than followed.",
1465
+ inputSchema: z.object({
1466
+ prefix: z
1467
+ .string()
1468
+ .optional()
1469
+ .describe("only entries whose path inside the state directory starts with this, e.g. 'kv/'"),
1470
+ includeContent: z.boolean().optional().describe("include file bodies (default true)"),
1471
+ stateDir: stateDirField,
1472
+ }),
1473
+ readOnly: true,
1474
+ concurrencySafe: true,
1475
+ execute: async (input) => {
1476
+ const root = stateRoot("StateExport", input.stateDir);
1477
+ const { files, truncated } = walkFiles(root.abs, MAX_EXPORT_FILES);
1478
+ const selected = files.filter((file) => input.prefix === undefined || file.path.startsWith(input.prefix));
1479
+ const totalBytes = selected.reduce((sum, file) => sum + file.bytes, 0);
1480
+ if (totalBytes > MAX_EXPORT_BYTES) {
1481
+ return `the state directory holds ${totalBytes} bytes, over the ${MAX_EXPORT_BYTES} export limit — narrow it with \`prefix\`, or copy the directory with the filesystem tools instead`;
1482
+ }
1483
+ const entries = [];
1484
+ // Listed apart from `files`, never inside it: an entry with no content
1485
+ // would fail StateImport's schema and make the whole document unusable.
1486
+ const unreadable = [];
1487
+ for (const file of selected) {
1488
+ const text = readTextFile(file.abs, MAX_EXPORT_BYTES);
1489
+ if (text.kind === "ok") {
1490
+ entries.push({
1491
+ path: file.path,
1492
+ encoding: "utf8",
1493
+ bytes: file.bytes,
1494
+ sha256: sha256(text.value),
1495
+ ...(input.includeContent === false ? {} : { content: text.value }),
1496
+ });
1497
+ continue;
1498
+ }
1499
+ // Binary, or unreadable as text: carry the bytes verbatim instead.
1500
+ const raw = readBytes(file.abs, MAX_EXPORT_BYTES);
1501
+ if (raw === undefined) {
1502
+ unreadable.push({
1503
+ path: file.path,
1504
+ reason: text.kind === "corrupt" ? text.reason : "could not be read as bytes",
1505
+ });
1506
+ continue;
1507
+ }
1508
+ entries.push({
1509
+ path: file.path,
1510
+ encoding: "base64",
1511
+ bytes: file.bytes,
1512
+ sha256: sha256(raw),
1513
+ ...(input.includeContent === false ? {} : { content: raw.toString("base64") }),
1514
+ });
1515
+ }
1516
+ return json({
1517
+ version: 1,
1518
+ stateDir: root.rel,
1519
+ fileCount: entries.length,
1520
+ totalBytes,
1521
+ truncated,
1522
+ files: entries,
1523
+ ...(unreadable.length > 0 ? { unreadable } : {}),
1524
+ });
1525
+ },
1526
+ });
1527
+ export const stateImport = stateTool({
1528
+ name: "StateImport",
1529
+ description: "Restore a state directory from a StateExport document, merging into what is there or replacing it. Use it to seed a fresh workspace or roll state back; `dryRun` reports exactly what would be written first, every entry path is checked for escapes before anything is created, and 'replace' refuses any directory holding anything this package did not put there, so it can never be pointed at a source tree.",
1530
+ inputSchema: z.object({
1531
+ document: z
1532
+ .object({
1533
+ version: z.literal(1),
1534
+ files: z
1535
+ .array(z.object({
1536
+ path: z.string().min(1),
1537
+ encoding: z.enum(["utf8", "base64"]),
1538
+ content: z.string(),
1539
+ }))
1540
+ .max(MAX_EXPORT_FILES),
1541
+ })
1542
+ .describe("a document produced by StateExport, with contents included"),
1543
+ mode: z
1544
+ .enum(["merge", "replace"])
1545
+ .optional()
1546
+ .describe("'merge' (default) overwrites the named files and leaves the rest; 'replace' empties the state directory first"),
1547
+ dryRun: z.boolean().optional().describe("report what would happen and write nothing"),
1548
+ stateDir: stateDirField,
1549
+ }),
1550
+ destructive: true,
1551
+ execute: async (input) => {
1552
+ const root = stateRoot("StateImport", input.stateDir);
1553
+ const mode = input.mode ?? "merge";
1554
+ const dryRun = input.dryRun === true;
1555
+ // Validate every path BEFORE writing anything, so a document with one bad
1556
+ // entry cannot leave the state directory half-replaced.
1557
+ const planned = [];
1558
+ const refused = [];
1559
+ let plannedBytes = 0;
1560
+ for (const file of input.document.files) {
1561
+ if (entryNameEscapes(file.path)) {
1562
+ refused.push({ path: file.path, reason: "path segment would escape the state directory" });
1563
+ continue;
1564
+ }
1565
+ const segments = file.path.split("/");
1566
+ let target;
1567
+ try {
1568
+ target = statePath("StateImport", root, ...segments);
1569
+ }
1570
+ catch (err) {
1571
+ if (err instanceof ToolPermissionError) {
1572
+ refused.push({ path: file.path, reason: "resolves outside the state directory" });
1573
+ continue;
1574
+ }
1575
+ throw err;
1576
+ }
1577
+ const body = file.encoding === "utf8"
1578
+ ? Buffer.from(file.content, "utf8")
1579
+ : Buffer.from(file.content, "base64");
1580
+ if (plannedBytes + body.byteLength > MAX_EXPORT_BYTES) {
1581
+ refused.push({
1582
+ path: file.path,
1583
+ reason: `would take the import over the ${MAX_EXPORT_BYTES} byte limit`,
1584
+ });
1585
+ continue;
1586
+ }
1587
+ plannedBytes += body.byteLength;
1588
+ planned.push({ path: file.path, target, body });
1589
+ }
1590
+ planned.sort((a, b) => compareStrings(a.path, b.path));
1591
+ const refusedReplace = mode === "replace" ? replaceRefusal(root) : undefined;
1592
+ if (refusedReplace !== undefined)
1593
+ return refusedReplace;
1594
+ let written = 0;
1595
+ if (!dryRun) {
1596
+ // `replace` empties the directory rather than removing it, so a state
1597
+ // directory that is itself a mount point or the process's cwd survives.
1598
+ if (mode === "replace") {
1599
+ for (const name of listNames(root.abs, "dir"))
1600
+ removeTree(path.join(root.abs, name));
1601
+ for (const name of listNames(root.abs, "file"))
1602
+ removeFile(path.join(root.abs, name));
1603
+ }
1604
+ for (const file of planned) {
1605
+ writeBuffer(file.target, file.body);
1606
+ written += 1;
1607
+ }
1608
+ }
1609
+ return json({
1610
+ stateDir: root.rel,
1611
+ mode,
1612
+ dryRun,
1613
+ planned: planned.length,
1614
+ written,
1615
+ totalBytes: planned.reduce((sum, file) => sum + file.body.byteLength, 0),
1616
+ files: planned.map((file) => file.path),
1617
+ ...(refused.length > 0 ? { refused } : {}),
1618
+ });
1619
+ },
1620
+ });
1621
+ // ---------------------------------------------------------------------------
1622
+ // idempotency
1623
+ // ---------------------------------------------------------------------------
1624
+ export const dedupeMark = stateTool({
1625
+ name: "DedupeMark",
1626
+ description: "Record that an external id has been handled, and say whether it had been seen before. Use it as the guard in front of anything that must not happen twice — sending a mail, charging a card, filing a ticket — because a retried run marks the same id and gets `alreadySeen: true` instead of doing it again.",
1627
+ inputSchema: z.object({
1628
+ scope: z.string().min(1).describe("what is being de-duplicated, e.g. 'emails' or 'webhook'"),
1629
+ id: z.string().min(1).max(MAX_KEY_LENGTH).describe("the external id, e.g. a message id"),
1630
+ note: z.string().max(500).optional().describe("a short note stored with the first sighting"),
1631
+ peek: z.boolean().optional().describe("only report whether the id is known; mark nothing"),
1632
+ now: nowField,
1633
+ stateDir: stateDirField,
1634
+ }),
1635
+ destructive: true,
1636
+ execute: async (input) => {
1637
+ const badScope = validateName("scope", input.scope);
1638
+ if (badScope !== undefined)
1639
+ return badScope;
1640
+ const badId = validateKey("id", input.id);
1641
+ if (badId !== undefined)
1642
+ return badId;
1643
+ const now = parseNow(input.now);
1644
+ if (now.error !== undefined)
1645
+ return now.error;
1646
+ const root = stateRoot("DedupeMark", input.stateDir);
1647
+ const abs = statePath("DedupeMark", root, DEDUPE_DIR, encodeSegment(input.scope), `${encodeSegment(input.id)}.json`);
1648
+ const rel = relativeToRoot(root, abs);
1649
+ if (input.peek === true) {
1650
+ const existing = readJsonFile(abs, SMALL_FILE_BYTES);
1651
+ if (existing.kind === "corrupt")
1652
+ return corruptMessage(rel, existing.reason);
1653
+ return json({
1654
+ scope: input.scope,
1655
+ id: input.id,
1656
+ alreadySeen: existing.kind === "ok",
1657
+ marked: false,
1658
+ ...(existing.kind === "ok" && isPlainObject(existing.value)
1659
+ ? { firstSeen: existing.value }
1660
+ : {}),
1661
+ });
1662
+ }
1663
+ // The exclusive create IS the de-duplication: exactly one caller can win,
1664
+ // with no lock and no read-then-write window for a retry to slip through.
1665
+ const record = {
1666
+ scope: input.scope,
1667
+ id: input.id,
1668
+ ...(now.ms !== undefined ? { at: formatInstant(now.ms) } : {}),
1669
+ ...(input.note !== undefined ? { note: input.note } : {}),
1670
+ };
1671
+ if (createExclusive(abs, `${JSON.stringify(record)}\n`)) {
1672
+ return json({ scope: input.scope, id: input.id, alreadySeen: false, marked: true });
1673
+ }
1674
+ const existing = readJsonFile(abs, SMALL_FILE_BYTES);
1675
+ if (existing.kind === "corrupt")
1676
+ return corruptMessage(rel, existing.reason);
1677
+ return json({
1678
+ scope: input.scope,
1679
+ id: input.id,
1680
+ alreadySeen: true,
1681
+ marked: false,
1682
+ ...(existing.kind === "ok" && isPlainObject(existing.value)
1683
+ ? { firstSeen: existing.value }
1684
+ : {}),
1685
+ });
1686
+ },
1687
+ });
1688
+ // ---------------------------------------------------------------------------
1689
+ // vector store — the one tool here that leaves the workspace
1690
+ // ---------------------------------------------------------------------------
1691
+ export const vectorDelete = stateTool({
1692
+ name: "VectorDelete",
1693
+ description: "Delete entries from the registered vector store by id, reporting how many deletes were ATTEMPTED and what the store's count was before and after. Use it to erase indexed content on request, and read the result exactly as it is worded: the store offers no way to ask whether an id exists, so nothing here can tell you an id was present or is now gone, and on an eventually-consistent backend `countAfter` is one indicative observation rather than proof.",
1694
+ inputSchema: z.object({
1695
+ ids: z
1696
+ .array(z.string())
1697
+ .min(1)
1698
+ .max(MAX_VECTOR_IDS)
1699
+ .describe("ids to delete, exactly as the store holds them — nothing is trimmed or folded"),
1700
+ expectCollection: z
1701
+ .string()
1702
+ .min(1)
1703
+ .optional()
1704
+ .describe("refuse unless the registered store is bound to this collection"),
1705
+ protectedCollections: z
1706
+ .array(z.string().min(1))
1707
+ .max(100)
1708
+ .optional()
1709
+ .describe("collections that must never be deleted from; checked once, before any delete"),
1710
+ requireChunkIdShape: z
1711
+ .boolean()
1712
+ .optional()
1713
+ .describe("refuse any id that is not '<docId>:<index>:<startOffset>', as chunker builds it"),
1714
+ dryRun: z
1715
+ .boolean()
1716
+ .optional()
1717
+ .describe("select through the same code and report what would be attempted, deleting nothing"),
1718
+ }),
1719
+ destructive: true,
1720
+ // Two of these in flight against one store interleave their counts, and the
1721
+ // before/after pair stops meaning anything at all.
1722
+ concurrencySafe: false,
1723
+ // The registered store may be a qdrant/pinecone/weaviate collection over
1724
+ // HTTP. Nothing in this file can tell, so it is labelled for the worst case:
1725
+ // the egress classifier has to see the ids before they leave.
1726
+ scope: "external",
1727
+ ioCapability: "network",
1728
+ requireJustification: true,
1729
+ execute: async (input, ctx) => {
1730
+ const target = getVectorTarget();
1731
+ if (target === undefined) {
1732
+ return "VectorDelete has no vector store registered, and will not invent one — the host registers the store it already built with registerVectorTarget({ store, collection }). Nothing was deleted.";
1733
+ }
1734
+ const policy = readVectorToolConfig(ctx?.toolConfig);
1735
+ if (!policy.ok) {
1736
+ return `VectorDelete refused: ${policy.reason} — an unreadable protection list is not an empty one, so nothing was deleted`;
1737
+ }
1738
+ const protectedCollections = unionProtected(input.protectedCollections, target.protectedCollections, policy.protectedCollections);
1739
+ // ONCE, here: before the selection, before the first count, before the
1740
+ // first delete. A refusal means the store was never touched — which is
1741
+ // the only way a dry run can promise anything about a real run.
1742
+ const refusal = checkCollection({
1743
+ collection: target.collection,
1744
+ protectedCollections,
1745
+ expectCollection: input.expectCollection,
1746
+ });
1747
+ if (refusal !== undefined) {
1748
+ return json({
1749
+ refused: true,
1750
+ reasonCode: refusal.code,
1751
+ reason: refusal.message,
1752
+ dryRun: input.dryRun === true,
1753
+ deletesAttempted: 0,
1754
+ collection: target.collection ?? null,
1755
+ protectedCollections,
1756
+ });
1757
+ }
1758
+ const dryRun = input.dryRun === true;
1759
+ const selection = selectVectorIds(input.ids, {
1760
+ requireChunkIdShape: input.requireChunkIdShape === true,
1761
+ });
1762
+ const before = await observeCount(target.store);
1763
+ const applied = dryRun
1764
+ ? undefined
1765
+ : await applyVectorDeletes(target.store, selection.ids, ctx?.signal);
1766
+ const after = dryRun ? undefined : await observeCount(target.store);
1767
+ const rejected = capList(selection.rejected);
1768
+ const errored = capList(applied?.errors ?? []);
1769
+ const indicative = countIsIndicative(target);
1770
+ return json({
1771
+ // Stated, not implied by the absence of the refusal shape's `refused`:
1772
+ // a caller should not have to read a missing key as an answer.
1773
+ refused: false,
1774
+ dryRun,
1775
+ // Only a non-empty STRING is a backend name. Echoing `store.backend`
1776
+ // straight through put a whole object in the result for a store that
1777
+ // reported one, and "unknown" is the honest reading of a self-report
1778
+ // that is not a name — the same reading `countAfterIsIndicative` makes.
1779
+ backend: describeBackend(target.store),
1780
+ // Declared by the host at registration; the store exposes no way to
1781
+ // confirm it, which is why an absent one refuses rather than assumes.
1782
+ collection: target.collection ?? null,
1783
+ collectionSource: target.collection === undefined ? "none" : "registration",
1784
+ idsRequested: input.ids.length,
1785
+ // The selected ids are not echoed: the caller sent them, and a thousand
1786
+ // of them back is a thousand ids of context. Selected = `ids` minus
1787
+ // `idsRejected` minus repeats.
1788
+ idsSelected: selection.ids.length,
1789
+ duplicatesCollapsed: selection.duplicatesCollapsed,
1790
+ ...(rejected.listed.length > 0 ? { idsRejected: rejected.listed } : {}),
1791
+ ...(rejected.truncated ? { idsRejectedTruncated: true } : {}),
1792
+ deletesAttempted: applied?.attempted ?? 0,
1793
+ deletesAcknowledged: applied?.acknowledged ?? 0,
1794
+ ...(errored.listed.length > 0 ? { deletesErrored: errored.listed } : {}),
1795
+ ...(errored.truncated ? { deletesErroredTruncated: true } : {}),
1796
+ ...(applied?.halted === true
1797
+ ? { halted: "aborted — ids after the last attempted one were left alone" }
1798
+ : {}),
1799
+ countBefore: before.count,
1800
+ ...(before.error !== undefined ? { countBeforeError: before.error } : {}),
1801
+ countAfter: after?.count ?? null,
1802
+ ...(after?.error !== undefined ? { countAfterError: after.error } : {}),
1803
+ ...(dryRun
1804
+ ? { countAfterSkipped: "dry run — nothing was deleted, so nothing to re-count" }
1805
+ : {}),
1806
+ countAfterIsIndicative: indicative,
1807
+ perIdOutcome: "unavailable",
1808
+ caveats: [
1809
+ "an acknowledged delete means the store accepted the request; it exposes no existence check, so no id here can be reported as found-and-deleted or as already-absent",
1810
+ indicative
1811
+ ? "countAfter is a single observation on a store whose count is eventually consistent — it may not reflect these deletes yet, and its difference from countBefore is not a count of what was deleted"
1812
+ : "countBefore and countAfter are two observations of a store other writers may also be changing — their difference is not a count of what this call deleted",
1813
+ ],
1814
+ });
1815
+ },
1816
+ });
1817
+ /**
1818
+ * Every tool this package registers that keeps to the workspace, in the order
1819
+ * a catalog should list them.
1820
+ *
1821
+ * `vectorDelete` is deliberately absent: membership of this list is what the
1822
+ * "nothing here crosses a process or network boundary" test checks, and that
1823
+ * tool crosses one by design. It is listed in {@link VECTOR_TOOLS} instead —
1824
+ * see `vector.ts` for why the two are kept apart.
1825
+ */
1826
+ export const STATE_TOOLS = Object.freeze([
1827
+ blackboardPost,
1828
+ blackboardRead,
1829
+ checkpointList,
1830
+ checkpointLoad,
1831
+ checkpointSave,
1832
+ counterGet,
1833
+ counterIncrement,
1834
+ dedupeMark,
1835
+ indexBuild,
1836
+ indexSearch,
1837
+ journalAppend,
1838
+ journalRead,
1839
+ kvDelete,
1840
+ kvGet,
1841
+ kvList,
1842
+ kvSet,
1843
+ noteSearch,
1844
+ noteWrite,
1845
+ stateExport,
1846
+ stateImport,
1847
+ ]);
1848
+ /**
1849
+ * The tools here that reach a store outside the workspace — today, one.
1850
+ *
1851
+ * Kept apart from {@link STATE_TOOLS} rather than folded into it: the two
1852
+ * lists carry different promises, and a catalog registering both is saying so
1853
+ * explicitly instead of inheriting the wrong one.
1854
+ */
1855
+ export const VECTOR_TOOLS = Object.freeze([vectorDelete]);
1856
+ export { ToolPermissionError } from "./paths";
1857
+ export { DEFAULT_STATE_DIR } from "./store";
1858
+ export { MAX_VECTOR_IDS, VectorTargetError, _resetVectorTarget, countIsIndicative, getVectorTarget, parseChunkId, registerVectorTarget, selectVectorIds, } from "./vector";