@khanglvm/outline-cli 0.1.6 → 0.1.8

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.
@@ -1,5 +1,7 @@
1
1
  import { CliError } from "./errors.js";
2
2
 
3
+ const MEMORY_ENTITY_TYPES = ["document", "collection", "user", "group", "template"];
4
+
3
5
  const TYPES = {
4
6
  string: (v) => typeof v === "string",
5
7
  number: (v) => typeof v === "number" && Number.isFinite(v),
@@ -155,6 +157,447 @@ function buildValidationDetails(tool, spec, issues, args = undefined) {
155
157
  };
156
158
  }
157
159
 
160
+ const ACCESS_RESOLVE_COMMON_PROPERTIES = {
161
+ refs: { type: "string[]" },
162
+ queries: { type: "string[]" },
163
+ documentQueries: { type: "string[]" },
164
+ profile: { type: "string" },
165
+ resolveLimit: { type: "number", min: 1 },
166
+ minScore: { type: "number", min: 0 },
167
+ maxAgeHours: { type: "number", min: 0 },
168
+ refresh: { type: "boolean" },
169
+ strict: { type: "boolean" },
170
+ strictThreshold: { type: "number", min: 0 },
171
+ fallbackSearch: { type: "boolean" },
172
+ fallbackMinScore: { type: "number", min: 0 },
173
+ fallbackLimit: { type: "number", min: 1 },
174
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
175
+ resolveConcurrency: { type: "number", min: 1 },
176
+ resolveHydrateConcurrency: { type: "number", min: 1 },
177
+ };
178
+
179
+ const DOCUMENT_ACCESS_RESOLVE_PROPERTIES = {
180
+ id: { type: "string" },
181
+ documentId: { type: "string" },
182
+ query: { type: "string" },
183
+ documentQuery: { type: "string" },
184
+ shareId: { type: "string" },
185
+ shareIds: { type: "string[]" },
186
+ urlId: { type: "string" },
187
+ urlIds: { type: "string[]" },
188
+ url: { type: "string" },
189
+ urls: { type: "string[]" },
190
+ resolveCollectionId: { type: "string" },
191
+ snippetMinWords: { type: "number", min: 1 },
192
+ snippetMaxWords: { type: "number", min: 1 },
193
+ ...ACCESS_RESOLVE_COMMON_PROPERTIES,
194
+ };
195
+
196
+ const COLLECTION_ACCESS_RESOLVE_PROPERTIES = {
197
+ id: { type: "string" },
198
+ collectionId: { type: "string" },
199
+ query: { type: "string" },
200
+ urlId: { type: "string" },
201
+ urlIds: { type: "string[]" },
202
+ url: { type: "string" },
203
+ urls: { type: "string[]" },
204
+ ...ACCESS_RESOLVE_COMMON_PROPERTIES,
205
+ };
206
+
207
+ const PRINCIPAL_RESOLVE_PROPERTIES = {
208
+ query: { type: "string" },
209
+ refs: { type: "string[]" },
210
+ queries: { type: "string[]" },
211
+ profile: { type: "string" },
212
+ resolveLimit: { type: "number", min: 1 },
213
+ minScore: { type: "number", min: 0 },
214
+ maxAgeHours: { type: "number", min: 0 },
215
+ refresh: { type: "boolean" },
216
+ strict: { type: "boolean" },
217
+ strictThreshold: { type: "number", min: 0 },
218
+ fallbackSearch: { type: "boolean" },
219
+ fallbackMinScore: { type: "number", min: 0 },
220
+ fallbackLimit: { type: "number", min: 1 },
221
+ resolveConcurrency: { type: "number", min: 1 },
222
+ resolveHydrateConcurrency: { type: "number", min: 1 },
223
+ };
224
+
225
+ const PRINCIPAL_RESOLVE_OPTION_PROPERTIES = {
226
+ profile: { type: "string" },
227
+ resolveLimit: { type: "number", min: 1 },
228
+ minScore: { type: "number", min: 0 },
229
+ maxAgeHours: { type: "number", min: 0 },
230
+ refresh: { type: "boolean" },
231
+ strict: { type: "boolean" },
232
+ strictThreshold: { type: "number", min: 0 },
233
+ fallbackSearch: { type: "boolean" },
234
+ fallbackMinScore: { type: "number", min: 0 },
235
+ fallbackLimit: { type: "number", min: 1 },
236
+ resolveConcurrency: { type: "number", min: 1 },
237
+ resolveHydrateConcurrency: { type: "number", min: 1 },
238
+ };
239
+
240
+ const USER_PRINCIPAL_RESOLVE_PROPERTIES = {
241
+ userQuery: { type: "string" },
242
+ userRef: { type: "string" },
243
+ userQueries: { type: "string[]" },
244
+ userRefs: { type: "string[]" },
245
+ ...PRINCIPAL_RESOLVE_OPTION_PROPERTIES,
246
+ };
247
+
248
+ const GROUP_PRINCIPAL_RESOLVE_PROPERTIES = {
249
+ groupQuery: { type: "string" },
250
+ groupRef: { type: "string" },
251
+ groupQueries: { type: "string[]" },
252
+ groupRefs: { type: "string[]" },
253
+ ...PRINCIPAL_RESOLVE_OPTION_PROPERTIES,
254
+ };
255
+
256
+ const TEMPLATE_RESOLVE_PROPERTIES = {
257
+ templateQuery: { type: "string" },
258
+ templateRef: { type: "string" },
259
+ templateQueries: { type: "string[]" },
260
+ templateRefs: { type: "string[]" },
261
+ refs: { type: "string[]" },
262
+ queries: { type: "string[]" },
263
+ profile: { type: "string" },
264
+ resolveLimit: { type: "number", min: 1 },
265
+ minScore: { type: "number", min: 0 },
266
+ maxAgeHours: { type: "number", min: 0 },
267
+ refresh: { type: "boolean" },
268
+ strict: { type: "boolean" },
269
+ strictThreshold: { type: "number", min: 0 },
270
+ fallbackSearch: { type: "boolean" },
271
+ fallbackMinScore: { type: "number", min: 0 },
272
+ fallbackLimit: { type: "number", min: 1 },
273
+ resolveConcurrency: { type: "number", min: 1 },
274
+ resolveHydrateConcurrency: { type: "number", min: 1 },
275
+ };
276
+
277
+ const DOCUMENT_TARGET_RESOLVE_PROPERTIES = {
278
+ documentId: { type: "string" },
279
+ query: { type: "string" },
280
+ documentQuery: { type: "string" },
281
+ documentRef: { type: "string" },
282
+ queries: { type: "string[]" },
283
+ documentQueries: { type: "string[]" },
284
+ documentRefs: { type: "string[]" },
285
+ refs: { type: "string[]" },
286
+ shareId: { type: "string" },
287
+ shareIds: { type: "string[]" },
288
+ urlId: { type: "string" },
289
+ urlIds: { type: "string[]" },
290
+ url: { type: "string" },
291
+ urls: { type: "string[]" },
292
+ profile: { type: "string" },
293
+ resolveLimit: { type: "number", min: 1 },
294
+ minScore: { type: "number", min: 0 },
295
+ maxAgeHours: { type: "number", min: 0 },
296
+ refresh: { type: "boolean" },
297
+ strict: { type: "boolean" },
298
+ strictThreshold: { type: "number", min: 0 },
299
+ fallbackSearch: { type: "boolean" },
300
+ fallbackMinScore: { type: "number", min: 0 },
301
+ fallbackLimit: { type: "number", min: 1 },
302
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
303
+ resolveCollectionId: { type: "string" },
304
+ resolveConcurrency: { type: "number", min: 1 },
305
+ resolveHydrateConcurrency: { type: "number", min: 1 },
306
+ snippetMinWords: { type: "number", min: 1 },
307
+ snippetMaxWords: { type: "number", min: 1 },
308
+ };
309
+
310
+ const DOCUMENT_MUTATION_TARGET_RESOLVE_PROPERTIES = {
311
+ id: { type: "string" },
312
+ ...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
313
+ };
314
+
315
+ function hasNonEmptyString(value) {
316
+ return typeof value === "string" && value.trim().length > 0;
317
+ }
318
+
319
+ function hasNonEmptyStringArray(value) {
320
+ return Array.isArray(value) && value.some((item) => hasNonEmptyString(item));
321
+ }
322
+
323
+ function validateAccessResolveConcurrency(args, issues) {
324
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
325
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
326
+ }
327
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
328
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
329
+ }
330
+ }
331
+
332
+ function validateDocumentAccessSelector(args, issues) {
333
+ const hasScalar = ["id", "documentId", "query", "documentQuery", "shareId", "urlId", "url"].some((key) =>
334
+ hasNonEmptyString(args[key])
335
+ );
336
+ const hasArray = ["refs", "queries", "documentQueries", "shareIds", "urlIds", "urls"].some((key) =>
337
+ hasNonEmptyStringArray(args[key])
338
+ );
339
+ if (!hasScalar && !hasArray) {
340
+ issues.push({ path: "args.id", message: "or args.documentId, args.query, args.refs, args.shareId, args.urlId, or args.url is required" });
341
+ }
342
+ if (args.id && args.documentId) {
343
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
344
+ }
345
+ validateAccessResolveConcurrency(args, issues);
346
+ }
347
+
348
+ function hasDocumentResolveSelector(args, { includeQuery = true } = {}) {
349
+ const scalarKeys = [
350
+ "documentId",
351
+ "documentQuery",
352
+ "documentRef",
353
+ "shareId",
354
+ "urlId",
355
+ "url",
356
+ ...(includeQuery ? ["query"] : []),
357
+ ];
358
+ const arrayKeys = [
359
+ "refs",
360
+ "documentRefs",
361
+ "documentQueries",
362
+ "shareIds",
363
+ "urlIds",
364
+ "urls",
365
+ ...(includeQuery ? ["queries"] : []),
366
+ ];
367
+ return scalarKeys.some((key) => hasNonEmptyString(args[key]))
368
+ || arrayKeys.some((key) => hasNonEmptyStringArray(args[key]));
369
+ }
370
+
371
+ function validateOptionalDocumentResolveArgs(args, issues) {
372
+ validateAccessResolveConcurrency(args, issues);
373
+ }
374
+
375
+ function validateRequiredDocumentResolveArgs(args, issues) {
376
+ if (!hasDocumentResolveSelector(args)) {
377
+ issues.push({ path: "args.documentId", message: "or args.query, args.documentQuery, args.refs, args.shareId, args.urlId, or args.url is required" });
378
+ }
379
+ const hasExact = hasNonEmptyString(args.documentId);
380
+ const hasRef = [
381
+ "query",
382
+ "documentQuery",
383
+ "documentRef",
384
+ "shareId",
385
+ "urlId",
386
+ "url",
387
+ ].some((key) => hasNonEmptyString(args[key]))
388
+ || ["refs", "queries", "documentQueries", "documentRefs", "shareIds", "urlIds", "urls"].some((key) => hasNonEmptyStringArray(args[key]));
389
+ if (hasExact && hasRef) {
390
+ issues.push({ path: "args.documentQuery", message: "cannot be combined with args.documentId" });
391
+ }
392
+ validateAccessResolveConcurrency(args, issues);
393
+ }
394
+
395
+ function validateRequiredDocumentMutationTargetArgs(args, issues) {
396
+ const hasId = hasNonEmptyString(args.id);
397
+ const hasDocumentId = hasNonEmptyString(args.documentId);
398
+ const hasRef = [
399
+ "query",
400
+ "documentQuery",
401
+ "documentRef",
402
+ "shareId",
403
+ "urlId",
404
+ "url",
405
+ ].some((key) => hasNonEmptyString(args[key]))
406
+ || ["refs", "queries", "documentQueries", "documentRefs", "shareIds", "urlIds", "urls"].some((key) => hasNonEmptyStringArray(args[key]));
407
+
408
+ if (!hasId && !hasDocumentId && !hasRef) {
409
+ issues.push({ path: "args.id", message: "or args.documentId, args.query, args.refs, args.shareId, args.urlId, or args.url is required" });
410
+ }
411
+ if (hasId && hasDocumentId) {
412
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
413
+ }
414
+ if ((hasId || hasDocumentId) && hasRef) {
415
+ issues.push({ path: "args.query", message: "cannot be combined with args.id or args.documentId" });
416
+ }
417
+ validateAccessResolveConcurrency(args, issues);
418
+ }
419
+
420
+ function validateExpectedRevisionGuard(args, issues) {
421
+ if (typeof args.expectedRevision === "string" && args.expectedRevision.trim().toLowerCase() !== "latest") {
422
+ issues.push({ path: "args.expectedRevision", message: "must be a number or latest" });
423
+ }
424
+ }
425
+
426
+ function validateRequiredDocumentMutationTargetAndExpectedRevision(args, issues) {
427
+ validateRequiredDocumentMutationTargetArgs(args, issues);
428
+ validateExpectedRevisionGuard(args, issues);
429
+ }
430
+
431
+ function validateBatchUpdateDocumentTarget(update, issues, path) {
432
+ const hasId = hasNonEmptyString(update.id);
433
+ const hasDocumentId = hasNonEmptyString(update.documentId);
434
+ const hasRef = [
435
+ "query",
436
+ "documentQuery",
437
+ "documentRef",
438
+ "shareId",
439
+ "urlId",
440
+ "url",
441
+ ].some((key) => hasNonEmptyString(update[key]))
442
+ || ["refs", "queries", "documentQueries", "documentRefs", "shareIds", "urlIds", "urls"].some((key) => hasNonEmptyStringArray(update[key]));
443
+
444
+ if (!hasId && !hasDocumentId && !hasRef) {
445
+ issues.push({ path: `${path}.id`, message: "or document refs are required" });
446
+ }
447
+ if (hasId && hasDocumentId) {
448
+ issues.push({ path: `${path}.documentId`, message: "cannot be combined with id" });
449
+ }
450
+ if ((hasId || hasDocumentId) && hasRef) {
451
+ issues.push({ path: `${path}.query`, message: "cannot be combined with id or documentId" });
452
+ }
453
+ if (hasRef && !Object.prototype.hasOwnProperty.call(update, "expectedRevision")) {
454
+ issues.push({ path: `${path}.expectedRevision`, message: "is required when using document refs" });
455
+ }
456
+ }
457
+
458
+ function validateEventsListResolveSelectors(args, issues) {
459
+ const hasDocumentRef = ["documentQuery", "documentRef", "shareId", "urlId", "url"].some((key) => hasNonEmptyString(args[key]))
460
+ || ["documentQueries", "documentRefs", "refs", "shareIds", "urlIds", "urls"].some((key) => hasNonEmptyStringArray(args[key]));
461
+ if (hasNonEmptyString(args.documentId) && hasDocumentRef) {
462
+ issues.push({ path: "args.documentQuery", message: "cannot be combined with args.documentId" });
463
+ }
464
+ if (hasNonEmptyString(args.collectionId) && hasDocumentFilterResolveSelector(args, "collection")) {
465
+ issues.push({ path: "args.collectionQuery", message: "cannot be combined with args.collectionId" });
466
+ }
467
+ if (hasNonEmptyString(args.actorId) && hasDocumentFilterResolveSelector(args, "user")) {
468
+ issues.push({ path: "args.userQuery", message: "cannot be combined with args.actorId" });
469
+ }
470
+ validateAccessResolveConcurrency(args, issues);
471
+ }
472
+
473
+ function validateOptionalCollectionFilterResolveArgs(args, issues) {
474
+ if (hasNonEmptyString(args.collectionId) && hasDocumentFilterResolveSelector(args, "collection")) {
475
+ issues.push({ path: "args.collectionQuery", message: "cannot be combined with args.collectionId" });
476
+ }
477
+ validateAccessResolveConcurrency(args, issues);
478
+ }
479
+
480
+ function validateShareInfoSelector(args, issues) {
481
+ const hasShareId = hasNonEmptyString(args.id);
482
+ const hasDocumentRef = hasDocumentResolveSelector(args);
483
+ if (!hasShareId && !hasDocumentRef) {
484
+ issues.push({ path: "args.id", message: "or args.documentId, args.query, args.documentQuery, args.refs, args.urlId, or args.url is required" });
485
+ }
486
+ if (hasShareId && hasDocumentRef) {
487
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
488
+ }
489
+ validateAccessResolveConcurrency(args, issues);
490
+ }
491
+
492
+ function validateCollectionAccessSelector(args, issues) {
493
+ const hasScalar = ["id", "collectionId", "query", "urlId", "url"].some((key) =>
494
+ hasNonEmptyString(args[key])
495
+ );
496
+ const hasArray = ["refs", "queries", "urlIds", "urls"].some((key) =>
497
+ hasNonEmptyStringArray(args[key])
498
+ );
499
+ if (!hasScalar && !hasArray) {
500
+ issues.push({ path: "args.id", message: "or args.collectionId, args.query, args.refs, args.urlId, or args.url is required" });
501
+ }
502
+ if (args.id && args.collectionId) {
503
+ issues.push({ path: "args.collectionId", message: "cannot be combined with args.id" });
504
+ }
505
+ validateAccessResolveConcurrency(args, issues);
506
+ }
507
+
508
+ function hasPrincipalResolveSelector(args) {
509
+ return ["query"].some((key) => hasNonEmptyString(args[key]))
510
+ || ["refs", "queries"].some((key) => hasNonEmptyStringArray(args[key]));
511
+ }
512
+
513
+ function validatePrincipalResolveConcurrency(args, issues) {
514
+ validateAccessResolveConcurrency(args, issues);
515
+ }
516
+
517
+ function hasNamedPrincipalSelector(args, type) {
518
+ const prefix = type === "group" ? "group" : "user";
519
+ return [`${prefix}Query`, `${prefix}Ref`].some((key) => hasNonEmptyString(args[key]))
520
+ || [`${prefix}Queries`, `${prefix}Refs`].some((key) => hasNonEmptyStringArray(args[key]));
521
+ }
522
+
523
+ function validateNamedPrincipalSelector(args, issues, type) {
524
+ const idKey = type === "group" ? "groupId" : "userId";
525
+ const prefix = type === "group" ? "group" : "user";
526
+ const hasId = hasNonEmptyString(args[idKey]);
527
+ const hasResolvedRef = hasNamedPrincipalSelector(args, type);
528
+ if (!hasId && !hasResolvedRef) {
529
+ issues.push({ path: `args.${idKey}`, message: `or args.${prefix}Query/args.${prefix}Refs is required` });
530
+ }
531
+ if (hasId && hasResolvedRef) {
532
+ issues.push({ path: `args.${prefix}Query`, message: `cannot be combined with args.${idKey}` });
533
+ }
534
+ validatePrincipalResolveConcurrency(args, issues);
535
+ }
536
+
537
+ function hasGroupTargetSelector(args) {
538
+ return ["id", "groupId", "groupQuery", "groupRef"].some((key) => hasNonEmptyString(args[key]))
539
+ || ["groupQueries", "groupRefs"].some((key) => hasNonEmptyStringArray(args[key]));
540
+ }
541
+
542
+ function hasTemplateResolveSelector(args, { includeQuery = true } = {}) {
543
+ return ["templateQuery", "templateRef", ...(includeQuery ? ["query"] : [])].some((key) => hasNonEmptyString(args[key]))
544
+ || ["templateQueries", "templateRefs", "refs", ...(includeQuery ? ["queries"] : [])].some((key) => hasNonEmptyStringArray(args[key]));
545
+ }
546
+
547
+ function validateTemplateTargetSelector(args, issues, options = {}) {
548
+ const idKeys = options.idKeys || ["id"];
549
+ const hasId = idKeys.some((key) => hasNonEmptyString(args[key]));
550
+ const hasIds = hasNonEmptyStringArray(args.ids);
551
+ const hasResolvedRef = hasTemplateResolveSelector(args, { includeQuery: options.includeQuery !== false });
552
+ if (!hasId && !hasIds && !hasResolvedRef) {
553
+ issues.push({ path: `args.${idKeys[0]}`, message: "or args.templateQuery/args.templateRefs is required" });
554
+ }
555
+ if ((hasId || hasIds) && hasResolvedRef) {
556
+ issues.push({ path: "args.templateQuery", message: `cannot be combined with args.${hasIds ? "ids" : idKeys[0]}` });
557
+ }
558
+ validatePrincipalResolveConcurrency(args, issues);
559
+ }
560
+
561
+ function validateGroupTargetSelector(args, issues) {
562
+ if (!hasGroupTargetSelector(args)) {
563
+ issues.push({ path: "args.id", message: "or args.groupId/args.groupQuery/args.groupRefs is required" });
564
+ }
565
+ const hasId = hasNonEmptyString(args.id) || hasNonEmptyString(args.groupId);
566
+ const hasResolvedRef = hasNamedPrincipalSelector(args, "group");
567
+ if (hasNonEmptyString(args.id) && hasNonEmptyString(args.groupId)) {
568
+ issues.push({ path: "args.groupId", message: "cannot be combined with args.id" });
569
+ }
570
+ if (hasId && hasResolvedRef) {
571
+ issues.push({ path: "args.groupQuery", message: "cannot be combined with args.id or args.groupId" });
572
+ }
573
+ validatePrincipalResolveConcurrency(args, issues);
574
+ }
575
+
576
+ function validateGroupUserMutationSelector(args, issues) {
577
+ validateGroupTargetSelector(args, issues);
578
+ validateNamedPrincipalSelector(args, issues, "user");
579
+ }
580
+
581
+ function validateCollectionUserMutationSelector(args, issues) {
582
+ validateCollectionAccessSelector(args, issues);
583
+ validateNamedPrincipalSelector(args, issues, "user");
584
+ }
585
+
586
+ function validateCollectionGroupMutationSelector(args, issues) {
587
+ validateCollectionAccessSelector(args, issues);
588
+ validateNamedPrincipalSelector(args, issues, "group");
589
+ }
590
+
591
+ function validateDocumentUserMutationSelector(args, issues) {
592
+ validateDocumentAccessSelector(args, issues);
593
+ validateNamedPrincipalSelector(args, issues, "user");
594
+ }
595
+
596
+ function validateDocumentGroupMutationSelector(args, issues) {
597
+ validateDocumentAccessSelector(args, issues);
598
+ validateNamedPrincipalSelector(args, issues, "group");
599
+ }
600
+
158
601
  function looksNumeric(value) {
159
602
  return /^-?(?:\d+|\d+\.\d+)$/.test(String(value || "").trim());
160
603
  }
