@vpxa/aikit 0.1.1

package/packages/server/dist/tools/reindex.tool.js

@@ -0,0 +1,3 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{createTaskRunner as t}from"../task-manager.js";import{z as n}from"zod";import{createLogger as r,serializeError as i}from"../../../core/dist/index.js";const a=r(`tools`);function o(r,o,s,c,l,u){let d=e(`reindex`);r.registerTool(`reindex`,{title:d.title,description:`Trigger re-indexing of the knowledge base. Can do incremental (only changed files) or full re-index.`,inputSchema:{full:n.boolean().default(!1).describe(`If true, force full re-index ignoring file hashes`)},annotations:d.annotations},async({full:e},n)=>{try{if(o.isIndexing)return{content:[{type:`text`,text:`## Reindex Already in Progress
+
+A reindex operation is currently running. Search and other tools continue to work with existing data. Use \`status({})\` to check when it completes.`}]};let r=t(n).createTask(`Reindex`,1);r.progress(0,`Starting ${e?`full`:`incremental`} reindex`),a.info(`Starting background re-index`,{mode:e?`full`:`incremental`});let d=e=>t=>{t.phase===`chunking`&&t.currentFile&&a.debug(`Re-index progress`,{prefix:e,current:t.filesProcessed+1,total:t.filesTotal,file:t.currentFile})};return(e?o.reindexAll(s,d(`Reindex`)):o.index(s,d(`Index`))).then(async e=>{if(a.info(`Background re-index complete`,{filesProcessed:e.filesProcessed,chunksCreated:e.chunksCreated,durationMs:e.durationMs}),r.complete(`Reindex complete: ${e.filesProcessed} files, ${e.chunksCreated} chunks in ${e.durationMs}ms`),l)try{await l.createFtsIndex(),a.info(`FTS index rebuilt after reindex`)}catch(e){a.warn(`FTS index rebuild failed`,i(e))}try{let e=await c.reindexAll();a.info(`Curated re-index complete`,{indexed:e.indexed})}catch(e){a.warn(`Curated re-index failed`,i(e))}if(u)try{await u.notifyAfterReindex()}catch(e){a.warn(`Post-reindex resource notification failed`,i(e))}}).catch(e=>{r.fail(`Reindex failed: ${e instanceof Error?e.message:String(e)}`),a.error(`Background reindex failed`,i(e))}),{content:[{type:`text`,text:`## Reindex Started (Background)\n\n- **Mode**: ${e?`Full`:`Incremental`}\n- Search and other tools continue to work with existing data during reindex.\n- Completion will be logged. Use \`status({})\` to check index stats afterward.\n\n---\n_Next: Continue working — the reindex runs in the background._`}]}}catch(e){return a.error(`Reindex failed`,i(e)),{content:[{type:`text`,text:`Reindex failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{o as registerReindexTool};

package/packages/server/dist/tools/remember.tool.d.ts

@@ -0,0 +1,9 @@
+import { CuratedKnowledgeManager } from "../curated-manager.js";
+import { ResourceNotifier } from "../resources/resource-notifier.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { EvolutionCollector, PolicyStore } from "../../../enterprise-bridge/dist/index.js";
+
+//#region packages/server/src/tools/remember.tool.d.ts
+declare function registerRememberTool(server: McpServer, curated: CuratedKnowledgeManager, policyStore?: PolicyStore, evolutionCollector?: EvolutionCollector, resourceNotifier?: ResourceNotifier): void;
+//#endregion
+export { registerRememberTool };

package/packages/server/dist/tools/remember.tool.js

@@ -0,0 +1,4 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{curatedResourceLink as t}from"../resource-links.js";import{z as n}from"zod";import{createLogger as r,serializeError as i}from"../../../core/dist/index.js";const a=r(`tools`);function o(r,o,s,c,l){let u=e(`remember`);r.registerTool(`remember`,{title:u.title,description:`Store a new piece of curated knowledge. Use this to persist decisions, patterns, conventions, or any insight worth remembering across sessions.`,inputSchema:{title:n.string().min(3).max(120).describe(`Short descriptive title for the knowledge entry`),content:n.string().min(10).max(1e5).describe(`The markdown content to store`),category:n.string().regex(/^[a-z][a-z0-9-]*$/).describe(`Category slug (e.g., "decisions", "patterns", "conventions", "api-contracts")`),tags:n.array(n.string()).default([]).describe(`Optional tags for filtering`)},annotations:u.annotations},async({title:e,content:n,category:r,tags:u})=>{try{let i=await o.remember(e,n,r,u),a=``;if(s){let t=s.classify(e,n,u);c&&c.recordClassification(e,t.matchingRules.map(e=>e.ruleId),t.pushRecommended),t.matchingRules.length>0&&(a=`\n\n### Classification Signals\n${t.matchingRules.map(e=>`  - **${e.ruleId}** (${e.category}, weight: ${e.pushWeight}) — matched: ${e.matchedPatterns.join(`, `)}`).join(`
+`)}\n- **Push recommended**: ${t.pushRecommended?`yes`:`no`} (max weight: ${t.maxPushWeight})`,t.pushRecommended&&(a+=`
+
+> 💡 This entry matches push rules. Consider \`er_push\` to share with Enterprise RAG.`))}l&&l.notifyAfterCuratedWrite(i.path).catch(()=>{});let d=t(i.path,e,`[${r}]`);return{content:[{type:`text`,text:`Remembered: **${e}**\n\nStored at \`.ai/curated/${i.path}\` and indexed for semantic search.${a}\n\n---\n_Next: Use \`search\` to verify the entry is findable, or \`list\` to see all curated entries._`},...d?[d]:[]]}}catch(e){return a.error(`Remember failed`,i(e)),{content:[{type:`text`,text:`Remember failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{o as registerRememberTool};

package/packages/server/dist/tools/replay.tool.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region packages/server/src/tools/replay.tool.d.ts
+declare function registerReplayTool(server: McpServer): void;
+//#endregion
+export { registerReplayTool };

package/packages/server/dist/tools/replay.tool.js

@@ -0,0 +1,3 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{z as t}from"zod";import{createLogger as n,serializeError as r}from"../../../core/dist/index.js";import{replayClear as i,replayList as a,replayTrim as o}from"../../../tools/dist/index.js";const s=n(`tools`);function c(n){let c=e(`replay`);n.registerTool(`replay`,{title:c.title,description:`View or clear the audit trail of recent MCP tool and CLI invocations. Shows tool name, duration, status, and input/output summaries.`,inputSchema:{action:t.enum([`list`,`clear`]).default(`list`).describe(`Action: "list" (default) to view entries, "clear" to wipe the log`),last:t.number().optional().describe(`Number of entries to return (default: 20, list only)`),tool:t.string().optional().describe(`Filter by tool name (list only)`),source:t.enum([`mcp`,`cli`]).optional().describe(`Filter by source: "mcp" or "cli" (list only)`),since:t.string().optional().describe(`ISO timestamp — only show entries after this time (list only)`)},annotations:c.annotations},async({action:e,last:t,tool:n,source:c,since:l})=>{try{if(e===`clear`)return i(),{content:[{type:`text`,text:`Replay log cleared.`}]};let r=a({last:t,tool:n,source:c,since:l});if(r.length===0)return{content:[{type:`text`,text:`No replay entries found. Activity is logged when tools are invoked via MCP or CLI.`}]};let s=r.map(e=>`${e.ts.split(`T`)[1]?.split(`.`)[0]??e.ts} ${e.status===`ok`?`✓`:`✗`} ${e.tool} (${e.durationMs}ms) [${e.source}]\n  in: ${e.input}\n  out: ${e.output}`);return o().catch(()=>{}),{content:[{type:`text`,text:`**Replay Log** (${r.length} entries)\n\n${s.join(`
+
+`)}`}]}}catch(e){return s.error(`Replay failed`,r(e)),{content:[{type:`text`,text:`Replay failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{c as registerReplayTool};

package/packages/server/dist/tools/restore.tool.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region packages/server/src/tools/restore.tool.d.ts
+declare function registerRestoreTool(server: McpServer): void;
+//#endregion
+export { registerRestoreTool };

package/packages/server/dist/tools/restore.tool.js

@@ -0,0 +1,3 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{z as t}from"zod";import{createLogger as n,serializeError as r}from"../../../core/dist/index.js";import{listRestorePoints as i,restoreFromPoint as a}from"../../../tools/dist/index.js";const o=n(`tools`);function s(n){let s=e(`restore`);n.registerTool(`restore`,{title:s.title,description:`List and restore file snapshots taken before destructive operations (codemod, rename, forget). Use action=list to see available restore points, action=restore with an id to undo.`,inputSchema:{action:t.enum([`list`,`restore`]).describe(`list: show restore points, restore: apply a restore point`),id:t.string().optional().describe(`Restore point ID (required for action=restore)`),limit:t.number().min(1).max(50).default(10).describe(`Max restore points to list`)},annotations:s.annotations},async({action:e,id:t,limit:n})=>{try{if(e===`list`){let e=i().slice(0,n);return e.length===0?{content:[{type:`text`,text:`No restore points found.`}]}:{content:[{type:`text`,text:`## Restore Points\n\n${e.map(e=>`- **${e.id}** (${e.timestamp}) — ${e.operation}: ${e.description} (${e.files.length} files)`).join(`
+`)}`}]}}if(!t)throw Error(`id is required for restore action`);let r=await a(t);return{content:[{type:`text`,text:`Restored ${r.length} files:\n${r.map(e=>`- \`${e}\``).join(`
+`)}`}]}}catch(e){return o.error(`Restore failed`,r(e)),{content:[{type:`text`,text:`Restore failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{s as registerRestoreTool};

package/packages/server/dist/tools/search.tool.d.ts

@@ -0,0 +1,11 @@
+import { ISamplingClient } from "../sampling.js";
+import { BridgeComponents } from "./bridge.tools.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { EvolutionCollector } from "../../../enterprise-bridge/dist/index.js";
+import { IGraphStore, IKnowledgeStore } from "../../../store/dist/index.js";
+import { IEmbedder } from "../../../embeddings/dist/index.js";
+
+//#region packages/server/src/tools/search.tool.d.ts
+declare function registerSearchTool(server: McpServer, embedder: IEmbedder, store: IKnowledgeStore, graphStore?: IGraphStore, bridge?: BridgeComponents, evolutionCollector?: EvolutionCollector, samplingClient?: ISamplingClient): void;
+//#endregion
+export { registerSearchTool };

package/packages/server/dist/tools/search.tool.js

@@ -0,0 +1,10 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{SearchOutputSchema as t}from"../output-schemas.js";import{fanOutFtsSearch as n,fanOutSearch as r,openWorkspaceStores as i,resolveWorkspaces as a}from"../cross-workspace.js";import{curatedResourceLink as o,extractCuratedPath as s}from"../resource-links.js";import{basename as c}from"node:path";import{stat as l}from"node:fs/promises";import{z as u}from"zod";import{CONTENT_TYPES as d,KNOWLEDGE_ORIGINS as f,SOURCE_TYPES as p,computePartitionKey as m,createLogger as h,serializeError as g}from"../../../core/dist/index.js";import{bookendReorder as _,graphAugmentSearch as v,stashGet as y,truncateToTokenBudget as ee}from"../../../tools/dist/index.js";import{mergeResults as b}from"../../../enterprise-bridge/dist/index.js";const x=h(`tools`);function S(e){let t=[],n=c(process.cwd());n&&t.push(`[project: ${n}]`);let r=y(`__context_boost`);return r&&t.push(`[focus: ${r.value}]`),t.length===0?e:`${t.join(` `)} ${e}`}async function C(e,t,n,r,i){if(!e||t>=e.config.fallbackThreshold&&n.length>0)return{results:n,triggered:!1,cacheHit:!1};let a=!1;try{let t=e.cache.get(r);return t?a=!0:(t=await e.client.search(r,i),t.length>0&&e.cache.set(r,t)),t.length>0?{results:b(n,t,i).map(e=>({record:{id:`er:${e.sourcePath}`,content:e.content,sourcePath:e.source===`er`?`[ER] ${e.sourcePath}`:e.sourcePath,startLine:e.startLine??0,endLine:e.endLine??0,contentType:e.contentType??`documentation`,headingPath:e.headingPath,origin:e.source===`er`?`curated`:e.origin??`indexed`,category:e.category,tags:e.tags??[],chunkIndex:0,totalChunks:1,fileHash:``,indexedAt:new Date().toISOString(),version:1},score:e.score})),triggered:!0,cacheHit:a}:{results:n,triggered:!0,cacheHit:a}}catch(e){return x.warn(`ER fallback failed`,g(e)),{results:n,triggered:!0,cacheHit:a}}}function te(e,t,n=60){let r=new Map;for(let t=0;t<e.length;t++){let i=e[t];r.set(i.record.id,{record:i.record,score:1/(n+t+1)})}for(let e=0;e<t.length;e++){let i=t[e],a=r.get(i.record.id);a?a.score+=1/(n+e+1):r.set(i.record.id,{record:i.record,score:1/(n+e+1)})}return[...r.values()].sort((e,t)=>t.score-e.score).map(({record:e,score:t})=>({record:e,score:t}))}function w(e,t){let n=t.toLowerCase().split(/\s+/).filter(e=>e.length>=2);return n.length<2?e:e.map(e=>{let t=e.record.content.toLowerCase(),r=n.map(e=>{let n=[],r=t.indexOf(e);for(;r!==-1;)n.push(r),r=t.indexOf(e,r+1);return n});if(r.some(e=>e.length===0))return e;let i=t.length;for(let e of r[0]){let t=e,a=e+n[0].length;for(let i=1;i<r.length;i++){let o=r[i][0],s=Math.abs(o-e);for(let t=1;t<r[i].length;t++){let n=Math.abs(r[i][t]-e);n<s&&(s=n,o=r[i][t])}t=Math.min(t,o),a=Math.max(a,o+n[i].length)}i=Math.min(i,a-t)}let a=1+.25/(1+i/200);return{record:e.record,score:e.score*a}}).sort((e,t)=>t.score-e.score)}function T(e,t,n=8){let r=new Set(t.toLowerCase().split(/\s+/).filter(e=>e.length>=2)),i=new Map,a=e.length;for(let t of e){let e=new Set(t.record.content.split(/[^a-zA-Z0-9_]+/).filter(e=>e.length>=3&&!E.has(e.toLowerCase())));for(let t of e){let e=t.toLowerCase();/[_A-Z]/.test(t)&&i.set(`__id__${e}`,1)}let n=new Set(t.record.content.toLowerCase().split(/[^a-zA-Z0-9_]+/).filter(e=>e.length>=3&&!E.has(e)));for(let e of n)i.set(e,(i.get(e)??0)+1)}let o=[];for(let[e,t]of i){if(e.startsWith(`__id__`)||r.has(e)||t>a*.8)continue;let n=Math.log(a/t),s=i.has(`__id__${e}`)?1:0,c=e.length>8?.5:0;o.push({term:e,score:n+s+c})}return o.sort((e,t)=>t.score-e.score).slice(0,n).map(e=>e.term)}const E=new Set(`the.and.for.are.but.not.you.all.can.had.her.was.one.our.out.has.have.from.this.that.with.they.been.said.each.which.their.will.other.about.many.then.them.these.some.would.make.like.into.could.time.very.when.come.just.know.take.people.also.back.after.only.more.than.over.such.import.export.const.function.return.true.false.null.undefined.string.number.boolean.void.type.interface`.split(`.`));async function D(e,t){try{let n=await e.getStats();if(!n.lastIndexedAt)return;let r=new Date(n.lastIndexedAt).getTime(),i=Date.now(),a=[...new Set(t.map(e=>e.record.sourcePath))].filter(e=>!e.startsWith(`[ER]`)).slice(0,5);if(a.length===0)return;let o=0;for(let e of a)try{(await l(e)).mtimeMs>r&&o++}catch{o++}if(o>0){let e=i-r,t=Math.floor(e/6e4),n=t<1?`<1 min`:`${t} min`;return`> ⚠️ **Index may be stale** — ${o} file(s) modified since last index (${n} ago). Use \`reindex\` to refresh.`}}catch{}}function O(c,l,h,y,b,E,O){let k=e(`search`);c.registerTool(`search`,{title:k.title,description:`Search the knowledge base for code, docs, and prior decisions. Default choice for discovery. Modes: hybrid (default), semantic, keyword. For multi-strategy precision queries use find; for a known file path use lookup.`,outputSchema:t,inputSchema:{query:u.string().max(5e3).describe(`Natural language search query`),limit:u.number().min(1).max(20).default(5).describe(`Maximum results to return`),search_mode:u.enum([`hybrid`,`semantic`,`keyword`]).default(`hybrid`).describe(`Search strategy: hybrid (vector + FTS + RRF fusion, default), semantic (vector only), keyword (FTS only)`),content_type:u.enum(d).optional().describe(`Filter by content type`),source_type:u.enum(p).optional().describe(`Coarse filter: "source" (code only), "documentation" (md, curated), "test", "config". Overrides content_type if both set.`),origin:u.enum(f).optional().describe(`Filter by knowledge origin`),category:u.string().optional().describe(`Filter by category (e.g., decisions, patterns, conventions)`),tags:u.array(u.string()).optional().describe(`Filter by tags (returns results matching ANY of the specified tags)`),min_score:u.number().min(0).max(1).default(.25).describe(`Minimum similarity score`),graph_hops:u.number().min(0).max(3).default(1).describe(`Number of graph hops to augment results with connected entities (0 = disabled, 1 = direct connections, 2-3 = deeper traversal). Default 1 provides module/symbol context automatically.`),max_tokens:u.number().min(100).max(5e4).optional().describe(`Maximum token budget for the response. When set, output is truncated to fit.`),dedup:u.enum([`file`,`chunk`]).default(`chunk`).describe(`Deduplication mode: "chunk" (default, show all matching chunks) or "file" (collapse chunks from same file into single result with merged line ranges)`),workspaces:u.array(u.string()).optional().describe(`Cross-workspace search: partition names or folder basenames to include. Use ["*"] for all registered workspaces. Only works in user-level install mode.`)},annotations:k.annotations},async({query:e,limit:t,search_mode:c,content_type:u,source_type:d,origin:f,category:p,tags:k,min_score:ne,graph_hops:A,max_tokens:j,dedup:M,workspaces:N})=>{try{let P={limit:t,minScore:ne,contentType:u,sourceType:d,origin:f,category:p,tags:k},F,I=!1,L=!1,R=``,z=S(e);if(c===`keyword`)F=await h.ftsSearch(e,P),F=F.slice(0,t);else if(c===`semantic`){let n=await l.embedQuery(z);F=await h.search(n,P);let r=await C(b,F[0]?.score??0,F,e,t);F=r.results,I=r.triggered,L=r.cacheHit}else{let n=await l.embedQuery(z),[r,i]=await Promise.all([h.search(n,{...P,limit:t*2}),h.ftsSearch(e,{...P,limit:t*2}).catch(()=>[])]);F=te(r,i).slice(0,t);let a=await C(b,r[0]?.score??0,F,e,t);F=a.results,I=a.triggered,L=a.cacheHit}E&&E.recordSearch(e,I,L),F.length>1&&(F=w(F,e));let B=``;if(N&&N.length>0){let o=a(N,m(process.cwd()));if(o.length>0){let{stores:a,closeAll:s}=await i(o);try{let i;i=c===`keyword`?await n(a,e,{...P,limit:t}):await r(a,await l.embedQuery(e),{...P,limit:t});for(let e of i)F.push({record:{...e.record,sourcePath:`[${e.workspace}] ${e.record.sourcePath}`},score:e.score});F=F.sort((e,t)=>t.score-e.score).slice(0,t),B=` + ${o.length} workspace(s)`}finally{await s()}}}if(M===`file`&&F.length>1){let e=new Map;for(let t of F){let n=t.record.sourcePath,r=e.get(n);r?(t.score>r.best.score&&(r.best=t),r.ranges.push({start:t.record.startLine,end:t.record.endLine})):e.set(n,{best:t,ranges:[{start:t.record.startLine,end:t.record.endLine}]})}F=[...e.values()].sort((e,t)=>t.best.score-e.best.score).map(({best:e,ranges:t})=>({record:{...e.record,content:t.length>1?`${e.record.content}\n\n_Matched ${t.length} sections: ${t.sort((e,t)=>e.start-t.start).map(e=>`L${e.start}-${e.end}`).join(`, `)}_`:e.record.content},score:e.score}))}if(F.length===0){if(O?.available)try{let t=(await O.createMessage({prompt:`The search query "${e}" returned 0 results in a code knowledge base. Suggest ONE alternative search query that might find relevant results. Reply with ONLY the alternative query, nothing else.`,systemPrompt:`You are a search query optimizer for a code knowledge base. Generate a single alternative query.`,maxTokens:100})).text.trim().split(`
+`)[0].slice(0,500);if(t&&t!==e){let n=await l.embedQuery(t),r=await h.search(n,P);r.length>0&&(F=r,R=`> _Original query "${e}" returned 0 results. Auto-reformulated to "${t}"._\n\n`,x.info(`Smart search fallback succeeded`,{originalQuery:e,altQuery:t,resultCount:r.length}))}}catch(e){x.debug(`Smart search fallback failed`,{error:String(e)})}if(F.length===0)return{content:[{type:`text`,text:`No results found for the given query.`}],structuredContent:{results:[],totalResults:0,searchMode:c,query:e}}}let V,H;if(A>0&&!y&&(H="> **Note:** `graph_hops` was set but no graph store is available. Graph augmentation skipped."),A>0&&y)try{let e=await v(y,F.map(e=>({recordId:e.record.id,score:e.score,sourcePath:e.record.sourcePath})),{hops:A,maxPerHit:5});V=new Map;for(let t of e)if(t.graphContext.nodes.length>0){let e=t.graphContext.nodes.slice(0,5).map(e=>`  - **${e.name}** (${e.type})`).join(`
+`),n=t.graphContext.edges.slice(0,5).map(e=>`  - ${e.fromId} —[${e.type}]→ ${e.toId}`).join(`
+`),r=[`- **Graph Context** (${A} hop${A>1?`s`:``}):`];e&&r.push(`  Entities:\n${e}`),n&&r.push(`  Relationships:\n${n}`),V.set(t.recordId,r.join(`
+`))}}catch(e){x.warn(`Graph augmentation failed`,g(e)),H=`> **Note:** Graph augmentation failed. Results shown without graph context.`}let U=Date.now();for(let e of F)if(e.record.origin===`curated`&&e.record.indexedAt){let t=U-new Date(e.record.indexedAt).getTime(),n=Math.max(0,t/864e5);e.score*=.95**n}F.sort((e,t)=>t.score-e.score),F=_(F);let W=F.map((e,t)=>{let n=e.record;return`${`### Result ${t+1} (score: ${e.score.toFixed(3)})`}\n${[`- **Source**: ${n.sourcePath}`,n.headingPath?`- **Section**: ${n.headingPath}`:null,`- **Type**: ${n.contentType}`,n.startLine?`- **Lines**: ${n.startLine}-${n.endLine}`:null,n.origin===`indexed`?null:`- **Origin**: ${n.origin}`,n.category?`- **Category**: ${n.category}`:null,n.tags?.length?`- **Tags**: ${n.tags.join(`, `)}`:null,V?.get(n.id)??null].filter(Boolean).join(`
+`)}\n\n${n.content}`}).join(`
+
+---
+
+`),G=(c===`hybrid`?`hybrid (vector + keyword RRF)`:c===`keyword`?`keyword (FTS)`:`semantic (vector)`)+B,K=T(F,e),q=K.length>0?`\n_Distinctive terms: ${K.map(e=>`\`${e}\``).join(`, `)}_`:``,J=await D(h,F),Y=[];if(F.length===0)Y.push("`reindex` — no results found, index may be stale"),Y.push("`find` — try federated search with glob/regex");else{let e=F[0]?.record.sourcePath;e&&Y.push(`\`lookup\` — see all chunks from \`${e}\``),Y.push("`symbol` — resolve a specific symbol from the results"),Y.push("`compact` — compress a result file for focused reading")}let X=[H?`${H}\n\n`:``,J?`${J}\n\n`:``,W,`\n\n---\n_Search mode: ${G} | ${F.length} results_${q}`,`\n_Next: ${Y.join(` | `)}_`],Z=R+X.join(``);j&&(Z=ee(Z,j));let Q=new Set,$=[];for(let e of F){if(e.record.origin!==`curated`||e.record.sourcePath.startsWith(`[`))continue;let t=s(e.record.sourcePath);if(!t)continue;let n=o(t,e.record.headingPath??t);n&&!Q.has(n.uri)&&(Q.add(n.uri),$.push(n))}return{content:[{type:`text`,text:Z},...$],structuredContent:{results:F.map(e=>({sourcePath:e.record.sourcePath,contentType:e.record.contentType,score:e.score,...e.record.headingPath?{headingPath:e.record.headingPath}:{},...e.record.startLine?{startLine:e.record.startLine}:{},...e.record.endLine?{endLine:e.record.endLine}:{},...e.record.origin===`indexed`?{}:{origin:e.record.origin},...e.record.category?{category:e.record.category}:{},...e.record.tags?.length?{tags:e.record.tags}:{}})),totalResults:F.length,searchMode:c,query:e}}}catch(e){return x.error(`Search failed`,g(e)),{content:[{type:`text`,text:`Search failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{O as registerSearchTool};

package/packages/server/dist/tools/status.tool.d.ts

@@ -0,0 +1,20 @@
+import { CuratedKnowledgeManager } from "../curated-manager.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { KBConfig } from "../../../core/dist/index.js";
+import { IGraphStore, IKnowledgeStore } from "../../../store/dist/index.js";
+
+//#region packages/server/src/tools/status.tool.d.ts
+interface OnboardState {
+  onboardComplete: boolean;
+  onboardTimestamp?: string;
+}
+declare function getScaffoldVersion(): string | null;
+declare function getWorkspaceScaffoldVersion(): string | null;
+/**
+ * Lightweight status tool registered during init — returns version info
+ * without needing the KB store, graph, or curated manager.
+ */
+declare function registerEarlyStatusTool(server: McpServer): void;
+declare function registerStatusTool(server: McpServer, store: IKnowledgeStore, graphStore?: IGraphStore, curated?: CuratedKnowledgeManager, onboardState?: OnboardState, config?: KBConfig): void;
+//#endregion
+export { OnboardState, getScaffoldVersion, getWorkspaceScaffoldVersion, registerEarlyStatusTool, registerStatusTool };

package/packages/server/dist/tools/status.tool.js

@@ -0,0 +1,3 @@
+import{getGcStatus as e}from"../auto-gc.js";import{getToolTelemetry as t}from"../replay-interceptor.js";import{getToolMeta as n}from"../tool-metadata.js";import{StatusOutputSchema as r}from"../output-schemas.js";import{autoUpgradeScaffold as i,getCurrentVersion as a,getUpgradeState as o}from"../version-check.js";import{existsSync as s,readFileSync as c,statSync as l}from"node:fs";import{resolve as u}from"node:path";import{AIKIT_PATHS as d,createLogger as f,serializeError as p}from"../../../core/dist/index.js";import{WasmRuntime as m}from"../../../chunker/dist/index.js";import{homedir as h}from"node:os";const g=f(`tools`);function _(e,t,n,r=4e3){let i,a=new Promise(e=>{i=setTimeout(()=>{g.warn(`Status sub-operation "${n}" timed out after ${r}ms`),e({value:t,timedOut:!0})},r)});return Promise.race([e.then(e=>(clearTimeout(i),{value:e,timedOut:!1}),e=>(clearTimeout(i),g.warn(`Status sub-operation "${n}" failed: ${e instanceof Error?e.message:String(e)}`),{value:t,timedOut:!1})),a])}function v(){try{let e=u(h(),`.copilot`,`.aikit-scaffold.json`);return s(e)?JSON.parse(c(e,`utf-8`)).version??null:null}catch{return null}}function y(){try{let e=u(process.cwd(),`.github`,`.aikit-scaffold.json`);return s(e)?JSON.parse(c(e,`utf-8`)).version??null:null}catch{return null}}function b(e){let t=n(`status`);e.registerTool(`status`,{title:t.title,description:`Get the current status and statistics of the knowledge base index.`,outputSchema:r,annotations:t.annotations},async()=>{let e=a(),t=v(),n=y(),r=t!=null&&t!==e,s=n!=null&&n!==e,c=[`## Knowledge Base Status`,``,`⏳ **KB is initializing** — index stats will be available shortly.`,``,`### Runtime`,`- **Tree-sitter (WASM)**: ${m.get()?`✅ Available (AST analysis)`:`⚠ Unavailable (regex fallback)`}`,``,`### Version`,`- **Server**: ${e}`,`- **Scaffold (user)**: ${t??`not installed`}`,`- **Scaffold (workspace)**: ${n??`not installed`}`];if(r||s){let a=o(),l=[];r&&l.push(`user scaffold v${t}`),s&&l.push(`workspace scaffold v${n}`);let u=l.join(`, `);a.state===`success`?c.push(``,`### ✅ Upgrade Applied`,`- Server v${e} — ${u} auto-upgraded successfully.`,`- _Restart the MCP server to use the updated version._`):a.state===`pending`?c.push(``,`### ⏳ Upgrade In Progress`,`- Server v${e} ≠ ${u}`,`- Auto-upgrade is running in the background…`):a.state===`failed`?(i(),c.push(``,`### ⬆ Upgrade Available (auto-upgrade failed, retrying)`,`- Server v${e} ≠ ${u}`,`- Error: ${a.error??`unknown`}`)):(i(),c.push(``,`### ⬆ Upgrade Available`,`- Server v${e} ≠ ${u}`,`- Auto-upgrade triggered — check again shortly.`))}let l={totalRecords:0,totalFiles:0,lastIndexedAt:null,onboarded:!1,onboardDir:``,contentTypes:{},wasmAvailable:!!m.get(),graphStats:null,curatedCount:0,serverVersion:e,scaffoldVersion:t??null,workspaceScaffoldVersion:n??null,upgradeAvailable:r||s};return{content:[{type:`text`,text:c.join(`
+`)}],structuredContent:l}})}function x(c,f,h,b,x,S){let C=n(`status`);c.registerTool(`status`,{title:C.title,description:`Get the current status and statistics of the knowledge base index.`,outputSchema:r,annotations:C.annotations},async()=>{let n=[];try{let r=await _(f.getStats(),{totalRecords:0,totalFiles:0,lastIndexedAt:null,contentTypeBreakdown:{}},`store.getStats`),c=r.value;r.timedOut&&n.push(`⚠ Index stats timed out — values may be incomplete`);let p=await _(f.listSourcePaths(),[],`store.listSourcePaths`),g=p.value;p.timedOut&&n.push(`⚠ File listing timed out`);let C=null,w=0,T=[`## Knowledge Base Status`,``,`- **Total Records**: ${c.totalRecords}`,`- **Total Files**: ${c.totalFiles}`,`- **Last Indexed**: ${c.lastIndexedAt??`Never`}`,``,`### Content Types`,...Object.entries(c.contentTypeBreakdown).map(([e,t])=>`- ${e}: ${t}`),``,`### Indexed Files`,...g.slice(0,50).map(e=>`- ${e}`),g.length>50?`\n... and ${g.length-50} more files`:``];if(h)try{let e=await _(h.getStats(),{nodeCount:0,edgeCount:0,nodeTypes:{},edgeTypes:{}},`graphStore.getStats`);if(e.timedOut)n.push(`⚠ Graph stats timed out`),T.push(``,`### Knowledge Graph`,`- Graph stats timed out`);else{let t=e.value;C={nodes:t.nodeCount,edges:t.edgeCount},T.push(``,`### Knowledge Graph`,`- **Nodes**: ${t.nodeCount}`,`- **Edges**: ${t.edgeCount}`,...Object.entries(t.nodeTypes).map(([e,t])=>`  - ${e}: ${t}`));try{let e=await _(h.validate(),{valid:!0,danglingEdges:[],orphanNodes:[],stats:{nodeCount:0,edgeCount:0,nodeTypes:{},edgeTypes:{}}},`graphStore.validate`);if(!e.timedOut){let t=e.value;t.valid||T.push(`- **⚠ Integrity Issues**: ${t.danglingEdges.length} dangling edges`),t.orphanNodes.length>0&&T.push(`- **Orphan nodes**: ${t.orphanNodes.length}`)}}catch{}}}catch{T.push(``,`### Knowledge Graph`,`- Graph store unavailable`)}let E=S?.onboardDir??u(process.cwd(),d.aiKb),D=s(E),O=x?.onboardComplete??D;if(T.push(``,`### Onboard Status`,O?`- ✅ Complete${x?.onboardTimestamp?` (last: ${x.onboardTimestamp})`:``}`:'- ❌ Not run — call `onboard({ path: "." })` to analyze the codebase',`- **Onboard Directory**: \`${E}\``),b)try{let e=await _(b.list(),[],`curated.list`);if(e.timedOut)n.push(`⚠ Curated knowledge listing timed out`),T.push(``,`### Curated Knowledge`,`- Listing timed out`);else{let t=e.value;w=t.length,T.push(``,`### Curated Knowledge`,t.length>0?`- ${t.length} entries`:"- Empty — use `remember()` to persist decisions")}}catch{T.push(``,`### Curated Knowledge`,`- Unable to read curated entries`)}let k=0;if(c.lastIndexedAt){k=new Date(c.lastIndexedAt).getTime();let e=(Date.now()-k)/(1e3*60*60);T.push(``,`### Index Freshness`,e>24?`- ⚠ Last indexed ${Math.floor(e)}h ago — may be stale. Run \`reindex({})\``:`- ✅ Last indexed ${e<1?`less than 1h`:`${Math.floor(e)}h`} ago`)}{try{let e=u(process.cwd(),d.data,`stash`);if(s(e)){let t=l(e).mtimeMs;t>k&&(k=t)}}catch{}let e=[];if(b)try{let t=w>0?await b.list():[];for(let e of t){let t=new Date(e.updated||e.created).getTime();t>k&&(k=t)}e.push(...t.sort((e,t)=>new Date(t.updated).getTime()-new Date(e.updated).getTime()).slice(0,5))}catch{}let t=k>0?Date.now()-k:0;if(t>=144e5){let n=Math.floor(t/36e5);if(T.push(``,`### 🌅 Session Briefing`,`_${n}+ hours since last activity — here's what to pick up:_`,``),e.length>0){T.push(`**Recent decisions/notes:**`);for(let t of e)T.push(`- **${t.title}** (${t.category??`note`}) — ${(t.contentPreview??``).slice(0,80)}…`)}T.push(``,`**Suggested next steps:**`,'- `search({ query: "SESSION CHECKPOINT", origin: "curated" })` — find your last checkpoint',"- `restore({})` — resume from a saved checkpoint","- `list()` — browse all stored knowledge")}}T.push(``,`### Runtime`,`- **Tree-sitter (WASM)**: ${m.get()?`✅ Available (AST analysis)`:`⚠ Unavailable (regex fallback)`}`);let A=v(),j=y(),M=a(),N=A!=null&&A!==M,P=j!=null&&j!==M;if(N||P){let e=o(),t=[];N&&t.push(`user scaffold v${A}`),P&&t.push(`workspace scaffold v${j}`);let n=t.join(`, `);e.state===`success`?T.push(``,`### ✅ Upgrade Applied`,`- Server v${M} — ${n} auto-upgraded successfully.`,`- _Restart the MCP server to use the updated version._`):e.state===`pending`?T.push(``,`### ⏳ Upgrade In Progress`,`- Server v${M} ≠ ${n}`,`- Auto-upgrade is running in the background…`):e.state===`failed`?(i(),T.push(``,`### ⬆ Upgrade Available (auto-upgrade failed, retrying)`,`- Server v${M} ≠ ${n}`,`- Error: ${e.error??`unknown`}`)):(i(),T.push(``,`### ⬆ Upgrade Available`,`- Server v${M} ≠ ${n}`,`- Auto-upgrade triggered — check again shortly.`))}n.length>0&&T.push(``,`### ⚠ Warnings`,...n.map(e=>`- ${e}`));let F=t();if(F.length>0){let e=F.sort((e,t)=>t.callCount-e.callCount);T.push(``,`### Tool Usage This Session`,``),T.push(`| Tool | Calls | Tokens In | Tokens Out | Errors | Avg Latency |`),T.push(`|------|-------|-----------|------------|--------|-------------|`);for(let t of e.slice(0,15)){let e=Math.round(t.totalInputChars/4),n=Math.round(t.totalOutputChars/4),r=Math.round(t.totalDurationMs/t.callCount);T.push(`| ${t.tool} | ${t.callCount} | ${e.toLocaleString()} | ${n.toLocaleString()} | ${t.errorCount} | ${r}ms |`)}}let I=e();if(I.bufferSize>=10){let e=I.state===`healthy`?`🟢`:I.state===`degraded`?`🔴`:`🟡`;T.push(``,`### Auto-GC: ${e} ${I.state}`),T.push(`- p95 latency: ${I.p95}ms | buffer: ${I.bufferSize} samples`),I.gcCount>0&&T.push(`- GC cycles triggered: ${I.gcCount}`)}let L=T.join(`
+`),R={totalRecords:c.totalRecords,totalFiles:c.totalFiles,lastIndexedAt:c.lastIndexedAt??null,onboarded:O,onboardDir:E,contentTypes:c.contentTypeBreakdown,wasmAvailable:!!m.get(),graphStats:C,curatedCount:w,serverVersion:M,scaffoldVersion:A??null,workspaceScaffoldVersion:j??null,upgradeAvailable:N||P};return{content:[{type:`text`,text:L+"\n\n---\n_Next: Use `search` to query indexed content, `graph(stats)` to explore the knowledge graph, or `reindex` to refresh the index._"}],structuredContent:R}}catch(e){return g.error(`Status failed`,p(e)),{content:[{type:`text`,text:`Status check failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{v as getScaffoldVersion,y as getWorkspaceScaffoldVersion,b as registerEarlyStatusTool,x as registerStatusTool};

package/packages/server/dist/tools/update.tool.d.ts

@@ -0,0 +1,8 @@
+import { CuratedKnowledgeManager } from "../curated-manager.js";
+import { ResourceNotifier } from "../resources/resource-notifier.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region packages/server/src/tools/update.tool.d.ts
+declare function registerUpdateTool(server: McpServer, curated: CuratedKnowledgeManager, resourceNotifier?: ResourceNotifier): void;
+//#endregion
+export { registerUpdateTool };

package/packages/server/dist/tools/update.tool.js

@@ -0,0 +1 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{z as t}from"zod";import{createLogger as n,serializeError as r}from"../../../core/dist/index.js";const i=n(`tools`);function a(n,a,o){let s=e(`update`);n.registerTool(`update`,{title:s.title,description:`Update an existing curated knowledge entry. Increments version and records the reason in the changelog.`,inputSchema:{path:t.string().describe(`Relative path within .ai/curated/ (e.g., "decisions/use-lancedb.md")`),content:t.string().min(10).max(1e5).describe(`New markdown content to replace existing content`),reason:t.string().min(3).max(1e3).describe(`Why this update is being made (recorded in changelog)`)},annotations:s.annotations},async({path:e,content:t,reason:n})=>{try{let r=await a.update(e,t,n);return o&&o.notifyAfterCuratedWrite(e).catch(()=>{}),{content:[{type:`text`,text:`Updated: \`.ai/curated/${r.path}\` → version ${r.version}\n\nReason: ${n}\n\n---\n_Next: Use \`read\` to verify the updated content, or \`search\` to test searchability._`}]}}catch(e){return i.error(`Update failed`,r(e)),{content:[{type:`text`,text:`Update failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{a as registerUpdateTool};

package/packages/server/dist/tools/utility.tools.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region packages/server/src/tools/utility.tools.d.ts
+declare function registerWebSearchTool(server: McpServer): void;
+declare function registerHttpTool(server: McpServer): void;
+declare function registerRegexTestTool(server: McpServer): void;
+declare function registerEncodeTool(server: McpServer): void;
+declare function registerMeasureTool(server: McpServer): void;
+declare function registerChangelogTool(server: McpServer): void;
+declare function registerSchemaValidateTool(server: McpServer): void;
+declare function registerSnippetTool(server: McpServer): void;
+declare function registerEnvTool(server: McpServer): void;
+declare function registerTimeTool(server: McpServer): void;
+//#endregion
+export { registerChangelogTool, registerEncodeTool, registerEnvTool, registerHttpTool, registerMeasureTool, registerRegexTestTool, registerSchemaValidateTool, registerSnippetTool, registerTimeTool, registerWebSearchTool };

package/packages/server/dist/tools/utility.tools.js

@@ -0,0 +1,13 @@
+import{getToolMeta as e}from"../tool-metadata.js";import{EnvOutputSchema as t,MeasureOutputSchema as n,TimeOutputSchema as r}from"../output-schemas.js";import{z as i}from"zod";import{createLogger as a,serializeError as o}from"../../../core/dist/index.js";import{changelog as s,encode as c,envInfo as l,httpRequest as u,measure as d,regexTest as f,schemaValidate as p,snippet as m,timeUtils as h,webSearch as g}from"../../../tools/dist/index.js";const _=a(`tools`);function v(t){let n=e(`web_search`);t.registerTool(`web_search`,{title:n.title,description:`PREFERRED web search — search the web via DuckDuckGo (no API key). Pass one query or multiple for parallel searching. Returns structured results with title, URL, and snippet.`,inputSchema:{queries:i.array(i.string().max(2e3)).min(1).max(5).describe('Search queries (1–5). Single: `["react hooks"]`. Multiple searched in parallel.'),limit:i.number().min(1).max(20).default(5).describe(`Max results per query`),site:i.string().optional().describe(`Restrict to domain (e.g., "docs.aws.amazon.com")`)},annotations:n.annotations},async({queries:e,limit:t,site:n})=>{let r=e,i=async e=>{let r=await g({query:e,limit:t,site:n}),i=[`## Search: ${r.query}`,``];if(r.results.length===0)i.push(`No results found.`);else for(let e of r.results)i.push(`### [${e.title}](${e.url})`,e.snippet,``);return i.join(`
+`)};if(r.length===1)try{return{content:[{type:`text`,text:`${await i(r[0])}\n---\n_Next: Use \`web_fetch\` to read any of these pages in full._`}]}}catch(e){return _.error(`Web search failed`,o(e)),{content:[{type:`text`,text:`Web search failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}let a=await Promise.allSettled(r.map(e=>i(e))),s=[],c=0;for(let e=0;e<a.length;e++){let t=a[e];if(t.status===`fulfilled`)s.push(t.value);else{c++;let n=t.reason instanceof Error?t.reason.message:String(t.reason);_.error(`Web search failed`,{query:r[e],error:n}),s.push(`## ❌ Search failed: ${r[e]}\n\n${n}`)}}let l=`_Searched ${a.length-c}/${a.length} queries successfully._`;return s.push(``,`---`,l,"_Next: Use `web_fetch` to read any of these pages in full._"),{content:[{type:`text`,text:s.join(`
+
+`)}],...c===a.length?{isError:!0}:{}}})}function y(t){let n=e(`http`);t.registerTool(`http`,{title:n.title,description:`Make HTTP requests (GET/POST/PUT/PATCH/DELETE/HEAD) for API testing. Returns status, headers, and formatted body with timing info.`,inputSchema:{url:i.string().url().describe(`Request URL (http/https only)`),method:i.enum([`GET`,`POST`,`PUT`,`PATCH`,`DELETE`,`HEAD`]).default(`GET`).describe(`HTTP method`),headers:i.record(i.string(),i.string()).optional().describe(`Request headers as key-value pairs`),body:i.string().optional().describe(`Request body (for POST/PUT/PATCH)`),timeout:i.number().min(1e3).max(6e4).default(15e3).describe(`Timeout in milliseconds`)},annotations:n.annotations},async({url:e,method:t,headers:n,body:r,timeout:i})=>{try{let a=await u({url:e,method:t,headers:n,body:r,timeout:i}),o=[`## ${t} ${e}`,``,`**Status:** ${a.status} ${a.statusText}`,`**Time:** ${a.durationMs}ms`,`**Size:** ${a.sizeBytes} bytes`,`**Content-Type:** ${a.contentType}`,``,`### Headers`,"```json",JSON.stringify(a.headers),"```",``,`### Body`,a.contentType.includes(`json`)?"```json":"```",a.body,"```"];return a.truncated&&o.push(``,`_Response truncated — total size: ${a.sizeBytes} bytes_`),{content:[{type:`text`,text:o.join(`
+`)}]}}catch(e){return _.error(`HTTP request failed`,o(e)),{content:[{type:`text`,text:`HTTP request failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function b(t){let n=e(`regex_test`);t.registerTool(`regex_test`,{title:n.title,description:`Test a regex pattern against sample strings. Supports match, replace, and split modes.`,inputSchema:{pattern:i.string().max(500).describe(`Regex pattern (without delimiters)`),flags:i.string().max(10).regex(/^[gimsuy]*$/).default(``).describe(`Regex flags (g, i, m, s, etc.)`),test_strings:i.array(i.string().max(1e4)).max(50).describe(`Strings to test the pattern against`),mode:i.enum([`match`,`replace`,`split`]).default(`match`).describe(`Test mode`),replacement:i.string().optional().describe(`Replacement string (for replace mode)`)},annotations:n.annotations},async({pattern:e,flags:t,test_strings:n,mode:r,replacement:i})=>{let a=f({pattern:e,flags:t,testStrings:n,mode:r,replacement:i});if(!a.valid)return{content:[{type:`text`,text:`Invalid regex: ${a.error}`}],isError:!0};let o=[`## Regex: \`/${a.pattern}/${a.flags}\``,``,`Mode: ${r}`,``];for(let e of a.results){if(o.push(`**Input:** \`${e.input}\``),o.push(`**Matched:** ${e.matched}`),e.matches)for(let t of e.matches){let e=t.groups.length>0?` groups: [${t.groups.join(`, `)}]`:``;o.push(`  - "${t.full}" at index ${t.index}${e}`)}e.replaced!==void 0&&o.push(`**Result:** \`${e.replaced}\``),e.split&&o.push(`**Split:** ${JSON.stringify(e.split)}`),o.push(``)}return{content:[{type:`text`,text:o.join(`
+`)}]}})}function x(t){let n=e(`encode`);t.registerTool(`encode`,{title:n.title,description:`Encode, decode, or hash text. Supports base64, URL encoding, SHA-256, MD5, JWT decode, hex.`,inputSchema:{operation:i.enum([`base64_encode`,`base64_decode`,`url_encode`,`url_decode`,`sha256`,`md5`,`jwt_decode`,`hex_encode`,`hex_decode`]).describe(`Operation to perform`),input:i.string().max(1e6).describe(`Input text`)},annotations:n.annotations},async({operation:e,input:t})=>{try{let n=c({operation:e,input:t});return{content:[{type:`text`,text:`## ${e}\n\n**Input:** \`${t.length>100?`${t.slice(0,100)}...`:t}\`\n**Output:**\n\`\`\`\n${n.output}\n\`\`\``}]}}catch(e){return _.error(`Encode failed`,o(e)),{content:[{type:`text`,text:`Encode failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function S(t){let r=e(`measure`);t.registerTool(`measure`,{title:r.title,description:`Measure code complexity, line counts, and function counts for a file or directory. Returns per-file metrics sorted by complexity.`,outputSchema:n,inputSchema:{path:i.string().describe(`File or directory path to measure`),extensions:i.array(i.string()).optional().describe(`File extensions to include (default: .ts,.tsx,.js,.jsx)`)},annotations:r.annotations},async({path:e,extensions:t})=>{try{let n=await d({path:e,extensions:t}),r=[`## Code Metrics`,``,`**Files:** ${n.summary.totalFiles}`,`**Total lines:** ${n.summary.totalLines} (${n.summary.totalCodeLines} code)`,`**Functions:** ${n.summary.totalFunctions}`,`**Avg complexity:** ${n.summary.avgComplexity}`,`**Max complexity:** ${n.summary.maxComplexity.value} (${n.summary.maxComplexity.file})`,``,`### Top files by complexity`,``,`| File | Lines | Code | Complexity | Cognitive | Functions | Imports |`,`|------|-------|------|------------|-----------|-----------|---------|`];for(let e of n.files.slice(0,20)){let t=e.cognitiveComplexity===void 0?`—`:String(e.cognitiveComplexity);r.push(`| ${e.path} | ${e.lines.total} | ${e.lines.code} | ${e.complexity} | ${t} | ${e.functions} | ${e.imports} |`)}n.files.length>20&&r.push(``,`_...and ${n.files.length-20} more files_`);let i={summary:{totalFiles:n.summary.totalFiles,totalLines:n.summary.totalLines,totalCodeLines:n.summary.totalCodeLines,totalFunctions:n.summary.totalFunctions,avgComplexity:n.summary.avgComplexity,maxComplexity:{value:n.summary.maxComplexity.value,file:n.summary.maxComplexity.file}},files:n.files.map(e=>({path:e.path,lines:e.lines.total,code:e.lines.code,complexity:e.complexity,functions:e.functions}))};return{content:[{type:`text`,text:r.join(`
+`)}],structuredContent:i}}catch(e){return _.error(`Measure failed`,o(e)),{content:[{type:`text`,text:`Measure failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function C(t){let n=e(`changelog`);t.registerTool(`changelog`,{title:n.title,description:`Generate a changelog from git history between two refs. Groups by conventional commit type.`,inputSchema:{from:i.string().max(200).describe(`Start ref (tag, SHA, HEAD~N)`),to:i.string().max(200).default(`HEAD`).describe(`End ref (default: HEAD)`),format:i.enum([`grouped`,`chronological`,`per-scope`]).default(`grouped`).describe(`Output format`),include_breaking:i.boolean().default(!0).describe(`Highlight breaking changes`),cwd:i.string().optional().describe(`Repository root or working directory`)},annotations:n.annotations},async({from:e,to:t,format:n,include_breaking:r,cwd:i})=>{try{let a=s({from:e,to:t,format:n,includeBreaking:r,cwd:i}),o=`${a.stats.total} commits (${Object.entries(a.stats.types).map(([e,t])=>`${t} ${e}`).join(`, `)})`;return{content:[{type:`text`,text:`${a.markdown}\n---\n_${o}_`}]}}catch(e){return _.error(`Changelog failed`,o(e)),{content:[{type:`text`,text:`Changelog failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function w(t){let n=e(`schema_validate`);t.registerTool(`schema_validate`,{title:n.title,description:`Validate JSON data against a JSON Schema. Supports type, required, properties, items, enum, pattern, min/max.`,inputSchema:{data:i.string().max(5e5).describe(`JSON data to validate (as string)`),schema:i.string().max(5e5).describe(`JSON Schema to validate against (as string)`)},annotations:n.annotations},async({data:e,schema:t})=>{try{let n=p({data:JSON.parse(e),schema:JSON.parse(t)});if(n.valid)return{content:[{type:`text`,text:`## Validation: PASSED
+
+Data matches the schema.`}]};let r=[`## Validation: FAILED`,``,`**${n.errors.length} error(s):**`,``];for(let e of n.errors){let t=e.expected?` (expected: ${e.expected}, got: ${e.received})`:``;r.push(`- \`${e.path}\`: ${e.message}${t}`)}return{content:[{type:`text`,text:r.join(`
+`)}]}}catch(e){return _.error(`Schema validation failed`,o(e)),{content:[{type:`text`,text:`Schema validation failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function T(t){let n=e(`snippet`);t.registerTool(`snippet`,{title:n.title,description:`Save, retrieve, search, and manage persistent code snippets/templates.`,inputSchema:{action:i.enum([`save`,`get`,`list`,`search`,`delete`]).describe(`Operation to perform`),name:i.string().optional().describe(`Snippet name (required for save/get/delete)`),language:i.string().optional().describe(`Language tag (for save)`),code:i.string().max(1e5).optional().describe(`Code content (for save)`),tags:i.array(i.string()).optional().describe(`Tags for categorization (for save)`),query:i.string().optional().describe(`Search query (for search)`)},annotations:n.annotations},async({action:e,name:t,language:n,code:r,tags:i,query:a})=>{try{let o=m({action:e,name:t,language:n,code:r,tags:i,query:a});if(`deleted`in o)return{content:[{type:`text`,text:o.deleted?`Snippet "${t}" deleted.`:`Snippet "${t}" not found.`}]};if(`snippets`in o){if(o.snippets.length===0)return{content:[{type:`text`,text:`No snippets found.`}]};let e=[`## Snippets`,``];for(let t of o.snippets){let n=t.tags.length>0?` [${t.tags.join(`, `)}]`:``;e.push(`- **${t.name}** (${t.language})${n}`)}return{content:[{type:`text`,text:e.join(`
+`)}]}}let s=o,c=s.tags.length>0?`\nTags: ${s.tags.join(`, `)}`:``;return{content:[{type:`text`,text:`## ${s.name} (${s.language})${c}\n\n\`\`\`${s.language}\n${s.code}\n\`\`\``}]}}catch(e){return _.error(`Snippet failed`,o(e)),{content:[{type:`text`,text:`Snippet failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}function E(n){let r=e(`env`);n.registerTool(`env`,{title:r.title,description:`Get system and runtime environment info. Sensitive env vars are redacted by default.`,outputSchema:t,inputSchema:{include_env:i.boolean().default(!1).describe(`Include environment variables`),filter_env:i.string().optional().describe(`Filter env vars by name substring`),show_sensitive:i.boolean().default(!1).describe(`Show sensitive values (keys, tokens, etc.) — redacted by default`)},annotations:r.annotations},async({include_env:e,filter_env:t,show_sensitive:n})=>{let r=l({includeEnv:e,filterEnv:t,showSensitive:n}),i=[`## Environment`,``,`**Platform:** ${r.system.platform} ${r.system.arch}`,`**OS:** ${r.system.type} ${r.system.release}`,`**Host:** ${r.system.hostname}`,`**CPUs:** ${r.system.cpus}`,`**Memory:** ${r.system.memoryFreeGb}GB free / ${r.system.memoryTotalGb}GB total`,``,`**Node:** ${r.runtime.node}`,`**V8:** ${r.runtime.v8}`,`**CWD:** ${r.cwd}`];if(r.env){i.push(``,`### Environment Variables`,``);for(let[e,t]of Object.entries(r.env))i.push(`- \`${e}\`: ${t}`)}let a={platform:r.system.platform,arch:r.system.arch,nodeVersion:r.runtime.node,cwd:r.cwd,cpus:r.system.cpus,memoryFreeGb:r.system.memoryFreeGb,memoryTotalGb:r.system.memoryTotalGb};return{content:[{type:`text`,text:i.join(`
+`)}],structuredContent:a}})}function D(t){let n=e(`time`);t.registerTool(`time`,{title:n.title,description:`Parse dates, convert timezones, calculate durations, add time. Supports ISO 8601, unix timestamps, and human-readable formats.`,outputSchema:r,inputSchema:{operation:i.enum([`now`,`parse`,`convert`,`diff`,`add`]).describe(`now: current time | parse: parse a date string | convert: timezone conversion | diff: duration between two dates | add: add duration to date`),input:i.string().optional().describe(`Date input (ISO, unix timestamp, or parseable string). For diff: two comma-separated dates`),timezone:i.string().optional().describe(`Target timezone (e.g., "America/New_York", "Asia/Tokyo")`),duration:i.string().optional().describe(`Duration to add (e.g., "2h30m", "1d", "30s") — for add operation`)},annotations:n.annotations},async({operation:e,input:t,timezone:n,duration:r})=>{try{let i=h({operation:e,input:t,timezone:n,duration:r}),a=[`**${i.output}**`,``,`ISO: ${i.iso}`,`Unix: ${i.unix}`];i.details&&a.push(``,"```json",JSON.stringify(i.details),"```");let o={iso:i.iso,unix:i.unix,timezone:n??Intl.DateTimeFormat().resolvedOptions().timeZone,formatted:i.output};return{content:[{type:`text`,text:a.join(`
+`)}],structuredContent:o}}catch(e){return _.error(`Time failed`,o(e)),{content:[{type:`text`,text:`Time failed: ${e instanceof Error?e.message:String(e)}`}],isError:!0}}})}export{C as registerChangelogTool,x as registerEncodeTool,E as registerEnvTool,y as registerHttpTool,S as registerMeasureTool,b as registerRegexTestTool,w as registerSchemaValidateTool,T as registerSnippetTool,D as registerTimeTool,v as registerWebSearchTool};

package/packages/server/dist/version-check.d.ts

@@ -0,0 +1,32 @@
+//#region packages/server/src/version-check.d.ts
+/**
+ * Non-blocking check for newer @vpxa/aikit versions on npm.
+ * Logs a warning to stderr if the running version is outdated.
+ * Auto-upgrades scaffold files when server version ≠ scaffold version.
+ */
+declare function getCurrentVersion(): string;
+/**
+ * Check for a newer version on npm and log a warning if outdated.
+ * This is fire-and-forget — it never throws and never blocks startup.
+ */
+declare function checkForUpdates(): void;
+/** Upgrade state visible to other modules (e.g. the status tool). */
+type UpgradeState = 'idle' | 'pending' | 'success' | 'failed';
+/** Return the current auto-upgrade state. */
+declare function getUpgradeState(): {
+  state: UpgradeState;
+  error: string | null;
+};
+/**
+ * Auto-upgrade scaffold files when the running server version differs from
+ * the installed scaffold version.  This is fire-and-forget — it never throws
+ * and never blocks startup.  The upgrade process runs in a detached child so
+ * the MCP server stays responsive.
+ *
+ * State is tracked via `getUpgradeState()` so the status tool can report
+ * whether the upgrade is pending, succeeded, or failed without asking the
+ * LLM to run a terminal command.
+ */
+declare function autoUpgradeScaffold(): void;
+//#endregion
+export { UpgradeState, autoUpgradeScaffold, checkForUpdates, getCurrentVersion, getUpgradeState };

package/packages/server/dist/version-check.js

@@ -0,0 +1 @@
+import{existsSync as e,readFileSync as t}from"node:fs";import{dirname as n,resolve as r}from"node:path";import{fileURLToPath as i}from"node:url";import{createLogger as a}from"../../core/dist/index.js";import{execFile as o}from"node:child_process";import{homedir as s}from"node:os";const c=a(`server`);function l(){let e=r(n(i(import.meta.url)),`..`,`..`,`..`,`package.json`);try{return JSON.parse(t(e,`utf-8`)).version??`0.0.0`}catch{return`0.0.0`}}function u(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=(n[e]??0)-(r[e]??0);if(t!==0)return t>0?1:-1}return 0}function d(){let e=l();fetch(`https://registry.npmjs.org/@vpxa/aikit/latest`,{signal:AbortSignal.timeout(5e3)}).then(e=>{if(e.ok)return e.json()}).then(t=>{if(!t||typeof t!=`object`)return;let n=t.version;n&&u(e,n)<0&&c.warn(`Update available`,{currentVersion:e,latestVersion:n,updateCommand:`aikit upgrade`})}).catch(()=>{})}function f(){try{let n=r(s(),`.copilot`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}function p(){try{let n=r(process.cwd(),`.github`,`.aikit-scaffold.json`);return e(n)?JSON.parse(t(n,`utf-8`)).version??null:null}catch{return null}}let m=`idle`,h=null;function g(){return{state:m,error:h}}function _(){try{let t=l(),a=f(),s=p();if(!(a!=null&&a!==t)&&!(s!=null&&s!==t)||m===`pending`||m===`success`)return;m=`pending`,h=null,c.info(`Scaffold version mismatch — auto-upgrading`,{serverVersion:t,userScaffoldVersion:a,workspaceScaffoldVersion:s});let u=r(n(i(import.meta.url)),`..`,`..`,`..`,`bin`,`aikit.mjs`);if(!e(u)){m=`failed`,h=`aikit CLI binary not found at ${u}`,c.warn(`Cannot auto-upgrade: aikit CLI binary not found`,{binPath:u});return}o(process.execPath,[u,`upgrade`],{timeout:3e4,windowsHide:!0},(e,t,n)=>{e?(m=`failed`,h=e.message,c.warn(`Auto-upgrade failed`,{error:e.message,stderr:n?.slice(0,500)})):(m=`success`,h=null,c.info(`Auto-upgrade complete`))}).unref()}catch(e){m=`failed`,h=e instanceof Error?e.message:String(e),c.warn(`Auto-upgrade check failed`,{error:h})}}export{_ as autoUpgradeScaffold,d as checkForUpdates,l as getCurrentVersion,g as getUpgradeState};

package/packages/store/dist/graph-store.interface.d.ts

@@ -0,0 +1,118 @@
+//#region packages/store/src/graph-store.interface.d.ts
+/**
+ * Knowledge graph store abstraction — typed nodes + edges for entity-relationship storage.
+ * Complements the vector store: vector search finds similar content,
+ * graph traversal finds connected concepts.
+ */
+/** A node in the knowledge graph (entity, concept, service, etc.) */
+interface GraphNode {
+  /** Unique identifier */
+  id: string;
+  /** Node type (e.g., 'entity', 'service', 'api', 'concept', 'decision') */
+  type: string;
+  /** Display name */
+  name: string;
+  /** Arbitrary properties */
+  properties: Record<string, unknown>;
+  /** Back-link to KnowledgeRecord.id that produced this node */
+  sourceRecordId?: string;
+  /** Source file path (for cleanup on re-index) */
+  sourcePath?: string;
+  /** ISO timestamp */
+  createdAt?: string;
+}
+/** An edge connecting two nodes */
+interface GraphEdge {
+  /** Unique identifier */
+  id: string;
+  /** Source node ID */
+  fromId: string;
+  /** Target node ID */
+  toId: string;
+  /** Relationship type (e.g., 'depends-on', 'implements', 'calls', 'affects') */
+  type: string;
+  /** Optional weight (0-1) */
+  weight?: number;
+  /** Arbitrary properties */
+  properties?: Record<string, unknown>;
+}
+/** Options for graph traversal */
+interface GraphTraversalOptions {
+  /** Relationship type filter */
+  edgeType?: string;
+  /** Max traversal depth (default: 2) */
+  maxDepth?: number;
+  /** Direction: outgoing from start, incoming to start, or both */
+  direction?: 'outgoing' | 'incoming' | 'both';
+  /** Max total nodes returned (default: 50) */
+  limit?: number;
+}
+/** Result of a graph traversal */
+interface GraphTraversalResult {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+/** Graph statistics */
+interface GraphStats {
+  nodeCount: number;
+  edgeCount: number;
+  nodeTypes: Record<string, number>;
+  edgeTypes: Record<string, number>;
+}
+/** Result of graph validation */
+interface GraphValidationResult {
+  valid: boolean;
+  orphanNodes: string[];
+  danglingEdges: Array<{
+    edgeId: string;
+    missingNodeId: string;
+  }>;
+  stats: GraphStats;
+}
+/** Knowledge graph store interface */
+interface IGraphStore {
+  /** Initialize the store (create tables, indices) */
+  initialize(): Promise<void>;
+  /** Add or update a single node */
+  upsertNode(node: GraphNode): Promise<void>;
+  /** Add or update a single edge */
+  upsertEdge(edge: GraphEdge): Promise<void>;
+  /** Batch add/update nodes */
+  upsertNodes(nodes: GraphNode[]): Promise<void>;
+  /** Batch add/update edges */
+  upsertEdges(edges: GraphEdge[]): Promise<void>;
+  /** Get a node by ID */
+  getNode(id: string): Promise<GraphNode | null>;
+  /** Get direct neighbors of a node */
+  getNeighbors(nodeId: string, options?: GraphTraversalOptions): Promise<GraphTraversalResult>;
+  /** Multi-hop traversal from a starting node */
+  traverse(startId: string, options?: GraphTraversalOptions): Promise<GraphTraversalResult>;
+  /** Find nodes by type and/or name pattern */
+  findNodes(filter: {
+    type?: string;
+    namePattern?: string;
+    sourcePath?: string;
+    limit?: number;
+  }): Promise<GraphNode[]>;
+  /** Find edges by type between optional node filters */
+  findEdges(filter: {
+    type?: string;
+    fromId?: string;
+    toId?: string;
+    limit?: number;
+  }): Promise<GraphEdge[]>;
+  /** Delete a node and all its edges */
+  deleteNode(id: string): Promise<void>;
+  /** Delete all nodes/edges originating from a source path */
+  deleteBySourcePath(sourcePath: string): Promise<number>;
+  /** Delete all nodes and edges (full reset) */
+  clear(): Promise<void>;
+  /** Get graph statistics */
+  getStats(): Promise<GraphStats>;
+  /** Validate graph integrity — check for orphan nodes and dangling edges */
+  validate(): Promise<GraphValidationResult>;
+  /** Close the store */
+  close(): Promise<void>;
+}
+//#endregion
+export { GraphEdge, GraphNode, GraphStats, GraphTraversalOptions, GraphTraversalResult, GraphValidationResult, IGraphStore };

package/packages/store/dist/graph-store.interface.js

@@ -0,0 +1 @@
+export{};

package/packages/store/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { GraphEdge, GraphNode, GraphStats, GraphTraversalOptions, GraphTraversalResult, GraphValidationResult, IGraphStore } from "./graph-store.interface.js";
+import { IKnowledgeStore, SearchOptions } from "./store.interface.js";
+import { LanceStore } from "./lance-store.js";
+import { SqliteGraphStore } from "./sqlite-graph-store.js";
+import { StoreBackend, StoreConfig, createStore } from "./store-factory.js";
+export { type GraphEdge, type GraphNode, type GraphStats, type GraphTraversalOptions, type GraphTraversalResult, type GraphValidationResult, type IGraphStore, type IKnowledgeStore, LanceStore, type SearchOptions, SqliteGraphStore, type StoreBackend, type StoreConfig, createStore };

package/packages/store/dist/index.js

@@ -0,0 +1 @@
+import{LanceStore as e}from"./lance-store.js";import{SqliteGraphStore as t}from"./sqlite-graph-store.js";import{createStore as n}from"./store-factory.js";export{e as LanceStore,t as SqliteGraphStore,n as createStore};

package/packages/store/dist/lance-store.d.ts

@@ -0,0 +1,44 @@
+import { IKnowledgeStore, SearchOptions } from "./store.interface.js";
+import { IndexStats, KnowledgeRecord, SearchResult } from "../../core/dist/index.js";
+
+//#region packages/store/src/lance-store.d.ts
+declare class LanceStore implements IKnowledgeStore {
+  private db;
+  private table;
+  private readonly dbPath;
+  private readonly tableName;
+  private _draining;
+  private _priorityQueue;
+  private _normalQueue;
+  private _ftsReady;
+  private enqueueWrite;
+  private _drain;
+  constructor(options?: {
+    path?: string;
+    tableName?: string;
+  });
+  initialize(): Promise<void>;
+  upsert(records: KnowledgeRecord[], vectors: Float32Array[]): Promise<void>;
+  upsertInteractive(records: KnowledgeRecord[], vectors: Float32Array[]): Promise<void>;
+  private _upsertImpl;
+  search(queryVector: Float32Array, options?: SearchOptions): Promise<SearchResult[]>;
+  createFtsIndex(): Promise<void>;
+  private _createFtsIndexImpl;
+  ftsSearch(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  getById(id: string): Promise<KnowledgeRecord | null>;
+  deleteBySourcePath(sourcePath: string): Promise<number>;
+  private _deleteBySourcePathImpl;
+  deleteById(id: string): Promise<boolean>;
+  deleteByIdInteractive(id: string): Promise<boolean>;
+  private _deleteByIdImpl;
+  getBySourcePath(sourcePath: string): Promise<KnowledgeRecord[]>;
+  getStats(): Promise<IndexStats>;
+  listSourcePaths(): Promise<string[]>;
+  dropTable(): Promise<void>;
+  private _dropTableImpl;
+  close(): Promise<void>;
+  private buildFilterString;
+  private fromLanceRecord;
+}
+//#endregion
+export { LanceStore };

package/packages/store/dist/lance-store.js

@@ -0,0 +1 @@
+import{EMBEDDING_DEFAULTS as e,SEARCH_DEFAULTS as t,STORE_DEFAULTS as n,createLogger as r,serializeError as i,sourceTypeContentTypes as a}from"../../core/dist/index.js";import{Index as o,connect as s}from"@lancedb/lancedb";function c(e){if(!e)return[];try{let t=JSON.parse(e);return Array.isArray(t)?t:[]}catch{return[]}}const l=/^[\w.\-/ ]+$/,u=r(`store`);function d(e,t){if(!l.test(e))throw Error(`Invalid ${t} filter value: contains disallowed characters`);return e.replace(/'/g,`''`)}var f=class{db=null;table=null;dbPath;tableName;_draining=!1;_priorityQueue=[];_normalQueue=[];_ftsReady=!1;enqueueWrite(e,t=!1){return new Promise((n,r)=>{let i=async()=>{try{n(await e())}catch(e){r(e)}};t?this._priorityQueue.push(i):this._normalQueue.push(i),this._drain()})}async _drain(){if(!this._draining){this._draining=!0;try{for(;this._priorityQueue.length>0||this._normalQueue.length>0;){let e=this._priorityQueue.shift()??this._normalQueue.shift();e&&await e()}}finally{this._draining=!1}}}constructor(e){this.dbPath=e?.path??n.path,this.tableName=e?.tableName??n.tableName}async initialize(){this.db=await s(this.dbPath),(await this.db.tableNames()).includes(this.tableName)&&(this.table=await this.db.openTable(this.tableName),await this.createFtsIndex())}async upsert(e,t){if(e.length!==0){if(e.length!==t.length)throw Error(`Record count (${e.length}) does not match vector count (${t.length})`);return this.enqueueWrite(()=>this._upsertImpl(e,t))}}async upsertInteractive(e,t){if(e.length!==0){if(e.length!==t.length)throw Error(`Record count (${e.length}) does not match vector count (${t.length})`);return this.enqueueWrite(()=>this._upsertImpl(e,t),!0)}}async _upsertImpl(e,t){let n=e.map((e,n)=>({id:e.id,vector:Array.from(t[n]),content:e.content,sourcePath:e.sourcePath,contentType:e.contentType,headingPath:e.headingPath??``,chunkIndex:e.chunkIndex,totalChunks:e.totalChunks,startLine:e.startLine,endLine:e.endLine,fileHash:e.fileHash,indexedAt:e.indexedAt,origin:e.origin,tags:JSON.stringify(e.tags),category:e.category??``,version:e.version}));if(this.table){let t=[...new Set(e.map(e=>e.sourcePath))];for(let e of t)try{await this.table.delete(`sourcePath = '${d(e,`sourcePath`)}'`)}catch{}await this.table.add(n)}else try{this.table=await this.db?.createTable(this.tableName,n)??null}catch(e){if(String(e).includes(`already exists`)&&this.db)this.table=await this.db.openTable(this.tableName),await this.table.add(n);else throw e}}async search(e,n){if(!this.table)return[];let r=n?.limit??t.maxResults,i=n?.minScore??t.minScore,a=this.table.search(e).limit(r*2),o=this.buildFilterString(n);return o&&(a=a.where(o)),(await a.toArray()).map(e=>({record:this.fromLanceRecord(e),score:1-(e._distance??1)})).filter(e=>e.score>=i).slice(0,r)}async createFtsIndex(){return this.enqueueWrite(()=>this._createFtsIndexImpl())}async _createFtsIndexImpl(){if(this.table)try{await this.table.createIndex(`content`,{config:o.fts(),replace:!0}),this._ftsReady=!0,u.info(`FTS index created/updated`,{column:`content`})}catch(e){u.warn(`FTS index creation failed`,i(e))}}async ftsSearch(e,n){if(!this.table||!this._ftsReady)return[];let r=n?.limit??t.maxResults;try{let t=this.table.search(e).limit(r*2),i=this.buildFilterString(n);return i&&(t=t.where(i)),(await t.toArray()).map(e=>({record:this.fromLanceRecord(e),score:e._score??e._relevance_score??0}))}catch(e){return(e instanceof Error?e.message:String(e)).includes(`INVERTED index`)?(u.debug(`FTS search skipped — index not yet available`),this._ftsReady=!1):u.warn(`FTS search failed`,i(e)),[]}}async getById(e){if(!this.table)return null;let t=await this.table.query().where(`id = '${d(e,`id`)}'`).limit(1).toArray();return t.length===0?null:this.fromLanceRecord(t[0])}async deleteBySourcePath(e){return this.enqueueWrite(()=>this._deleteBySourcePathImpl(e))}async _deleteBySourcePathImpl(e){if(!this.table)return 0;let t=await this.getBySourcePath(e);return t.length===0?0:(await this.table.delete(`sourcePath = '${d(e,`sourcePath`)}'`),t.length)}async deleteById(e){return this.enqueueWrite(()=>this._deleteByIdImpl(e))}async deleteByIdInteractive(e){return this.enqueueWrite(()=>this._deleteByIdImpl(e),!0)}async _deleteByIdImpl(e){return!this.table||!await this.getById(e)?!1:(await this.table.delete(`id = '${d(e,`id`)}'`),!0)}async getBySourcePath(e){return this.table?(await this.table.query().where(`sourcePath = '${d(e,`sourcePath`)}'`).limit(1e3).toArray()).map(e=>this.fromLanceRecord(e)):[]}async getStats(){if(!this.table)return{totalRecords:0,totalFiles:0,contentTypeBreakdown:{},lastIndexedAt:null,storeBackend:`lancedb`,embeddingModel:e.model};let t=await this.table.countRows(),n=await this.table.query().select([`sourcePath`,`contentType`,`indexedAt`]).limit(1e5).toArray(),r={},i=new Set,a=null;for(let e of n){let t=e;r[t.contentType]=(r[t.contentType]??0)+1,i.add(t.sourcePath),(!a||t.indexedAt>a)&&(a=t.indexedAt)}return{totalRecords:t,totalFiles:i.size,contentTypeBreakdown:r,lastIndexedAt:a,storeBackend:`lancedb`,embeddingModel:e.model}}async listSourcePaths(){if(!this.table)return[];let e=await this.table.query().select([`sourcePath`]).limit(1e5).toArray();return[...new Set(e.map(e=>e.sourcePath))]}async dropTable(){return this.enqueueWrite(()=>this._dropTableImpl())}async _dropTableImpl(){if(this.db&&(await this.db.tableNames()).includes(this.tableName))for(let e=1;e<=3;e++)try{await this.db.dropTable(this.tableName);break}catch(t){if(e===3)throw t;let n=e*500;u.warn(`dropTable attempt failed, retrying`,{attempt:e,delayMs:n}),await new Promise(e=>setTimeout(e,n))}this.table=null}async close(){try{this.db&&typeof this.db.close==`function`&&await this.db.close()}catch{}this.table=null,this.db=null}buildFilterString(e){let t=[];if(e?.contentType&&t.push(`contentType = '${d(e.contentType,`contentType`)}'`),e?.sourceType){let n=a(e.sourceType);if(n.length>0){let e=n.map(e=>`'${d(e,`sourceType`)}'`).join(`, `);t.push(`contentType IN (${e})`)}}if(e?.origin&&t.push(`origin = '${d(e.origin,`origin`)}'`),e?.category&&t.push(`category = '${d(e.category,`category`)}'`),e?.tags&&e.tags.length>0){let n=e.tags.map(e=>`tags LIKE '%${d(e,`tag`)}%'`);t.push(`(${n.join(` OR `)})`)}return t.length>0?t.join(` AND `):null}fromLanceRecord(e){return{id:e.id,content:e.content,sourcePath:e.sourcePath,contentType:e.contentType,headingPath:e.headingPath||void 0,chunkIndex:e.chunkIndex,totalChunks:e.totalChunks,startLine:e.startLine,endLine:e.endLine,fileHash:e.fileHash,indexedAt:e.indexedAt,origin:e.origin,tags:c(e.tags),category:e.category||void 0,version:e.version}}};export{f as LanceStore};

package/packages/store/dist/sqlite-graph-store.d.ts

@@ -0,0 +1,45 @@
+import { GraphEdge, GraphNode, GraphStats, GraphTraversalOptions, GraphTraversalResult, GraphValidationResult, IGraphStore } from "./graph-store.interface.js";
+
+//#region packages/store/src/sqlite-graph-store.d.ts
+declare class SqliteGraphStore implements IGraphStore {
+  private db;
+  private readonly dbPath;
+  private dirty;
+  constructor(options?: {
+    path?: string;
+  });
+  initialize(): Promise<void>;
+  private ensureDb;
+  private persist;
+  private markDirty;
+  private flushIfDirty;
+  private query;
+  private run;
+  upsertNode(node: GraphNode): Promise<void>;
+  upsertEdge(edge: GraphEdge): Promise<void>;
+  upsertNodes(nodes: GraphNode[]): Promise<void>;
+  upsertEdges(edges: GraphEdge[]): Promise<void>;
+  getNode(id: string): Promise<GraphNode | null>;
+  getNeighbors(nodeId: string, options?: GraphTraversalOptions): Promise<GraphTraversalResult>;
+  traverse(startId: string, options?: GraphTraversalOptions): Promise<GraphTraversalResult>;
+  findNodes(filter: {
+    type?: string;
+    namePattern?: string;
+    sourcePath?: string;
+    limit?: number;
+  }): Promise<GraphNode[]>;
+  findEdges(filter: {
+    type?: string;
+    fromId?: string;
+    toId?: string;
+    limit?: number;
+  }): Promise<GraphEdge[]>;
+  deleteNode(id: string): Promise<void>;
+  deleteBySourcePath(sourcePath: string): Promise<number>;
+  clear(): Promise<void>;
+  getStats(): Promise<GraphStats>;
+  validate(): Promise<GraphValidationResult>;
+  close(): Promise<void>;
+}
+//#endregion
+export { SqliteGraphStore };

package/packages/store/dist/sqlite-graph-store.js

@@ -0,0 +1,58 @@
+import{AIKIT_PATHS as e}from"../../core/dist/index.js";import{existsSync as t,mkdirSync as n,readFileSync as r,writeFileSync as i}from"node:fs";import{dirname as a,join as o}from"node:path";var s=class{db=null;dbPath;dirty=!1;constructor(t){this.dbPath=o(t?.path??e.data,`graph.db`)}async initialize(){let e=a(this.dbPath);t(e)||n(e,{recursive:!0});let i=(await import(`sql.js`)).default,o=await i();if(t(this.dbPath)){let e=r(this.dbPath);this.db=new o.Database(e)}else this.db=new o.Database;this.db.run(`PRAGMA journal_mode = WAL`),this.db.exec(`PRAGMA foreign_keys = ON;`),this.db.run(`
+      CREATE TABLE IF NOT EXISTS nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        name TEXT NOT NULL,
+        properties TEXT NOT NULL DEFAULT '{}',
+        source_record_id TEXT,
+        source_path TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `),this.db.run(`
+      CREATE TABLE IF NOT EXISTS edges (
+        id TEXT PRIMARY KEY,
+        from_id TEXT NOT NULL,
+        to_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        weight REAL DEFAULT 1.0,
+        properties TEXT NOT NULL DEFAULT '{}',
+        FOREIGN KEY (from_id) REFERENCES nodes(id) ON DELETE CASCADE,
+        FOREIGN KEY (to_id) REFERENCES nodes(id) ON DELETE CASCADE
+      )
+    `),this.db.run(`CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)`),this.db.run(`CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name)`),this.db.run(`CREATE INDEX IF NOT EXISTS idx_nodes_source_path ON nodes(source_path)`),this.db.run(`CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id)`),this.db.run(`CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_id)`),this.db.run(`CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type)`),this.persist()}ensureDb(){if(!this.db)throw Error(`Graph store not initialized — call initialize() first`);return this.db}persist(){if(!this.db)return;let e=this.db.export();try{i(this.dbPath,Buffer.from(e))}finally{this.db.exec(`PRAGMA foreign_keys = ON;`)}this.dirty=!1}markDirty(){this.dirty=!0}flushIfDirty(){this.dirty&&this.persist()}query(e,t=[]){let n=this.ensureDb().prepare(e);n.bind(t);let r=[];try{for(;n.step();)r.push(n.getAsObject())}finally{n.free()}return r}run(e,t=[]){this.ensureDb().run(e,t)}async upsertNode(e){this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         type = excluded.type, name = excluded.name, properties = excluded.properties,
+         source_record_id = excluded.source_record_id, source_path = excluded.source_path`,[e.id,e.type,e.name,JSON.stringify(e.properties),e.sourceRecordId??null,e.sourcePath??null,e.createdAt??new Date().toISOString()]),this.markDirty(),this.flushIfDirty()}async upsertEdge(e){this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, properties)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         from_id = excluded.from_id, to_id = excluded.to_id,
+         type = excluded.type, weight = excluded.weight, properties = excluded.properties`,[e.id,e.fromId,e.toId,e.type,e.weight??1,JSON.stringify(e.properties??{})]),this.markDirty(),this.flushIfDirty()}async upsertNodes(e){if(e.length===0)return;let t=this.ensureDb();t.run(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO nodes (id, type, name, properties, source_record_id, source_path, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             type = excluded.type, name = excluded.name, properties = excluded.properties,
+             source_record_id = excluded.source_record_id, source_path = excluded.source_path`,[t.id,t.type,t.name,JSON.stringify(t.properties),t.sourceRecordId??null,t.sourcePath??null,t.createdAt??new Date().toISOString()]);t.run(`COMMIT`)}catch(e){throw t.run(`ROLLBACK`),e}this.markDirty(),this.flushIfDirty()}async upsertEdges(e){if(e.length===0)return;let t=this.ensureDb();t.run(`PRAGMA foreign_keys = OFF`),t.run(`BEGIN TRANSACTION`);try{for(let t of e)this.run(`INSERT INTO edges (id, from_id, to_id, type, weight, properties)
+           VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             from_id = excluded.from_id, to_id = excluded.to_id,
+             type = excluded.type, weight = excluded.weight, properties = excluded.properties`,[t.id,t.fromId,t.toId,t.type,t.weight??1,JSON.stringify(t.properties??{})]);t.run(`COMMIT`)}catch(e){throw t.run(`ROLLBACK`),e}finally{t.run(`PRAGMA foreign_keys = ON`)}this.markDirty(),this.flushIfDirty()}async getNode(e){let t=this.query(`SELECT * FROM nodes WHERE id = ?`,[e]);return t.length>0?l(t[0]):null}async getNeighbors(e,t){let n=t?.direction??`both`,r=t?.edgeType,i=t?.limit??50,a=[],o=[],s=new Set;if(n===`outgoing`||n===`both`){let t=`
+      SELECT e.id AS edge_id, e.from_id, e.to_id, e.type AS edge_type, e.weight, e.properties AS edge_props,
+             n.id AS node_id, n.type AS node_type, n.name AS node_name, n.properties AS node_props,
+             n.source_record_id AS node_src_rec, n.source_path AS node_src_path, n.created_at AS node_created
+      FROM edges e JOIN nodes n ON e.to_id = n.id WHERE e.from_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(d(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(f(e)))}if(n===`incoming`||n===`both`){let t=`
+      SELECT e.id AS edge_id, e.from_id, e.to_id, e.type AS edge_type, e.weight, e.properties AS edge_props,
+             n.id AS node_id, n.type AS node_type, n.name AS node_name, n.properties AS node_props,
+             n.source_record_id AS node_src_rec, n.source_path AS node_src_path, n.created_at AS node_created
+      FROM edges e JOIN nodes n ON e.from_id = n.id WHERE e.to_id = ?`,n=[e];r&&(t+=` AND e.type = ?`,n.push(r)),t+=` LIMIT ?`,n.push(i);let c=this.query(t,n);for(let e of c)o.push(d(e)),s.has(e.node_id)||(s.add(e.node_id),a.push(f(e)))}return{nodes:a,edges:o}}async traverse(e,t){let n=t?.maxDepth??2,r=t?.direction??`both`,i=t?.edgeType,a=t?.limit??50,o=new Map,s=new Map,c=new Set,l=[{nodeId:e,depth:0}];for(;l.length>0&&o.size<a;){let e=l.shift();if(!e||c.has(e.nodeId)||e.depth>n)continue;c.add(e.nodeId);let t=await this.getNeighbors(e.nodeId,{direction:r,edgeType:i,limit:a-o.size});for(let r of t.nodes)o.has(r.id)||(o.set(r.id,r),e.depth+1<n&&l.push({nodeId:r.id,depth:e.depth+1}));for(let e of t.edges)s.set(e.id,e)}return{nodes:[...o.values()],edges:[...s.values()]}}async findNodes(e){let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.namePattern&&(t.push(`name LIKE ?`),n.push(`%${e.namePattern}%`)),e.sourcePath&&(t.push(`source_path = ?`),n.push(e.sourcePath));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM nodes ${r} LIMIT ?`,[...n,i]).map(e=>l(e))}async findEdges(e){let t=[],n=[];e.type&&(t.push(`type = ?`),n.push(e.type)),e.fromId&&(t.push(`from_id = ?`),n.push(e.fromId)),e.toId&&(t.push(`to_id = ?`),n.push(e.toId));let r=t.length>0?`WHERE ${t.join(` AND `)}`:``,i=e.limit??100;return this.query(`SELECT * FROM edges ${r} LIMIT ?`,[...n,i]).map(e=>u(e))}async deleteNode(e){let t=this.ensureDb();t.run(`BEGIN TRANSACTION`);try{this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e,e]),this.run(`DELETE FROM nodes WHERE id = ?`,[e]),t.run(`COMMIT`)}catch(e){throw t.run(`ROLLBACK`),e}this.markDirty(),this.flushIfDirty()}async deleteBySourcePath(e){let t=this.query(`SELECT id FROM nodes WHERE source_path = ?`,[e]);if(t.length===0)return 0;let n=this.ensureDb();n.run(`BEGIN TRANSACTION`);try{for(let e of t)this.run(`DELETE FROM edges WHERE from_id = ? OR to_id = ?`,[e.id,e.id]);this.run(`DELETE FROM nodes WHERE source_path = ?`,[e]),n.run(`COMMIT`)}catch(e){throw n.run(`ROLLBACK`),e}return this.markDirty(),this.flushIfDirty(),t.length}async clear(){this.run(`DELETE FROM edges`),this.run(`DELETE FROM nodes`),this.markDirty(),this.flushIfDirty()}async getStats(){let e=this.query(`SELECT COUNT(*) as count FROM nodes`)[0]?.count??0,t=this.query(`SELECT COUNT(*) as count FROM edges`)[0]?.count??0,n=this.query(`SELECT type, COUNT(*) as count FROM nodes GROUP BY type`),r={};for(let e of n)r[e.type]=e.count;let i=this.query(`SELECT type, COUNT(*) as count FROM edges GROUP BY type`),a={};for(let e of i)a[e.type]=e.count;return{nodeCount:e,edgeCount:t,nodeTypes:r,edgeTypes:a}}async validate(){let e=await this.getStats(),t=this.query(`SELECT e.id AS edgeId,
+              CASE
+                WHEN n1.id IS NULL THEN e.from_id
+                WHEN n2.id IS NULL THEN e.to_id
+              END AS missingNodeId
+       FROM edges e
+       LEFT JOIN nodes n1 ON e.from_id = n1.id
+       LEFT JOIN nodes n2 ON e.to_id = n2.id
+       WHERE n1.id IS NULL OR n2.id IS NULL`),n=this.query(`SELECT n.id AS id
+       FROM nodes n
+       LEFT JOIN edges e1 ON n.id = e1.from_id
+       LEFT JOIN edges e2 ON n.id = e2.to_id
+       WHERE e1.id IS NULL AND e2.id IS NULL`).map(e=>e.id);return{valid:t.length===0,orphanNodes:n,danglingEdges:t,stats:e}}async close(){this.db&&=(this.flushIfDirty(),this.db.close(),null)}};function c(e){if(!e)return{};try{return JSON.parse(e)}catch{return{}}}function l(e){return{id:e.id,type:e.type,name:e.name,properties:c(e.properties),sourceRecordId:e.source_record_id??void 0,sourcePath:e.source_path??void 0,createdAt:e.created_at}}function u(e){return{id:e.id,fromId:e.from_id,toId:e.to_id,type:e.type,weight:e.weight??1,properties:c(e.properties)}}function d(e){return{id:e.edge_id,fromId:e.from_id,toId:e.to_id,type:e.edge_type,weight:e.weight??1,properties:c(e.edge_props??`{}`)}}function f(e){return{id:e.node_id,type:e.node_type,name:e.node_name,properties:c(e.node_props??`{}`),sourceRecordId:e.node_src_rec??void 0,sourcePath:e.node_src_path??void 0,createdAt:e.node_created}}export{s as SqliteGraphStore};

package/packages/store/dist/store-factory.d.ts

@@ -0,0 +1,12 @@
+import { IKnowledgeStore } from "./store.interface.js";
+
+//#region packages/store/src/store-factory.d.ts
+type StoreBackend = 'lancedb' | 'sqlite-vec';
+interface StoreConfig {
+  backend: StoreBackend;
+  path: string;
+  options?: Record<string, unknown>;
+}
+declare function createStore(config: StoreConfig): Promise<IKnowledgeStore>;
+//#endregion
+export { StoreBackend, StoreConfig, createStore };

package/packages/store/dist/store-factory.js

@@ -0,0 +1 @@
+async function e(e){switch(e.backend){case`lancedb`:{let{LanceStore:t}=await import(`./lance-store.js`);return new t({path:e.path})}default:throw Error(`Unknown store backend: "${e.backend}". Supported: lancedb`)}}export{e as createStore};