@crewhaus/tool-state 0.8.0 → 0.8.2

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/README.md CHANGED
@@ -73,12 +73,24 @@ directory that is not ours.
73
73
 
74
74
  `StateImport` never writes the run's own record either (0.8.0): the session
75
75
  logs, the tool results the runtime saved to a file, and the proof bundles,
76
- which the runtime hands each call on its bridge. An import with an entry
77
- that would land in one is refused, and so is a `replace` of a directory that
78
- holds one, in every permission mode and before anything is written. A
79
- `stateDir` of `.crewhaus` would otherwise put an entry such as
76
+ which the runtime hands each call on its bridge with the files that control
77
+ the run (the harness's run files, settings, gate records, environment files,
78
+ compiled bundle and dependencies, Hangar's directory). An import
79
+ with an entry that would land in one is refused, and so is a `replace` of a
80
+ directory that holds one, in every permission mode and before anything is
81
+ written. A `stateDir` of `.crewhaus` would otherwise put an entry such as
80
82
  `sessions/<id>.jsonl` in the live session log.
81
83
 
84
+ The tools here that write check where each record resolves against the same
85
+ roots, and refuse one a link leads into, in every permission mode and before
86
+ anything is written.
87
+
88
+ On a `channel` or `managed` harness, `StateExport` leaves out a file named
89
+ `.env`, `.env.<name>` or `.npmrc` and the credential files the run keeps from
90
+ its tools, and says how many under `heldBack`. There `IndexSearch` reports such a
91
+ file as `missing` with no snippet, and `StateImport` refuses a document that names
92
+ one, whole.
93
+
82
94
  **Determinism.** Same inputs against the same state, same bytes out. Listings
83
95
  are sorted by plain code-unit comparison — never `localeCompare`, whose order
84
96
  depends on the machine's locale. Nothing samples a random source. And **no
package/dist/index.js CHANGED
@@ -46,14 +46,14 @@
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 { protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
49
+ import { credentialRootsOf, gitDirectoryWriteRefusal, heldFileRefusal, isHeldFile, landsInGitDirectory, protectedRootBeneath, protectedRootHolding, protectedRootsOf, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
50
50
  import { z } from "zod";
51
51
  import { DEFAULT_B, DEFAULT_K1, buildIndex, isInvertedIndex, searchIndex, snippet, } from "./lib/bm25";
52
52
  import { filterRecords, highestSeq, parseJsonl, toJsonlLine, } from "./lib/jsonl";
53
53
  import { MAX_KEY_LENGTH, compareStrings, decodeSegment, encodeSegment, validateKey, validateName, } from "./lib/names";
54
54
  import { byteLength, casConflict, expiryFrom, formatInstant, isExpired, isPlainObject, isStoredRecord, parseInstant, } from "./lib/records";
55
55
  import { ToolPermissionError, entryNameEscapes, resolveSafe, workspaceRoot, } from "./paths";
56
- 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 { 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
57
  import { MAX_VECTOR_IDS, VECTOR_DELETE_EXAMPLE, applyVectorDeletes, capList, checkCollection, countIsIndicative, describeBackend, getVectorTarget, observeCount, readVectorToolConfig, selectVectorIds, unionProtected, } from "./vector";
58
58
  /** Compact JSON — the reader is a model, and every byte is context. */
59
59
  const json = (value) => JSON.stringify(value);
@@ -117,11 +117,13 @@ function stateTool(def) {
117
117
  ...def,
118
118
  execute: async (input, ctx) => {
119
119
  try {
120
- return await inner(input, ctx);
120
+ return await withProtectedRoots(def.name, protectedRootsOf(ctx), async () => inner(input, ctx));
121
121
  }
122
122
  catch (err) {
123
123
  if (err instanceof ToolPermissionError)
124
124
  return err.message;
125
+ if (err instanceof ProtectedWriteError)
126
+ return err.message;
125
127
  const io = describeIoError(err);
126
128
  if (io !== undefined)
127
129
  return `${def.name} could not complete: ${io}`;
@@ -276,7 +278,7 @@ export const kvSet = stateTool({
276
278
  stateDir: stateDirField,
277
279
  }),
278
280
  destructive: true,
279
- execute: async (input) => {
281
+ execute: async (input, ctx) => {
280
282
  const badNamespace = validateName("namespace", input.namespace);
281
283
  if (badNamespace !== undefined)
282
284
  return badNamespace;
@@ -294,7 +296,7 @@ export const kvSet = stateTool({
294
296
  if (input.ttlSeconds !== undefined && now.ms === undefined) {
295
297
  return "ttlSeconds needs `now`: expiry is computed from the instant you supply, never from the system clock";
296
298
  }
297
- const root = stateRoot("KvSet", input.stateDir);
299
+ const root = stateRoot("KvSet", input.stateDir, protectedRootsOf(ctx));
298
300
  const abs = statePath("KvSet", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
299
301
  const rel = relativeToRoot(root, abs);
300
302
  const locked = await withLock(`${abs}.lock`, () => {
@@ -419,14 +421,14 @@ export const kvDelete = stateTool({
419
421
  stateDir: stateDirField,
420
422
  }),
421
423
  destructive: true,
422
- execute: async (input) => {
424
+ execute: async (input, ctx) => {
423
425
  const badNamespace = validateName("namespace", input.namespace);
424
426
  if (badNamespace !== undefined)
425
427
  return badNamespace;
426
428
  const badKey = validateKey("key", input.key);
427
429
  if (badKey !== undefined)
428
430
  return badKey;
429
- const root = stateRoot("KvDelete", input.stateDir);
431
+ const root = stateRoot("KvDelete", input.stateDir, protectedRootsOf(ctx));
430
432
  const abs = statePath("KvDelete", root, KV_DIR, encodeSegment(input.namespace), `${encodeSegment(input.key)}.json`);
431
433
  const rel = relativeToRoot(root, abs);
432
434
  const locked = await withLock(`${abs}.lock`, () => {
@@ -563,7 +565,7 @@ export const counterIncrement = stateTool({
563
565
  stateDir: stateDirField,
564
566
  }),
565
567
  destructive: true,
566
- execute: async (input) => {
568
+ execute: async (input, ctx) => {
567
569
  const badName = validateName("name", input.name);
568
570
  if (badName !== undefined)
569
571
  return badName;
@@ -571,7 +573,7 @@ export const counterIncrement = stateTool({
571
573
  if (now.error !== undefined)
572
574
  return now.error;
573
575
  const by = input.by ?? 1;
574
- const root = stateRoot("CounterIncrement", input.stateDir);
576
+ const root = stateRoot("CounterIncrement", input.stateDir, protectedRootsOf(ctx));
575
577
  const abs = statePath("CounterIncrement", root, COUNTER_DIR, `${encodeSegment(input.name)}.json`);
576
578
  const rel = relativeToRoot(root, abs);
577
579
  const locked = await withLock(`${abs}.lock`, () => {
@@ -725,7 +727,7 @@ export const checkpointSave = stateTool({
725
727
  stateDir: stateDirField,
726
728
  }),
727
729
  destructive: true,
728
- execute: async (input) => {
730
+ execute: async (input, ctx) => {
729
731
  const badName = validateName("name", input.name);
730
732
  if (badName !== undefined)
731
733
  return badName;
@@ -738,7 +740,7 @@ export const checkpointSave = stateTool({
738
740
  const now = parseNow(input.now);
739
741
  if (now.error !== undefined)
740
742
  return now.error;
741
- const root = stateRoot("CheckpointSave", input.stateDir);
743
+ const root = stateRoot("CheckpointSave", input.stateDir, protectedRootsOf(ctx));
742
744
  const folder = encodeSegment(input.name);
743
745
  const dir = statePath("CheckpointSave", root, CHECKPOINT_DIR, folder);
744
746
  const locked = await withLock(`${dir}.lock`, () => {
@@ -914,7 +916,7 @@ export const journalAppend = stateTool({
914
916
  stateDir: stateDirField,
915
917
  }),
916
918
  destructive: true,
917
- execute: async (input) => {
919
+ execute: async (input, ctx) => {
918
920
  const badName = validateName("stream", input.stream);
919
921
  if (badName !== undefined)
920
922
  return badName;
@@ -924,7 +926,7 @@ export const journalAppend = stateTool({
924
926
  const now = parseNow(input.now);
925
927
  if (now.error !== undefined)
926
928
  return now.error;
927
- const root = stateRoot("JournalAppend", input.stateDir);
929
+ const root = stateRoot("JournalAppend", input.stateDir, protectedRootsOf(ctx));
928
930
  const result = await appendSequenced("JournalAppend", root, JOURNAL_DIR, input.stream, (seq) => ({
929
931
  seq,
930
932
  ...(input.kind !== undefined ? { kind: input.kind } : {}),
@@ -1023,7 +1025,7 @@ export const blackboardPost = stateTool({
1023
1025
  stateDir: stateDirField,
1024
1026
  }),
1025
1027
  destructive: true,
1026
- execute: async (input) => {
1028
+ execute: async (input, ctx) => {
1027
1029
  const badTopic = validateName("topic", input.topic);
1028
1030
  if (badTopic !== undefined)
1029
1031
  return badTopic;
@@ -1033,7 +1035,7 @@ export const blackboardPost = stateTool({
1033
1035
  const now = parseNow(input.now);
1034
1036
  if (now.error !== undefined)
1035
1037
  return now.error;
1036
- const root = stateRoot("BlackboardPost", input.stateDir);
1038
+ const root = stateRoot("BlackboardPost", input.stateDir, protectedRootsOf(ctx));
1037
1039
  const result = await appendSequenced("BlackboardPost", root, BLACKBOARD_DIR, input.topic, (seq) => ({
1038
1040
  seq,
1039
1041
  author: input.author,
@@ -1149,14 +1151,14 @@ export const noteWrite = stateTool({
1149
1151
  stateDir: stateDirField,
1150
1152
  }),
1151
1153
  destructive: true,
1152
- execute: async (input) => {
1154
+ execute: async (input, ctx) => {
1153
1155
  const badId = validateKey("id", input.id, 200);
1154
1156
  if (badId !== undefined)
1155
1157
  return badId;
1156
1158
  const now = parseNow(input.now);
1157
1159
  if (now.error !== undefined)
1158
1160
  return now.error;
1159
- const root = stateRoot("NoteWrite", input.stateDir);
1161
+ const root = stateRoot("NoteWrite", input.stateDir, protectedRootsOf(ctx));
1160
1162
  const abs = statePath("NoteWrite", root, NOTE_DIR, `${encodeSegment(input.id)}.json`);
1161
1163
  const rel = relativeToRoot(root, abs);
1162
1164
  const locked = await withLock(`${abs}.lock`, () => {
@@ -1322,7 +1324,7 @@ export const indexBuild = stateTool({
1322
1324
  stateDir: stateDirField,
1323
1325
  }),
1324
1326
  destructive: true,
1325
- execute: async (input) => {
1327
+ execute: async (input, ctx) => {
1326
1328
  const badName = validateName("name", input.name);
1327
1329
  if (badName !== undefined)
1328
1330
  return badName;
@@ -1370,7 +1372,7 @@ export const indexBuild = stateTool({
1370
1372
  });
1371
1373
  }
1372
1374
  const index = buildIndex(docs);
1373
- const root = stateRoot("IndexBuild", input.stateDir);
1375
+ const root = stateRoot("IndexBuild", input.stateDir, protectedRootsOf(ctx));
1374
1376
  const abs = statePath("IndexBuild", root, INDEX_DIR, `${encodeSegment(input.name)}.json`);
1375
1377
  // Serialise first and check the size: `IndexSearch` reads with a cap, so
1376
1378
  // an index written over it would be built successfully and then be
@@ -1431,7 +1433,7 @@ export const indexSearch = stateTool({
1431
1433
  }),
1432
1434
  readOnly: true,
1433
1435
  concurrencySafe: true,
1434
- execute: async (input) => {
1436
+ execute: async (input, ctx) => {
1435
1437
  const badName = validateName("name", input.name);
1436
1438
  if (badName !== undefined)
1437
1439
  return badName;
@@ -1456,11 +1458,20 @@ export const indexSearch = stateTool({
1456
1458
  ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
1457
1459
  });
1458
1460
  const snippetChars = input.snippetChars ?? 0;
1461
+ const held = credentialRootsOf(ctx);
1459
1462
  const hits = result.hits.map((hit) => {
1460
1463
  let state = "current";
1461
1464
  let text;
1462
1465
  try {
1463
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
+ }
1464
1475
  const stats = statSync(safe.abs);
1465
1476
  const sizeChanged = hit.entry.bytes !== undefined && hit.entry.bytes !== stats.size;
1466
1477
  const timeChanged = hit.entry.mtimeMs !== undefined && hit.entry.mtimeMs !== Math.round(stats.mtimeMs);
@@ -1547,10 +1558,15 @@ export const stateExport = stateTool({
1547
1558
  }),
1548
1559
  readOnly: true,
1549
1560
  concurrencySafe: true,
1550
- execute: async (input) => {
1561
+ execute: async (input, ctx) => {
1551
1562
  const root = stateRoot("StateExport", input.stateDir);
1552
1563
  const { files, truncated } = walkFiles(root.abs, MAX_EXPORT_FILES);
1553
- 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;
1554
1570
  const totalBytes = selected.reduce((sum, file) => sum + file.bytes, 0);
1555
1571
  if (totalBytes > MAX_EXPORT_BYTES) {
1556
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`;
@@ -1596,6 +1612,7 @@ export const stateExport = stateTool({
1596
1612
  truncated,
1597
1613
  files: entries,
1598
1614
  ...(unreadable.length > 0 ? { unreadable } : {}),
1615
+ ...(heldBack > 0 ? { heldBack } : {}),
1599
1616
  });
1600
1617
  },
1601
1618
  });
@@ -1635,6 +1652,7 @@ export const stateImport = stateTool({
1635
1652
  // forged fetch grounds any text. Refused in every mode, before anything
1636
1653
  // is written, as CopyPath and MovePath refuse.
1637
1654
  const protectedRoots = protectedRootsOf(ctx);
1655
+ const held = credentialRootsOf(ctx);
1638
1656
  if (mode === "replace" &&
1639
1657
  protectedRoots.length > 0 &&
1640
1658
  protectedRootBeneath(root.abs, protectedRoots) !== undefined) {
@@ -1665,6 +1683,14 @@ export const stateImport = stateTool({
1665
1683
  if (protectedRoots.length > 0 && protectedRootHolding(target, protectedRoots) !== undefined) {
1666
1684
  return protectedWriteRefusal("StateImport", `importing ${file.path}`);
1667
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
+ }
1668
1694
  const body = file.encoding === "utf8"
1669
1695
  ? Buffer.from(file.content, "utf8")
1670
1696
  : Buffer.from(file.content, "base64");
@@ -1728,7 +1754,7 @@ export const dedupeMark = stateTool({
1728
1754
  stateDir: stateDirField,
1729
1755
  }),
1730
1756
  destructive: true,
1731
- execute: async (input) => {
1757
+ execute: async (input, ctx) => {
1732
1758
  const badScope = validateName("scope", input.scope);
1733
1759
  if (badScope !== undefined)
1734
1760
  return badScope;
@@ -1738,7 +1764,7 @@ export const dedupeMark = stateTool({
1738
1764
  const now = parseNow(input.now);
1739
1765
  if (now.error !== undefined)
1740
1766
  return now.error;
1741
- const root = stateRoot("DedupeMark", input.stateDir);
1767
+ const root = stateRoot("DedupeMark", input.stateDir, protectedRootsOf(ctx));
1742
1768
  const abs = statePath("DedupeMark", root, DEDUPE_DIR, encodeSegment(input.scope), `${encodeSegment(input.id)}.json`);
1743
1769
  const rel = relativeToRoot(root, abs);
1744
1770
  if (input.peek === true) {
package/dist/store.d.ts CHANGED
@@ -10,6 +10,16 @@ export declare const LOCK_WAIT_MS = 2000;
10
10
  export declare const LOCK_STALE_MS = 30000;
11
11
  /** How deep a walk of the state directory goes before it calls it truncated. */
12
12
  export declare const MAX_WALK_DEPTH = 32;
13
+ /** A write this package refused because it resolves into a protected root. */
14
+ export declare class ProtectedWriteError extends Error {
15
+ }
16
+ /**
17
+ * Run one tool call with the run's protected roots in force: while it runs,
18
+ * every write helper below refuses a path that resolves into one, wherever a
19
+ * link on the way leads. The state directory can sit anywhere in the workspace,
20
+ * so naming `stateDir` says nothing about where a file under it lands.
21
+ */
22
+ export declare function withProtectedRoots<T>(tool: string, roots: readonly string[], run: () => Promise<T>): Promise<T>;
13
23
  /** The outcome of reading a file that may legitimately be absent or broken. */
14
24
  export type ReadOutcome<T> = {
15
25
  readonly kind: "ok";
@@ -21,11 +31,18 @@ export type ReadOutcome<T> = {
21
31
  readonly kind: "corrupt";
22
32
  readonly reason: string;
23
33
  };
34
+ /** A state directory, and the roots a call that writes beneath it keeps out of. */
35
+ export type StateRoot = SafePath & {
36
+ readonly protectedRoots?: readonly string[];
37
+ };
24
38
  /**
25
39
  * Resolve the state directory for this call. Throws `ToolPermissionError`
26
- * when the caller points it outside the workspace.
40
+ * when the caller points it outside the workspace. A tool that writes passes
41
+ * the roots on its call's bridge, and every interior path it then asks for is
42
+ * held to them: the floor reads the directory the call names, and where a
43
+ * record lands beneath it is read here.
27
44
  */
28
- export declare function stateRoot(toolName: string, stateDir: string | undefined): SafePath;
45
+ export declare function stateRoot(toolName: string, stateDir: string | undefined, protectedRoots?: readonly string[]): StateRoot;
29
46
  /**
30
47
  * Join segments beneath the state root and check containment BOTH ways.
31
48
  *
@@ -40,8 +57,11 @@ export declare function stateRoot(toolName: string, stateDir: string | undefined
40
57
  * The returned path is the lexical one, which is what the result messages and
41
58
  * `relativeToRoot` are expressed in; the residual check-to-use window is the
42
59
  * usual one, and is narrower than the lifetime of any single tool call.
60
+ *
61
+ * For a root opened to write, a path that resolves into a protected root
62
+ * through a link is refused here, before anything is opened or created.
43
63
  */
44
- export declare function statePath(toolName: string, root: SafePath, ...segments: string[]): string;
64
+ export declare function statePath(toolName: string, root: StateRoot, ...segments: string[]): string;
45
65
  /** Path relative to the state root, `/`-separated, for echoing in results. */
46
66
  export declare function relativeToRoot(root: SafePath, abs: string): string;
47
67
  export declare function ensureDir(abs: string): void;
package/dist/store.js CHANGED
@@ -30,11 +30,13 @@
30
30
  * `O_APPEND` gives, which is atomic per write on local filesystems but not
31
31
  * guaranteed on network ones.
32
32
  */
33
+ import { AsyncLocalStorage } from "node:async_hooks";
33
34
  import { createHash } from "node:crypto";
34
35
  import { closeSync, mkdirSync, openSync, readSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeSync, } from "node:fs";
35
36
  import * as path from "node:path";
37
+ import { protectedRootHolding, protectedRootLinkedInto, protectedWriteRefusal, } from "@crewhaus/tool-safety/fs";
36
38
  import { compareStrings } from "./lib/names";
37
- import { ToolPermissionError, isInside, resolveSafe, resolveWithin, toPosix, } from "./paths";
39
+ import { ToolPermissionError, isInside, resolveSafe, resolveWithin, toPosix, workspaceRoot, } from "./paths";
38
40
  /** Where state lives when the caller does not say otherwise. */
39
41
  export const DEFAULT_STATE_DIR = ".crewhaus/state";
40
42
  /** Largest single record, index or export file this package will read. */
@@ -45,12 +47,45 @@ export const LOCK_WAIT_MS = 2_000;
45
47
  export const LOCK_STALE_MS = 30_000;
46
48
  /** How deep a walk of the state directory goes before it calls it truncated. */
47
49
  export const MAX_WALK_DEPTH = 32;
50
+ /** A write this package refused because it resolves into a protected root. */
51
+ export class ProtectedWriteError extends Error {
52
+ }
53
+ const protectedWrites = new AsyncLocalStorage();
54
+ /**
55
+ * Run one tool call with the run's protected roots in force: while it runs,
56
+ * every write helper below refuses a path that resolves into one, wherever a
57
+ * link on the way leads. The state directory can sit anywhere in the workspace,
58
+ * so naming `stateDir` says nothing about where a file under it lands.
59
+ */
60
+ export function withProtectedRoots(tool, roots, run) {
61
+ return roots.length > 0 ? protectedWrites.run({ tool, roots }, run) : run();
62
+ }
63
+ function refuseProtected(abs) {
64
+ const scope = protectedWrites.getStore();
65
+ if (scope !== undefined && protectedRootHolding(abs, scope.roots) !== undefined) {
66
+ throw new ProtectedWriteError(protectedWriteRefusal(scope.tool, "this call"));
67
+ }
68
+ }
69
+ /**
70
+ * Raised by {@link statePath} when a link would carry a write into a protected
71
+ * root. Its message is the refusal the tool returns.
72
+ */
73
+ class ProtectedStateWrite extends ToolPermissionError {
74
+ constructor(toolName, label) {
75
+ super(toolName, label);
76
+ this.message = protectedWriteRefusal(toolName, `"${label}"`);
77
+ }
78
+ }
48
79
  /**
49
80
  * Resolve the state directory for this call. Throws `ToolPermissionError`
50
- * when the caller points it outside the workspace.
81
+ * when the caller points it outside the workspace. A tool that writes passes
82
+ * the roots on its call's bridge, and every interior path it then asks for is
83
+ * held to them: the floor reads the directory the call names, and where a
84
+ * record lands beneath it is read here.
51
85
  */
52
- export function stateRoot(toolName, stateDir) {
53
- return resolveSafe(toolName, stateDir ?? DEFAULT_STATE_DIR);
86
+ export function stateRoot(toolName, stateDir, protectedRoots = []) {
87
+ const root = resolveSafe(toolName, stateDir ?? DEFAULT_STATE_DIR);
88
+ return protectedRoots.length > 0 ? { ...root, protectedRoots } : root;
54
89
  }
55
90
  /**
56
91
  * Join segments beneath the state root and check containment BOTH ways.
@@ -66,6 +101,9 @@ export function stateRoot(toolName, stateDir) {
66
101
  * The returned path is the lexical one, which is what the result messages and
67
102
  * `relativeToRoot` are expressed in; the residual check-to-use window is the
68
103
  * usual one, and is narrower than the lifetime of any single tool call.
104
+ *
105
+ * For a root opened to write, a path that resolves into a protected root
106
+ * through a link is refused here, before anything is opened or created.
69
107
  */
70
108
  export function statePath(toolName, root, ...segments) {
71
109
  const label = segments.join("/");
@@ -76,7 +114,11 @@ export function statePath(toolName, root, ...segments) {
76
114
  const joined = path.join(root.abs, segments.filter((s) => s !== "").join(path.sep));
77
115
  if (!isInside(root.abs, joined))
78
116
  throw new ToolPermissionError(toolName, label);
79
- resolveWithin(toolName, root.real, joined, label);
117
+ const landsAt = resolveWithin(toolName, root.real, joined, label);
118
+ if (root.protectedRoots !== undefined &&
119
+ protectedRootLinkedInto(joined, landsAt, root.protectedRoots, workspaceRoot()) !== undefined) {
120
+ throw new ProtectedStateWrite(toolName, label);
121
+ }
80
122
  return joined;
81
123
  }
82
124
  /** Path relative to the state root, `/`-separated, for echoing in results. */
@@ -189,6 +231,7 @@ let tempCounter = 0;
189
231
  * random suffix, so a crashed run leaves a name you can recognise.
190
232
  */
191
233
  export function writeJsonAtomic(abs, value) {
234
+ refuseProtected(abs);
192
235
  ensureDir(path.dirname(abs));
193
236
  const body = `${JSON.stringify(value)}\n`;
194
237
  tempCounter += 1;
@@ -220,6 +263,7 @@ export function writeJsonAtomic(abs, value) {
220
263
  * other's lines.
221
264
  */
222
265
  export function appendLine(abs, line) {
266
+ refuseProtected(abs);
223
267
  ensureDir(path.dirname(abs));
224
268
  const fd = openSync(abs, "a");
225
269
  try {
@@ -235,6 +279,7 @@ export function appendLine(abs, line) {
235
279
  * exactly one caller can win, with no lock involved.
236
280
  */
237
281
  export function createExclusive(abs, body) {
282
+ refuseProtected(abs);
238
283
  ensureDir(path.dirname(abs));
239
284
  let fd;
240
285
  try {
@@ -261,6 +306,7 @@ export function createExclusive(abs, body) {
261
306
  * workspace from clobbering a counter. It is not a distributed lock.
262
307
  */
263
308
  export async function withLock(lockPath, body, waitMs = LOCK_WAIT_MS) {
309
+ refuseProtected(lockPath);
264
310
  ensureDir(path.dirname(lockPath));
265
311
  const deadline = Date.now() + waitMs;
266
312
  for (;;) {
@@ -400,6 +446,7 @@ export function fileSize(abs) {
400
446
  }
401
447
  /** Remove a file, reporting whether it was there. */
402
448
  export function removeFile(abs) {
449
+ refuseProtected(abs);
403
450
  try {
404
451
  unlinkSync(abs);
405
452
  return true;
@@ -412,6 +459,7 @@ export function removeFile(abs) {
412
459
  }
413
460
  /** Remove a directory tree. Used only by `StateImport` in replace mode. */
414
461
  export function removeTree(abs) {
462
+ refuseProtected(abs);
415
463
  rmSync(abs, { recursive: true, force: true });
416
464
  }
417
465
  export function sha256(text) {
@@ -461,6 +509,7 @@ export function describeIoError(err) {
461
509
  * used only by `StateImport` when restoring a base64-carried entry.
462
510
  */
463
511
  export function writeBuffer(abs, body) {
512
+ refuseProtected(abs);
464
513
  ensureDir(path.dirname(abs));
465
514
  tempCounter += 1;
466
515
  const temp = `${abs}.tmp-${process.pid}-${tempCounter}`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crewhaus/tool-state",
3
- "version": "0.8.0",
3
+ "version": "0.8.2",
4
4
  "type": "module",
5
5
  "description": "Deterministic harness state tools: key-value storage, counters, checkpoints, journals, blackboards and lexical search over local notes",
6
6
  "main": "dist/index.js",
@@ -16,11 +16,11 @@
16
16
  "test": "bun test src"
17
17
  },
18
18
  "dependencies": {
19
- "@crewhaus/errors": "0.8.0",
20
- "@crewhaus/tool-builder": "0.8.0",
21
- "@crewhaus/tool-catalog": "0.8.0",
22
- "@crewhaus/tool-safety": "0.8.0",
23
- "@crewhaus/vector-store": "0.8.0",
19
+ "@crewhaus/errors": "0.8.2",
20
+ "@crewhaus/tool-builder": "0.8.2",
21
+ "@crewhaus/tool-catalog": "0.8.2",
22
+ "@crewhaus/tool-safety": "0.8.2",
23
+ "@crewhaus/vector-store": "0.8.2",
24
24
  "zod": "^3.23.8"
25
25
  },
26
26
  "devDependencies": {