@@ -331,11 +774,58 @@ function validateSpec(tool, args, spec) {
331
774
 
332
775
  const SHARED_DOC_COMMON = {
333
776
  collectionId: { type: "string" },
777
+ collectionQuery: { type: "string" },
778
+ collectionRef: { type: "string" },
779
+ collectionQueries: { type: "string[]" },
780
+ collectionRefs: { type: "string[]" },
334
781
  userId: { type: "string" },
782
+ userQuery: { type: "string" },
783
+ userRef: { type: "string" },
784
+ userQueries: { type: "string[]" },
785
+ userRefs: { type: "string[]" },
786
+ profile: { type: "string" },
787
+ resolveLimit: { type: "number", min: 1 },
788
+ minScore: { type: "number", min: 0 },
789
+ maxAgeHours: { type: "number", min: 0 },
790
+ refresh: { type: "boolean" },
791
+ strict: { type: "boolean" },
792
+ strictThreshold: { type: "number", min: 0 },
793
+ fallbackSearch: { type: "boolean" },
794
+ fallbackMinScore: { type: "number", min: 0 },
795
+ fallbackLimit: { type: "number", min: 1 },
335
796
  statusFilter: { type: ["string", "string[]"] },
336
797
  view: { type: "string", enum: ["ids", "summary", "full"] },
337
798
  };
338
799
 
800
+ function hasDocumentFilterResolveSelector(args, prefix) {
801
+ return [`${prefix}Query`, `${prefix}Ref`].some((key) => hasNonEmptyString(args[key]))
802
+ || [`${prefix}Queries`, `${prefix}Refs`].some((key) => hasNonEmptyStringArray(args[key]));
803
+ }
804
+
805
+ function validateDocumentFilterSelectors(args, issues) {
806
+ if (hasNonEmptyString(args.collectionId) && hasDocumentFilterResolveSelector(args, "collection")) {
807
+ issues.push({ path: "args.collectionQuery", message: "cannot be combined with args.collectionId" });
808
+ }
809
+ if (hasNonEmptyString(args.userId) && hasDocumentFilterResolveSelector(args, "user")) {
810
+ issues.push({ path: "args.userQuery", message: "cannot be combined with args.userId" });
811
+ }
812
+ }
813
+
814
+ function hasAnswerDocumentResolveSelector(args) {
815
+ return ["documentQuery", "documentRef", "shareId", "urlId", "url"].some((key) => hasNonEmptyString(args[key]))
816
+ || ["documentQueries", "documentRefs", "refs", "shareIds", "urlIds", "urls"].some((key) => hasNonEmptyStringArray(args[key]));
817
+ }
818
+
819
+ function validateAnswerScopeSelectors(args, issues) {
820
+ validateDocumentFilterSelectors(args, issues);
821
+ if (hasNonEmptyString(args.id) && hasNonEmptyString(args.documentId)) {
822
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
823
+ }
824
+ if ((hasNonEmptyString(args.id) || hasNonEmptyString(args.documentId)) && hasAnswerDocumentResolveSelector(args)) {
825
+ issues.push({ path: "args.documentQuery", message: "cannot be combined with args.id or args.documentId" });
826
+ }
827
+ }
828
+
339
829
  const DATA_ATTRIBUTE_DATA_TYPES = ["string", "number", "boolean", "list"];
340
830
  const USER_ROLE_TYPES = ["admin", "member", "viewer", "guest"];
341
831
 
@@ -385,6 +875,7 @@ export const TOOL_ARG_SCHEMAS = {
385
875
  if (!args.query && !args.queries) {
386
876
  issues.push({ path: "args.query", message: "or args.queries[] is required" });
387
877
  }
878
+ validateDocumentFilterSelectors(args, issues);
388
879
  },
389
880
  },
390
881
  "documents.list": {
@@ -406,12 +897,28 @@ export const TOOL_ARG_SCHEMAS = {
406
897
  message: "cannot be combined with a non-null args.parentDocumentId",
407
898
  });
408
899
  }
900
+ validateDocumentFilterSelectors(args, issues);
409
901
  },
410
902
  },
