@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/paths.js
CHANGED
|
@@ -22,15 +22,45 @@
|
|
|
22
22
|
import { lstatSync, readlinkSync, realpathSync } from "node:fs";
|
|
23
23
|
import * as path from "node:path";
|
|
24
24
|
import { CrewhausError } from "@crewhaus/errors";
|
|
25
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* The longest path this resolves, in UTF-16 code units; a longer one is
|
|
27
|
+
* refused before it is walked. Nothing that long can be opened or created:
|
|
28
|
+
* PATH_MAX is 1,024 bytes on macOS and 4,096 on Linux, Windows stops at
|
|
29
|
+
* 32,767 UTF-16 units, and a path's UTF-8 form is never shorter than its
|
|
30
|
+
* UTF-16 one. The limit is twice that because the part of a path that exists
|
|
31
|
+
* is itself under PATH_MAX, so the part that does not is over PATH_MAX on its
|
|
32
|
+
* own: no spelling of the place reaches it, not even one through a symlink
|
|
33
|
+
* that shortens the part that exists.
|
|
34
|
+
*/
|
|
35
|
+
export const MAX_PATH_CHARS = 2 * (process.platform === "darwin" ? 1_024 : process.platform === "win32" ? 32_767 : 4_096);
|
|
36
|
+
/** A path as a refusal quotes it: whole, unless it is past {@link MAX_PATH_CHARS}. */
|
|
37
|
+
function shownPath(given) {
|
|
38
|
+
return given.length > MAX_PATH_CHARS ? `${given.slice(0, 64)}…` : given;
|
|
39
|
+
}
|
|
40
|
+
/** Why a path past {@link MAX_PATH_CHARS} is refused: its length and the limit. */
|
|
41
|
+
function tooLong(abs) {
|
|
42
|
+
return `it is ${abs.length} characters once resolved, over the ${MAX_PATH_CHARS}-character limit: no path that long can be opened or created`;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Raised when a caller-supplied path resolves outside the workspace root, or
|
|
46
|
+
* is longer than any path can be.
|
|
47
|
+
*/
|
|
26
48
|
export class ToolPermissionError extends CrewhausError {
|
|
27
49
|
name = "ToolPermissionError";
|
|
28
50
|
toolName;
|
|
29
51
|
path;
|
|
30
|
-
|
|
31
|
-
|
|
52
|
+
/**
|
|
53
|
+
* Why, when it is not that the location escapes the workspace root: a path
|
|
54
|
+
* longer than any path can be. A caller that rewords the refusal says this.
|
|
55
|
+
*/
|
|
56
|
+
reason;
|
|
57
|
+
constructor(toolName, attemptedPath, reason) {
|
|
58
|
+
super("tool", reason === undefined
|
|
59
|
+
? `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`
|
|
60
|
+
: `tool "${toolName}" rejected path "${shownPath(attemptedPath)}": ${reason}`);
|
|
32
61
|
this.toolName = toolName;
|
|
33
62
|
this.path = attemptedPath;
|
|
63
|
+
this.reason = reason;
|
|
34
64
|
}
|
|
35
65
|
}
|
|
36
66
|
/**
|
|
@@ -41,7 +71,7 @@ export class ToolPermissionError extends CrewhausError {
|
|
|
41
71
|
* writes through it to wherever it points. `lstat` answers about the link
|
|
42
72
|
* itself, which is what a containment check has to reason about.
|
|
43
73
|
*/
|
|
44
|
-
function
|
|
74
|
+
function nameExists(abs) {
|
|
45
75
|
try {
|
|
46
76
|
lstatSync(abs);
|
|
47
77
|
return true;
|
|
@@ -109,15 +139,7 @@ export function workspaceRoot() {
|
|
|
109
139
|
function resolveLocation(target, depth = 0) {
|
|
110
140
|
if (depth > 40)
|
|
111
141
|
throw new Error(`symlink chain at "${target}" is too long to resolve`);
|
|
112
|
-
|
|
113
|
-
const tail = [];
|
|
114
|
-
while (!existsNoFollow(probe)) {
|
|
115
|
-
tail.unshift(path.basename(probe));
|
|
116
|
-
const parent = path.dirname(probe);
|
|
117
|
-
if (parent === probe)
|
|
118
|
-
break; // reached the filesystem root
|
|
119
|
-
probe = parent;
|
|
120
|
-
}
|
|
142
|
+
const { probe, tail } = deepestName(target);
|
|
121
143
|
let probeReal;
|
|
122
144
|
try {
|
|
123
145
|
probeReal = realpathSync(probe);
|
|
@@ -139,7 +161,41 @@ function resolveLocation(target, depth = 0) {
|
|
|
139
161
|
const base = realpathSync(path.dirname(probe));
|
|
140
162
|
probeReal = resolveLocation(path.resolve(base, link), depth + 1);
|
|
141
163
|
}
|
|
142
|
-
|
|
164
|
+
// One string, not one argument per name: Bun's `path.join` keeps only
|
|
165
|
+
// (argument count mod 65,536) of its arguments.
|
|
166
|
+
return tail.length > 0 ? path.join(probeReal, tail) : probeReal;
|
|
167
|
+
}
|
|
168
|
+
/**
|
|
169
|
+
* `target`, an absolute path, split where its deepest prefix that exists as
|
|
170
|
+
* a NAME ends: that prefix, and the names below it, which do not exist, as
|
|
171
|
+
* one string ("" when `target` itself exists). This is `path.dirname` and
|
|
172
|
+
* `path.basename` worked by index on `target` itself: handing them each
|
|
173
|
+
* shorter prefix in turn copied the rest of the path once per missing name,
|
|
174
|
+
* the square of a count the caller picks.
|
|
175
|
+
*/
|
|
176
|
+
function deepestName(target) {
|
|
177
|
+
const top = path.parse(target).root.length;
|
|
178
|
+
const isSep = (i) => target[i] === "/" || target[i] === path.sep;
|
|
179
|
+
let probe = target;
|
|
180
|
+
let start = target.length;
|
|
181
|
+
let stop = -1;
|
|
182
|
+
while (!nameExists(probe)) {
|
|
183
|
+
// `path.basename(probe)` is `target.slice(start, end)`, and
|
|
184
|
+
// `path.dirname(probe)` is `target.slice(0, up)`.
|
|
185
|
+
let end = probe.length;
|
|
186
|
+
while (end > top && isSep(end - 1))
|
|
187
|
+
end--;
|
|
188
|
+
if (stop < 0)
|
|
189
|
+
stop = end;
|
|
190
|
+
start = end;
|
|
191
|
+
while (start > top && !isSep(start - 1))
|
|
192
|
+
start--;
|
|
193
|
+
const up = start > top ? start - 1 : top;
|
|
194
|
+
if (up === probe.length)
|
|
195
|
+
break; // reached the filesystem root
|
|
196
|
+
probe = target.slice(0, up);
|
|
197
|
+
}
|
|
198
|
+
return { probe, tail: stop < 0 ? "" : target.slice(start, stop) };
|
|
143
199
|
}
|
|
144
200
|
export function resolveSafe(toolName, rel, root = workspaceRoot()) {
|
|
145
201
|
const rootResolved = path.resolve(root);
|
|
@@ -149,6 +205,9 @@ export function resolveSafe(toolName, rel, root = workspaceRoot()) {
|
|
|
149
205
|
if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
|
|
150
206
|
throw new ToolPermissionError(toolName, rel);
|
|
151
207
|
}
|
|
208
|
+
// Longer than any path can be: refused before the walk below reads it.
|
|
209
|
+
if (abs.length > MAX_PATH_CHARS)
|
|
210
|
+
throw new ToolPermissionError(toolName, rel, tooLong(abs));
|
|
152
211
|
// 2) Symlink-aware containment. The real path must land inside the real
|
|
153
212
|
// root, so an in-workspace symlink pointing at /etc is refused here.
|
|
154
213
|
let rootReal;
|
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):
|
|
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:
|
|
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
|
-
|
|
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,13 +101,24 @@ 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("/");
|
|
72
|
-
|
|
110
|
+
// One string, not one argument per segment: Bun's `path.join` keeps only
|
|
111
|
+
// (argument count mod 65,536) of its arguments, and StateImport's count is
|
|
112
|
+
// the document's. Empty segments are dropped first, as `join` drops them,
|
|
113
|
+
// so `a/` still names `a` and not `a/`.
|
|
114
|
+
const joined = path.join(root.abs, segments.filter((s) => s !== "").join(path.sep));
|
|
73
115
|
if (!isInside(root.abs, joined))
|
|
74
116
|
throw new ToolPermissionError(toolName, label);
|
|
75
|
-
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
|
+
}
|
|
76
122
|
return joined;
|
|
77
123
|
}
|
|
78
124
|
/** Path relative to the state root, `/`-separated, for echoing in results. */
|
|
@@ -185,6 +231,7 @@ let tempCounter = 0;
|
|
|
185
231
|
* random suffix, so a crashed run leaves a name you can recognise.
|
|
186
232
|
*/
|
|
187
233
|
export function writeJsonAtomic(abs, value) {
|
|
234
|
+
refuseProtected(abs);
|
|
188
235
|
ensureDir(path.dirname(abs));
|
|
189
236
|
const body = `${JSON.stringify(value)}\n`;
|
|
190
237
|
tempCounter += 1;
|
|
@@ -216,6 +263,7 @@ export function writeJsonAtomic(abs, value) {
|
|
|
216
263
|
* other's lines.
|
|
217
264
|
*/
|
|
218
265
|
export function appendLine(abs, line) {
|
|
266
|
+
refuseProtected(abs);
|
|
219
267
|
ensureDir(path.dirname(abs));
|
|
220
268
|
const fd = openSync(abs, "a");
|
|
221
269
|
try {
|
|
@@ -231,6 +279,7 @@ export function appendLine(abs, line) {
|
|
|
231
279
|
* exactly one caller can win, with no lock involved.
|
|
232
280
|
*/
|
|
233
281
|
export function createExclusive(abs, body) {
|
|
282
|
+
refuseProtected(abs);
|
|
234
283
|
ensureDir(path.dirname(abs));
|
|
235
284
|
let fd;
|
|
236
285
|
try {
|
|
@@ -257,6 +306,7 @@ export function createExclusive(abs, body) {
|
|
|
257
306
|
* workspace from clobbering a counter. It is not a distributed lock.
|
|
258
307
|
*/
|
|
259
308
|
export async function withLock(lockPath, body, waitMs = LOCK_WAIT_MS) {
|
|
309
|
+
refuseProtected(lockPath);
|
|
260
310
|
ensureDir(path.dirname(lockPath));
|
|
261
311
|
const deadline = Date.now() + waitMs;
|
|
262
312
|
for (;;) {
|
|
@@ -396,6 +446,7 @@ export function fileSize(abs) {
|
|
|
396
446
|
}
|
|
397
447
|
/** Remove a file, reporting whether it was there. */
|
|
398
448
|
export function removeFile(abs) {
|
|
449
|
+
refuseProtected(abs);
|
|
399
450
|
try {
|
|
400
451
|
unlinkSync(abs);
|
|
401
452
|
return true;
|
|
@@ -408,6 +459,7 @@ export function removeFile(abs) {
|
|
|
408
459
|
}
|
|
409
460
|
/** Remove a directory tree. Used only by `StateImport` in replace mode. */
|
|
410
461
|
export function removeTree(abs) {
|
|
462
|
+
refuseProtected(abs);
|
|
411
463
|
rmSync(abs, { recursive: true, force: true });
|
|
412
464
|
}
|
|
413
465
|
export function sha256(text) {
|
|
@@ -457,6 +509,7 @@ export function describeIoError(err) {
|
|
|
457
509
|
* used only by `StateImport` when restoring a base64-carried entry.
|
|
458
510
|
*/
|
|
459
511
|
export function writeBuffer(abs, body) {
|
|
512
|
+
refuseProtected(abs);
|
|
460
513
|
ensureDir(path.dirname(abs));
|
|
461
514
|
tempCounter += 1;
|
|
462
515
|
const temp = `${abs}.tmp-${process.pid}-${tempCounter}`;
|
package/dist/vector.d.ts
CHANGED
|
@@ -88,6 +88,31 @@ export declare class VectorTargetError extends CrewhausError {
|
|
|
88
88
|
* OPEN when it was not what it said it was — see the three refusals below.
|
|
89
89
|
*/
|
|
90
90
|
export declare function registerVectorTarget(registration: VectorTargetRegistration): void;
|
|
91
|
+
/** The spec's `tool_config.vectorDelete` block: which store to delete from. */
|
|
92
|
+
export type VectorDeleteConfigInput = {
|
|
93
|
+
readonly backend?: unknown;
|
|
94
|
+
readonly url?: unknown;
|
|
95
|
+
readonly collection?: unknown;
|
|
96
|
+
readonly api_key?: unknown;
|
|
97
|
+
readonly apiKey?: unknown;
|
|
98
|
+
readonly protected_collections?: unknown;
|
|
99
|
+
readonly protectedCollections?: unknown;
|
|
100
|
+
readonly count_consistency?: unknown;
|
|
101
|
+
readonly countConsistency?: unknown;
|
|
102
|
+
};
|
|
103
|
+
/** What a spec writes to give VectorDelete a store — quoted by every refusal about it. */
|
|
104
|
+
export declare const VECTOR_DELETE_EXAMPLE = "tool_config.vectorDelete: { backend: qdrant, url: https://qdrant.example:6333, collection: chunks, api_key: $QDRANT_API_KEY }";
|
|
105
|
+
/**
|
|
106
|
+
* Deliver the spec's block at boot: build the named store and register it,
|
|
107
|
+
* with the block's protection list. The api key is read from the environment
|
|
108
|
+
* when written `$VAR`, like every tool_config credential.
|
|
109
|
+
*
|
|
110
|
+
* A block without `backend` registers nothing, so the tool keeps refusing and
|
|
111
|
+
* says what to write — the same as a spec with no block. `in-memory` is
|
|
112
|
+
* refused: a store that starts empty in this process holds nothing to erase,
|
|
113
|
+
* and a delete from it would report a clean success having deleted nothing.
|
|
114
|
+
*/
|
|
115
|
+
export declare function registerVectorDeleteConfig(input: VectorDeleteConfigInput): void;
|
|
91
116
|
export declare function getVectorTarget(): VectorTargetRegistration | undefined;
|
|
92
117
|
/** Test-only — back to "nothing registered", which is the shipped default. */
|
|
93
118
|
export declare function _resetVectorTarget(): void;
|
package/dist/vector.js
CHANGED
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
* equal the one before it for deletes that did land.
|
|
37
37
|
*/
|
|
38
38
|
import { CrewhausError } from "@crewhaus/errors";
|
|
39
|
+
import { createVectorStore } from "@crewhaus/vector-store";
|
|
39
40
|
import { compareStrings, validateKey } from "./lib/names";
|
|
40
41
|
/** Most ids one call takes. Bounds the work, and the result, per call. */
|
|
41
42
|
export const MAX_VECTOR_IDS = 1_000;
|
|
@@ -105,6 +106,68 @@ export function registerVectorTarget(registration) {
|
|
|
105
106
|
}
|
|
106
107
|
activeTarget = registration;
|
|
107
108
|
}
|
|
109
|
+
/** Backends a delete can reach. An in-process store starts empty in every process. */
|
|
110
|
+
const DELETE_BACKENDS = ["qdrant", "pinecone", "weaviate", "lance"];
|
|
111
|
+
/** What a spec writes to give VectorDelete a store — quoted by every refusal about it. */
|
|
112
|
+
export const VECTOR_DELETE_EXAMPLE = "tool_config.vectorDelete: { backend: qdrant, url: https://qdrant.example:6333, collection: chunks, api_key: $QDRANT_API_KEY }";
|
|
113
|
+
function oneOf(block, snake, camel) {
|
|
114
|
+
const a = Object.hasOwn(block, snake);
|
|
115
|
+
const b = Object.hasOwn(block, camel);
|
|
116
|
+
if (a && b) {
|
|
117
|
+
throw new VectorTargetError(`tool_config.vectorDelete sets both ${snake} and ${camel}. Write it once, as ${snake}.`);
|
|
118
|
+
}
|
|
119
|
+
return a ? block[snake] : block[camel];
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Deliver the spec's block at boot: build the named store and register it,
|
|
123
|
+
* with the block's protection list. The api key is read from the environment
|
|
124
|
+
* when written `$VAR`, like every tool_config credential.
|
|
125
|
+
*
|
|
126
|
+
* A block without `backend` registers nothing, so the tool keeps refusing and
|
|
127
|
+
* says what to write — the same as a spec with no block. `in-memory` is
|
|
128
|
+
* refused: a store that starts empty in this process holds nothing to erase,
|
|
129
|
+
* and a delete from it would report a clean success having deleted nothing.
|
|
130
|
+
*/
|
|
131
|
+
export function registerVectorDeleteConfig(input) {
|
|
132
|
+
const block = (input ?? {});
|
|
133
|
+
const backend = block["backend"];
|
|
134
|
+
if (backend === undefined)
|
|
135
|
+
return;
|
|
136
|
+
if (typeof backend !== "string" ||
|
|
137
|
+
!DELETE_BACKENDS.includes(backend)) {
|
|
138
|
+
throw new VectorTargetError(`tool_config.vectorDelete.backend must be one of ${DELETE_BACKENDS.join(", ")}, not ${describeStoreValue(backend)}${backend === "in-memory" ? " — an in-memory store starts empty in every process, so there is nothing in it to delete" : ""}. For example: ${VECTOR_DELETE_EXAMPLE}`);
|
|
139
|
+
}
|
|
140
|
+
const url = block["url"];
|
|
141
|
+
const collection = block["collection"];
|
|
142
|
+
const apiKey = oneOf(block, "api_key", "apiKey");
|
|
143
|
+
for (const [name, value] of [
|
|
144
|
+
["url", url],
|
|
145
|
+
["collection", collection],
|
|
146
|
+
["api_key", apiKey],
|
|
147
|
+
]) {
|
|
148
|
+
if (value !== undefined && typeof value !== "string") {
|
|
149
|
+
throw new VectorTargetError(`tool_config.vectorDelete.${name} must be a string.`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
const store = createVectorStore({
|
|
153
|
+
backend: backend,
|
|
154
|
+
...(url !== undefined ? { url: url } : {}),
|
|
155
|
+
...(collection !== undefined ? { collection: collection } : {}),
|
|
156
|
+
...(apiKey !== undefined ? { apiKey: apiKey } : {}),
|
|
157
|
+
});
|
|
158
|
+
const protectedCollections = oneOf(block, "protected_collections", "protectedCollections");
|
|
159
|
+
const countConsistency = oneOf(block, "count_consistency", "countConsistency");
|
|
160
|
+
registerVectorTarget({
|
|
161
|
+
store,
|
|
162
|
+
...(collection !== undefined ? { collection: collection } : {}),
|
|
163
|
+
...(protectedCollections !== undefined
|
|
164
|
+
? { protectedCollections: protectedCollections }
|
|
165
|
+
: {}),
|
|
166
|
+
...(countConsistency !== undefined
|
|
167
|
+
? { countConsistency: countConsistency }
|
|
168
|
+
: {}),
|
|
169
|
+
});
|
|
170
|
+
}
|
|
108
171
|
export function getVectorTarget() {
|
|
109
172
|
return activeTarget;
|
|
110
173
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crewhaus/tool-state",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
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",
|
|
@@ -8,16 +8,19 @@
|
|
|
8
8
|
"exports": {
|
|
9
9
|
".": {
|
|
10
10
|
"types": "./dist/index.d.ts",
|
|
11
|
-
"import": "./dist/index.js"
|
|
11
|
+
"import": "./dist/index.js",
|
|
12
|
+
"default": "./dist/index.js"
|
|
12
13
|
}
|
|
13
14
|
},
|
|
14
15
|
"scripts": {
|
|
15
16
|
"test": "bun test src"
|
|
16
17
|
},
|
|
17
18
|
"dependencies": {
|
|
18
|
-
"@crewhaus/errors": "0.
|
|
19
|
-
"@crewhaus/tool-builder": "0.
|
|
20
|
-
"@crewhaus/tool-catalog": "0.
|
|
19
|
+
"@crewhaus/errors": "0.8.1",
|
|
20
|
+
"@crewhaus/tool-builder": "0.8.1",
|
|
21
|
+
"@crewhaus/tool-catalog": "0.8.1",
|
|
22
|
+
"@crewhaus/tool-safety": "0.8.1",
|
|
23
|
+
"@crewhaus/vector-store": "0.8.1",
|
|
21
24
|
"zod": "^3.23.8"
|
|
22
25
|
},
|
|
23
26
|
"devDependencies": {
|
|
@@ -41,5 +44,8 @@
|
|
|
41
44
|
"publishConfig": {
|
|
42
45
|
"access": "public"
|
|
43
46
|
},
|
|
44
|
-
"files": ["dist", "README.md", "LICENSE", "NOTICE"]
|
|
47
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"],
|
|
48
|
+
"engines": {
|
|
49
|
+
"bun": ">=1.3.14"
|
|
50
|
+
}
|
|
45
51
|
}
|