@crewhaus/tool-state 0.7.0 → 0.8.1

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 CHANGED
@@ -46,14 +46,15 @@
46
46
  import { readdirSync, statSync } from "node:fs";
47
47
  import * as path from "node:path";
48
48
  import { buildTool } from "@crewhaus/tool-builder";
49
+ import { credentialRootsOf, gitDirectoryWriteRefusal, heldFileRefusal, isHeldFile, landsInGitDirectory, protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
49
50
  import { z } from "zod";
50
51
  import { DEFAULT_B, DEFAULT_K1, buildIndex, isInvertedIndex, searchIndex, snippet, } from "./lib/bm25";
51
52
  import { filterRecords, highestSeq, parseJsonl, toJsonlLine, } from "./lib/jsonl";
52
53
  import { MAX_KEY_LENGTH, compareStrings, decodeSegment, encodeSegment, validateKey, validateName, } from "./lib/names";
53
54
  import { byteLength, casConflict, expiryFrom, formatInstant, isExpired, isPlainObject, isStoredRecord, parseInstant, } from "./lib/records";
54
55
  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";
56
+ import { DEFAULT_STATE_DIR, MAX_FILE_BYTES, ProtectedWriteError, appendLine, createExclusive, describeIoError, errorCode, fileSize, listNames, readBytes, readJsonFile, readTextFile, relativeToRoot, removeFile, removeTree, sha256, statePath, stateRoot, walkFiles, withLock, withProtectedRoots, writeBuffer, writeJsonAtomic, } from "./store";
57
+ import { MAX_VECTOR_IDS, VECTOR_DELETE_EXAMPLE, applyVectorDeletes, capList, checkCollection, countIsIndicative, describeBackend, getVectorTarget, observeCount, readVectorToolConfig, selectVectorIds, unionProtected, } from "./vector";
57
58
  /** Compact JSON — the reader is a model, and every byte is context. */
58
59
  const json = (value) => JSON.stringify(value);
59
60
  // --- limits -----------------------------------------------------------------
@@ -116,11 +117,13 @@ function stateTool(def) {
116
117
  ...def,
117
118
  execute: async (input, ctx) => {
118
119
  try {
119
- return await inner(input, ctx);
120
+ return await withProtectedRoots(def.name, protectedRootsOf(ctx), async () => inner(input, ctx));
120
121
  }
121
122
  catch (err) {
122
123
  if (err instanceof ToolPermissionError)
123
124
  return err.message;
125
+ if (err instanceof ProtectedWriteError)
126
+ return err.message;
124
127
  const io = describeIoError(err);
125
128
  if (io !== undefined)
126
129
  return `${def.name} could not complete: ${io}`;
@@ -249,6 +252,10 @@ function readLog(toolName, root, dir, name) {
249
252
  // ---------------------------------------------------------------------------
250
253
  export const kvSet = stateTool({
251
254
  name: "KvSet",
255
+ operativeArgs: [
256
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
257
+ { field: "key", kind: "id", within: "namespace" },
258
+ ],
252
259
  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
260
  inputSchema: z.object({
254
261
  namespace: z.string().min(1).describe("a group of keys, e.g. 'orders' or 'session'"),
@@ -271,7 +278,7 @@ export const kvSet = stateTool({
271
278
  stateDir: stateDirField,
272
279
  }),
273
280
  destructive: true,
274
- execute: async (input) => {
281
+ execute: async (input, ctx) => {
275
282
  const badNamespace = validateName("namespace", input.namespace);
276
283
  if (badNamespace !== undefined)
277
284
  return badNamespace;
@@ -289,7 +296,7 @@ export const kvSet = stateTool({
289
296
  if (input.ttlSeconds !== undefined && now.ms === undefined) {
290
297
  return "ttlSeconds needs `now`: expiry is computed from the instant you supply, never from the system clock";
291
298
  }
292
- const root = stateRoot("KvSet", input.stateDir);
299
+ const root = stateRoot("KvSet", input.stateDir, protectedRootsOf(ctx));
293
300
  const abs = statePath("KvSet", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
294
301
  const rel = relativeToRoot(root, abs);
295
302
  const locked = await withLock(`${abs}.lock`, () => {
@@ -329,8 +336,16 @@ export const kvSet = stateTool({
329
336
  return locked.ok ? locked.value : locked.reason;
330
337
  },
331
338
  });
339
+ // The readers declare the store and the record as the writers do (C004): a
340
+ // deny on the store — `alwaysDeny *(.crewhaus/state/**)` — reads the default
341
+ // when the call leaves stateDir out, and a listing that names no record
342
+ // stands for every record (`*`), so a deny naming one fires on it.
332
343
  export const kvGet = stateTool({
333
344
  name: "KvGet",
345
+ operativeArgs: [
346
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
347
+ { field: "key", kind: "id", within: "namespace" },
348
+ ],
334
349
  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
350
  inputSchema: z.object({
336
351
  namespace: z.string().min(1),
@@ -389,6 +404,10 @@ export const kvGet = stateTool({
389
404
  });
390
405
  export const kvDelete = stateTool({
391
406
  name: "KvDelete",
407
+ operativeArgs: [
408
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
409
+ { field: "key", kind: "id", within: "namespace" },
410
+ ],
392
411
  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
412
  inputSchema: z.object({
394
413
  namespace: z.string().min(1),
@@ -402,14 +421,14 @@ export const kvDelete = stateTool({
402
421
  stateDir: stateDirField,
403
422
  }),
404
423
  destructive: true,
405
- execute: async (input) => {
424
+ execute: async (input, ctx) => {
406
425
  const badNamespace = validateName("namespace", input.namespace);
407
426
  if (badNamespace !== undefined)
408
427
  return badNamespace;
409
428
  const badKey = validateKey("key", input.key);
410
429
  if (badKey !== undefined)
411
430
  return badKey;
412
- const root = stateRoot("KvDelete", input.stateDir);
431
+ const root = stateRoot("KvDelete", input.stateDir, protectedRootsOf(ctx));
413
432
  const abs = statePath("KvDelete", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
414
433
  const rel = relativeToRoot(root, abs);
415
434
  const locked = await withLock(`${abs}.lock`, () => {
@@ -439,6 +458,11 @@ export const kvDelete = stateTool({
439
458
  });
440
459
  export const kvList = stateTool({
441
460
  name: "KvList",
461
+ operativeArgs: [
462
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
463
+ // A prefix: the listing holds every key that starts with it, `/` and all.
464
+ { field: "prefix", kind: "id", within: "namespace", default: "*", prefix: true },
465
+ ],
442
466
  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
467
  inputSchema: z.object({
444
468
  namespace: z.string().min(1),
@@ -518,6 +542,10 @@ function isCounter(value) {
518
542
  }
519
543
  export const counterIncrement = stateTool({
520
544
  name: "CounterIncrement",
545
+ operativeArgs: [
546
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
547
+ { field: "name", kind: "id" },
548
+ ],
521
549
  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
550
  inputSchema: z.object({
523
551
  name: z.string().min(1).describe("counter name, e.g. 'retries.orders'"),
@@ -537,7 +565,7 @@ export const counterIncrement = stateTool({
537
565
  stateDir: stateDirField,
538
566
  }),
539
567
  destructive: true,
540
- execute: async (input) => {
568
+ execute: async (input, ctx) => {
541
569
  const badName = validateName("name", input.name);
542
570
  if (badName !== undefined)
543
571
  return badName;
@@ -545,7 +573,7 @@ export const counterIncrement = stateTool({
545
573
  if (now.error !== undefined)
546
574
  return now.error;
547
575
  const by = input.by ?? 1;
548
- const root = stateRoot("CounterIncrement", input.stateDir);
576
+ const root = stateRoot("CounterIncrement", input.stateDir, protectedRootsOf(ctx));
549
577
  const abs = statePath("CounterIncrement", root, COUNTER_DIR, `${encodeSegment(input.name)}.json`);
550
578
  const rel = relativeToRoot(root, abs);
551
579
  const locked = await withLock(`${abs}.lock`, () => {
@@ -592,6 +620,10 @@ export const counterIncrement = stateTool({
592
620
  });
593
621
  export const counterGet = stateTool({
594
622
  name: "CounterGet",
623
+ operativeArgs: [
624
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
625
+ { field: "name", kind: "id", default: "*" },
626
+ ],
595
627
  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
628
  inputSchema: z.object({
597
629
  name: z.string().min(1).optional().describe("omit to list every counter, sorted by name"),
@@ -669,6 +701,10 @@ function versionFileName(version) {
669
701
  }
670
702
  export const checkpointSave = stateTool({
671
703
  name: "CheckpointSave",
704
+ operativeArgs: [
705
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
706
+ { field: "name", kind: "id" },
707
+ ],
672
708
  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
709
  inputSchema: z.object({
674
710
  name: z.string().min(1).describe("checkpoint name, e.g. 'migration' or 'crawl.batch-3'"),
@@ -691,7 +727,7 @@ export const checkpointSave = stateTool({
691
727
  stateDir: stateDirField,
692
728
  }),
693
729
  destructive: true,
694
- execute: async (input) => {
730
+ execute: async (input, ctx) => {
695
731
  const badName = validateName("name", input.name);
696
732
  if (badName !== undefined)
697
733
  return badName;
@@ -704,7 +740,7 @@ export const checkpointSave = stateTool({
704
740
  const now = parseNow(input.now);
705
741
  if (now.error !== undefined)
706
742
  return now.error;
707
- const root = stateRoot("CheckpointSave", input.stateDir);
743
+ const root = stateRoot("CheckpointSave", input.stateDir, protectedRootsOf(ctx));
708
744
  const folder = encodeSegment(input.name);
709
745
  const dir = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder);
710
746
  const locked = await withLock(`${dir}.lock`, () => {
@@ -748,6 +784,10 @@ export const checkpointSave = stateTool({
748
784
  });
749
785
  export const checkpointLoad = stateTool({
750
786
  name: "CheckpointLoad",
787
+ operativeArgs: [
788
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
789
+ { field: "name", kind: "id" },
790
+ ],
751
791
  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
792
  inputSchema: z.object({
753
793
  name: z.string().min(1),
@@ -800,6 +840,10 @@ export const checkpointLoad = stateTool({
800
840
  });
801
841
  export const checkpointList = stateTool({
802
842
  name: "CheckpointList",
843
+ operativeArgs: [
844
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
845
+ { field: "name", kind: "id", default: "*" },
846
+ ],
803
847
  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
848
  inputSchema: z.object({
805
849
  name: z.string().min(1).optional().describe("only this checkpoint"),
@@ -854,6 +898,10 @@ export const checkpointList = stateTool({
854
898
  // ---------------------------------------------------------------------------
855
899
  export const journalAppend = stateTool({
856
900
  name: "JournalAppend",
901
+ operativeArgs: [
902
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
903
+ { field: "stream", kind: "id" },
904
+ ],
857
905
  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
906
  inputSchema: z.object({
859
907
  stream: z.string().min(1).describe("stream name, e.g. 'runs' or 'orders.processed'"),
@@ -868,7 +916,7 @@ export const journalAppend = stateTool({
868
916
  stateDir: stateDirField,
869
917
  }),
870
918
  destructive: true,
871
- execute: async (input) => {
919
+ execute: async (input, ctx) => {
872
920
  const badName = validateName("stream", input.stream);
873
921
  if (badName !== undefined)
874
922
  return badName;
@@ -878,7 +926,7 @@ export const journalAppend = stateTool({
878
926
  const now = parseNow(input.now);
879
927
  if (now.error !== undefined)
880
928
  return now.error;
881
- const root = stateRoot("JournalAppend", input.stateDir);
929
+ const root = stateRoot("JournalAppend", input.stateDir, protectedRootsOf(ctx));
882
930
  const result = await appendSequenced("JournalAppend", root, JOURNAL_DIR, input.stream, (seq) => ({
883
931
  seq,
884
932
  ...(input.kind !== undefined ? { kind: input.kind } : {}),
@@ -897,6 +945,10 @@ export const journalAppend = stateTool({
897
945
  });
898
946
  export const journalRead = stateTool({
899
947
  name: "JournalRead",
948
+ operativeArgs: [
949
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
950
+ { field: "stream", kind: "id", default: "*" },
951
+ ],
900
952
  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
953
  inputSchema: z.object({
902
954
  stream: z
@@ -958,6 +1010,10 @@ export const journalRead = stateTool({
958
1010
  // ---------------------------------------------------------------------------
959
1011
  export const blackboardPost = stateTool({
960
1012
  name: "BlackboardPost",
1013
+ operativeArgs: [
1014
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1015
+ { field: "topic", kind: "id" },
1016
+ ],
961
1017
  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
1018
  inputSchema: z.object({
963
1019
  topic: z.string().min(1).describe("topic name, e.g. 'incident-421'"),
@@ -969,7 +1025,7 @@ export const blackboardPost = stateTool({
969
1025
  stateDir: stateDirField,
970
1026
  }),
971
1027
  destructive: true,
972
- execute: async (input) => {
1028
+ execute: async (input, ctx) => {
973
1029
  const badTopic = validateName("topic", input.topic);
974
1030
  if (badTopic !== undefined)
975
1031
  return badTopic;
@@ -979,7 +1035,7 @@ export const blackboardPost = stateTool({
979
1035
  const now = parseNow(input.now);
980
1036
  if (now.error !== undefined)
981
1037
  return now.error;
982
- const root = stateRoot("BlackboardPost", input.stateDir);
1038
+ const root = stateRoot("BlackboardPost", input.stateDir, protectedRootsOf(ctx));
983
1039
  const result = await appendSequenced("BlackboardPost", root, BLACKBOARD_DIR, input.topic, (seq) => ({
984
1040
  seq,
985
1041
  author: input.author,
@@ -1001,6 +1057,10 @@ export const blackboardPost = stateTool({
1001
1057
  });
1002
1058
  export const blackboardRead = stateTool({
1003
1059
  name: "BlackboardRead",
1060
+ operativeArgs: [
1061
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1062
+ { field: "topic", kind: "id", default: "*" },
1063
+ ],
1004
1064
  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
1065
  inputSchema: z.object({
1006
1066
  topic: z.string().min(1).optional().describe("omit to list every topic"),
@@ -1076,6 +1136,10 @@ function isNote(value) {
1076
1136
  }
1077
1137
  export const noteWrite = stateTool({
1078
1138
  name: "NoteWrite",
1139
+ operativeArgs: [
1140
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1141
+ { field: "id", kind: "id" },
1142
+ ],
1079
1143
  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
1144
  inputSchema: z.object({
1081
1145
  id: z.string().min(1).describe("note id; writing the same id again replaces the note"),
@@ -1087,14 +1151,14 @@ export const noteWrite = stateTool({
1087
1151
  stateDir: stateDirField,
1088
1152
  }),
1089
1153
  destructive: true,
1090
- execute: async (input) => {
1154
+ execute: async (input, ctx) => {
1091
1155
  const badId = validateKey("id", input.id, 200);
1092
1156
  if (badId !== undefined)
1093
1157
  return badId;
1094
1158
  const now = parseNow(input.now);
1095
1159
  if (now.error !== undefined)
1096
1160
  return now.error;
1097
- const root = stateRoot("NoteWrite", input.stateDir);
1161
+ const root = stateRoot("NoteWrite", input.stateDir, protectedRootsOf(ctx));
1098
1162
  const abs = statePath("NoteWrite", root, NOTE_DIR, `${encodeSegment(input.id)}.json`);
1099
1163
  const rel = relativeToRoot(root, abs);
1100
1164
  const locked = await withLock(`${abs}.lock`, () => {
@@ -1135,6 +1199,7 @@ export const noteWrite = stateTool({
1135
1199
  });
1136
1200
  export const noteSearch = stateTool({
1137
1201
  name: "NoteSearch",
1202
+ operativeArgs: [{ field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, beneath: "all" }],
1138
1203
  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
1204
  inputSchema: z.object({
1140
1205
  query: z.string().min(1).describe("the words to look for"),
@@ -1240,6 +1305,13 @@ export const noteSearch = stateTool({
1240
1305
  // ---------------------------------------------------------------------------
1241
1306
  export const indexBuild = stateTool({
1242
1307
  name: "IndexBuild",
1308
+ // `paths` are the files whose text goes into the index: a deny or ask reads
1309
+ // them, an allow on the index name need not.
1310
+ operativeArgs: [
1311
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1312
+ { field: "name", kind: "id" },
1313
+ { field: "paths", kind: "path", source: true },
1314
+ ],
1243
1315
  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
1316
  inputSchema: z.object({
1245
1317
  name: z.string().min(1).describe("index name, used later by IndexSearch"),
@@ -1252,7 +1324,7 @@ export const indexBuild = stateTool({
1252
1324
  stateDir: stateDirField,
1253
1325
  }),
1254
1326
  destructive: true,
1255
- execute: async (input) => {
1327
+ execute: async (input, ctx) => {
1256
1328
  const badName = validateName("name", input.name);
1257
1329
  if (badName !== undefined)
1258
1330
  return badName;
@@ -1270,7 +1342,7 @@ export const indexBuild = stateTool({
1270
1342
  }
1271
1343
  catch (err) {
1272
1344
  if (err instanceof ToolPermissionError) {
1273
- skipped.push({ path: given, reason: "resolves outside the workspace" });
1345
+ skipped.push({ path: given, reason: err.reason ?? "resolves outside the workspace" });
1274
1346
  continue;
1275
1347
  }
1276
1348
  throw err;
@@ -1300,7 +1372,7 @@ export const indexBuild = stateTool({
1300
1372
  });
1301
1373
  }
1302
1374
  const index = buildIndex(docs);
1303
- const root = stateRoot("IndexBuild", input.stateDir);
1375
+ const root = stateRoot("IndexBuild", input.stateDir, protectedRootsOf(ctx));
1304
1376
  const abs = statePath("IndexBuild", root, INDEX_DIR, `${encodeSegment(input.name)}.json`);
1305
1377
  // Serialise first and check the size: `IndexSearch` reads with a cap, so
1306
1378
  // an index written over it would be built successfully and then be
@@ -1328,6 +1400,10 @@ export const indexBuild = stateTool({
1328
1400
  });
1329
1401
  export const indexSearch = stateTool({
1330
1402
  name: "IndexSearch",
1403
+ operativeArgs: [
1404
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1405
+ { field: "name", kind: "id" },
1406
+ ],
1331
1407
  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
1408
  inputSchema: z.object({
1333
1409
  name: z.string().min(1),
@@ -1357,7 +1433,7 @@ export const indexSearch = stateTool({
1357
1433
  }),
1358
1434
  readOnly: true,
1359
1435
  concurrencySafe: true,
1360
- execute: async (input) => {
1436
+ execute: async (input, ctx) => {
1361
1437
  const badName = validateName("name", input.name);
1362
1438
  if (badName !== undefined)
1363
1439
  return badName;
@@ -1382,11 +1458,20 @@ export const indexSearch = stateTool({
1382
1458
  ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
1383
1459
  });
1384
1460
  const snippetChars = input.snippetChars ?? 0;
1461
+ const held = credentialRootsOf(ctx);
1385
1462
  const hits = result.hits.map((hit) => {
1386
1463
  let state = "current";
1387
1464
  let text;
1388
1465
  try {
1389
1466
  const safe = resolveSafe("IndexSearch", hit.id);
1467
+ if (held.length > 0 && isHeldFile(safe.abs, held)) {
1468
+ return {
1469
+ path: hit.id,
1470
+ score: hit.score,
1471
+ matchedTerms: hit.matchedTerms,
1472
+ file: "missing",
1473
+ };
1474
+ }
1390
1475
  const stats = statSync(safe.abs);
1391
1476
  const sizeChanged = hit.entry.bytes !== undefined && hit.entry.bytes !== stats.size;
1392
1477
  const timeChanged = hit.entry.mtimeMs !== undefined && hit.entry.mtimeMs !== Math.round(stats.mtimeMs);
@@ -1461,6 +1546,7 @@ function replaceRefusal(root) {
1461
1546
  }
1462
1547
  export const stateExport = stateTool({
1463
1548
  name: "StateExport",
1549
+ operativeArgs: [{ field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, beneath: "all" }],
1464
1550
  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
1551
  inputSchema: z.object({
1466
1552
  prefix: z
@@ -1472,10 +1558,15 @@ export const stateExport = stateTool({
1472
1558
  }),
1473
1559
  readOnly: true,
1474
1560
  concurrencySafe: true,
1475
- execute: async (input) => {
1561
+ execute: async (input, ctx) => {
1476
1562
  const root = stateRoot("StateExport", input.stateDir);
1477
1563
  const { files, truncated } = walkFiles(root.abs, MAX_EXPORT_FILES);
1478
- const selected = files.filter((file) => input.prefix === undefined || file.path.startsWith(input.prefix));
1564
+ const asked = files.filter((file) => input.prefix === undefined || file.path.startsWith(input.prefix));
1565
+ // A run that keeps files from its tools gets a document without them, and
1566
+ // the count of what it left out: a refusal would give it no document at all.
1567
+ const held = credentialRootsOf(ctx);
1568
+ const selected = held.length === 0 ? asked : asked.filter((file) => !isHeldFile(file.abs, held));
1569
+ const heldBack = asked.length - selected.length;
1479
1570
  const totalBytes = selected.reduce((sum, file) => sum + file.bytes, 0);
1480
1571
  if (totalBytes > MAX_EXPORT_BYTES) {
1481
1572
  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`;
@@ -1521,11 +1612,13 @@ export const stateExport = stateTool({
1521
1612
  truncated,
1522
1613
  files: entries,
1523
1614
  ...(unreadable.length > 0 ? { unreadable } : {}),
1615
+ ...(heldBack > 0 ? { heldBack } : {}),
1524
1616
  });
1525
1617
  },
1526
1618
  });
1527
1619
  export const stateImport = stateTool({
1528
1620
  name: "StateImport",
1621
+ operativeArgs: [{ field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, beneath: "all" }],
1529
1622
  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
1623
  inputSchema: z.object({
1531
1624
  document: z
@@ -1548,10 +1641,23 @@ export const stateImport = stateTool({
1548
1641
  stateDir: stateDirField,
1549
1642
  }),
1550
1643
  destructive: true,
1551
- execute: async (input) => {
1644
+ execute: async (input, ctx) => {
1552
1645
  const root = stateRoot("StateImport", input.stateDir);
1553
1646
  const mode = input.mode ?? "merge";
1554
1647
  const dryRun = input.dryRun === true;
1648
+ // 0.8.0 — the run's own record (`RuntimeBridge.protectedRoots`: the
1649
+ // session logs, spilled tool results, proof bundles) is never written:
1650
+ // a `stateDir` at the workspace root or above `.crewhaus` would put an
1651
+ // entry such as `.crewhaus/sessions/<id>.jsonl` in the live log, where a
1652
+ // forged fetch grounds any text. Refused in every mode, before anything
1653
+ // is written, as CopyPath and MovePath refuse.
1654
+ const protectedRoots = protectedRootsOf(ctx);
1655
+ const held = credentialRootsOf(ctx);
1656
+ if (mode === "replace" &&
1657
+ protectedRoots.length > 0 &&
1658
+ protectedRootBeneath(root.abs, protectedRoots) !== undefined) {
1659
+ return protectedWriteRefusal("StateImport", `replacing ${root.rel}`);
1660
+ }
1555
1661
  // Validate every path BEFORE writing anything, so a document with one bad
1556
1662
  // entry cannot leave the state directory half-replaced.
1557
1663
  const planned = [];
@@ -1574,6 +1680,17 @@ export const stateImport = stateTool({
1574
1680
  }
1575
1681
  throw err;
1576
1682
  }
1683
+ if (protectedRoots.length > 0 && protectedRootHolding(target, protectedRoots) !== undefined) {
1684
+ return protectedWriteRefusal("StateImport", `importing ${file.path}`);
1685
+ }
1686
+ // Read with the state directory in front: `config` imported to `.git` has
1687
+ // no such name of its own, and neither does an entry behind a link.
1688
+ if (protectedRoots.length > 0 && landsInGitDirectory(target)) {
1689
+ return gitDirectoryWriteRefusal("StateImport", `importing ${file.path}`);
1690
+ }
1691
+ if (held.length > 0 && isHeldFile(target, held)) {
1692
+ return heldFileRefusal("StateImport", `importing ${file.path}`);
1693
+ }
1577
1694
  const body = file.encoding === "utf8"
1578
1695
  ? Buffer.from(file.content, "utf8")
1579
1696
  : Buffer.from(file.content, "base64");
@@ -1623,6 +1740,10 @@ export const stateImport = stateTool({
1623
1740
  // ---------------------------------------------------------------------------
1624
1741
  export const dedupeMark = stateTool({
1625
1742
  name: "DedupeMark",
1743
+ operativeArgs: [
1744
+ { field: "stateDir", kind: "path", default: DEFAULT_STATE_DIR, relocates: true },
1745
+ { field: "scope", kind: "id" },
1746
+ ],
1626
1747
  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
1748
  inputSchema: z.object({
1628
1749
  scope: z.string().min(1).describe("what is being de-duplicated, e.g. 'emails' or 'webhook'"),
@@ -1633,7 +1754,7 @@ export const dedupeMark = stateTool({
1633
1754
  stateDir: stateDirField,
1634
1755
  }),
1635
1756
  destructive: true,
1636
- execute: async (input) => {
1757
+ execute: async (input, ctx) => {
1637
1758
  const badScope = validateName("scope", input.scope);
1638
1759
  if (badScope !== undefined)
1639
1760
  return badScope;
@@ -1643,7 +1764,7 @@ export const dedupeMark = stateTool({
1643
1764
  const now = parseNow(input.now);
1644
1765
  if (now.error !== undefined)
1645
1766
  return now.error;
1646
- const root = stateRoot("DedupeMark", input.stateDir);
1767
+ const root = stateRoot("DedupeMark", input.stateDir, protectedRootsOf(ctx));
1647
1768
  const abs = statePath("DedupeMark", root, DEDUPE_DIR, encodeSegment(input.scope), `${encodeSegment(input.id)}.json`);
1648
1769
  const rel = relativeToRoot(root, abs);
1649
1770
  if (input.peek === true) {
@@ -1690,6 +1811,7 @@ export const dedupeMark = stateTool({
1690
1811
  // ---------------------------------------------------------------------------
1691
1812
  export const vectorDelete = stateTool({
1692
1813
  name: "VectorDelete",
1814
+ operativeArgs: [{ field: "ids", kind: "id" }],
1693
1815
  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
1816
  inputSchema: z.object({
1695
1817
  ids: z
@@ -1729,7 +1851,7 @@ export const vectorDelete = stateTool({
1729
1851
  execute: async (input, ctx) => {
1730
1852
  const target = getVectorTarget();
1731
1853
  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.";
1854
+ return `VectorDelete has no vector store registered, and will not invent one. Name the store in the spec — ${VECTOR_DELETE_EXAMPLE} — or have the host call registerVectorTarget({ store, collection }). Nothing was deleted.`;
1733
1855
  }
1734
1856
  const policy = readVectorToolConfig(ctx?.toolConfig);
1735
1857
  if (!policy.ok) {
@@ -1855,4 +1977,4 @@ export const STATE_TOOLS = Object.freeze([
1855
1977
  export const VECTOR_TOOLS = Object.freeze([vectorDelete]);
1856
1978
  export { ToolPermissionError } from "./paths";
1857
1979
  export { DEFAULT_STATE_DIR } from "./store";
1858
- export { MAX_VECTOR_IDS, VectorTargetError, _resetVectorTarget, countIsIndicative, getVectorTarget, parseChunkId, registerVectorTarget, selectVectorIds, } from "./vector";
1980
+ export { MAX_VECTOR_IDS, VectorTargetError, _resetVectorTarget, countIsIndicative, getVectorTarget, parseChunkId, registerVectorDeleteConfig, registerVectorTarget, selectVectorIds, } from "./vector";
package/dist/paths.d.ts CHANGED
@@ -1,10 +1,29 @@
1
1
  import { CrewhausError } from "@crewhaus/errors";
2
- /** Raised when a caller-supplied path resolves outside the workspace root. */
2
+ /**
3
+ * The longest path this resolves, in UTF-16 code units; a longer one is
4
+ * refused before it is walked. Nothing that long can be opened or created:
5
+ * PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
6
+ * 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
7
+ * UTF-16 one. The limit is twice that because the part of a path that exists
8
+ * is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
9
+ * own: no spelling of the place reaches it, not even one through a symlink
10
+ * that shortens the part that exists.
11
+ */
12
+ export declare const MAX_PATH_CHARS: number;
13
+ /**
14
+ * Raised when a caller-supplied path resolves outside the workspace root, or
15
+ * is longer than any path can be.
16
+ */
3
17
  export declare class ToolPermissionError extends CrewhausError {
4
18
  readonly name = "ToolPermissionError";
5
19
  readonly toolName: string;
6
20
  readonly path: string;
7
- constructor(toolName: string, attemptedPath: string);
21
+ /**
22
+ * Why, when it is not that the location escapes the workspace root: a path
23
+ * longer than any path can be. A caller that rewords the refusal says this.
24
+ */
25
+ readonly reason: string | undefined;
26
+ constructor(toolName: string, attemptedPath: string, reason?: string);
8
27
  }
9
28
  /**
10
29
  * A validated path, in both forms the tools need.