411
903
  "documents.backlinks": {
412
- required: ["id"],
413
904
  properties: {
414
905
  id: { type: "string" },
906
+ query: { type: "string" },
907
+ shareId: { type: "string" },
908
+ urlId: { type: "string" },
909
+ url: { type: "string" },
910
+ profile: { type: "string" },
911
+ resolveLimit: { type: "number", min: 1 },
912
+ minScore: { type: "number", min: 0 },
913
+ maxAgeHours: { type: "number", min: 0 },
914
+ refresh: { type: "boolean" },
915
+ strict: { type: "boolean" },
916
+ strictThreshold: { type: "number", min: 0 },
917
+ fallbackSearch: { type: "boolean" },
918
+ fallbackMinScore: { type: "number", min: 0 },
919
+ fallbackLimit: { type: "number", min: 1 },
920
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
921
+ resolveCollectionId: { type: "string" },
415
922
  limit: { type: "number", min: 1 },
416
923
  offset: { type: "number", min: 0 },
417
924
  sort: { type: "string" },
@@ -421,8 +928,12 @@ export const TOOL_ARG_SCHEMAS = {
421
928
  maxAttempts: { type: "number", min: 1 },
422
929
  },
423
930
  custom(args, issues) {
424
- if (typeof args.id === "string" && args.id.trim().length === 0) {
425
- issues.push({ path: "args.id", message: "must be a non-empty string" });
931
+ const refs = ["id", "query", "shareId", "urlId", "url"].filter((key) => args[key]);
932
+ if (refs.length === 0) {
933
+ issues.push({ path: "args.id", message: "or args.query, args.shareId, args.urlId, or args.url is required" });
934
+ }
935
+ if (refs.length > 1) {
936
+ issues.push({ path: "args.id", message: "provide only one of args.id, args.query, args.shareId, args.urlId, or args.url" });
426
937
  }
427
938
  if (typeof args.limit === "number" && args.limit > 250) {
428
939
  issues.push({ path: "args.limit", message: "must be <= 250" });
@@ -433,6 +944,29 @@ export const TOOL_ARG_SCHEMAS = {
433
944
  properties: {
434
945
  id: { type: "string" },
435
946
  ids: { type: "string[]" },
947
+ refs: { type: "string[]" },
948
+ query: { type: "string" },
949
+ queries: { type: "string[]" },
950
+ shareId: { type: "string" },
951
+ shareIds: { type: "string[]" },
952
+ urlId: { type: "string" },
953
+ urlIds: { type: "string[]" },
954
+ url: { type: "string" },
955
+ urls: { type: "string[]" },
956
+ profile: { type: "string" },
957
+ resolveLimit: { type: "number", min: 1 },
958
+ minScore: { type: "number", min: 0 },
959
+ maxAgeHours: { type: "number", min: 0 },
960
+ refresh: { type: "boolean" },
961
+ strict: { type: "boolean" },
962
+ strictThreshold: { type: "number", min: 0 },
963
+ fallbackSearch: { type: "boolean" },
964
+ fallbackMinScore: { type: "number", min: 0 },
965
+ fallbackLimit: { type: "number", min: 1 },
966
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
967
+ resolveCollectionId: { type: "string" },
968
+ resolveConcurrency: { type: "number", min: 1 },
969
+ resolveHydrateConcurrency: { type: "number", min: 1 },
436
970
  includeBacklinks: { type: "boolean" },
437
971
  includeSearchNeighbors: { type: "boolean" },
438
972
  searchQueries: { type: "string[]" },
@@ -443,9 +977,15 @@ export const TOOL_ARG_SCHEMAS = {
443
977
  custom(args, issues) {
444
978
  const hasId = typeof args.id === "string" && args.id.trim().length > 0;
445
979
  const hasIds = Array.isArray(args.ids) && args.ids.length > 0;
980
+ const hasRefs = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
981
+ Array.isArray(args[key]) && args[key].length > 0
982
+ );
983
+ const hasSingularRef = ["query", "shareId", "urlId", "url"].some((key) =>
984
+ typeof args[key] === "string" && args[key].trim().length > 0
985
+ );
446
986
 
447
- if (!hasId && !hasIds) {
448
- issues.push({ path: "args.id", message: "or args.ids[] is required" });
987
+ if (!hasId && !hasIds && !hasRefs && !hasSingularRef) {
988
+ issues.push({ path: "args.id", message: "or args.ids[], args.refs[], args.query, args.queries[], args.shareId(s), args.urlId(s), or args.url(s) is required" });
449
989
  }
450
990
  if (Array.isArray(args.ids) && args.ids.length === 0) {
451
991
  issues.push({ path: "args.ids", message: "must be a non-empty string[] when provided" });
@@ -478,12 +1018,40 @@ export const TOOL_ARG_SCHEMAS = {
478
1018
  if (typeof args.limitPerSource === "number" && args.limitPerSource > 100) {
479
1019
  issues.push({ path: "args.limitPerSource", message: "must be <= 100" });
480
1020
  }
1021
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1022
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1023
+ }
1024
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1025
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1026
+ }
481
1027
  },
482
1028
  },
483
1029
  "documents.graph_report": {
484
- required: ["seedIds"],
485
1030
  properties: {
486
1031
  seedIds: { type: "string[]" },
1032
+ seedRefs: { type: "string[]" },
1033
+ seedQuery: { type: "string" },
1034
+ seedQueries: { type: "string[]" },
1035
+ seedShareId: { type: "string" },
1036
+ seedShareIds: { type: "string[]" },
1037
+ seedUrlId: { type: "string" },
1038
+ seedUrlIds: { type: "string[]" },
1039
+ seedUrl: { type: "string" },
1040
+ seedUrls: { type: "string[]" },
1041
+ profile: { type: "string" },
1042
+ resolveLimit: { type: "number", min: 1 },
1043
+ minScore: { type: "number", min: 0 },
1044
+ maxAgeHours: { type: "number", min: 0 },
1045
+ refresh: { type: "boolean" },
1046
+ strict: { type: "boolean" },
1047
+ strictThreshold: { type: "number", min: 0 },
1048
+ fallbackSearch: { type: "boolean" },
1049
+ fallbackMinScore: { type: "number", min: 0 },
1050
+ fallbackLimit: { type: "number", min: 1 },
1051
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1052
+ resolveCollectionId: { type: "string" },
1053
+ resolveConcurrency: { type: "number", min: 1 },
1054
+ resolveHydrateConcurrency: { type: "number", min: 1 },
487
1055
  depth: { type: "number", min: 0 },
488
1056
  maxNodes: { type: "number", min: 1 },
489
1057
  includeBacklinks: { type: "boolean" },
@@ -493,6 +1061,17 @@ export const TOOL_ARG_SCHEMAS = {
493
1061
  maxAttempts: { type: "number", min: 1 },
494
1062
  },
495
1063
  custom(args, issues) {
1064
+ const hasSeedIds = Array.isArray(args.seedIds) && args.seedIds.length > 0;
1065
+ const hasSeedArrays = ["seedRefs", "seedQueries", "seedShareIds", "seedUrlIds", "seedUrls"].some((key) =>
1066
+ Array.isArray(args[key]) && args[key].length > 0
1067
+ );
1068
+ const hasSeedSingle = ["seedQuery", "seedShareId", "seedUrlId", "seedUrl"].some((key) =>
1069
+ typeof args[key] === "string" && args[key].trim().length > 0
1070
+ );
1071
+
1072
+ if (!hasSeedIds && !hasSeedArrays && !hasSeedSingle) {
1073
+ issues.push({ path: "args.seedIds", message: "or args.seedRefs[], args.seedQuery, args.seedQueries[], args.seedShareId(s), args.seedUrlId(s), or args.seedUrl(s) is required" });
1074
+ }
496
1075
  if (Array.isArray(args.seedIds) && args.seedIds.length === 0) {
497
1076
  issues.push({ path: "args.seedIds", message: "must be a non-empty string[]" });
498
1077
  }
@@ -512,6 +1091,12 @@ export const TOOL_ARG_SCHEMAS = {
512
1091
  if (typeof args.limitPerSource === "number" && args.limitPerSource > 100) {
513
1092
  issues.push({ path: "args.limitPerSource", message: "must be <= 100" });
514
1093
  }
1094
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1095
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1096
+ }
1097
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1098
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1099
+ }
515
1100
  if (args.includeBacklinks === false && args.includeSearchNeighbors === false) {
516
1101
  issues.push({
517
1102
  path: "args.includeBacklinks",
@@ -524,6 +1109,29 @@ export const TOOL_ARG_SCHEMAS = {
524
1109
  properties: {
525
1110
  id: { type: "string" },
526
1111
  ids: { type: "string[]" },
1112
+ refs: { type: "string[]" },
1113
+ query: { type: "string" },
1114
+ queries: { type: "string[]" },
1115
+ shareId: { type: "string" },
1116
+ shareIds: { type: "string[]" },
1117
+ urlId: { type: "string" },
1118
+ urlIds: { type: "string[]" },
1119
+ url: { type: "string" },
1120
+ urls: { type: "string[]" },
1121
+ profile: { type: "string" },
1122
+ resolveLimit: { type: "number", min: 1 },
1123
+ minScore: { type: "number", min: 0 },
1124
+ maxAgeHours: { type: "number", min: 0 },
1125
+ refresh: { type: "boolean" },
1126
+ strict: { type: "boolean" },
1127
+ strictThreshold: { type: "number", min: 0 },
1128
+ fallbackSearch: { type: "boolean" },
1129
+ fallbackMinScore: { type: "number", min: 0 },
1130
+ fallbackLimit: { type: "number", min: 1 },
1131
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1132
+ resolveCollectionId: { type: "string" },
1133
+ resolveConcurrency: { type: "number", min: 1 },
1134
+ resolveHydrateConcurrency: { type: "number", min: 1 },
527
1135
  issueDomains: { type: "string[]" },
528
1136
  keyPattern: { type: "string" },
529
1137
  view: { type: "string", enum: ["ids", "summary", "full"] },
@@ -532,9 +1140,15 @@ export const TOOL_ARG_SCHEMAS = {
532
1140
  custom(args, issues) {
533
1141
  const hasId = typeof args.id === "string" && args.id.trim().length > 0;
534
1142
  const hasIds = Array.isArray(args.ids) && args.ids.length > 0;
1143
+ const hasRefs = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
1144
+ Array.isArray(args[key]) && args[key].length > 0
1145
+ );
1146
+ const hasSingularRef = ["query", "shareId", "urlId", "url"].some((key) =>
1147
+ typeof args[key] === "string" && args[key].trim().length > 0
1148
+ );
535
1149
 
536
- if (!hasId && !hasIds) {
537
- issues.push({ path: "args.id", message: "or args.ids[] is required" });
1150
+ if (!hasId && !hasIds && !hasRefs && !hasSingularRef) {
1151
+ issues.push({ path: "args.id", message: "or args.ids[], args.refs[], args.query, args.queries[], args.shareId(s), args.urlId(s), or args.url(s) is required" });
538
1152
  }
539
1153
  if (typeof args.id === "string" && args.id.trim().length === 0) {
540
1154
  issues.push({ path: "args.id", message: "must be a non-empty string" });
@@ -562,6 +1176,12 @@ export const TOOL_ARG_SCHEMAS = {
562
1176
  }
563
1177
  }
564
1178
  }
1179
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1180
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1181
+ }
1182
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1183
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1184
+ }
565
1185
  if (typeof args.keyPattern === "string") {
566
1186
  if (args.keyPattern.trim().length === 0) {
567
1187
  issues.push({ path: "args.keyPattern", message: "must be a non-empty string when provided" });
@@ -640,6 +1260,127 @@ export const TOOL_ARG_SCHEMAS = {
640
1260
  }
641
1261
  },
642
1262
  },
1263
+ "documents.attachments": {
1264
+ properties: {
1265
+ id: { type: "string" },
1266
+ documentId: { type: "string" },
1267
+ refs: { type: "string[]" },
1268
+ query: { type: "string" },
1269
+ queries: { type: "string[]" },
1270
+ url: { type: "string" },
1271
+ urlId: { type: "string" },
1272
+ urlIds: { type: "string[]" },
1273
+ urls: { type: "string[]" },
1274
+ shareId: { type: "string" },
1275
+ shareIds: { type: "string[]" },
1276
+ profile: { type: "string" },
1277
+ resolveLimit: { type: "number", min: 1 },
1278
+ minScore: { type: "number", min: 0 },
1279
+ maxAgeHours: { type: "number", min: 0 },
1280
+ refresh: { type: "boolean" },
1281
+ strict: { type: "boolean" },
1282
+ strictThreshold: { type: "number", min: 0 },
1283
+ fallbackSearch: { type: "boolean" },
1284
+ fallbackMinScore: { type: "number", min: 0 },
1285
+ fallbackLimit: { type: "number", min: 1 },
1286
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1287
+ resolveCollectionId: { type: "string" },
1288
+ resolveConcurrency: { type: "number", min: 1 },
1289
+ resolveHydrateConcurrency: { type: "number", min: 1 },
1290
+ maxAttempts: { type: "number", min: 1 },
1291
+ },
1292
+ custom(args, issues) {
1293
+ const hasArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
1294
+ Array.isArray(args[key]) && args[key].length > 0
1295
+ );
1296
+ const hasSingle = ["query", "urlId"].some((key) =>
1297
+ typeof args[key] === "string" && args[key].trim().length > 0
1298
+ );
1299
+ if (!args.id && !args.documentId && !args.url && !args.shareId && !hasArrays && !hasSingle) {
1300
+ issues.push({ path: "args.id", message: "or args.documentId, args.url, args.shareId, or document refs are required" });
1301
+ }
1302
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1303
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1304
+ }
1305
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1306
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1307
+ }
1308
+ },
1309
+ },
1310
+ "attachments.download": {
1311
+ properties: {
1312
+ id: { type: "string" },
1313
+ attachmentId: { type: "string" },
1314
+ url: { type: "string" },
1315
+ path: { type: "string" },
1316
+ outputDir: { type: "string" },
1317
+ filePath: { type: "string" },
1318
+ fileName: { type: "string" },
1319
+ overwrite: { type: "boolean" },
1320
+ maxAttempts: { type: "number", min: 1 },
1321
+ },
1322
+ custom(args, issues) {
1323
+ if (!args.id && !args.attachmentId && !args.url && !args.path) {
1324
+ issues.push({ path: "args.id", message: "or args.attachmentId, args.url, or args.path is required" });
1325
+ }
1326
+ if (args.filePath && (args.outputDir || args.fileName)) {
1327
+ issues.push({ path: "args.filePath", message: "cannot be combined with args.outputDir or args.fileName" });
1328
+ }
1329
+ },
1330
+ },
1331
+ "documents.download_attachments": {
1332
+ properties: {
1333
+ id: { type: "string" },
1334
+ documentId: { type: "string" },
1335
+ refs: { type: "string[]" },
1336
+ query: { type: "string" },
1337
+ queries: { type: "string[]" },
1338
+ url: { type: "string" },
1339
+ urlId: { type: "string" },
1340
+ urlIds: { type: "string[]" },
1341
+ urls: { type: "string[]" },
1342
+ shareId: { type: "string" },
1343
+ shareIds: { type: "string[]" },
1344
+ profile: { type: "string" },
1345
+ resolveLimit: { type: "number", min: 1 },
1346
+ minScore: { type: "number", min: 0 },
1347
+ maxAgeHours: { type: "number", min: 0 },
1348
+ refresh: { type: "boolean" },
1349
+ strict: { type: "boolean" },
1350
+ strictThreshold: { type: "number", min: 0 },
1351
+ fallbackSearch: { type: "boolean" },
1352
+ fallbackMinScore: { type: "number", min: 0 },
1353
+ fallbackLimit: { type: "number", min: 1 },
1354
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1355
+ resolveCollectionId: { type: "string" },
1356
+ resolveConcurrency: { type: "number", min: 1 },
1357
+ resolveHydrateConcurrency: { type: "number", min: 1 },
1358
+ outputDir: { type: "string" },
1359
+ overwrite: { type: "boolean" },
1360
+ concurrency: { type: "number", min: 1 },
1361
+ maxAttempts: { type: "number", min: 1 },
1362
+ },
1363
+ custom(args, issues) {
1364
+ const hasArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
1365
+ Array.isArray(args[key]) && args[key].length > 0
1366
+ );
1367
+ const hasSingle = ["query", "urlId"].some((key) =>
1368
+ typeof args[key] === "string" && args[key].trim().length > 0
1369
+ );
1370
+ if (!args.id && !args.documentId && !args.url && !args.shareId && !hasArrays && !hasSingle) {
1371
+ issues.push({ path: "args.id", message: "or args.documentId, args.url, args.shareId, or document refs are required" });
1372
+ }
1373
+ if (typeof args.concurrency === "number" && args.concurrency > 8) {
1374
+ issues.push({ path: "args.concurrency", message: "must be <= 8" });
1375
+ }
1376
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1377
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1378
+ }
1379
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1380
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1381
+ }
1382
+ },
1383
+ },
643
1384
  "documents.info": {
644
1385
  properties: {
645
1386
  id: { type: "string" },
@@ -657,6 +1398,84 @@ export const TOOL_ARG_SCHEMAS = {
657
1398
  }
658
1399
  },
659
1400
  },
1401
+ "documents.open": {
1402
+ properties: {
1403
+ query: { type: "string" },
1404
+ id: { type: "string" },
1405
+ shareId: { type: "string" },
1406
+ urlId: { type: "string" },
1407
+ url: { type: "string" },
1408
+ profile: { type: "string" },
1409
+ limit: { type: "number", min: 1 },
1410
+ minScore: { type: "number", min: 0 },
1411
+ maxAgeHours: { type: "number", min: 0 },
1412
+ refresh: { type: "boolean" },
1413
+ strict: { type: "boolean" },
1414
+ strictThreshold: { type: "number", min: 0 },
1415
+ fallbackSearch: { type: "boolean" },
1416
+ fallbackMinScore: { type: "number", min: 0 },
1417
+ fallbackLimit: { type: "number", min: 1 },
1418
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1419
+ collectionId: { type: "string" },
1420
+ snippetMinWords: { type: "number", min: 1 },
1421
+ snippetMaxWords: { type: "number", min: 1 },
1422
+ includePolicies: { type: "boolean" },
1423
+ view: { type: "string", enum: ["summary", "full"] },
1424
+ maxAttempts: { type: "number", min: 1 },
1425
+ },
1426
+ custom(args, issues) {
1427
+ const refs = ["query", "id", "shareId", "urlId", "url"].filter((key) => args[key]);
1428
+ if (refs.length === 0) {
1429
+ issues.push({ path: "args.query", message: "or args.id, args.shareId, args.urlId, or args.url is required" });
1430
+ }
1431
+ if (refs.length > 1) {
1432
+ issues.push({ path: "args.query", message: "provide only one of args.query, args.id, args.shareId, args.urlId, or args.url" });
1433
+ }
1434
+ },
1435
+ },
1436
+ "documents.open_batch": {
1437
+ properties: {
1438
+ refs: { type: "string[]" },
1439
+ queries: { type: "string[]" },
1440
+ ids: { type: "string[]" },
1441
+ shareIds: { type: "string[]" },
1442
+ urlIds: { type: "string[]" },
1443
+ urls: { type: "string[]" },
1444
+ profile: { type: "string" },
1445
+ limit: { type: "number", min: 1 },
1446
+ minScore: { type: "number", min: 0 },
1447
+ maxAgeHours: { type: "number", min: 0 },
1448
+ refresh: { type: "boolean" },
1449
+ strict: { type: "boolean" },
1450
+ strictThreshold: { type: "number", min: 0 },
1451
+ fallbackSearch: { type: "boolean" },
1452
+ fallbackMinScore: { type: "number", min: 0 },
1453
+ fallbackLimit: { type: "number", min: 1 },
1454
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1455
+ collectionId: { type: "string" },
1456
+ snippetMinWords: { type: "number", min: 1 },
1457
+ snippetMaxWords: { type: "number", min: 1 },
1458
+ includePolicies: { type: "boolean" },
1459
+ view: { type: "string", enum: ["summary", "full"] },
1460
+ concurrency: { type: "number", min: 1 },
1461
+ hydrateConcurrency: { type: "number", min: 1 },
1462
+ maxAttempts: { type: "number", min: 1 },
1463
+ },
1464
+ custom(args, issues) {
1465
+ const hasRef = ["refs", "queries", "ids", "shareIds", "urlIds", "urls"].some((key) =>
1466
+ Array.isArray(args[key]) && args[key].length > 0
1467
+ );
1468
+ if (!hasRef) {
1469
+ issues.push({ path: "args.refs", message: "or args.queries, args.ids, args.shareIds, args.urlIds, or args.urls must include at least one value" });
1470
+ }
1471
+ if (typeof args.concurrency === "number" && args.concurrency > 8) {
1472
+ issues.push({ path: "args.concurrency", message: "must be <= 8" });
1473
+ }
1474
+ if (typeof args.hydrateConcurrency === "number" && args.hydrateConcurrency > 8) {
1475
+ issues.push({ path: "args.hydrateConcurrency", message: "must be <= 8" });
1476
+ }
1477
+ },
1478
+ },
660
1479
  "documents.create": {
661
1480
  properties: {
662
1481
  id: { type: "string" },
@@ -718,6 +1537,74 @@ export const TOOL_ARG_SCHEMAS = {
718
1537
  }
719
1538
  },
720
1539
  },
1540
+ "collections.open": {
1541
+ properties: {
1542
+ query: { type: "string" },
1543
+ id: { type: "string" },
1544
+ urlId: { type: "string" },
1545
+ url: { type: "string" },
1546
+ profile: { type: "string" },
1547
+ limit: { type: "number", min: 1 },
1548
+ minScore: { type: "number", min: 0 },
1549
+ maxAgeHours: { type: "number", min: 0 },
1550
+ refresh: { type: "boolean" },
1551
+ strict: { type: "boolean" },
1552
+ strictThreshold: { type: "number", min: 0 },
1553
+ fallbackSearch: { type: "boolean" },
1554
+ fallbackMinScore: { type: "number", min: 0 },
1555
+ fallbackLimit: { type: "number", min: 1 },
1556
+ includePolicies: { type: "boolean" },
1557
+ view: { type: "string", enum: ["summary", "full"] },
1558
+ maxAttempts: { type: "number", min: 1 },
1559
+ },
1560
+ custom(args, issues) {
1561
+ const refs = ["query", "id", "urlId", "url"].filter((key) => args[key]);
1562
+ if (refs.length === 0) {
1563
+ issues.push({ path: "args.query", message: "or args.id, args.urlId, or args.url is required" });
1564
+ }
1565
+ if (refs.length > 1) {
1566
+ issues.push({ path: "args.query", message: "provide only one of args.query, args.id, args.urlId, or args.url" });
1567
+ }
1568
+ },
1569
+ },
1570
+ "collections.open_batch": {
1571
+ properties: {
1572
+ refs: { type: "string[]" },
1573
+ queries: { type: "string[]" },
1574
+ ids: { type: "string[]" },
1575
+ urlIds: { type: "string[]" },
1576
+ urls: { type: "string[]" },
1577
+ profile: { type: "string" },
1578
+ limit: { type: "number", min: 1 },
1579
+ minScore: { type: "number", min: 0 },
1580
+ maxAgeHours: { type: "number", min: 0 },
1581
+ refresh: { type: "boolean" },
1582
+ strict: { type: "boolean" },
1583
+ strictThreshold: { type: "number", min: 0 },
1584
+ fallbackSearch: { type: "boolean" },
1585
+ fallbackMinScore: { type: "number", min: 0 },
1586
+ fallbackLimit: { type: "number", min: 1 },
1587
+ includePolicies: { type: "boolean" },
1588
+ view: { type: "string", enum: ["summary", "full"] },
1589
+ concurrency: { type: "number", min: 1 },
1590
+ hydrateConcurrency: { type: "number", min: 1 },
1591
+ maxAttempts: { type: "number", min: 1 },
1592
+ },
1593
+ custom(args, issues) {
1594
+ const hasRef = ["refs", "queries", "ids", "urlIds", "urls"].some((key) =>
1595
+ Array.isArray(args[key]) && args[key].length > 0
1596
+ );
1597
+ if (!hasRef) {
1598
+ issues.push({ path: "args.refs", message: "or args.queries, args.ids, args.urlIds, or args.urls must include at least one value" });
1599
+ }
1600
+ if (typeof args.concurrency === "number" && args.concurrency > 8) {
1601
+ issues.push({ path: "args.concurrency", message: "must be <= 8" });
1602
+ }
1603
+ if (typeof args.hydrateConcurrency === "number" && args.hydrateConcurrency > 8) {
1604
+ issues.push({ path: "args.hydrateConcurrency", message: "must be <= 8" });
1605
+ }
1606
+ },
1607
+ },
721
1608
  "collections.create": {
722
1609
  required: ["name"],
723
1610
  properties: {
@@ -749,6 +1636,25 @@ export const TOOL_ARG_SCHEMAS = {
749
1636
  query: { type: "string" },
750
1637
  queries: { type: "string[]" },
751
1638
  collectionId: { type: "string" },
1639
+ collectionQuery: { type: "string" },
1640
+ collectionRef: { type: "string" },
1641
+ collectionQueries: { type: "string[]" },
1642
+ collectionRefs: { type: "string[]" },
1643
+ userId: { type: "string" },
1644
+ userQuery: { type: "string" },
1645
+ userRef: { type: "string" },
1646
+ userQueries: { type: "string[]" },
1647
+ userRefs: { type: "string[]" },
1648
+ profile: { type: "string" },
1649
+ memory: { type: "boolean" },
1650
+ memoryMinScore: { type: "number", min: 0 },
1651
+ minScore: { type: "number", min: 0 },
1652
+ maxAgeHours: { type: "number", min: 0 },
1653
+ refresh: { type: "boolean" },
1654
+ fallbackSearch: { type: "boolean" },
1655
+ fallbackLimit: { type: "number", min: 1 },
1656
+ fallbackMinScore: { type: "number", min: 0 },
1657
+ resolveLimit: { type: "number", min: 1 },
752
1658
  limit: { type: "number", min: 1 },
753
1659
  strict: { type: "boolean" },
754
1660
  strictThreshold: { type: "number", min: 0 },
@@ -764,6 +1670,7 @@ export const TOOL_ARG_SCHEMAS = {
764
1670
  if (!args.query && !args.queries) {
765
1671
  issues.push({ path: "args.query", message: "or args.queries[] is required" });
766
1672
  }
1673
+ validateDocumentFilterSelectors(args, issues);
767
1674
  if (typeof args.strictThreshold === "number" && args.strictThreshold > 1) {
768
1675
  issues.push({ path: "args.strictThreshold", message: "must be <= 1" });
769
1676
  }
@@ -774,6 +1681,25 @@ export const TOOL_ARG_SCHEMAS = {
774
1681
  url: { type: "string" },
775
1682
  urls: { type: "string[]" },
776
1683
  collectionId: { type: "string" },
1684
+ collectionQuery: { type: "string" },
1685
+ collectionRef: { type: "string" },
1686
+ collectionQueries: { type: "string[]" },
1687
+ collectionRefs: { type: "string[]" },
1688
+ userId: { type: "string" },
1689
+ userQuery: { type: "string" },
1690
+ userRef: { type: "string" },
1691
+ userQueries: { type: "string[]" },
1692
+ userRefs: { type: "string[]" },
1693
+ profile: { type: "string" },
1694
+ memory: { type: "boolean" },
1695
+ memoryMinScore: { type: "number", min: 0 },
1696
+ minScore: { type: "number", min: 0 },
1697
+ maxAgeHours: { type: "number", min: 0 },
1698
+ refresh: { type: "boolean" },
1699
+ fallbackSearch: { type: "boolean" },
1700
+ fallbackLimit: { type: "number", min: 1 },
1701
+ fallbackMinScore: { type: "number", min: 0 },
1702
+ resolveLimit: { type: "number", min: 1 },
777
1703
  limit: { type: "number", min: 1 },
778
1704
  strict: { type: "boolean" },
779
1705
  strictHost: { type: "boolean" },
@@ -790,6 +1716,7 @@ export const TOOL_ARG_SCHEMAS = {
790
1716
  if (!args.url && !args.urls) {
791
1717
  issues.push({ path: "args.url", message: "or args.urls[] is required" });
792
1718
  }
1719
+ validateDocumentFilterSelectors(args, issues);
793
1720
  if (typeof args.strictThreshold === "number" && args.strictThreshold > 1) {
794
1721
  issues.push({ path: "args.strictThreshold", message: "must be <= 1" });
795
1722
  }
@@ -829,9 +1756,22 @@ export const TOOL_ARG_SCHEMAS = {
829
1756
  },
830
1757
  },
831
1758
  "collections.tree": {
832
- required: ["collectionId"],
833
1759
  properties: {
834
1760
  collectionId: { type: "string" },
1761
+ id: { type: "string" },
1762
+ query: { type: "string" },
1763
+ urlId: { type: "string" },
1764
+ url: { type: "string" },
1765
+ profile: { type: "string" },
1766
+ resolveLimit: { type: "number", min: 1 },
1767
+ minScore: { type: "number", min: 0 },
1768
+ maxAgeHours: { type: "number", min: 0 },
1769
+ refresh: { type: "boolean" },
1770
+ strict: { type: "boolean" },
1771
+ strictThreshold: { type: "number", min: 0 },
1772
+ fallbackSearch: { type: "boolean" },
1773
+ fallbackMinScore: { type: "number", min: 0 },
1774
+ fallbackLimit: { type: "number", min: 1 },
835
1775
  includeDrafts: { type: "boolean" },
836
1776
  maxDepth: { type: "number", min: 0 },
837
1777
  view: { type: "string", enum: ["summary", "full"] },
@@ -842,6 +1782,15 @@ export const TOOL_ARG_SCHEMAS = {
842
1782
  direction: { type: "string", enum: ["ASC", "DESC"] },
843
1783
  maxAttempts: { type: "number", min: 1 },
844
1784
  },
1785
+ custom(args, issues) {
1786
+ const refs = ["collectionId", "id", "query", "urlId", "url"].filter((key) => args[key]);
1787
+ if (refs.length === 0) {
1788
+ issues.push({ path: "args.collectionId", message: "or args.id, args.query, args.urlId, or args.url is required" });
1789
+ }
1790
+ if (refs.length > 1) {
1791
+ issues.push({ path: "args.collectionId", message: "provide only one of args.collectionId, args.id, args.query, args.urlId, or args.url" });
1792
+ }
1793
+ },
845
1794
  },
846
1795
  "search.expand": {
847
1796
  properties: {
@@ -855,8 +1804,25 @@ export const TOOL_ARG_SCHEMAS = {
855
1804
  concurrency: { type: "number", min: 1 },
856
1805
  hydrateConcurrency: { type: "number", min: 1 },
857
1806
  collectionId: { type: "string" },
1807
+ collectionQuery: { type: "string" },
1808
+ collectionRef: { type: "string" },
1809
+ collectionQueries: { type: "string[]" },
1810
+ collectionRefs: { type: "string[]" },
858
1811
  documentId: { type: "string" },
859
1812
  userId: { type: "string" },
1813
+ userQuery: { type: "string" },
1814
+ userRef: { type: "string" },
1815
+ userQueries: { type: "string[]" },
1816
+ userRefs: { type: "string[]" },
1817
+ profile: { type: "string" },
1818
+ resolveLimit: { type: "number", min: 1 },
1819
+ maxAgeHours: { type: "number", min: 0 },
1820
+ refresh: { type: "boolean" },
1821
+ strict: { type: "boolean" },
1822
+ strictThreshold: { type: "number", min: 0 },
1823
+ fallbackSearch: { type: "boolean" },
1824
+ fallbackMinScore: { type: "number", min: 0 },
1825
+ fallbackLimit: { type: "number", min: 1 },
860
1826
  sort: { type: "string" },
861
1827
  direction: { type: "string", enum: ["ASC", "DESC"] },
862
1828
  snippetMinWords: { type: "number", min: 1 },
@@ -870,6 +1836,7 @@ export const TOOL_ARG_SCHEMAS = {
870
1836
  if (!args.query && !args.queries) {
871
1837
  issues.push({ path: "args.query", message: "or args.queries[] is required" });
872
1838
  }
1839
+ validateDocumentFilterSelectors(args, issues);
873
1840
  },
874
1841
  },
875
1842
  "search.research": {
@@ -878,6 +1845,24 @@ export const TOOL_ARG_SCHEMAS = {
878
1845
  query: { type: "string" },
879
1846
  queries: { type: "string[]" },
880
1847
  collectionId: { type: "string" },
1848
+ collectionQuery: { type: "string" },
1849
+ collectionRef: { type: "string" },
1850
+ collectionQueries: { type: "string[]" },
1851
+ collectionRefs: { type: "string[]" },
1852
+ userId: { type: "string" },
1853
+ userQuery: { type: "string" },
1854
+ userRef: { type: "string" },
1855
+ userQueries: { type: "string[]" },
1856
+ userRefs: { type: "string[]" },
1857
+ profile: { type: "string" },
1858
+ resolveLimit: { type: "number", min: 1 },
1859
+ maxAgeHours: { type: "number", min: 0 },
1860
+ refresh: { type: "boolean" },
1861
+ strict: { type: "boolean" },
1862
+ strictThreshold: { type: "number", min: 0 },
1863
+ fallbackSearch: { type: "boolean" },
1864
+ fallbackMinScore: { type: "number", min: 0 },
1865
+ fallbackLimit: { type: "number", min: 1 },
881
1866
  limitPerQuery: { type: "number", min: 1 },
882
1867
  offset: { type: "number", min: 0 },
883
1868
  includeTitleSearch: { type: "boolean" },
@@ -913,6 +1898,7 @@ export const TOOL_ARG_SCHEMAS = {
913
1898
  if (!args.question && !args.query && !args.queries) {
914
1899
  issues.push({ path: "args.question", message: "or args.query or args.queries[] is required" });
915
1900
  }
1901
+ validateDocumentFilterSelectors(args, issues);
916
1902
  if (args.includeTitleSearch === false && args.includeSemanticSearch === false) {
917
1903
  issues.push({
918
1904
  path: "args.includeTitleSearch",
@@ -928,10 +1914,10 @@ export const TOOL_ARG_SCHEMAS = {
928
1914
  },
929
1915
  },
930
1916
  "documents.safe_update": {
931
- required: ["id", "expectedRevision"],
1917
+ required: ["expectedRevision"],
932
1918
  properties: {
933
- id: { type: "string" },
934
- expectedRevision: { type: "number", min: 0 },
1919
+ ...DOCUMENT_MUTATION_TARGET_RESOLVE_PROPERTIES,
1920
+ expectedRevision: { type: ["number", "string"], min: 0 },
935
1921
  title: { type: "string" },
936
1922
  text: { type: "string" },
937
1923
  icon: { type: "string" },
@@ -948,24 +1934,71 @@ export const TOOL_ARG_SCHEMAS = {
948
1934
  maxAttempts: { type: "number", min: 1 },
949
1935
  performAction: { type: "boolean" },
950
1936
  },
1937
+ custom: validateRequiredDocumentMutationTargetAndExpectedRevision,
951
1938
  },
952
1939
  "documents.diff": {
953
- required: ["id", "proposedText"],
1940
+ required: ["proposedText"],
954
1941
  properties: {
955
1942
  id: { type: "string" },
1943
+ documentId: { type: "string" },
1944
+ refs: { type: "string[]" },
1945
+ query: { type: "string" },
1946
+ queries: { type: "string[]" },
1947
+ shareId: { type: "string" },
1948
+ shareIds: { type: "string[]" },
1949
+ urlId: { type: "string" },
1950
+ urlIds: { type: "string[]" },
1951
+ url: { type: "string" },
1952
+ urls: { type: "string[]" },
1953
+ profile: { type: "string" },
1954
+ resolveLimit: { type: "number", min: 1 },
1955
+ minScore: { type: "number", min: 0 },
1956
+ maxAgeHours: { type: "number", min: 0 },
1957
+ refresh: { type: "boolean" },
1958
+ strict: { type: "boolean" },
1959
+ strictThreshold: { type: "number", min: 0 },
1960
+ fallbackSearch: { type: "boolean" },
1961
+ fallbackMinScore: { type: "number", min: 0 },
1962
+ fallbackLimit: { type: "number", min: 1 },
1963
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
1964
+ resolveCollectionId: { type: "string" },
1965
+ resolveConcurrency: { type: "number", min: 1 },
1966
+ resolveHydrateConcurrency: { type: "number", min: 1 },
956
1967
  proposedText: { type: "string" },
957
1968
  includeFullHunks: { type: "boolean" },
958
1969
  hunkLimit: { type: "number", min: 1 },
959
1970
  hunkLineLimit: { type: "number", min: 1 },
960
1971
  maxAttempts: { type: "number", min: 1 },
961
1972
  },
1973
+ custom(args, issues) {
1974
+ const hasId = typeof args.id === "string" && args.id.trim().length > 0;
1975
+ const hasDocumentId = typeof args.documentId === "string" && args.documentId.trim().length > 0;
1976
+ const hasArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
1977
+ Array.isArray(args[key]) && args[key].length > 0
1978
+ );
1979
+ const hasSingle = ["query", "shareId", "urlId", "url"].some((key) =>
1980
+ typeof args[key] === "string" && args[key].trim().length > 0
1981
+ );
1982
+ if (!hasId && !hasDocumentId && !hasArrays && !hasSingle) {
1983
+ issues.push({ path: "args.id", message: "or document refs are required" });
1984
+ }
1985
+ if (hasId && hasDocumentId) {
1986
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
1987
+ }
1988
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
1989
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
1990
+ }
1991
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
1992
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
1993
+ }
1994
+ },
962
1995
  },
963
1996
  "documents.apply_patch": {
964
- required: ["id", "patch"],
1997
+ required: ["patch"],
965
1998
  properties: {
966
- id: { type: "string" },
1999
+ ...DOCUMENT_MUTATION_TARGET_RESOLVE_PROPERTIES,
967
2000
  patch: { type: "string" },
968
- expectedRevision: { type: "number", min: 0 },
2001
+ expectedRevision: { type: ["number", "string"], min: 0 },
969
2002
  mode: { type: "string", enum: ["unified", "replace"] },
970
2003
  title: { type: "string" },
971
2004
  view: { type: "string", enum: ["summary", "full"] },
@@ -973,13 +2006,17 @@ export const TOOL_ARG_SCHEMAS = {
973
2006
  maxAttempts: { type: "number", min: 1 },
974
2007
  performAction: { type: "boolean" },
975
2008
  },
2009
+ custom(args, issues) {
2010
+ validateRequiredDocumentMutationTargetArgs(args, issues);
2011
+ validateExpectedRevisionGuard(args, issues);
2012
+ },
976
2013
  },
977
2014
  "documents.apply_patch_safe": {
978
- required: ["id", "expectedRevision", "patch"],
2015
+ required: ["expectedRevision", "patch"],
979
2016
  properties: {
980
- id: { type: "string" },
2017
+ ...DOCUMENT_MUTATION_TARGET_RESOLVE_PROPERTIES,
981
2018
  patch: { type: "string" },
982
- expectedRevision: { type: "number", min: 0 },
2019
+ expectedRevision: { type: ["number", "string"], min: 0 },
983
2020
  mode: { type: "string", enum: ["unified", "replace"] },
984
2021
  title: { type: "string" },
985
2022
  view: { type: "string", enum: ["summary", "full"] },
@@ -987,6 +2024,7 @@ export const TOOL_ARG_SCHEMAS = {
987
2024
  maxAttempts: { type: "number", min: 1 },
988
2025
  performAction: { type: "boolean" },
989
2026
  },
2027
+ custom: validateRequiredDocumentMutationTargetAndExpectedRevision,
990
2028
  },
991
2029
  "documents.batch_update": {
992
2030
  required: ["updates"],
@@ -1008,14 +2046,15 @@ export const TOOL_ARG_SCHEMAS = {
1008
2046
  issues.push({ path: `args.updates[${i}]`, message: "must be an object" });
1009
2047
  continue;
1010
2048
  }
1011
- if (!update.id || typeof update.id !== "string") {
1012
- issues.push({ path: `args.updates[${i}].id`, message: "is required and must be a string" });
1013
- }
2049
+ validateBatchUpdateDocumentTarget(update, issues, `args.updates[${i}]`);
1014
2050
  if (
1015
2051
  Object.prototype.hasOwnProperty.call(update, "expectedRevision") &&
1016
- !(typeof update.expectedRevision === "number" && Number.isFinite(update.expectedRevision))
2052
+ !(
2053
+ (typeof update.expectedRevision === "number" && Number.isFinite(update.expectedRevision)) ||
2054
+ (typeof update.expectedRevision === "string" && update.expectedRevision.trim().toLowerCase() === "latest")
2055
+ )
1017
2056
  ) {
1018
- issues.push({ path: `args.updates[${i}].expectedRevision`, message: "must be a number" });
2057
+ issues.push({ path: `args.updates[${i}].expectedRevision`, message: "must be a number or latest" });
1019
2058
  }
1020
2059
  if (
1021
2060
  Object.prototype.hasOwnProperty.call(update, "editMode") &&
@@ -1102,9 +2141,32 @@ export const TOOL_ARG_SCHEMAS = {
1102
2141
  },
1103
2142
  },
1104
2143
  "revisions.list": {
1105
- required: ["documentId"],
1106
2144
  properties: {
2145
+ id: { type: "string" },
1107
2146
  documentId: { type: "string" },
2147
+ refs: { type: "string[]" },
2148
+ query: { type: "string" },
2149
+ queries: { type: "string[]" },
2150
+ shareId: { type: "string" },
2151
+ shareIds: { type: "string[]" },
2152
+ urlId: { type: "string" },
2153
+ urlIds: { type: "string[]" },
2154
+ url: { type: "string" },
2155
+ urls: { type: "string[]" },
2156
+ profile: { type: "string" },
2157
+ resolveLimit: { type: "number", min: 1 },
2158
+ minScore: { type: "number", min: 0 },
2159
+ maxAgeHours: { type: "number", min: 0 },
2160
+ refresh: { type: "boolean" },
2161
+ strict: { type: "boolean" },
2162
+ strictThreshold: { type: "number", min: 0 },
2163
+ fallbackSearch: { type: "boolean" },
2164
+ fallbackMinScore: { type: "number", min: 0 },
2165
+ fallbackLimit: { type: "number", min: 1 },
2166
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
2167
+ resolveCollectionId: { type: "string" },
2168
+ resolveConcurrency: { type: "number", min: 1 },
2169
+ resolveHydrateConcurrency: { type: "number", min: 1 },
1108
2170
  limit: { type: "number", min: 1 },
1109
2171
  offset: { type: "number", min: 0 },
1110
2172
  sort: { type: "string" },
@@ -1112,19 +2174,102 @@ export const TOOL_ARG_SCHEMAS = {
1112
2174
  view: { type: "string", enum: ["summary", "full"] },
1113
2175
  maxAttempts: { type: "number", min: 1 },
1114
2176
  },
2177
+ custom(args, issues) {
2178
+ const hasId = typeof args.id === "string" && args.id.trim().length > 0;
2179
+ const hasDocumentId = typeof args.documentId === "string" && args.documentId.trim().length > 0;
2180
+ const hasArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
2181
+ Array.isArray(args[key]) && args[key].length > 0
2182
+ );
2183
+ const hasSingle = ["query", "shareId", "urlId", "url"].some((key) =>
2184
+ typeof args[key] === "string" && args[key].trim().length > 0
2185
+ );
2186
+ if (!hasId && !hasDocumentId && !hasArrays && !hasSingle) {
2187
+ issues.push({ path: "args.documentId", message: "or document refs are required" });
2188
+ }
2189
+ if (hasId && hasDocumentId) {
2190
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
2191
+ }
2192
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
2193
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
2194
+ }
2195
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
2196
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
2197
+ }
2198
+ },
1115
2199
  },
1116
2200
  "revisions.diff": {
1117
- required: ["id", "baseRevisionId", "targetRevisionId"],
1118
2201
  properties: {
1119
2202
  id: { type: "string" },
2203
+ documentId: { type: "string" },
2204
+ refs: { type: "string[]" },
2205
+ query: { type: "string" },
2206
+ queries: { type: "string[]" },
2207
+ shareId: { type: "string" },
2208
+ shareIds: { type: "string[]" },
2209
+ urlId: { type: "string" },
2210
+ urlIds: { type: "string[]" },
2211
+ url: { type: "string" },
2212
+ urls: { type: "string[]" },
2213
+ profile: { type: "string" },
2214
+ resolveLimit: { type: "number", min: 1 },
2215
+ minScore: { type: "number", min: 0 },
2216
+ maxAgeHours: { type: "number", min: 0 },
2217
+ refresh: { type: "boolean" },
2218
+ strict: { type: "boolean" },
2219
+ strictThreshold: { type: "number", min: 0 },
2220
+ fallbackSearch: { type: "boolean" },
2221
+ fallbackMinScore: { type: "number", min: 0 },
2222
+ fallbackLimit: { type: "number", min: 1 },
2223
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
2224
+ resolveCollectionId: { type: "string" },
2225
+ resolveConcurrency: { type: "number", min: 1 },
2226
+ resolveHydrateConcurrency: { type: "number", min: 1 },
1120
2227
  baseRevisionId: { type: "string" },
1121
2228
  targetRevisionId: { type: "string" },
2229
+ revisionPair: { type: "string", enum: ["latest"] },
2230
+ revisionLimit: { type: "number", min: 2 },
2231
+ sort: { type: "string" },
2232
+ direction: { type: "string", enum: ["ASC", "DESC"] },
1122
2233
  includeFullHunks: { type: "boolean" },
1123
2234
  hunkLimit: { type: "number", min: 1 },
1124
2235
  hunkLineLimit: { type: "number", min: 1 },
1125
2236
  view: { type: "string", enum: ["summary", "full"] },
1126
2237
  maxAttempts: { type: "number", min: 1 },
1127
2238
  },
2239
+ custom(args, issues) {
2240
+ const hasId = typeof args.id === "string" && args.id.trim().length > 0;
2241
+ const hasDocumentId = typeof args.documentId === "string" && args.documentId.trim().length > 0;
2242
+ const hasArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
2243
+ Array.isArray(args[key]) && args[key].length > 0
2244
+ );
2245
+ const hasSingle = ["query", "shareId", "urlId", "url"].some((key) =>
2246
+ typeof args[key] === "string" && args[key].trim().length > 0
2247
+ );
2248
+ const hasBase = typeof args.baseRevisionId === "string" && args.baseRevisionId.trim().length > 0;
2249
+ const hasTarget = typeof args.targetRevisionId === "string" && args.targetRevisionId.trim().length > 0;
2250
+
2251
+ if (!hasId && !hasDocumentId && !hasArrays && !hasSingle) {
2252
+ issues.push({ path: "args.documentId", message: "or document refs are required" });
2253
+ }
2254
+ if (hasId && hasDocumentId) {
2255
+ issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
2256
+ }
2257
+ if (hasBase !== hasTarget) {
2258
+ issues.push({ path: hasBase ? "args.targetRevisionId" : "args.baseRevisionId", message: "must be provided with the other revision id" });
2259
+ }
2260
+ if ((hasBase || hasTarget) && args.revisionPair) {
2261
+ issues.push({ path: "args.revisionPair", message: "cannot be combined with explicit revision IDs" });
2262
+ }
2263
+ if (typeof args.revisionLimit === "number" && args.revisionLimit > 20) {
2264
+ issues.push({ path: "args.revisionLimit", message: "must be <= 20" });
2265
+ }
2266
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
2267
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
2268
+ }
2269
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
2270
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
2271
+ }
2272
+ },
1128
2273
  },
1129
2274
  "revisions.restore": {
1130
2275
  required: ["id", "revisionId"],
@@ -1151,6 +2296,31 @@ export const TOOL_ARG_SCHEMAS = {
1151
2296
  properties: {
1152
2297
  query: { type: "string" },
1153
2298
  documentId: { type: "string" },
2299
+ documentQuery: { type: "string" },
2300
+ documentQueries: { type: "string[]" },
2301
+ refs: { type: "string[]" },
2302
+ shareId: { type: "string" },
2303
+ shareIds: { type: "string[]" },
2304
+ urlId: { type: "string" },
2305
+ urlIds: { type: "string[]" },
2306
+ url: { type: "string" },
2307
+ urls: { type: "string[]" },
2308
+ profile: { type: "string" },
2309
+ resolveLimit: { type: "number", min: 1 },
2310
+ minScore: { type: "number", min: 0 },
2311
+ maxAgeHours: { type: "number", min: 0 },
2312
+ refresh: { type: "boolean" },
2313
+ strict: { type: "boolean" },
2314
+ strictThreshold: { type: "number", min: 0 },
2315
+ fallbackSearch: { type: "boolean" },
2316
+ fallbackMinScore: { type: "number", min: 0 },
2317
+ fallbackLimit: { type: "number", min: 1 },
2318
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
2319
+ resolveCollectionId: { type: "string" },
2320
+ resolveConcurrency: { type: "number", min: 1 },
2321
+ resolveHydrateConcurrency: { type: "number", min: 1 },
2322
+ snippetMinWords: { type: "number", min: 1 },
2323
+ snippetMaxWords: { type: "number", min: 1 },
1154
2324
  limit: { type: "number", min: 1 },
1155
2325
  offset: { type: "number", min: 0 },
1156
2326
  sort: { type: "string" },
@@ -1159,28 +2329,48 @@ export const TOOL_ARG_SCHEMAS = {
1159
2329
  view: { type: "string", enum: ["ids", "summary", "full"] },
1160
2330
  maxAttempts: { type: "number", min: 1 },
1161
2331
  },
2332
+ custom: validateOptionalDocumentResolveArgs,
1162
2333
  },
1163
2334
  "shares.info": {
1164
2335
  properties: {
1165
2336
  id: { type: "string" },
1166
2337
  documentId: { type: "string" },
2338
+ query: { type: "string" },
2339
+ documentQuery: { type: "string" },
2340
+ queries: { type: "string[]" },
2341
+ documentQueries: { type: "string[]" },
2342
+ refs: { type: "string[]" },
2343
+ shareId: { type: "string" },
2344
+ shareIds: { type: "string[]" },
2345
+ urlId: { type: "string" },
2346
+ urlIds: { type: "string[]" },
2347
+ url: { type: "string" },
2348
+ urls: { type: "string[]" },
2349
+ profile: { type: "string" },
2350
+ resolveLimit: { type: "number", min: 1 },
2351
+ minScore: { type: "number", min: 0 },
2352
+ maxAgeHours: { type: "number", min: 0 },
2353
+ refresh: { type: "boolean" },
2354
+ strict: { type: "boolean" },
2355
+ strictThreshold: { type: "number", min: 0 },
2356
+ fallbackSearch: { type: "boolean" },
2357
+ fallbackMinScore: { type: "number", min: 0 },
2358
+ fallbackLimit: { type: "number", min: 1 },
2359
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
2360
+ resolveCollectionId: { type: "string" },
2361
+ resolveConcurrency: { type: "number", min: 1 },
2362
+ resolveHydrateConcurrency: { type: "number", min: 1 },
2363
+ snippetMinWords: { type: "number", min: 1 },
2364
+ snippetMaxWords: { type: "number", min: 1 },
1167
2365
  includePolicies: { type: "boolean" },
1168
2366
  view: { type: "string", enum: ["summary", "full"] },
1169
2367
  maxAttempts: { type: "number", min: 1 },
1170
2368
  },
1171
- custom(args, issues) {
1172
- if (!args.id && !args.documentId) {
1173
- issues.push({ path: "args.id", message: "or args.documentId is required" });
1174
- }
1175
- if (args.id && args.documentId) {
1176
- issues.push({ path: "args.documentId", message: "cannot be combined with args.id" });
1177
- }
1178
- },
2369
+ custom: validateShareInfoSelector,
1179
2370
  },
1180
2371
  "shares.create": {
1181
- required: ["documentId"],
1182
2372
  properties: {
1183
- documentId: { type: "string" },
2373
+ ...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
1184
2374
  includeChildDocuments: { type: "boolean" },
1185
2375
  published: { type: "boolean" },
1186
2376
  includePolicies: { type: "boolean" },
@@ -1188,6 +2378,7 @@ export const TOOL_ARG_SCHEMAS = {
1188
2378
  maxAttempts: { type: "number", min: 1 },
1189
2379
  performAction: { type: "boolean" },
1190
2380
  },
2381
+ custom: validateRequiredDocumentResolveArgs,
1191
2382
  },
1192
2383
  "shares.update": {
1193
2384
  required: ["id", "published"],
@@ -1212,7 +2403,12 @@ export const TOOL_ARG_SCHEMAS = {
1212
2403
  "templates.list": {
1213
2404
  properties: {
1214
2405
  collectionId: { type: "string" },
2406
+ collectionQuery: { type: "string" },
2407
+ collectionRef: { type: "string" },
2408
+ collectionQueries: { type: "string[]" },
2409
+ collectionRefs: { type: "string[]" },
1215
2410
  query: { type: "string" },
2411
+ ...PRINCIPAL_RESOLVE_OPTION_PROPERTIES,
1216
2412
  limit: { type: "number", min: 1 },
1217
2413
  offset: { type: "number", min: 0 },
1218
2414
  sort: { type: "string" },
@@ -1221,32 +2417,33 @@ export const TOOL_ARG_SCHEMAS = {
1221
2417
  view: { type: "string", enum: ["ids", "summary", "full"] },
1222
2418
  maxAttempts: { type: "number", min: 1 },
1223
2419
  },
2420
+ custom: validateOptionalCollectionFilterResolveArgs,
1224
2421
  },
1225
2422
  "templates.info": {
1226
2423
  properties: {
1227
2424
  id: { type: "string" },
1228
2425
  ids: { type: "string[]" },
2426
+ query: { type: "string" },
2427
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1229
2428
  includePolicies: { type: "boolean" },
1230
2429
  concurrency: { type: "number", min: 1 },
1231
2430
  view: { type: "string", enum: ["summary", "full"] },
1232
2431
  maxAttempts: { type: "number", min: 1 },
1233
2432
  },
1234
- custom(args, issues) {
1235
- if (!args.id && !args.ids) {
1236
- issues.push({ path: "args.id", message: "or args.ids[] is required" });
1237
- }
1238
- },
2433
+ custom: validateTemplateTargetSelector,
1239
2434
  },
1240
2435
  "templates.extract_placeholders": {
1241
- required: ["id"],
1242
2436
  properties: {
1243
2437
  id: { type: "string" },
2438
+ query: { type: "string" },
2439
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1244
2440
  maxAttempts: { type: "number", min: 1 },
1245
2441
  },
1246
2442
  custom(args, issues) {
1247
2443
  if (typeof args.id === "string" && args.id.trim().length === 0) {
1248
2444
  issues.push({ path: "args.id", message: "must be a non-empty string" });
1249
2445
  }
2446
+ validateTemplateTargetSelector(args, issues);
1250
2447
  },
1251
2448
  },
1252
2449
  "templates.create": {
@@ -1265,9 +2462,9 @@ export const TOOL_ARG_SCHEMAS = {
1265
2462
  },
1266
2463
  },
1267
2464
  "templates.update": {
1268
- required: ["id"],
1269
2465
  properties: {
1270
2466
  id: { type: "string" },
2467
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1271
2468
  title: { type: "string" },
1272
2469
  data: { type: "object" },
1273
2470
  icon: { type: ["string", "null"] },
@@ -1279,29 +2476,38 @@ export const TOOL_ARG_SCHEMAS = {
1279
2476
  maxAttempts: { type: "number", min: 1 },
1280
2477
  performAction: { type: "boolean" },
1281
2478
  },
2479
+ custom(args, issues) {
2480
+ validateTemplateTargetSelector(args, issues, { includeQuery: false });
2481
+ },
1282
2482
  },
1283
2483
  "templates.delete": {
1284
- required: ["id"],
1285
2484
  properties: {
1286
2485
  id: { type: "string" },
2486
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1287
2487
  maxAttempts: { type: "number", min: 1 },
1288
2488
  performAction: { type: "boolean" },
1289
2489
  },
2490
+ custom(args, issues) {
2491
+ validateTemplateTargetSelector(args, issues, { includeQuery: false });
2492
+ },
1290
2493
  },
1291
2494
  "templates.restore": {
1292
- required: ["id"],
1293
2495
  properties: {
1294
2496
  id: { type: "string" },
2497
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1295
2498
  includePolicies: { type: "boolean" },
1296
2499
  view: { type: "string", enum: ["summary", "full"] },
1297
2500
  maxAttempts: { type: "number", min: 1 },
1298
2501
  performAction: { type: "boolean" },
1299
2502
  },
2503
+ custom(args, issues) {
2504
+ validateTemplateTargetSelector(args, issues, { includeQuery: false });
2505
+ },
1300
2506
  },
1301
2507
  "templates.duplicate": {
1302
- required: ["id"],
1303
2508
  properties: {
1304
2509
  id: { type: "string" },
2510
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1305
2511
  title: { type: "string" },
1306
2512
  collectionId: { type: ["string", "null"] },
1307
2513
  includePolicies: { type: "boolean" },
@@ -1309,6 +2515,9 @@ export const TOOL_ARG_SCHEMAS = {
1309
2515
  maxAttempts: { type: "number", min: 1 },
1310
2516
  performAction: { type: "boolean" },
1311
2517
  },
2518
+ custom(args, issues) {
2519
+ validateTemplateTargetSelector(args, issues, { includeQuery: false });
2520
+ },
1312
2521
  },
1313
2522
  "documents.templatize": {
1314
2523
  required: ["id"],
@@ -1644,9 +2853,10 @@ export const TOOL_ARG_SCHEMAS = {
1644
2853
  },
1645
2854
  },
1646
2855
  "documents.create_from_template": {
1647
- required: ["templateId"],
1648
2856
  properties: {
1649
2857
  templateId: { type: "string" },
2858
+ query: { type: "string" },
2859
+ ...TEMPLATE_RESOLVE_PROPERTIES,
1650
2860
  title: { type: "string" },
1651
2861
  collectionId: { type: "string" },
1652
2862
  parentDocumentId: { type: "string" },
@@ -1662,6 +2872,7 @@ export const TOOL_ARG_SCHEMAS = {
1662
2872
  if (typeof args.templateId === "string" && args.templateId.trim().length === 0) {
1663
2873
  issues.push({ path: "args.templateId", message: "must be a non-empty string" });
1664
2874
  }
2875
+ validateTemplateTargetSelector(args, issues, { idKeys: ["templateId"] });
1665
2876
 
1666
2877
  for (const key of ["title", "collectionId", "parentDocumentId"]) {
1667
2878
  if (typeof args[key] === "string" && args[key].trim().length === 0) {
@@ -1688,6 +2899,33 @@ export const TOOL_ARG_SCHEMAS = {
1688
2899
  "comments.list": {
1689
2900
  properties: {
1690
2901
  documentId: { type: "string" },
2902
+ query: { type: "string" },
2903
+ documentQuery: { type: "string" },
2904
+ queries: { type: "string[]" },
2905
+ documentQueries: { type: "string[]" },
2906
+ refs: { type: "string[]" },
2907
+ shareId: { type: "string" },
2908
+ shareIds: { type: "string[]" },
2909
+ urlId: { type: "string" },
2910
+ urlIds: { type: "string[]" },
2911
+ url: { type: "string" },
2912
+ urls: { type: "string[]" },
2913
+ profile: { type: "string" },
2914
+ resolveLimit: { type: "number", min: 1 },
2915
+ minScore: { type: "number", min: 0 },
2916
+ maxAgeHours: { type: "number", min: 0 },
2917
+ refresh: { type: "boolean" },
2918
+ strict: { type: "boolean" },
2919
+ strictThreshold: { type: "number", min: 0 },
2920
+ fallbackSearch: { type: "boolean" },
2921
+ fallbackMinScore: { type: "number", min: 0 },
2922
+ fallbackLimit: { type: "number", min: 1 },
2923
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
2924
+ resolveCollectionId: { type: "string" },
2925
+ resolveConcurrency: { type: "number", min: 1 },
2926
+ resolveHydrateConcurrency: { type: "number", min: 1 },
2927
+ snippetMinWords: { type: "number", min: 1 },
2928
+ snippetMaxWords: { type: "number", min: 1 },
1691
2929
  collectionId: { type: "string" },
1692
2930
  parentCommentId: { type: "string" },
1693
2931
  includeAnchorText: { type: "boolean" },
@@ -1700,6 +2938,7 @@ export const TOOL_ARG_SCHEMAS = {
1700
2938
  view: { type: "string", enum: ["ids", "summary", "full"] },
1701
2939
  maxAttempts: { type: "number", min: 1 },
1702
2940
  },
2941
+ custom: validateOptionalDocumentResolveArgs,
1703
2942
  },
1704
2943
  "comments.info": {
1705
2944
  required: ["id"],
@@ -1712,9 +2951,8 @@ export const TOOL_ARG_SCHEMAS = {
1712
2951
  },
1713
2952
  },
1714
2953
  "comments.create": {
1715
- required: ["documentId"],
1716
2954
  properties: {
1717
- documentId: { type: "string" },
2955
+ ...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
1718
2956
  text: { type: "string" },
1719
2957
  data: { type: "object" },
1720
2958
  parentCommentId: { type: "string" },
@@ -1724,6 +2962,7 @@ export const TOOL_ARG_SCHEMAS = {
1724
2962
  performAction: { type: "boolean" },
1725
2963
  },
1726
2964
  custom(args, issues) {
2965
+ validateRequiredDocumentResolveArgs(args, issues);
1727
2966
  if (!args.text && !args.data) {
1728
2967
  issues.push({ path: "args.text", message: "or args.data is required" });
1729
2968
  }
@@ -1827,8 +3066,42 @@ export const TOOL_ARG_SCHEMAS = {
1827
3066
  },
1828
3067
  "comments.review_queue": {
1829
3068
  properties: {
3069
+ documentId: { type: "string" },
1830
3070
  documentIds: { type: "string[]" },
3071
+ refs: { type: "string[]" },
3072
+ query: { type: "string" },
3073
+ queries: { type: "string[]" },
3074
+ shareId: { type: "string" },
3075
+ shareIds: { type: "string[]" },
3076
+ urlId: { type: "string" },
3077
+ urlIds: { type: "string[]" },
3078
+ url: { type: "string" },
3079
+ urls: { type: "string[]" },
3080
+ profile: { type: "string" },
3081
+ resolveLimit: { type: "number", min: 1 },
3082
+ minScore: { type: "number", min: 0 },
3083
+ maxAgeHours: { type: "number", min: 0 },
3084
+ refresh: { type: "boolean" },
3085
+ strict: { type: "boolean" },
3086
+ strictThreshold: { type: "number", min: 0 },
3087
+ fallbackSearch: { type: "boolean" },
3088
+ fallbackMinScore: { type: "number", min: 0 },
3089
+ fallbackLimit: { type: "number", min: 1 },
3090
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
3091
+ resolveCollectionId: { type: "string" },
3092
+ resolveConcurrency: { type: "number", min: 1 },
3093
+ resolveHydrateConcurrency: { type: "number", min: 1 },
1831
3094
  collectionId: { type: "string" },
3095
+ collectionQuery: { type: "string" },
3096
+ collectionRefId: { type: "string" },
3097
+ collectionUrlId: { type: "string" },
3098
+ collectionUrl: { type: "string" },
3099
+ collectionResolveLimit: { type: "number", min: 1 },
3100
+ collectionMinScore: { type: "number", min: 0 },
3101
+ collectionMaxAgeHours: { type: "number", min: 0 },
3102
+ collectionStrictThreshold: { type: "number", min: 0 },
3103
+ collectionFallbackMinScore: { type: "number", min: 0 },
3104
+ collectionFallbackLimit: { type: "number", min: 1 },
1832
3105
  includeAnchorText: { type: "boolean" },
1833
3106
  includeReplies: { type: "boolean" },
1834
3107
  limitPerDocument: { type: "number", min: 1 },
@@ -1837,13 +3110,29 @@ export const TOOL_ARG_SCHEMAS = {
1837
3110
  },
1838
3111
  custom(args, issues) {
1839
3112
  const hasDocumentIds = Array.isArray(args.documentIds) && args.documentIds.length > 0;
3113
+ const hasDocumentId = typeof args.documentId === "string" && args.documentId.trim().length > 0;
3114
+ const hasDocumentArrays = ["refs", "queries", "shareIds", "urlIds", "urls"].some((key) =>
3115
+ Array.isArray(args[key]) && args[key].length > 0
3116
+ );
3117
+ const hasDocumentSingle = ["query", "shareId", "urlId", "url"].some((key) =>
3118
+ typeof args[key] === "string" && args[key].trim().length > 0
3119
+ );
1840
3120
  const hasCollectionId = typeof args.collectionId === "string" && args.collectionId.length > 0;
1841
- if (!hasDocumentIds && !hasCollectionId) {
1842
- issues.push({ path: "args.documentIds", message: "or args.collectionId is required" });
3121
+ const hasCollectionRef = ["collectionQuery", "collectionRefId", "collectionUrlId", "collectionUrl"].some((key) =>
3122
+ typeof args[key] === "string" && args[key].trim().length > 0
3123
+ );
3124
+ if (!hasDocumentIds && !hasDocumentId && !hasDocumentArrays && !hasDocumentSingle && !hasCollectionId && !hasCollectionRef) {
3125
+ issues.push({ path: "args.documentIds", message: "or document refs, args.collectionId, or collection refs are required" });
1843
3126
  }
1844
3127
  if (Array.isArray(args.documentIds) && args.documentIds.length === 0) {
1845
3128
  issues.push({ path: "args.documentIds", message: "must be a non-empty string[] when provided" });
1846
3129
  }
3130
+ if (typeof args.resolveConcurrency === "number" && args.resolveConcurrency > 8) {
3131
+ issues.push({ path: "args.resolveConcurrency", message: "must be <= 8" });
3132
+ }
3133
+ if (typeof args.resolveHydrateConcurrency === "number" && args.resolveHydrateConcurrency > 8) {
3134
+ issues.push({ path: "args.resolveHydrateConcurrency", message: "must be <= 8" });
3135
+ }
1847
3136
  },
1848
3137
  },
1849
3138
  "federated.sync_manifest": {
@@ -2013,11 +3302,46 @@ export const TOOL_ARG_SCHEMAS = {
2013
3302
  "events.list": {
2014
3303
  properties: {
2015
3304
  actorId: { type: "string" },
3305
+ userQuery: { type: "string" },
3306
+ userRef: { type: "string" },
3307
+ userQueries: { type: "string[]" },
3308
+ userRefs: { type: "string[]" },
2016
3309
  documentId: { type: "string" },
3310
+ documentQuery: { type: "string" },
3311
+ documentRef: { type: "string" },
3312
+ documentQueries: { type: "string[]" },
3313
+ documentRefs: { type: "string[]" },
3314
+ refs: { type: "string[]" },
3315
+ shareId: { type: "string" },
3316
+ shareIds: { type: "string[]" },
3317
+ urlId: { type: "string" },
3318
+ urlIds: { type: "string[]" },
3319
+ url: { type: "string" },
3320
+ urls: { type: "string[]" },
2017
3321
  collectionId: { type: "string" },
3322
+ collectionQuery: { type: "string" },
3323
+ collectionRef: { type: "string" },
3324
+ collectionQueries: { type: "string[]" },
3325
+ collectionRefs: { type: "string[]" },
2018
3326
  name: { type: "string" },
2019
3327
  auditLog: { type: "boolean" },
2020
3328
  ip: { type: "string" },
3329
+ profile: { type: "string" },
3330
+ resolveLimit: { type: "number", min: 1 },
3331
+ minScore: { type: "number", min: 0 },
3332
+ maxAgeHours: { type: "number", min: 0 },
3333
+ refresh: { type: "boolean" },
3334
+ strict: { type: "boolean" },
3335
+ strictThreshold: { type: "number", min: 0 },
3336
+ fallbackSearch: { type: "boolean" },
3337
+ fallbackMinScore: { type: "number", min: 0 },
3338
+ fallbackLimit: { type: "number", min: 1 },
3339
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
3340
+ resolveCollectionId: { type: "string" },
3341
+ resolveConcurrency: { type: "number", min: 1 },
3342
+ resolveHydrateConcurrency: { type: "number", min: 1 },
3343
+ snippetMinWords: { type: "number", min: 1 },
3344
+ snippetMaxWords: { type: "number", min: 1 },
2021
3345
  limit: { type: "number", min: 1 },
2022
3346
  offset: { type: "number", min: 0 },
2023
3347
  sort: { type: "string" },
@@ -2026,10 +3350,33 @@ export const TOOL_ARG_SCHEMAS = {
2026
3350
  view: { type: "string", enum: ["ids", "summary", "full"] },
2027
3351
  maxAttempts: { type: "number", min: 1 },
2028
3352
  },
3353
+ custom: validateEventsListResolveSelectors,
2029
3354
  },
2030
3355
  "documents.archived": {
2031
3356
  properties: {
2032
3357
  collectionId: { type: "string" },
3358
+ collectionQuery: { type: "string" },
3359
+ collectionRef: { type: "string" },
3360
+ collectionQueries: { type: "string[]" },
3361
+ collectionRefs: { type: "string[]" },
3362
+ refs: { type: "string[]" },
3363
+ urlId: { type: "string" },
3364
+ urlIds: { type: "string[]" },
3365
+ url: { type: "string" },
3366
+ urls: { type: "string[]" },
3367
+ profile: { type: "string" },
3368
+ resolveLimit: { type: "number", min: 1 },
3369
+ minScore: { type: "number", min: 0 },
3370
+ maxAgeHours: { type: "number", min: 0 },
3371
+ refresh: { type: "boolean" },
3372
+ strict: { type: "boolean" },
3373
+ strictThreshold: { type: "number", min: 0 },
3374
+ fallbackSearch: { type: "boolean" },
3375
+ fallbackMinScore: { type: "number", min: 0 },
3376
+ fallbackLimit: { type: "number", min: 1 },
3377
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
3378
+ resolveConcurrency: { type: "number", min: 1 },
3379
+ resolveHydrateConcurrency: { type: "number", min: 1 },
2033
3380
  limit: { type: "number", min: 1 },
2034
3381
  offset: { type: "number", min: 0 },
2035
3382
  sort: { type: "string" },
@@ -2038,9 +3385,33 @@ export const TOOL_ARG_SCHEMAS = {
2038
3385
  view: { type: "string", enum: ["ids", "summary", "full"] },
2039
3386
  maxAttempts: { type: "number", min: 1 },
2040
3387
  },
3388
+ custom: validateOptionalCollectionFilterResolveArgs,
2041
3389
  },
2042
3390
  "documents.deleted": {
2043
3391
  properties: {
3392
+ collectionId: { type: "string" },
3393
+ collectionQuery: { type: "string" },
3394
+ collectionRef: { type: "string" },
3395
+ collectionQueries: { type: "string[]" },
3396
+ collectionRefs: { type: "string[]" },
3397
+ refs: { type: "string[]" },
3398
+ urlId: { type: "string" },
3399
+ urlIds: { type: "string[]" },
3400
+ url: { type: "string" },
3401
+ urls: { type: "string[]" },
3402
+ profile: { type: "string" },
3403
+ resolveLimit: { type: "number", min: 1 },
3404
+ minScore: { type: "number", min: 0 },
3405
+ maxAgeHours: { type: "number", min: 0 },
3406
+ refresh: { type: "boolean" },
3407
+ strict: { type: "boolean" },
3408
+ strictThreshold: { type: "number", min: 0 },
3409
+ fallbackSearch: { type: "boolean" },
3410
+ fallbackMinScore: { type: "number", min: 0 },
3411
+ fallbackLimit: { type: "number", min: 1 },
3412
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
3413
+ resolveConcurrency: { type: "number", min: 1 },
3414
+ resolveHydrateConcurrency: { type: "number", min: 1 },
2044
3415
  limit: { type: "number", min: 1 },
2045
3416
  offset: { type: "number", min: 0 },
2046
3417
  sort: { type: "string" },
@@ -2049,6 +3420,7 @@ export const TOOL_ARG_SCHEMAS = {
2049
3420
  view: { type: "string", enum: ["ids", "summary", "full"] },
2050
3421
  maxAttempts: { type: "number", min: 1 },
2051
3422
  },
3423
+ custom: validateOptionalCollectionFilterResolveArgs,
2052
3424
  },
2053
3425
  "documents.archive": {
2054
3426
  required: ["id"],
@@ -2179,6 +3551,7 @@ export const TOOL_ARG_SCHEMAS = {
2179
3551
  id: { type: "string" },
2180
3552
  ids: { type: "string[]" },
2181
3553
  email: { type: "string" },
3554
+ ...PRINCIPAL_RESOLVE_PROPERTIES,
2182
3555
  includePolicies: { type: "boolean" },
2183
3556
  concurrency: { type: "number", min: 1 },
2184
3557
  view: { type: "string", enum: ["summary", "full"] },
@@ -2187,9 +3560,10 @@ export const TOOL_ARG_SCHEMAS = {
2187
3560
  custom(args, issues) {
2188
3561
  const hasId = typeof args.id === "string" && args.id.length > 0;
2189
3562
  const hasIds = Array.isArray(args.ids) && args.ids.length > 0;
3563
+ const hasResolvedRef = hasPrincipalResolveSelector(args);
2190
3564
 
2191
- if (!hasId && !hasIds && !args.email) {
2192
- issues.push({ path: "args.id", message: "or args.ids[] or args.email is required" });
3565
+ if (!hasId && !hasIds && !args.email && !hasResolvedRef) {
3566
+ issues.push({ path: "args.id", message: "or args.ids[], args.email, args.query, or args.refs is required" });
2193
3567
  }
2194
3568
  if (Array.isArray(args.ids) && args.ids.length === 0) {
2195
3569
  issues.push({ path: "args.ids", message: "must be a non-empty string[] when provided" });
@@ -2197,6 +3571,10 @@ export const TOOL_ARG_SCHEMAS = {
2197
3571
  if (hasId && Array.isArray(args.ids)) {
2198
3572
  issues.push({ path: "args.ids", message: "cannot be combined with args.id" });
2199
3573
  }
3574
+ if (hasResolvedRef && (hasId || hasIds || args.email)) {
3575
+ issues.push({ path: "args.query", message: "cannot be combined with args.id, args.ids, or args.email" });
3576
+ }
3577
+ validatePrincipalResolveConcurrency(args, issues);
2200
3578
  },
2201
3579
  },
2202
3580
  "users.invite": {
@@ -2263,6 +3641,7 @@ export const TOOL_ARG_SCHEMAS = {
2263
3641
  properties: {
2264
3642
  id: { type: "string" },
2265
3643
  ids: { type: "string[]" },
3644
+ ...PRINCIPAL_RESOLVE_PROPERTIES,
2266
3645
  includePolicies: { type: "boolean" },
2267
3646
  concurrency: { type: "number", min: 1 },
2268
3647
  view: { type: "string", enum: ["summary", "full"] },
@@ -2271,9 +3650,10 @@ export const TOOL_ARG_SCHEMAS = {
2271
3650
  custom(args, issues) {
2272
3651
  const hasId = typeof args.id === "string" && args.id.length > 0;
2273
3652
  const hasIds = Array.isArray(args.ids) && args.ids.length > 0;
3653
+ const hasResolvedRef = hasPrincipalResolveSelector(args);
2274
3654
 
2275
- if (!hasId && !hasIds) {
2276
- issues.push({ path: "args.id", message: "or args.ids[] is required" });
3655
+ if (!hasId && !hasIds && !hasResolvedRef) {
3656
+ issues.push({ path: "args.id", message: "or args.ids[], args.query, or args.refs is required" });
2277
3657
  }
2278
3658
  if (Array.isArray(args.ids) && args.ids.length === 0) {
2279
3659
  issues.push({ path: "args.ids", message: "must be a non-empty string[] when provided" });
@@ -2281,12 +3661,16 @@ export const TOOL_ARG_SCHEMAS = {
2281
3661
  if (hasId && Array.isArray(args.ids)) {
2282
3662
  issues.push({ path: "args.ids", message: "cannot be combined with args.id" });
2283
3663
  }
3664
+ if (hasResolvedRef && (hasId || hasIds)) {
3665
+ issues.push({ path: "args.query", message: "cannot be combined with args.id or args.ids" });
3666
+ }
3667
+ validatePrincipalResolveConcurrency(args, issues);
2284
3668
  },
2285
3669
  },
2286
3670
  "groups.memberships": {
2287
- required: ["id"],
2288
3671
  properties: {
2289
3672
  id: { type: "string" },
3673
+ ...PRINCIPAL_RESOLVE_PROPERTIES,
2290
3674
  limit: { type: "number", min: 1 },
2291
3675
  offset: { type: "number", min: 0 },
2292
3676
  sort: { type: "string" },
@@ -2295,6 +3679,17 @@ export const TOOL_ARG_SCHEMAS = {
2295
3679
  view: { type: "string", enum: ["ids", "summary", "full"] },
2296
3680
  maxAttempts: { type: "number", min: 1 },
2297
3681
  },
3682
+ custom(args, issues) {
3683
+ const hasId = hasNonEmptyString(args.id);
3684
+ const hasResolvedRef = hasPrincipalResolveSelector(args);
3685
+ if (!hasId && !hasResolvedRef) {
3686
+ issues.push({ path: "args.id", message: "or args.query or args.refs is required" });
3687
+ }
3688
+ if (hasId && hasResolvedRef) {
3689
+ issues.push({ path: "args.query", message: "cannot be combined with args.id" });
3690
+ }
3691
+ validatePrincipalResolveConcurrency(args, issues);
3692
+ },
2298
3693
  },
2299
3694
  "groups.create": {
2300
3695
  required: ["name"],
@@ -2332,27 +3727,32 @@ export const TOOL_ARG_SCHEMAS = {
2332
3727
  },
2333
3728
  },
2334
3729
  "groups.add_user": {
2335
- required: ["id", "userId"],
2336
3730
  properties: {
2337
3731
  id: { type: "string" },
3732
+ groupId: { type: "string" },
2338
3733
  userId: { type: "string" },
3734
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
3735
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
2339
3736
  maxAttempts: { type: "number", min: 1 },
2340
3737
  performAction: { type: "boolean" },
2341
3738
  },
3739
+ custom: validateGroupUserMutationSelector,
2342
3740
  },
2343
3741
  "groups.remove_user": {
2344
- required: ["id", "userId"],
2345
3742
  properties: {
2346
3743
  id: { type: "string" },
3744
+ groupId: { type: "string" },
2347
3745
  userId: { type: "string" },
3746
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
3747
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
2348
3748
  maxAttempts: { type: "number", min: 1 },
2349
3749
  performAction: { type: "boolean" },
2350
3750
  },
3751
+ custom: validateGroupUserMutationSelector,
2351
3752
  },
2352
3753
  "collections.memberships": {
2353
- required: ["id"],
2354
3754
  properties: {
2355
- id: { type: "string" },
3755
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2356
3756
  limit: { type: "number", min: 1 },
2357
3757
  offset: { type: "number", min: 0 },
2358
3758
  sort: { type: "string" },
@@ -2361,11 +3761,11 @@ export const TOOL_ARG_SCHEMAS = {
2361
3761
  view: { type: "string", enum: ["ids", "summary", "full"] },
2362
3762
  maxAttempts: { type: "number", min: 1 },
2363
3763
  },
3764
+ custom: validateCollectionAccessSelector,
2364
3765
  },
2365
3766
  "collections.group_memberships": {
2366
- required: ["id"],
2367
3767
  properties: {
2368
- id: { type: "string" },
3768
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2369
3769
  limit: { type: "number", min: 1 },
2370
3770
  offset: { type: "number", min: 0 },
2371
3771
  sort: { type: "string" },
@@ -2374,47 +3774,53 @@ export const TOOL_ARG_SCHEMAS = {
2374
3774
  view: { type: "string", enum: ["ids", "summary", "full"] },
2375
3775
  maxAttempts: { type: "number", min: 1 },
2376
3776
  },
3777
+ custom: validateCollectionAccessSelector,
2377
3778
  },
2378
3779
  "collections.add_user": {
2379
- required: ["id", "userId"],
2380
3780
  properties: {
2381
- id: { type: "string" },
3781
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2382
3782
  userId: { type: "string" },
3783
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
3784
+ permission: { type: "string" },
2383
3785
  maxAttempts: { type: "number", min: 1 },
2384
3786
  performAction: { type: "boolean" },
2385
3787
  },
3788
+ custom: validateCollectionUserMutationSelector,
2386
3789
  },
2387
3790
  "collections.remove_user": {
2388
- required: ["id", "userId"],
2389
3791
  properties: {
2390
- id: { type: "string" },
3792
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2391
3793
  userId: { type: "string" },
3794
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
2392
3795
  maxAttempts: { type: "number", min: 1 },
2393
3796
  performAction: { type: "boolean" },
2394
3797
  },
3798
+ custom: validateCollectionUserMutationSelector,
2395
3799
  },
2396
3800
  "collections.add_group": {
2397
- required: ["id", "groupId"],
2398
3801
  properties: {
2399
- id: { type: "string" },
3802
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2400
3803
  groupId: { type: "string" },
3804
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
3805
+ permission: { type: "string" },
2401
3806
  maxAttempts: { type: "number", min: 1 },
2402
3807
  performAction: { type: "boolean" },
2403
3808
  },
3809
+ custom: validateCollectionGroupMutationSelector,
2404
3810
  },
2405
3811
  "collections.remove_group": {
2406
- required: ["id", "groupId"],
2407
3812
  properties: {
2408
- id: { type: "string" },
3813
+ ...COLLECTION_ACCESS_RESOLVE_PROPERTIES,
2409
3814
  groupId: { type: "string" },
3815
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
2410
3816
  maxAttempts: { type: "number", min: 1 },
2411
3817
  performAction: { type: "boolean" },
2412
3818
  },
3819
+ custom: validateCollectionGroupMutationSelector,
2413
3820
  },
2414
3821
  "documents.memberships": {
2415
- required: ["id"],
2416
3822
  properties: {
2417
- id: { type: "string" },
3823
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2418
3824
  limit: { type: "number", min: 1 },
2419
3825
  offset: { type: "number", min: 0 },
2420
3826
  sort: { type: "string" },
@@ -2423,11 +3829,11 @@ export const TOOL_ARG_SCHEMAS = {
2423
3829
  view: { type: "string", enum: ["ids", "summary", "full"] },
2424
3830
  maxAttempts: { type: "number", min: 1 },
2425
3831
  },
3832
+ custom: validateDocumentAccessSelector,
2426
3833
  },
2427
3834
  "documents.users": {
2428
- required: ["id"],
2429
3835
  properties: {
2430
- id: { type: "string" },
3836
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2431
3837
  limit: { type: "number", min: 1 },
2432
3838
  offset: { type: "number", min: 0 },
2433
3839
  sort: { type: "string" },
@@ -2436,11 +3842,11 @@ export const TOOL_ARG_SCHEMAS = {
2436
3842
  view: { type: "string", enum: ["ids", "summary", "full"] },
2437
3843
  maxAttempts: { type: "number", min: 1 },
2438
3844
  },
3845
+ custom: validateDocumentAccessSelector,
2439
3846
  },
2440
3847
  "documents.group_memberships": {
2441
- required: ["id"],
2442
3848
  properties: {
2443
- id: { type: "string" },
3849
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2444
3850
  limit: { type: "number", min: 1 },
2445
3851
  offset: { type: "number", min: 0 },
2446
3852
  sort: { type: "string" },
@@ -2449,56 +3855,102 @@ export const TOOL_ARG_SCHEMAS = {
2449
3855
  view: { type: "string", enum: ["ids", "summary", "full"] },
2450
3856
  maxAttempts: { type: "number", min: 1 },
2451
3857
  },
3858
+ custom: validateDocumentAccessSelector,
2452
3859
  },
2453
3860
  "documents.add_user": {
2454
- required: ["id", "userId"],
2455
3861
  properties: {
2456
- id: { type: "string" },
3862
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2457
3863
  userId: { type: "string" },
3864
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
3865
+ permission: { type: "string" },
2458
3866
  maxAttempts: { type: "number", min: 1 },
2459
3867
  performAction: { type: "boolean" },
2460
3868
  },
3869
+ custom: validateDocumentUserMutationSelector,
2461
3870
  },
2462
3871
  "documents.remove_user": {
2463
- required: ["id", "userId"],
2464
3872
  properties: {
2465
- id: { type: "string" },
3873
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2466
3874
  userId: { type: "string" },
3875
+ ...USER_PRINCIPAL_RESOLVE_PROPERTIES,
2467
3876
  maxAttempts: { type: "number", min: 1 },
2468
3877
  performAction: { type: "boolean" },
2469
3878
  },
3879
+ custom: validateDocumentUserMutationSelector,
2470
3880
  },
2471
3881
  "documents.add_group": {
2472
- required: ["id", "groupId"],
2473
3882
  properties: {
2474
- id: { type: "string" },
3883
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2475
3884
  groupId: { type: "string" },
3885
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
3886
+ permission: { type: "string" },
2476
3887
  maxAttempts: { type: "number", min: 1 },
2477
3888
  performAction: { type: "boolean" },
2478
3889
  },
3890
+ custom: validateDocumentGroupMutationSelector,
2479
3891
  },
2480
3892
  "documents.remove_group": {
2481
- required: ["id", "groupId"],
2482
3893
  properties: {
2483
- id: { type: "string" },
3894
+ ...DOCUMENT_ACCESS_RESOLVE_PROPERTIES,
2484
3895
  groupId: { type: "string" },
3896
+ ...GROUP_PRINCIPAL_RESOLVE_PROPERTIES,
2485
3897
  maxAttempts: { type: "number", min: 1 },
2486
3898
  performAction: { type: "boolean" },
2487
3899
  },
3900
+ custom: validateDocumentGroupMutationSelector,
2488
3901
  },
2489
3902
  "documents.answer": {
2490
3903
  properties: {
2491
3904
  question: { type: "string" },
2492
3905
  query: { type: "string" },
2493
- collectionId: { type: "string" },
3906
+ id: { type: "string" },
2494
3907
  documentId: { type: "string" },
3908
+ documentQuery: { type: "string" },
3909
+ documentRef: { type: "string" },
3910
+ documentQueries: { type: "string[]" },
3911
+ documentRefs: { type: "string[]" },
3912
+ refs: { type: "string[]" },
3913
+ shareId: { type: "string" },
3914
+ shareIds: { type: "string[]" },
3915
+ urlId: { type: "string" },
3916
+ urlIds: { type: "string[]" },
3917
+ url: { type: "string" },
3918
+ urls: { type: "string[]" },
3919
+ collectionId: { type: "string" },
3920
+ collectionQuery: { type: "string" },
3921
+ collectionRef: { type: "string" },
3922
+ collectionQueries: { type: "string[]" },
3923
+ collectionRefs: { type: "string[]" },
2495
3924
  userId: { type: "string" },
3925
+ userQuery: { type: "string" },
3926
+ userRef: { type: "string" },
3927
+ userQueries: { type: "string[]" },
3928
+ userRefs: { type: "string[]" },
3929
+ profile: { type: "string" },
3930
+ resolveLimit: { type: "number", min: 1 },
3931
+ minScore: { type: "number", min: 0 },
3932
+ maxAgeHours: { type: "number", min: 0 },
3933
+ refresh: { type: "boolean" },
3934
+ strict: { type: "boolean" },
3935
+ strictThreshold: { type: "number", min: 0 },
3936
+ fallbackSearch: { type: "boolean" },
3937
+ fallbackMinScore: { type: "number", min: 0 },
3938
+ fallbackLimit: { type: "number", min: 1 },
3939
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
3940
+ resolveCollectionId: { type: "string" },
3941
+ resolveConcurrency: { type: "number", min: 1 },
3942
+ resolveHydrateConcurrency: { type: "number", min: 1 },
3943
+ hydrateConcurrency: { type: "number", min: 1 },
2496
3944
  statusFilter: { type: ["string", "string[]"] },
2497
3945
  dateFilter: { type: "string", enum: ["day", "week", "month", "year"] },
2498
3946
  includePolicies: { type: "boolean" },
2499
3947
  includeEvidenceDocs: { type: "boolean" },
2500
3948
  limit: { type: "number", min: 1 },
2501
3949
  view: { type: "string", enum: ["summary", "full"] },
3950
+ contextChars: { type: "number", min: 1 },
3951
+ excerptChars: { type: "number", min: 1 },
3952
+ snippetMinWords: { type: "number", min: 1 },
3953
+ snippetMaxWords: { type: "number", min: 1 },
2502
3954
  maxAttempts: { type: "number", min: 1 },
2503
3955
  },
2504
3956
  custom(args, issues) {
@@ -2506,6 +3958,7 @@ export const TOOL_ARG_SCHEMAS = {
2506
3958
  if (typeof selected !== "string" || selected.trim().length === 0) {
2507
3959
  issues.push({ path: "args.question", message: "or args.query is required and must be non-empty" });
2508
3960
  }
3961
+ validateAnswerScopeSelectors(args, issues);
2509
3962
  },
2510
3963
  },
2511
3964
  "documents.answer_batch": {
@@ -2513,15 +3966,54 @@ export const TOOL_ARG_SCHEMAS = {
2513
3966
  question: { type: "string" },
2514
3967
  query: { type: "string" },
2515
3968
  questions: { type: "array" },
2516
- collectionId: { type: "string" },
3969
+ id: { type: "string" },
2517
3970
  documentId: { type: "string" },
3971
+ documentQuery: { type: "string" },
3972
+ documentRef: { type: "string" },
3973
+ documentQueries: { type: "string[]" },
3974
+ documentRefs: { type: "string[]" },
3975
+ refs: { type: "string[]" },
3976
+ shareId: { type: "string" },
3977
+ shareIds: { type: "string[]" },
3978
+ urlId: { type: "string" },
3979
+ urlIds: { type: "string[]" },
3980
+ url: { type: "string" },
3981
+ urls: { type: "string[]" },
3982
+ collectionId: { type: "string" },
3983
+ collectionQuery: { type: "string" },
3984
+ collectionRef: { type: "string" },
3985
+ collectionQueries: { type: "string[]" },
3986
+ collectionRefs: { type: "string[]" },
2518
3987
  userId: { type: "string" },
3988
+ userQuery: { type: "string" },
3989
+ userRef: { type: "string" },
3990
+ userQueries: { type: "string[]" },
3991
+ userRefs: { type: "string[]" },
3992
+ profile: { type: "string" },
3993
+ resolveLimit: { type: "number", min: 1 },
3994
+ minScore: { type: "number", min: 0 },
3995
+ maxAgeHours: { type: "number", min: 0 },
3996
+ refresh: { type: "boolean" },
3997
+ strict: { type: "boolean" },
3998
+ strictThreshold: { type: "number", min: 0 },
3999
+ fallbackSearch: { type: "boolean" },
4000
+ fallbackMinScore: { type: "number", min: 0 },
4001
+ fallbackLimit: { type: "number", min: 1 },
4002
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
4003
+ resolveCollectionId: { type: "string" },
4004
+ resolveConcurrency: { type: "number", min: 1 },
4005
+ resolveHydrateConcurrency: { type: "number", min: 1 },
4006
+ hydrateConcurrency: { type: "number", min: 1 },
2519
4007
  statusFilter: { type: ["string", "string[]"] },
2520
4008
  dateFilter: { type: "string", enum: ["day", "week", "month", "year"] },
2521
4009
  includePolicies: { type: "boolean" },
2522
4010
  includeEvidenceDocs: { type: "boolean" },
2523
4011
  limit: { type: "number", min: 1 },
2524
4012
  view: { type: "string", enum: ["summary", "full"] },
4013
+ contextChars: { type: "number", min: 1 },
4014
+ excerptChars: { type: "number", min: 1 },
4015
+ snippetMinWords: { type: "number", min: 1 },
4016
+ snippetMaxWords: { type: "number", min: 1 },
2525
4017
  concurrency: { type: "number", min: 1 },
2526
4018
  maxAttempts: { type: "number", min: 1 },
2527
4019
  },
@@ -2538,6 +4030,8 @@ export const TOOL_ARG_SCHEMAS = {
2538
4030
  issues.push({ path: "args.questions", message: "or args.question or args.query is required" });
2539
4031
  }
2540
4032
 
4033
+ validateAnswerScopeSelectors(args, issues);
4034
+
2541
4035
  if (args.questions === undefined) {
2542
4036
  return;
2543
4037
  }
@@ -2573,6 +4067,123 @@ export const TOOL_ARG_SCHEMAS = {
2573
4067
  includeRaw: { type: "boolean" },
2574
4068
  },
2575
4069
  },
4070
+ "memory.lookup": {
4071
+ properties: {
4072
+ query: { type: "string" },
4073
+ id: { type: "string" },
4074
+ urlId: { type: "string" },
4075
+ url: { type: "string" },
4076
+ type: { type: "string", enum: MEMORY_ENTITY_TYPES },
4077
+ profile: { type: "string" },
4078
+ limit: { type: "number", min: 1 },
4079
+ minScore: { type: "number", min: 0 },
4080
+ maxAgeHours: { type: "number", min: 0 },
4081
+ },
4082
+ custom(args, issues) {
4083
+ if (!args.query && !args.id && !args.urlId && !args.url) {
4084
+ issues.push({ path: "args.query", message: "or args.id, args.urlId, or args.url is required" });
4085
+ }
4086
+ },
4087
+ },
4088
+ "memory.resolve": {
4089
+ properties: {
4090
+ query: { type: "string" },
4091
+ id: { type: "string" },
4092
+ urlId: { type: "string" },
4093
+ url: { type: "string" },
4094
+ type: { type: "string", enum: MEMORY_ENTITY_TYPES },
4095
+ profile: { type: "string" },
4096
+ limit: { type: "number", min: 1 },
4097
+ minScore: { type: "number", min: 0 },
4098
+ maxAgeHours: { type: "number", min: 0 },
4099
+ refresh: { type: "boolean" },
4100
+ hydrateLimit: { type: "number", min: 1 },
4101
+ fallbackSearch: { type: "boolean" },
4102
+ fallbackMinScore: { type: "number", min: 0 },
4103
+ fallbackLimit: { type: "number", min: 1 },
4104
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
4105
+ collectionId: { type: "string" },
4106
+ snippetMinWords: { type: "number", min: 1 },
4107
+ snippetMaxWords: { type: "number", min: 1 },
4108
+ view: { type: "string", enum: ["ids", "summary", "full"] },
4109
+ maxAttempts: { type: "number", min: 1 },
4110
+ },
4111
+ custom(args, issues) {
4112
+ if (!args.query && !args.id && !args.urlId && !args.url) {
4113
+ issues.push({ path: "args.query", message: "or args.id, args.urlId, or args.url is required" });
4114
+ }
4115
+ },
4116
+ },
4117
+ "memory.resolve_batch": {
4118
+ properties: {
4119
+ queries: { type: "string[]" },
4120
+ ids: { type: "string[]" },
4121
+ urlIds: { type: "string[]" },
4122
+ urls: { type: "string[]" },
4123
+ type: { type: "string", enum: MEMORY_ENTITY_TYPES },
4124
+ profile: { type: "string" },
4125
+ limit: { type: "number", min: 1 },
4126
+ minScore: { type: "number", min: 0 },
4127
+ maxAgeHours: { type: "number", min: 0 },
4128
+ refresh: { type: "boolean" },
4129
+ hydrateLimit: { type: "number", min: 1 },
4130
+ fallbackSearch: { type: "boolean" },
4131
+ fallbackMinScore: { type: "number", min: 0 },
4132
+ fallbackLimit: { type: "number", min: 1 },
4133
+ fallbackMode: { type: "string", enum: ["titles", "semantic", "both"] },
4134
+ collectionId: { type: "string" },
4135
+ snippetMinWords: { type: "number", min: 1 },
4136
+ snippetMaxWords: { type: "number", min: 1 },
4137
+ view: { type: "string", enum: ["ids", "summary", "full"] },
4138
+ concurrency: { type: "number", min: 1 },
4139
+ hydrateConcurrency: { type: "number", min: 1 },
4140
+ maxAttempts: { type: "number", min: 1 },
4141
+ },
4142
+ custom(args, issues) {
4143
+ const hasRef = ["queries", "ids", "urlIds", "urls"].some((key) =>
4144
+ Array.isArray(args[key]) && args[key].length > 0
4145
+ );
4146
+ if (!hasRef) {
4147
+ issues.push({ path: "args.queries", message: "or args.ids, args.urlIds, or args.urls must include at least one value" });
4148
+ }
4149
+ },
4150
+ },
4151
+ "memory.recent": {
4152
+ properties: {
4153
+ type: { type: "string", enum: MEMORY_ENTITY_TYPES },
4154
+ profile: { type: "string" },
4155
+ limit: { type: "number", min: 1 },
4156
+ maxAgeHours: { type: "number", min: 0 },
4157
+ includeDeleted: { type: "boolean" },
4158
+ },
4159
+ },
4160
+ "memory.remember": {
4161
+ required: ["type", "id"],
4162
+ properties: {
4163
+ type: { type: "string", enum: MEMORY_ENTITY_TYPES },
4164
+ id: { type: "string" },
4165
+ title: { type: "string" },
4166
+ name: { type: "string" },
4167
+ email: { type: "string" },
4168
+ urlId: { type: "string" },
4169
+ url: { type: "string" },
4170
+ aliases: { type: "string[]" },
4171
+ query: { type: "string" },
4172
+ queries: { type: "string[]" },
4173
+ profile: { type: "string" },
4174
+ performAction: { type: "boolean" },
4175
+ },
4176
+ },
4177
+ "memory.stats": {
4178
+ properties: {},
4179
+ },
4180
+ "memory.clear": {
4181
+ properties: {
4182
+ profile: { type: "string" },
4183
+ allProfiles: { type: "boolean" },
4184
+ performAction: { type: "boolean" },
4185
+ },
4186
+ },
2576
4187
  "documents.cleanup_test": {
2577
4188
  properties: {
2578
4189
  markerPrefix: { type: "string" },