aaronrene / knowtation public
search-vault.mjs
87 lines 2.9 KB
Raw
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ breaking 2 days ago
1 /**
2 * Skill: search-vault
3 *
4 * Project-scoped semantic search over the Knowtation vault.
5 * Used by research, blog-seo, and clip-factory agents to find supporting evidence
6 * (claims, quotes, prior content) without leaking across projects.
7 *
8 * Hard rules:
9 * - `project` is REQUIRED (no global search; agents see one project at a time).
10 * - default mode is 'semantic' (meaning), not 'keyword'.
11 * - default limit is 8, max 25.
12 * - default fields shape is 'path+snippet' (cheap; agents pull full body via read-* skills).
13 *
14 * @param {ReturnType<import('./hub-client.mjs').createHubClient>} hub
15 * @param {{
16 * project: 'born-free' | 'store-free' | 'knowtation',
17 * query: string,
18 * limit?: number,
19 * mode?: 'semantic' | 'keyword',
20 * fields?: 'path' | 'path+snippet' | 'full',
21 * tag?: string,
22 * since?: string,
23 * until?: string,
24 * }} args
25 * @returns {Promise<{ results: Array<{ path: string, snippet?: string }>, query: string, count: number, project: string }>}
26 */
27 import { assertProject } from './hub-client.mjs';
28
29 const DEFAULT_LIMIT = 8;
30 const MAX_LIMIT = 25;
31
32 export async function searchVault(hub, args) {
33 const project = assertProject(args.project);
34 const query = sanitizeQuery(args.query);
35 const limit = clampLimit(args.limit);
36 const mode = args.mode === 'keyword' ? 'keyword' : 'semantic';
37 const fields = ['path', 'path+snippet', 'full'].includes(args.fields) ? args.fields : 'path+snippet';
38
39 /** @type {Record<string, unknown>} */
40 const body = {
41 query,
42 project,
43 mode,
44 fields,
45 limit,
46 snippet_chars: 300,
47 };
48 if (args.tag != null && String(args.tag).trim() !== '') body.tag = String(args.tag).trim();
49 if (args.since != null && String(args.since).trim() !== '') body.since = String(args.since).trim();
50 if (args.until != null && String(args.until).trim() !== '') body.until = String(args.until).trim();
51
52 const data = await hub.search(body);
53 const rows = Array.isArray(data?.results) ? data.results : [];
54
55 return {
56 project,
57 query,
58 count: rows.length,
59 results: rows.map((r) => ({
60 path: String(r.path ?? ''),
61 ...(r.snippet != null ? { snippet: String(r.snippet) } : {}),
62 ...(r.title != null ? { title: String(r.title) } : {}),
63 ...(r.score != null ? { score: Number(r.score) } : {}),
64 })),
65 };
66 }
67
68 function sanitizeQuery(query) {
69 if (typeof query !== 'string' || !query.trim()) {
70 throw Object.assign(new Error('invalid_query: query must be a non-empty string'), {
71 code: 'INVALID_QUERY',
72 });
73 }
74 if (query.length > 4000) {
75 throw Object.assign(new Error('invalid_query: query exceeds 4000 chars'), {
76 code: 'INVALID_QUERY',
77 });
78 }
79 return query.trim();
80 }
81
82 function clampLimit(limit) {
83 if (limit == null) return DEFAULT_LIMIT;
84 const n = Number(limit);
85 if (!Number.isFinite(n) || n < 1) return DEFAULT_LIMIT;
86 return Math.min(Math.floor(n), MAX_LIMIT);
87 }
File History 2 commits
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ 2 days ago
sha256:9103f98c89257ed2b01c237cea895dabb3e85ea337dccb1161c175e4422355b6 docs: accept Calendar Events v0 spec with Phase 0 security … Human 3 days ago