agent-rag-mcp 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -33,25 +33,285 @@ async function renameWithRetry(source, destination) {
33
33
  }
34
34
  }
35
35
  }
36
- async function writeRootManifest(root, db) {
37
- const manifest = buildManifest(db);
38
- validateManifest(manifest);
36
+ const MANIFEST_LOCK_TIMEOUT_MS = 5e3;
37
+ const MANIFEST_LOCK_POLL_MS = 25;
38
+ const MANIFEST_LOCK_STALE_MS = 3e4;
39
+ async function processIsAlive(pid) {
40
+ try {
41
+ process.kill(pid, 0);
42
+ return true;
43
+ } catch (error) {
44
+ const code = error.code;
45
+ return code === "EPERM";
46
+ }
47
+ }
48
+ async function observeManifestLock(lockPath) {
49
+ let handle;
50
+ try {
51
+ handle = await fs.open(lockPath, "r");
52
+ } catch (error) {
53
+ if (error.code === "ENOENT") return void 0;
54
+ throw error;
55
+ }
56
+ try {
57
+ const [stat, contents] = await Promise.all([handle.stat(), handle.readFile("utf8")]);
58
+ return { dev: stat.dev, ino: stat.ino, mtimeMs: stat.mtimeMs, contents };
59
+ } finally {
60
+ await handle.close();
61
+ }
62
+ }
63
+ function sameLockIdentity(left, right) {
64
+ return left.dev === right.dev && left.ino === right.ino && left.contents === right.contents;
65
+ }
66
+ function parsedLockRecord(observation) {
67
+ try {
68
+ return JSON.parse(observation.contents);
69
+ } catch {
70
+ return void 0;
71
+ }
72
+ }
73
+ async function isStaleManifestLock(observation) {
74
+ const record = parsedLockRecord(observation);
75
+ if (!Number.isSafeInteger(record?.pid) || (record?.pid ?? 0) <= 0 || typeof record?.token !== "string" || record.token.length === 0) {
76
+ return Date.now() - observation.mtimeMs > MANIFEST_LOCK_STALE_MS;
77
+ }
78
+ return !await processIsAlive(record.pid);
79
+ }
80
+ async function acquireRecoveryGuard(lockPath, deadline) {
81
+ const guardPath = `${lockPath}.recovery`;
82
+ while (true) {
83
+ const token = randomUUID();
84
+ let handle;
85
+ try {
86
+ handle = await fs.open(guardPath, "wx");
87
+ } catch (error) {
88
+ if (error.code !== "EEXIST") throw error;
89
+ if (Date.now() >= deadline) return void 0;
90
+ await new Promise((resolve) => setTimeout(resolve, MANIFEST_LOCK_POLL_MS));
91
+ continue;
92
+ }
93
+ try {
94
+ await handle.writeFile(JSON.stringify({ pid: process.pid, token, createdAt: Date.now() }), "utf8");
95
+ } catch (error) {
96
+ await handle.close().catch(() => void 0);
97
+ await fs.unlink(guardPath).catch(() => void 0);
98
+ throw error;
99
+ }
100
+ await handle.close();
101
+ return async () => {
102
+ try {
103
+ const current = JSON.parse(await fs.readFile(guardPath, "utf8"));
104
+ if (current.token === token) await fs.unlink(guardPath);
105
+ } catch (error) {
106
+ if (error.code !== "ENOENT") throw error;
107
+ }
108
+ };
109
+ }
110
+ }
111
+ async function createManifestLock(lockPath, token) {
112
+ let handle;
113
+ try {
114
+ handle = await fs.open(lockPath, "wx");
115
+ } catch (error) {
116
+ if (error.code === "EEXIST") return void 0;
117
+ throw error;
118
+ }
119
+ try {
120
+ await handle.writeFile(JSON.stringify({ pid: process.pid, token, createdAt: Date.now() }), "utf8");
121
+ } finally {
122
+ await handle.close();
123
+ }
124
+ const observation = await observeManifestLock(lockPath);
125
+ if (!observation) throw new Error(`Manifest lock disappeared after exclusive creation: ${lockPath}`);
126
+ return observation;
127
+ }
128
+ async function takeoverStaleManifestLock(lockPath, observed, token = randomUUID()) {
129
+ const releaseGuard = await acquireRecoveryGuard(lockPath, Date.now());
130
+ if (!releaseGuard) return false;
131
+ try {
132
+ const current = await observeManifestLock(lockPath);
133
+ if (!current || !sameLockIdentity(current, observed) || !await isStaleManifestLock(current)) return false;
134
+ const quarantinedPath = `${lockPath}.${randomUUID()}.stale`;
135
+ await fs.rename(lockPath, quarantinedPath);
136
+ const moved = await observeManifestLock(quarantinedPath);
137
+ if (!moved || !sameLockIdentity(moved, current)) {
138
+ try {
139
+ await fs.link(quarantinedPath, lockPath);
140
+ } catch (restoreError) {
141
+ throw new Error(`Manifest lock identity changed during takeover; preserved ${quarantinedPath} and could not restore ${lockPath}: ${String(restoreError)}`);
142
+ }
143
+ throw new Error(`Manifest lock identity changed during takeover; restored ${lockPath} and preserved ${quarantinedPath}.`);
144
+ }
145
+ await fs.unlink(quarantinedPath);
146
+ const replacement = await createManifestLock(lockPath, token);
147
+ return replacement !== void 0;
148
+ } finally {
149
+ await releaseGuard();
150
+ }
151
+ }
152
+ async function acquireManifestLock(root, timeoutMs = MANIFEST_LOCK_TIMEOUT_MS) {
153
+ const lockPath = path.join(root, ".manifest.lock");
154
+ const deadline = Date.now() + timeoutMs;
155
+ while (true) {
156
+ const token = randomUUID();
157
+ const created = await createManifestLock(lockPath, token);
158
+ if (created) return async () => {
159
+ const releaseGuard = await acquireRecoveryGuard(lockPath, Date.now() + timeoutMs);
160
+ if (!releaseGuard) throw new Error(`Timed out waiting to release the root manifest lock at ${lockPath}.`);
161
+ try {
162
+ const current = await observeManifestLock(lockPath);
163
+ const record = current && parsedLockRecord(current);
164
+ if (current && sameLockIdentity(current, created) && record?.token === token) await fs.unlink(lockPath);
165
+ } finally {
166
+ await releaseGuard();
167
+ }
168
+ };
169
+ const observed = await observeManifestLock(lockPath);
170
+ if (!observed) continue;
171
+ if (await isStaleManifestLock(observed)) {
172
+ if (await takeoverStaleManifestLock(lockPath, observed, token)) {
173
+ const createdLock = await observeManifestLock(lockPath);
174
+ if (!createdLock) throw new Error(`Manifest lock disappeared after stale recovery: ${lockPath}`);
175
+ return async () => {
176
+ const releaseGuard = await acquireRecoveryGuard(lockPath, Date.now() + timeoutMs);
177
+ if (!releaseGuard) throw new Error(`Timed out waiting to release the root manifest lock at ${lockPath}.`);
178
+ try {
179
+ const current = await observeManifestLock(lockPath);
180
+ const record = current && parsedLockRecord(current);
181
+ if (current && sameLockIdentity(current, createdLock) && record?.token === token) await fs.unlink(lockPath);
182
+ } finally {
183
+ await releaseGuard();
184
+ }
185
+ };
186
+ }
187
+ }
188
+ if (Date.now() >= deadline) {
189
+ throw new Error(`Timed out waiting for the root manifest lock at ${lockPath} (recovery guard ${lockPath}.recovery may require manual verification).`);
190
+ }
191
+ await new Promise((resolve) => setTimeout(resolve, MANIFEST_LOCK_POLL_MS));
192
+ }
193
+ }
194
+ async function readRootManifestIfPresent(root) {
195
+ let contents;
196
+ try {
197
+ contents = await fs.readFile(path.join(root, "manifest.json"), "utf8");
198
+ } catch (error) {
199
+ if (error.code === "ENOENT") return null;
200
+ throw ioError("manifest_read_failed", `Unable to read manifest under ${root}.`);
201
+ }
202
+ let value;
203
+ try {
204
+ value = JSON.parse(contents);
205
+ } catch {
206
+ throw ioError("manifest_invalid", `Manifest under ${root} is not valid JSON.`);
207
+ }
208
+ validateManifest(value);
209
+ return value;
210
+ }
211
+ function subsetManifest(manifest, clientIds) {
212
+ const clients = manifest.clients.filter((client) => clientIds.has(client.client_id));
213
+ const projects = manifest.projects.filter((project) => clientIds.has(project.client_id));
214
+ const projectIds = new Set(projects.map((project) => project.project_id));
215
+ const ingestRuns = manifest.ingestRuns.filter((run) => projectIds.has(String(run.project_id)));
216
+ const entities = manifest.entities.filter((entity) => projectIds.has(entity.project_id));
217
+ const documents = manifest.documents.filter((document) => projectIds.has(document.project_id));
218
+ const documentIds = new Set(documents.map((document) => document.document_id));
219
+ const versions = manifest.versions.filter((version) => documentIds.has(version.document_id));
220
+ const versionIds = new Set(versions.map((version) => version.doc_version_id));
221
+ const objectHashes = new Set(versions.map((version) => version.sha256));
222
+ return {
223
+ version: 1,
224
+ clients,
225
+ projects,
226
+ ingestRuns,
227
+ entities,
228
+ documents,
229
+ versions,
230
+ sections: manifest.sections.filter((section) => versionIds.has(section.doc_version_id)),
231
+ chunks: manifest.chunks.filter((chunk) => versionIds.has(chunk.doc_version_id)),
232
+ relations: manifest.relations.filter((relation) => versionIds.has(relation.from_doc_version_id) && versionIds.has(relation.to_doc_version_id)),
233
+ objects: manifest.objects.filter((object) => objectHashes.has(object.sha256)),
234
+ namespaceAcls: manifest.namespaceAcls.filter((acl) => clientIds.has(String(acl.client_id)) || acl.project_id !== null && projectIds.has(String(acl.project_id)))
235
+ };
236
+ }
237
+ function selectManifestClient(manifest, clientName) {
238
+ const client = manifest.clients.find((row) => row.name === clientName);
239
+ if (!client) throw ioError("namespace_mismatch", `Manifest does not contain client ${clientName}.`);
240
+ return subsetManifest(manifest, /* @__PURE__ */ new Set([client.client_id]));
241
+ }
242
+ function mergeRootManifests(existing, replacement) {
243
+ if (replacement.clients.length === 0) return existing ?? replacement;
244
+ if (!existing) return replacement;
245
+ const replacedClientIds = new Set(replacement.clients.map((client) => client.client_id));
246
+ const oldTarget = subsetManifest(existing, replacedClientIds);
247
+ const retainedClientIds = new Set(existing.clients.filter((client) => !replacedClientIds.has(client.client_id)).map((client) => client.client_id));
248
+ const retained = subsetManifest(existing, retainedClientIds);
249
+ const retainedVersionHashes = new Set(retained.versions.map((version) => version.sha256));
250
+ const oldTargetVersionHashes = new Set(oldTarget.versions.map((version) => version.sha256));
251
+ const unownedOrSharedObjects = existing.objects.filter((object) => !oldTargetVersionHashes.has(object.sha256) || retainedVersionHashes.has(object.sha256));
252
+ const combinedObjectHashes = new Set(unownedOrSharedObjects.map((object) => object.sha256));
253
+ const objects = [
254
+ ...unownedOrSharedObjects,
255
+ ...replacement.objects.filter((object) => !combinedObjectHashes.has(object.sha256))
256
+ ];
257
+ const merged = {
258
+ version: 1,
259
+ clients: [...retained.clients, ...replacement.clients],
260
+ projects: [...retained.projects, ...replacement.projects],
261
+ ingestRuns: [...retained.ingestRuns, ...replacement.ingestRuns],
262
+ entities: [...retained.entities, ...replacement.entities],
263
+ documents: [...retained.documents, ...replacement.documents],
264
+ versions: [...retained.versions, ...replacement.versions],
265
+ sections: [...retained.sections, ...replacement.sections],
266
+ chunks: [...retained.chunks, ...replacement.chunks],
267
+ relations: [...retained.relations, ...replacement.relations],
268
+ objects,
269
+ namespaceAcls: [...retained.namespaceAcls, ...replacement.namespaceAcls]
270
+ };
271
+ validateManifest(merged);
272
+ return merged;
273
+ }
274
+ async function publishRootManifest(root, manifestOrFactory, hooks = {}) {
39
275
  const destination = path.join(root, "manifest.json");
40
276
  const temporary = path.join(root, `.manifest.${randomUUID()}.tmp`);
277
+ let releaseLock;
278
+ let manifest;
279
+ let writeFailure;
280
+ let cleanupFailed = false;
41
281
  try {
42
282
  await fs.mkdir(root, { recursive: true });
283
+ releaseLock = await acquireManifestLock(root);
284
+ manifest = typeof manifestOrFactory === "function" ? await manifestOrFactory() : manifestOrFactory;
285
+ validateManifest(manifest);
43
286
  await fs.writeFile(temporary, serializeManifest(manifest), { encoding: "utf8", flag: "wx" });
287
+ await hooks.afterTemporaryWrite?.();
44
288
  await renameWithRetry(temporary, destination);
45
- return manifest;
46
- } catch {
47
- let cleanupFailed = false;
289
+ } catch (error) {
290
+ writeFailure = error;
48
291
  try {
49
292
  await fs.rm(temporary, { force: true });
50
293
  } catch {
51
294
  cleanupFailed = true;
52
295
  }
296
+ }
297
+ try {
298
+ await releaseLock?.();
299
+ } catch (error) {
300
+ writeFailure ??= error;
301
+ }
302
+ if (writeFailure !== void 0) {
53
303
  throw ioError("manifest_write_failed", `Unable to atomically write manifest under ${root}.${cleanupFailed ? " Temporary manifest cleanup failed." : ""}`);
54
304
  }
305
+ return manifest;
306
+ }
307
+ async function writeRootManifest(root, db, hooks = {}) {
308
+ return publishRootManifest(root, async () => {
309
+ const replacement = buildManifest(db);
310
+ validateManifest(replacement);
311
+ const manifest = mergeRootManifests(await readRootManifestIfPresent(root), replacement);
312
+ validateManifest(manifest);
313
+ return manifest;
314
+ }, hooks);
55
315
  }
56
316
  function verifyObjectBytes(bytes, object) {
57
317
  if (bytes.byteLength !== object.byte_size || createHash("sha256").update(bytes).digest("hex") !== object.sha256) {
@@ -157,13 +417,12 @@ async function backupRoot(sourceRoot, db, destinationRoot) {
157
417
  }
158
418
  async function restoreRoot(sourceRoot, destinationRoot, client) {
159
419
  const manifest = await readRootManifest(sourceRoot);
160
- const foreignClient = manifest.clients.find((row) => row.name !== client);
161
- if (foreignClient) {
162
- throw ioError("foreign_client_in_manifest", `Manifest contains foreign client ${foreignClient.name}.`);
163
- }
164
- if (!manifest.clients.some((row) => row.name === client)) {
165
- throw ioError("namespace_mismatch", `Manifest does not contain client ${client}.`);
420
+ const projectClientIds = new Set(manifest.projects.map((project) => project.client_id));
421
+ const unscopedForeignClient = manifest.clients.find((row) => row.name !== client && !projectClientIds.has(row.client_id));
422
+ if (unscopedForeignClient) {
423
+ throw ioError("foreign_client_in_manifest", `Manifest contains foreign client ${unscopedForeignClient.name}.`);
166
424
  }
425
+ const clientManifest = selectManifestClient(manifest, client);
167
426
  const destination = path.resolve(destinationRoot);
168
427
  const parent = path.dirname(destination);
169
428
  let destinationExists = false;
@@ -184,15 +443,15 @@ async function restoreRoot(sourceRoot, destinationRoot, client) {
184
443
  try {
185
444
  await fs.mkdir(parent, { recursive: true });
186
445
  await fs.mkdir(temporary);
187
- await copyVerifiedObjects(manifest, sourceRoot, temporary);
446
+ await copyVerifiedObjects(clientManifest, sourceRoot, temporary);
188
447
  db = openDatabase(clientDbPath(temporary, client));
189
- importManifest(db, manifest);
448
+ importManifest(db, clientManifest);
190
449
  await writeRootManifest(temporary, db);
191
450
  db.close();
192
451
  db = void 0;
193
452
  if (destinationExists) await fs.rmdir(destination);
194
453
  await renameWithRetry(temporary, destination);
195
- return counts(manifest);
454
+ return counts(clientManifest);
196
455
  } catch (error) {
197
456
  try {
198
457
  db?.close();
@@ -223,10 +482,7 @@ async function removeDatabaseFiles(dbPath) {
223
482
  return failures.length > 0 ? ` Database cleanup failed: ${failures.join("; ")}` : "";
224
483
  }
225
484
  async function reindexRoot(root, client) {
226
- const manifest = await readRootManifest(root);
227
- if (!manifest.clients.some((row) => row.name === client)) {
228
- throw ioError("namespace_mismatch", `Manifest does not contain client ${client}.`);
229
- }
485
+ const manifest = selectManifestClient(await readRootManifest(root), client);
230
486
  for (const object of manifest.objects) await readAndVerifyObject(root, object);
231
487
  const dbPath = clientDbPath(root, client);
232
488
  try {
@@ -259,9 +515,13 @@ async function reindexRoot(root, client) {
259
515
  }
260
516
  }
261
517
  export {
518
+ acquireManifestLock,
262
519
  backupRoot,
520
+ observeManifestLock,
521
+ publishRootManifest,
263
522
  readRootManifest,
264
523
  reindexRoot,
265
524
  restoreRoot,
525
+ takeoverStaleManifestLock,
266
526
  writeRootManifest
267
527
  };
@@ -22,12 +22,30 @@ const retrievalNamespaceSchema = z.object({
22
22
  client: nonBlankString,
23
23
  project: nonBlankString
24
24
  }).strict();
25
+ function parseNamespaceAllowlist(value) {
26
+ if (value === void 0) return null;
27
+ let decoded;
28
+ try {
29
+ decoded = JSON.parse(value);
30
+ } catch {
31
+ throw new Error("invalid_namespace_allowlist: RAG_ALLOWED_NAMESPACES must be a JSON array.");
32
+ }
33
+ const parsed = z.array(retrievalNamespaceSchema).safeParse(decoded);
34
+ if (!parsed.success) throw new Error("invalid_namespace_allowlist: RAG_ALLOWED_NAMESPACES must be an array of client/project objects.");
35
+ return parsed.data;
36
+ }
37
+ function isNamespaceAllowed(allowlist, namespace) {
38
+ return allowlist === null || allowlist.some((item) => item.client === namespace.client && item.project === namespace.project);
39
+ }
25
40
  function defaultedInteger(minimum, maximum, fallback) {
26
41
  return z.number().int().min(minimum).max(maximum).optional().transform((value) => value ?? fallback);
27
42
  }
28
43
  const ragFindInputSchema = z.object({
29
44
  namespace: retrievalNamespaceSchema,
30
45
  query: nonBlankString,
46
+ includeHistorical: z.boolean().optional().default(false),
47
+ matchMode: z.enum(["all", "any"]).optional().default("all"),
48
+ searchMode: z.enum(["lexical", "semantic", "hybrid"]).optional().default("lexical"),
31
49
  limit: defaultedInteger(1, MAX_LIMIT, DEFAULT_LIMIT),
32
50
  excerptChars: defaultedInteger(1, MAX_EXCERPT_CHARS, DEFAULT_EXCERPT_CHARS)
33
51
  }).strict();
@@ -37,8 +55,12 @@ const ragReadInputSchema = z.object({
37
55
  chunkOrdinal: z.number().multipleOf(1).min(0).refine(Number.isSafeInteger),
38
56
  maxBytes: defaultedInteger(0, MAX_BYTES, DEFAULT_MAX_BYTES),
39
57
  maxLines: defaultedInteger(0, MAX_LINES, DEFAULT_MAX_LINES),
40
- startLine: defaultedInteger(0, MAX_LINES, 0)
41
- }).strict();
58
+ startLine: z.number().int().min(0).max(MAX_LINES).optional(),
59
+ startByte: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional()
60
+ }).strict().refine((value) => value.startLine === void 0 || value.startByte === void 0, {
61
+ path: ["startByte"],
62
+ message: "startByte and startLine cannot be combined."
63
+ });
42
64
  function unknownField(issues) {
43
65
  const issue = issues.find((item) => item.code === "unrecognized_keys" && item.path.length === 0) ?? issues.find((item) => item.code === "unrecognized_keys");
44
66
  if (!issue || issue.code !== "unrecognized_keys") return null;
@@ -70,6 +92,9 @@ function inputFailure(issues, kind) {
70
92
  if (hasIssue(issues, "limit")) return limitFailure("limit", 1, MAX_LIMIT);
71
93
  if (hasIssue(issues, "excerptChars")) return limitFailure("excerptChars", 1, MAX_EXCERPT_CHARS);
72
94
  } else {
95
+ if (issues.some((issue) => issue.path[0] === "startByte" && issue.code === "custom")) {
96
+ return { code: "invalid_input", message: "startByte and startLine cannot be combined." };
97
+ }
73
98
  if (hasIssue(issues, "docVersionId")) {
74
99
  return { code: "invalid_input", message: "docVersionId must be a non-empty string." };
75
100
  }
@@ -79,6 +104,7 @@ function inputFailure(issues, kind) {
79
104
  if (hasIssue(issues, "maxBytes")) return limitFailure("maxBytes", 0, MAX_BYTES);
80
105
  if (hasIssue(issues, "maxLines")) return limitFailure("maxLines", 0, MAX_LINES);
81
106
  if (hasIssue(issues, "startLine")) return limitFailure("startLine", 0, MAX_LINES);
107
+ if (hasIssue(issues, "startByte")) return limitFailure("startByte", 0, Number.MAX_SAFE_INTEGER);
82
108
  }
83
109
  if (issues.some((issue) => issue.path.length === 0)) {
84
110
  return { code: "invalid_input", message: "Tool arguments must be an object." };
@@ -122,12 +148,12 @@ function advertisedInputSchema(schema) {
122
148
  }
123
149
  const RAG_FIND_TOOL = {
124
150
  name: "rag_find",
125
- description: "Search a client/project knowledge base and return bounded citations.",
151
+ description: "Search current document versions. Semantic or hybrid search sends indexed text to the explicitly configured provider; use matchMode any for broader lexical matching or includeHistorical for older versions.",
126
152
  inputSchema: advertisedInputSchema(ragFindInputSchema)
127
153
  };
128
154
  const RAG_READ_TOOL = {
129
155
  name: "rag_read",
130
- description: "Read bounded text from a cited document chunk in the explicit namespace.",
156
+ description: "Read bounded text from a cited document chunk in the explicit namespace. For exact pagination use startByte: 0, modest maxBytes and positive maxLines; repeat with nextByteOffset until null, concatenating text directly. Do not combine startByte and startLine.",
131
157
  inputSchema: advertisedInputSchema(ragReadInputSchema)
132
158
  };
133
159
  const RAG_TOOLS = [RAG_FIND_TOOL, RAG_READ_TOOL];
@@ -143,8 +169,10 @@ export {
143
169
  RAG_FIND_TOOL,
144
170
  RAG_READ_TOOL,
145
171
  RAG_TOOLS,
172
+ isNamespaceAllowed,
146
173
  namespaceFromToolInput,
147
174
  parseCapabilities,
175
+ parseNamespaceAllowlist,
148
176
  ragFindInputSchema,
149
177
  ragReadInputSchema,
150
178
  validateRagFindInput,