@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/LICENSE +201 -0
- package/NOTICE +9 -0
- package/README.md +45 -5
- package/dist/index.d.ts +1 -1
- package/dist/index.js +150 -28
- package/dist/paths.d.ts +21 -2
- package/dist/paths.js +73 -14
- package/dist/store.d.ts +23 -3
- package/dist/store.js +59 -6
- package/dist/vector.d.ts +25 -0
- package/dist/vector.js +63 -0
- package/package.json +12 -6
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
|
|
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
|
|
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
|
-
/**
|
|
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
|
-
|
|
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.
|