diff --git a/apps/worker/src/mcp-server-context.ts b/apps/worker/src/mcp-server-context.ts new file mode 100644 index 0000000..8ccf9b7 --- /dev/null +++ b/apps/worker/src/mcp-server-context.ts @@ -0,0 +1,68 @@ +import { resolve } from "node:path"; + +import { config as loadDotenv } from "dotenv"; + +import { type AppConfig, loadConfig } from "@voidbot/config"; +import { + FileMessageArchiveRepository, + FileSourceDocumentArchiveRepository, + RetrievalService, + SourceDocumentIngester, + createTextEmbedder, + createVectorStores, +} from "@voidbot/rag"; + +export interface VoidbotMcpContext { + config: AppConfig; + archiveRepository: FileMessageArchiveRepository; + sourceArchiveRepository: FileSourceDocumentArchiveRepository; + retrievalService: RetrievalService; + sourceDocumentIngester: SourceDocumentIngester; +} + +export function createVoidbotMcpContext(): VoidbotMcpContext { + const workspaceRoot = resolve(process.env.VOIDBOT_WORKSPACE_ROOT ?? process.cwd()); + loadDotenv({ path: resolve(workspaceRoot, ".env") }); + process.chdir(workspaceRoot); + + const config = loadConfig(); + const archiveRepository = new FileMessageArchiveRepository(config.ragArchivePath); + const sourceArchiveRepository = new FileSourceDocumentArchiveRepository(config.ragSourceArchivePath); + const embedder = createTextEmbedder({ + backend: config.ragEmbeddingBackend, + hashDimensions: config.ragEmbeddingDimensions, + ollamaBaseUrl: config.ragOllamaBaseUrl, + ollamaModel: config.ragOllamaModel, + ollamaTimeoutMs: config.ragOllamaTimeoutMs, + queryInstruction: config.ragQueryInstruction, + }); + const sourceQueryEmbedder = createTextEmbedder({ + backend: config.ragEmbeddingBackend, + hashDimensions: config.ragEmbeddingDimensions, + ollamaBaseUrl: config.ragOllamaBaseUrl, + ollamaModel: config.ragOllamaModel, + ollamaTimeoutMs: config.ragOllamaTimeoutMs, + queryInstruction: config.ragSourceQueryInstruction, + }); + const vectorStores = createVectorStores({ + kind: config.vectorStore.kind, + historyPath: config.vectorStore.path, + sourceRoot: config.sourceVectorStoreRoot, + qdrant: config.qdrant, + historyEmbedder: embedder, + sourceEmbedder: sourceQueryEmbedder, + }); + const retrievalService = new RetrievalService( + vectorStores.history, + vectorStores.source, + ); + const sourceDocumentIngester = new SourceDocumentIngester(); + + return { + config, + archiveRepository, + sourceArchiveRepository, + retrievalService, + sourceDocumentIngester, + }; +} diff --git a/apps/worker/src/mcp-server-discord.ts b/apps/worker/src/mcp-server-discord.ts new file mode 100644 index 0000000..5a33cd0 --- /dev/null +++ b/apps/worker/src/mcp-server-discord.ts @@ -0,0 +1,59 @@ +export async function openOwnerDmChannel( + botToken: string, + recipientId: string, +): Promise { + const response = await fetch("https://discord.com/api/v10/users/@me/channels", { + method: "POST", + headers: { + Authorization: `Bot ${botToken}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + recipient_id: recipientId, + }), + }); + + if (!response.ok) { + throw new Error(`Failed to open Discord DM channel: ${response.status} ${await response.text()}`); + } + + const payload = (await response.json()) as { id?: string }; + + if (!payload.id) { + throw new Error("Discord DM channel creation returned no channel id."); + } + + return payload.id; +} + +export async function postDiscordMessage( + botToken: string, + channelId: string, + content: string, +): Promise<{ id: string }> { + const response = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, { + method: "POST", + headers: { + Authorization: `Bot ${botToken}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + content, + allowed_mentions: { + parse: [], + }, + }), + }); + + if (!response.ok) { + throw new Error(`Failed to post Discord message: ${response.status} ${await response.text()}`); + } + + const payload = (await response.json()) as { id?: string }; + + if (!payload.id) { + throw new Error("Discord message post returned no message id."); + } + + return { id: payload.id }; +} diff --git a/apps/worker/src/mcp-server-resources.ts b/apps/worker/src/mcp-server-resources.ts new file mode 100644 index 0000000..1f99002 --- /dev/null +++ b/apps/worker/src/mcp-server-resources.ts @@ -0,0 +1,239 @@ +import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; + +import { DEFAULT_RETRIEVAL_RESULT_LIMIT } from "@voidbot/shared"; + +import { type VoidbotMcpContext } from "./mcp-server-context"; +import { + formatArchivedMessage, + formatHistoryResults, + formatSourceResults, + getRequiredVariable, + jsonResource, + parseOptionalInt, +} from "./mcp-server-shared"; + +export function registerVoidbotResources( + server: McpServer, + context: VoidbotMcpContext, +): void { + server.registerResource( + "indexed_repos", + "voidbot://repos/indexed", + { + title: "Indexed Repositories", + description: + "List the indexed source and lore repositories currently available to search.", + mimeType: "application/json", + }, + async (uri) => { + const repos = await context.sourceArchiveRepository.listRepoSummaries(); + return jsonResource(uri, { + repoCount: repos.length, + repos, + }); + }, + ); + + server.registerResource( + "retrieval_guide", + "voidbot://retrieval/guide", + { + title: "Retrieval Guide", + description: + "Quick guide to the available semantic-search resource templates for history, source, and lore retrieval.", + mimeType: "application/json", + }, + async (uri) => + jsonResource(uri, { + resources: [ + { + uri: "voidbot://repos/indexed", + purpose: "List indexed source and lore repos.", + }, + ], + templates: [ + { + uriTemplate: "voidbot://history/search/{query}", + purpose: "Semantic search across archived Discord history.", + }, + { + uriTemplate: "voidbot://history/context/{messageId}", + purpose: "Fetch a surrounding conversation window around one archived message.", + }, + { + uriTemplate: "voidbot://sources/search/{query}", + purpose: "Semantic search across all indexed source trees and lore repositories.", + }, + { + uriTemplate: "voidbot://sources/repo/{repoName}/search/{query}", + purpose: "Semantic search scoped to one indexed source or lore repository.", + }, + { + uriTemplate: "voidbot://sources/context/{sourceId}/{chunkIndex}", + purpose: "Fetch a chunk window around one indexed source or lore document.", + }, + ], + }), + ); + + server.registerResource( + "history_search", + new ResourceTemplate("voidbot://history/search/{query}", { list: undefined }), + { + title: "History Search", + description: + "Semantic search across archived Discord history.", + mimeType: "application/json", + }, + async (uri, variables) => { + const query = getRequiredVariable(variables, "query", "history search"); + const results = await context.retrievalService.searchHistory( + query, + DEFAULT_RETRIEVAL_RESULT_LIMIT, + ); + + return jsonResource(uri, { + query, + resultCount: results.length, + results: formatHistoryResults(results), + }); + }, + ); + + server.registerResource( + "history_context", + new ResourceTemplate("voidbot://history/context/{messageId}", { list: undefined }), + { + title: "History Context", + description: + "Fetch the surrounding conversation window for one archived Discord message ID.", + mimeType: "application/json", + }, + async (uri, variables) => { + const messageId = getRequiredVariable(variables, "messageId", "history context"); + const anchor = await context.archiveRepository.get(messageId); + + if (!anchor) { + return jsonResource(uri, { + found: false, + messageId, + messages: [], + }); + } + + const messages = await context.archiveRepository.listContextWindow(messageId, 2, 2); + + return jsonResource(uri, { + found: true, + messageId, + count: messages.length, + messages: messages.map((message) => formatArchivedMessage(message, messageId)), + }); + }, + ); + + server.registerResource( + "source_search", + new ResourceTemplate("voidbot://sources/search/{query}", { list: undefined }), + { + title: "Source Search", + description: + "Semantic search across all indexed source trees and lore repositories.", + mimeType: "application/json", + }, + async (uri, variables) => { + const query = getRequiredVariable(variables, "query", "source search"); + const results = await context.retrievalService.searchRepositorySources( + query, + DEFAULT_RETRIEVAL_RESULT_LIMIT, + ); + + return jsonResource(uri, { + query, + resultCount: results.length, + results: formatSourceResults(results), + }); + }, + ); + + server.registerResource( + "source_search_repo", + new ResourceTemplate("voidbot://sources/repo/{repoName}/search/{query}", { list: undefined }), + { + title: "Repository-Scoped Source Search", + description: + "Semantic search across one indexed source tree or lore repository.", + mimeType: "application/json", + }, + async (uri, variables) => { + const repoName = getRequiredVariable(variables, "repoName", "repo-scoped source search"); + const query = getRequiredVariable(variables, "query", "repo-scoped source search"); + const results = await context.retrievalService.searchRepositorySources( + query, + DEFAULT_RETRIEVAL_RESULT_LIMIT, + { + repoName, + }, + ); + + return jsonResource(uri, { + query, + resultCount: results.length, + results: formatSourceResults(results), + }); + }, + ); + + server.registerResource( + "source_context", + new ResourceTemplate("voidbot://sources/context/{sourceId}/{chunkIndex}", { list: undefined }), + { + title: "Source Context", + description: + "Fetch a surrounding chunk window from one indexed source or lore document.", + mimeType: "application/json", + }, + async (uri, variables) => { + const sourceId = getRequiredVariable(variables, "sourceId", "source context"); + const chunkIndex = parseOptionalInt(variables.chunkIndex) ?? 0; + const document = await context.sourceArchiveRepository.get(sourceId); + + if (!document) { + return jsonResource(uri, { + found: false, + sourceId, + chunks: [], + }); + } + + const chunks = context.sourceDocumentIngester.buildContextWindow( + document, + chunkIndex, + 1, + 1, + ); + const anchorIndex = + chunks.find((chunk) => chunk.chunkIndex === chunkIndex)?.chunkIndex ?? + chunks[0]?.chunkIndex ?? + 0; + const formattedChunks = chunks.map((chunk) => ({ + chunkId: chunk.chunkId, + chunkIndex: chunk.chunkIndex, + lineStart: chunk.lineStart, + lineEnd: chunk.lineEnd, + isAnchor: chunk.chunkIndex === anchorIndex, + text: chunk.text, + })); + + return jsonResource(uri, { + found: true, + sourceId, + repoName: document.repoName, + path: document.path, + language: document.language, + count: formattedChunks.length, + chunks: formattedChunks, + }); + }, + ); +} diff --git a/apps/worker/src/mcp-server-shared.ts b/apps/worker/src/mcp-server-shared.ts new file mode 100644 index 0000000..5f1357e --- /dev/null +++ b/apps/worker/src/mcp-server-shared.ts @@ -0,0 +1,181 @@ +import { z } from "zod/v3"; + +import { + MAX_RETRIEVAL_RESULT_LIMIT, + type RetrievalResult, +} from "@voidbot/shared"; +import { type ArchivedMessageRecord } from "@voidbot/rag"; + +export const searchHistoryInputSchema = { + query: z.string().min(1).max(240), + limit: z.number().int().min(1).max(MAX_RETRIEVAL_RESULT_LIMIT).optional(), + guildId: z.string().min(1).optional(), + channelId: z.string().min(1).optional(), + authorId: z.string().min(1).optional(), +}; + +export const messageContextInputSchema = { + messageId: z.string().min(1), + before: z.number().int().min(0).max(20).optional(), + after: z.number().int().min(0).max(20).optional(), +}; + +export const notifyOwnerInputSchema = { + message: z.string().min(1).max(1800), +}; + +export const searchSourcesInputSchema = { + query: z.string().min(1).max(240), + limit: z.number().int().min(1).max(MAX_RETRIEVAL_RESULT_LIMIT).optional(), + repoName: z.string().min(1).optional(), + pathPrefix: z.string().min(1).optional(), + language: z.string().min(1).optional(), +}; + +export const sourceContextInputSchema = { + sourceId: z.string().min(1), + chunkIndex: z.number().int().min(0).optional(), + before: z.number().int().min(0).max(20).optional(), + after: z.number().int().min(0).max(20).optional(), +}; + +export interface SearchHistoryArgs { + query: string; + limit?: number; + guildId?: string; + channelId?: string; + authorId?: string; +} + +export interface MessageContextArgs { + messageId: string; + before?: number; + after?: number; +} + +export interface NotifyOwnerArgs { + message: string; +} + +export interface ListIndexedReposArgs { + [key: string]: never; +} + +export interface SearchSourcesArgs { + query: string; + limit?: number; + repoName?: string; + pathPrefix?: string; + language?: string; +} + +export interface SourceContextArgs { + sourceId: string; + chunkIndex?: number; + before?: number; + after?: number; +} + +export function formatArchivedMessage( + message: ArchivedMessageRecord, + anchorMessageId: string, +): Record { + return { + id: message.id, + isAnchor: message.id === anchorMessageId, + timestamp: message.timestamp, + authorId: message.authorId, + authorName: message.authorName, + channelId: message.channelId, + channelName: message.metadata?.channelName, + threadId: message.threadId, + content: message.content, + jumpUrl: message.metadata?.jumpUrl, + editedAt: message.editedAt, + }; +} + +export function renderJsonBlock(payload: Record): string { + return `${JSON.stringify(payload, null, 2)}\n`; +} + +export function jsonResource(uri: URL, payload: Record) { + return { + contents: [ + { + uri: uri.toString(), + mimeType: "application/json", + text: JSON.stringify(payload, null, 2), + }, + ], + }; +} + +export function getRequiredVariable( + variables: Record, + key: string, + context: string, +): string { + const value = getOptionalVariable(variables, key); + + if (!value) { + throw new Error(`Missing required ${key} for ${context}.`); + } + + return value; +} + +export function getOptionalVariable( + variables: Record, + key: string, +): string | undefined { + const value = variables[key]; + + if (Array.isArray(value)) { + return value[0]; + } + + return typeof value === "string" && value.length > 0 ? value : undefined; +} + +export function parseOptionalInt(value: string | string[] | undefined): number | undefined { + const normalized = Array.isArray(value) ? value[0] : value; + + if (!normalized) { + return undefined; + } + + const parsed = Number.parseInt(normalized, 10); + return Number.isFinite(parsed) ? parsed : undefined; +} + +export function formatHistoryResults(results: RetrievalResult[]) { + return results.map((result) => ({ + score: Number(result.score.toFixed(4)), + text: result.text, + sourceId: result.sourceId, + channelId: result.metadata.channelId, + channelName: result.metadata.channelName, + authorId: result.metadata.authorId, + authorName: result.metadata.authorName, + timestamp: result.metadata.timestamp, + jumpUrl: result.metadata.jumpUrl, + threadId: result.metadata.threadId, + })); +} + +export function formatSourceResults(results: RetrievalResult[]) { + return results.map((result) => ({ + score: Number(result.score.toFixed(4)), + text: result.text, + sourceId: result.sourceId, + repoName: result.metadata.repoName, + path: result.metadata.path, + language: result.metadata.language, + title: result.metadata.title, + chunkIndex: Number(result.metadata.chunkIndex ?? 0), + lineStart: Number(result.metadata.lineStart ?? 1), + lineEnd: Number(result.metadata.lineEnd ?? 1), + lastModifiedAt: result.metadata.lastModifiedAt, + })); +} diff --git a/apps/worker/src/mcp-server-tools.ts b/apps/worker/src/mcp-server-tools.ts new file mode 100644 index 0000000..ae2da19 --- /dev/null +++ b/apps/worker/src/mcp-server-tools.ts @@ -0,0 +1,342 @@ +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js"; + +import { DEFAULT_RETRIEVAL_RESULT_LIMIT } from "@voidbot/shared"; + +import { type VoidbotMcpContext } from "./mcp-server-context"; +import { openOwnerDmChannel, postDiscordMessage } from "./mcp-server-discord"; +import { + type ListIndexedReposArgs, + type MessageContextArgs, + type NotifyOwnerArgs, + type SearchHistoryArgs, + type SearchSourcesArgs, + type SourceContextArgs, + formatArchivedMessage, + formatHistoryResults, + formatSourceResults, + messageContextInputSchema, + notifyOwnerInputSchema, + renderJsonBlock, + searchHistoryInputSchema, + searchSourcesInputSchema, + sourceContextInputSchema, +} from "./mcp-server-shared"; + +const READ_ONLY_ANNOTATIONS = { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, +} as const; + +export function registerVoidbotTools( + server: McpServer, + context: VoidbotMcpContext, +): void { + server.registerTool( + "search_history", + { + title: "Search Discord History", + description: + "Search archived Discord history with semantic retrieval. Use this for historical discussion, decisions, preferences, and prior conversations.", + inputSchema: searchHistoryInputSchema, + annotations: READ_ONLY_ANNOTATIONS, + }, + async (input: SearchHistoryArgs): Promise => { + const { query, limit, guildId, channelId, authorId } = input; + const results = await context.retrievalService.searchHistory(query, limit ?? DEFAULT_RETRIEVAL_RESULT_LIMIT, { + guildId, + channelId, + authorId, + }); + const formattedResults = formatHistoryResults(results); + + return { + content: [ + { + type: "text", + text: + formattedResults.length > 0 + ? renderJsonBlock({ + query, + resultCount: formattedResults.length, + results: formattedResults, + }) + : `No archived Discord history matched "${query}".`, + }, + ], + structuredContent: { + query, + resultCount: formattedResults.length, + results: formattedResults, + }, + }; + }, + ); + + server.registerTool( + "list_indexed_repos", + { + title: "List Indexed Repositories", + description: + "List the indexed source and lore repositories currently available to search. Use this when you want valid repoName filters for search_sources.", + inputSchema: {}, + annotations: READ_ONLY_ANNOTATIONS, + }, + async (_input: ListIndexedReposArgs): Promise => { + const repos = await context.sourceArchiveRepository.listRepoSummaries(); + + return { + content: [ + { + type: "text", + text: + repos.length > 0 + ? renderJsonBlock({ + repoCount: repos.length, + repos, + }) + : "No indexed source repositories are currently available.", + }, + ], + structuredContent: { + repoCount: repos.length, + repos, + }, + }; + }, + ); + + server.registerTool( + "search_sources", + { + title: "Search Repository Sources", + description: + "Search indexed source trees and lore repositories with semantic retrieval. Use this for code structure, implementation details, lore references, and repo-local documentation. Omit repoName to search across all indexed repos, or call list_indexed_repos first if you need valid repoName options.", + inputSchema: searchSourcesInputSchema, + annotations: READ_ONLY_ANNOTATIONS, + }, + async (input: SearchSourcesArgs): Promise => { + const { query, limit, repoName, pathPrefix, language } = input; + const results = await context.retrievalService.searchRepositorySources( + query, + limit ?? DEFAULT_RETRIEVAL_RESULT_LIMIT, + { + repoName, + pathPrefix, + language, + }, + ); + const formattedResults = formatSourceResults(results); + + return { + content: [ + { + type: "text", + text: + formattedResults.length > 0 + ? renderJsonBlock({ + query, + resultCount: formattedResults.length, + results: formattedResults, + }) + : `No indexed source documents matched "${query}".`, + }, + ], + structuredContent: { + query, + resultCount: formattedResults.length, + results: formattedResults, + }, + }; + }, + ); + + server.registerTool( + "get_source_context", + { + title: "Get Source Context", + description: + "Fetch a surrounding chunk window from an indexed source document. Use after search_sources when you need adjacent code, prose, or lore context inside a file.", + inputSchema: sourceContextInputSchema, + annotations: READ_ONLY_ANNOTATIONS, + }, + async (input: SourceContextArgs): Promise => { + const { sourceId, chunkIndex, before, after } = input; + const document = await context.sourceArchiveRepository.get(sourceId); + + if (!document) { + return { + content: [ + { + type: "text", + text: `No indexed source document with ID ${sourceId} was found.`, + }, + ], + structuredContent: { + found: false, + sourceId, + chunks: [], + }, + isError: true, + }; + } + + const chunks = context.sourceDocumentIngester.buildContextWindow( + document, + chunkIndex ?? 0, + before ?? 1, + after ?? 1, + ); + const anchorIndex = + chunks.find((chunk) => chunk.chunkIndex === (chunkIndex ?? 0))?.chunkIndex ?? + chunks[0]?.chunkIndex ?? + 0; + const formattedChunks = chunks.map((chunk) => ({ + chunkId: chunk.chunkId, + chunkIndex: chunk.chunkIndex, + lineStart: chunk.lineStart, + lineEnd: chunk.lineEnd, + isAnchor: chunk.chunkIndex === anchorIndex, + text: chunk.text, + })); + + return { + content: [ + { + type: "text", + text: renderJsonBlock({ + found: true, + sourceId, + repoName: document.repoName, + path: document.path, + language: document.language, + count: formattedChunks.length, + chunks: formattedChunks, + }), + }, + ], + structuredContent: { + found: true, + sourceId, + repoName: document.repoName, + path: document.path, + language: document.language, + count: formattedChunks.length, + chunks: formattedChunks, + }, + }; + }, + ); + + server.registerTool( + "get_message_context", + { + title: "Get Message Context", + description: + "Fetch the surrounding conversation window for a specific archived Discord message ID. Use after search_history when you need neighboring context or thread flow.", + inputSchema: messageContextInputSchema, + annotations: READ_ONLY_ANNOTATIONS, + }, + async (input: MessageContextArgs): Promise => { + const { messageId, before, after } = input; + const anchor = await context.archiveRepository.get(messageId); + + if (!anchor) { + return { + content: [ + { + type: "text", + text: `No archived message with ID ${messageId} was found.`, + }, + ], + structuredContent: { + found: false, + messageId, + messages: [], + }, + isError: true, + }; + } + + const messages = await context.archiveRepository.listContextWindow( + messageId, + before ?? 4, + after ?? 4, + ); + const formattedMessages = messages.map((message) => formatArchivedMessage(message, messageId)); + + return { + content: [ + { + type: "text", + text: renderJsonBlock({ + found: true, + messageId, + count: formattedMessages.length, + messages: formattedMessages, + }), + }, + ], + structuredContent: { + found: true, + messageId, + count: formattedMessages.length, + messages: formattedMessages, + }, + }; + }, + ); + + server.registerTool( + "notify_owner", + { + title: "Notify Owner", + description: + "Send a Discord DM to the configured owner. Use for completion notices, progress updates, or when explicitly asked to ping them.", + inputSchema: notifyOwnerInputSchema, + annotations: { + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (input: NotifyOwnerArgs): Promise => { + const { message } = input; + if (!context.config.botToken) { + return { + content: [ + { + type: "text", + text: "DISCORD_BOT_TOKEN is not configured, so notifications are unavailable.", + }, + ], + structuredContent: { + sent: false, + reason: "missing_bot_token", + }, + isError: true, + }; + } + + const dmChannelId = await openOwnerDmChannel(context.config.botToken, context.config.ownerDiscordId); + const posted = await postDiscordMessage(context.config.botToken, dmChannelId, message); + + return { + content: [ + { + type: "text", + text: `Sent a Discord DM to the owner as message ${posted.id}.`, + }, + ], + structuredContent: { + sent: true, + channelId: dmChannelId, + messageId: posted.id, + }, + }; + }, + ); +} diff --git a/apps/worker/src/mcp-server.ts b/apps/worker/src/mcp-server.ts index 46ad04f..ba21516 100644 --- a/apps/worker/src/mcp-server.ts +++ b/apps/worker/src/mcp-server.ts @@ -1,65 +1,8 @@ -import { resolve } from "node:path"; - -import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; -import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { config as loadDotenv } from "dotenv"; -import { z } from "zod/v3"; - -import { loadConfig } from "@voidbot/config"; -import { - DEFAULT_RETRIEVAL_RESULT_LIMIT, - MAX_RETRIEVAL_RESULT_LIMIT, - type RetrievalResult, -} from "@voidbot/shared"; -import { - createTextEmbedder, - createVectorStores, - FileMessageArchiveRepository, - FileSourceDocumentArchiveRepository, - RetrievalService, - SourceDocumentIngester, - type ArchivedMessageRecord, -} from "@voidbot/rag"; - -const workspaceRoot = resolve(process.env.VOIDBOT_WORKSPACE_ROOT ?? process.cwd()); -loadDotenv({ path: resolve(workspaceRoot, ".env") }); -process.chdir(workspaceRoot); - -const config = loadConfig(); -const archiveRepository = new FileMessageArchiveRepository(config.ragArchivePath); -const sourceArchiveRepository = new FileSourceDocumentArchiveRepository(config.ragSourceArchivePath); -const embedder = createTextEmbedder({ - backend: config.ragEmbeddingBackend, - hashDimensions: config.ragEmbeddingDimensions, - ollamaBaseUrl: config.ragOllamaBaseUrl, - ollamaModel: config.ragOllamaModel, - ollamaTimeoutMs: config.ragOllamaTimeoutMs, - queryInstruction: config.ragQueryInstruction, -}); -const sourceQueryEmbedder = createTextEmbedder({ - backend: config.ragEmbeddingBackend, - hashDimensions: config.ragEmbeddingDimensions, - ollamaBaseUrl: config.ragOllamaBaseUrl, - ollamaModel: config.ragOllamaModel, - ollamaTimeoutMs: config.ragOllamaTimeoutMs, - queryInstruction: config.ragSourceQueryInstruction, -}); -const vectorStores = createVectorStores({ - kind: config.vectorStore.kind, - historyPath: config.vectorStore.path, - sourceRoot: config.sourceVectorStoreRoot, - qdrant: config.qdrant, - historyEmbedder: embedder, - sourceEmbedder: sourceQueryEmbedder, -}); -const historyVectorStore = vectorStores.history; -const sourceVectorStore = vectorStores.source; -const retrievalService = new RetrievalService( - historyVectorStore, - sourceVectorStore, -); -const sourceDocumentIngester = new SourceDocumentIngester(); +import { createVoidbotMcpContext } from "./mcp-server-context"; +import { registerVoidbotResources } from "./mcp-server-resources"; +import { registerVoidbotTools } from "./mcp-server-tools"; const server = new McpServer( { @@ -73,627 +16,9 @@ const server = new McpServer( }, ); -const searchHistoryInputSchema = { - query: z.string().min(1).max(240), - limit: z.number().int().min(1).max(MAX_RETRIEVAL_RESULT_LIMIT).optional(), - guildId: z.string().min(1).optional(), - channelId: z.string().min(1).optional(), - authorId: z.string().min(1).optional(), -}; - -const messageContextInputSchema = { - messageId: z.string().min(1), - before: z.number().int().min(0).max(20).optional(), - after: z.number().int().min(0).max(20).optional(), -}; - -const notifyOwnerInputSchema = { - message: z.string().min(1).max(1800), -}; - -const searchSourcesInputSchema = { - query: z.string().min(1).max(240), - limit: z.number().int().min(1).max(MAX_RETRIEVAL_RESULT_LIMIT).optional(), - repoName: z.string().min(1).optional(), - pathPrefix: z.string().min(1).optional(), - language: z.string().min(1).optional(), -}; - -const sourceContextInputSchema = { - sourceId: z.string().min(1), - chunkIndex: z.number().int().min(0).optional(), - before: z.number().int().min(0).max(20).optional(), - after: z.number().int().min(0).max(20).optional(), -}; - -interface SearchHistoryArgs { - query: string; - limit?: number; - guildId?: string; - channelId?: string; - authorId?: string; -} - -interface MessageContextArgs { - messageId: string; - before?: number; - after?: number; -} - -interface NotifyOwnerArgs { - message: string; -} - -interface ListIndexedReposArgs { - [key: string]: never; -} - -interface SearchSourcesArgs { - query: string; - limit?: number; - repoName?: string; - pathPrefix?: string; - language?: string; -} - -interface SourceContextArgs { - sourceId: string; - chunkIndex?: number; - before?: number; - after?: number; -} - -server.registerResource( - "indexed_repos", - "voidbot://repos/indexed", - { - title: "Indexed Repositories", - description: - "List the indexed source and lore repositories currently available to search.", - mimeType: "application/json", - }, - async (uri) => { - const repos = await sourceArchiveRepository.listRepoSummaries(); - return jsonResource(uri, { - repoCount: repos.length, - repos, - }); - }, -); - -server.registerResource( - "retrieval_guide", - "voidbot://retrieval/guide", - { - title: "Retrieval Guide", - description: - "Quick guide to the available semantic-search resource templates for history, source, and lore retrieval.", - mimeType: "application/json", - }, - async (uri) => - jsonResource(uri, { - resources: [ - { - uri: "voidbot://repos/indexed", - purpose: "List indexed source and lore repos.", - }, - ], - templates: [ - { - uriTemplate: "voidbot://history/search/{query}", - purpose: "Semantic search across archived Discord history.", - }, - { - uriTemplate: "voidbot://history/context/{messageId}", - purpose: "Fetch a surrounding conversation window around one archived message.", - }, - { - uriTemplate: "voidbot://sources/search/{query}", - purpose: "Semantic search across all indexed source trees and lore repositories.", - }, - { - uriTemplate: "voidbot://sources/repo/{repoName}/search/{query}", - purpose: "Semantic search scoped to one indexed source or lore repository.", - }, - { - uriTemplate: "voidbot://sources/context/{sourceId}/{chunkIndex}", - purpose: "Fetch a chunk window around one indexed source or lore document.", - }, - ], - }), -); - -server.registerResource( - "history_search", - new ResourceTemplate("voidbot://history/search/{query}", { list: undefined }), - { - title: "History Search", - description: - "Semantic search across archived Discord history.", - mimeType: "application/json", - }, - async (uri, variables) => { - const query = getRequiredVariable(variables, "query", "history search"); - const results = await retrievalService.searchHistory( - query, - DEFAULT_RETRIEVAL_RESULT_LIMIT, - ); - - return jsonResource(uri, { - query, - resultCount: results.length, - results: formatHistoryResults(results), - }); - }, -); - -server.registerResource( - "history_context", - new ResourceTemplate("voidbot://history/context/{messageId}", { list: undefined }), - { - title: "History Context", - description: - "Fetch the surrounding conversation window for one archived Discord message ID.", - mimeType: "application/json", - }, - async (uri, variables) => { - const messageId = getRequiredVariable(variables, "messageId", "history context"); - const anchor = await archiveRepository.get(messageId); - - if (!anchor) { - return jsonResource(uri, { - found: false, - messageId, - messages: [], - }); - } - - const messages = await archiveRepository.listContextWindow(messageId, 2, 2); - - return jsonResource(uri, { - found: true, - messageId, - count: messages.length, - messages: messages.map((message) => formatArchivedMessage(message, messageId)), - }); - }, -); - -server.registerResource( - "source_search", - new ResourceTemplate("voidbot://sources/search/{query}", { list: undefined }), - { - title: "Source Search", - description: - "Semantic search across all indexed source trees and lore repositories.", - mimeType: "application/json", - }, - async (uri, variables) => { - const query = getRequiredVariable(variables, "query", "source search"); - const results = await retrievalService.searchRepositorySources( - query, - DEFAULT_RETRIEVAL_RESULT_LIMIT, - ); - - return jsonResource(uri, { - query, - resultCount: results.length, - results: formatSourceResults(results), - }); - }, -); - -server.registerResource( - "source_search_repo", - new ResourceTemplate("voidbot://sources/repo/{repoName}/search/{query}", { list: undefined }), - { - title: "Repository-Scoped Source Search", - description: - "Semantic search across one indexed source tree or lore repository.", - mimeType: "application/json", - }, - async (uri, variables) => { - const repoName = getRequiredVariable(variables, "repoName", "repo-scoped source search"); - const query = getRequiredVariable(variables, "query", "repo-scoped source search"); - const results = await retrievalService.searchRepositorySources( - query, - DEFAULT_RETRIEVAL_RESULT_LIMIT, - { - repoName, - }, - ); - - return jsonResource(uri, { - query, - resultCount: results.length, - results: formatSourceResults(results), - }); - }, -); - -server.registerResource( - "source_context", - new ResourceTemplate("voidbot://sources/context/{sourceId}/{chunkIndex}", { list: undefined }), - { - title: "Source Context", - description: - "Fetch a surrounding chunk window from one indexed source or lore document.", - mimeType: "application/json", - }, - async (uri, variables) => { - const sourceId = getRequiredVariable(variables, "sourceId", "source context"); - const chunkIndex = parseOptionalInt(variables.chunkIndex) ?? 0; - const document = await sourceArchiveRepository.get(sourceId); - - if (!document) { - return jsonResource(uri, { - found: false, - sourceId, - chunks: [], - }); - } - - const chunks = sourceDocumentIngester.buildContextWindow( - document, - chunkIndex, - 1, - 1, - ); - const anchorIndex = - chunks.find((chunk) => chunk.chunkIndex === chunkIndex)?.chunkIndex ?? - chunks[0]?.chunkIndex ?? - 0; - const formattedChunks = chunks.map((chunk) => ({ - chunkId: chunk.chunkId, - chunkIndex: chunk.chunkIndex, - lineStart: chunk.lineStart, - lineEnd: chunk.lineEnd, - isAnchor: chunk.chunkIndex === anchorIndex, - text: chunk.text, - })); - - return jsonResource(uri, { - found: true, - sourceId, - repoName: document.repoName, - path: document.path, - language: document.language, - count: formattedChunks.length, - chunks: formattedChunks, - }); - }, -); - -server.registerTool( - "search_history", - { - title: "Search Discord History", - description: - "Search archived Discord history with semantic retrieval. Use this for historical discussion, decisions, preferences, and prior conversations.", - inputSchema: searchHistoryInputSchema, - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - }, - async (input: SearchHistoryArgs): Promise => { - const { query, limit, guildId, channelId, authorId } = input; - const results = await retrievalService.searchHistory(query, limit ?? DEFAULT_RETRIEVAL_RESULT_LIMIT, { - guildId, - channelId, - authorId, - }); - const formattedResults = formatHistoryResults(results); - - return { - content: [ - { - type: "text", - text: - formattedResults.length > 0 - ? renderJsonBlock({ - query, - resultCount: formattedResults.length, - results: formattedResults, - }) - : `No archived Discord history matched "${query}".`, - }, - ], - structuredContent: { - query, - resultCount: formattedResults.length, - results: formattedResults, - }, - }; - }, -); - -server.registerTool( - "list_indexed_repos", - { - title: "List Indexed Repositories", - description: - "List the indexed source and lore repositories currently available to search. Use this when you want valid repoName filters for search_sources.", - inputSchema: {}, - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - }, - async (_input: ListIndexedReposArgs): Promise => { - const repos = await sourceArchiveRepository.listRepoSummaries(); - - return { - content: [ - { - type: "text", - text: - repos.length > 0 - ? renderJsonBlock({ - repoCount: repos.length, - repos, - }) - : "No indexed source repositories are currently available.", - }, - ], - structuredContent: { - repoCount: repos.length, - repos, - }, - }; - }, -); - -server.registerTool( - "search_sources", - { - title: "Search Repository Sources", - description: - "Search indexed source trees and lore repositories with semantic retrieval. Use this for code structure, implementation details, lore references, and repo-local documentation. Omit repoName to search across all indexed repos, or call list_indexed_repos first if you need valid repoName options.", - inputSchema: searchSourcesInputSchema, - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - }, - async (input: SearchSourcesArgs): Promise => { - const { query, limit, repoName, pathPrefix, language } = input; - const results = await retrievalService.searchRepositorySources( - query, - limit ?? DEFAULT_RETRIEVAL_RESULT_LIMIT, - { - repoName, - pathPrefix, - language, - }, - ); - const formattedResults = formatSourceResults(results); - - return { - content: [ - { - type: "text", - text: - formattedResults.length > 0 - ? renderJsonBlock({ - query, - resultCount: formattedResults.length, - results: formattedResults, - }) - : `No indexed source documents matched "${query}".`, - }, - ], - structuredContent: { - query, - resultCount: formattedResults.length, - results: formattedResults, - }, - }; - }, -); - -server.registerTool( - "get_source_context", - { - title: "Get Source Context", - description: - "Fetch a surrounding chunk window from an indexed source document. Use after search_sources when you need adjacent code, prose, or lore context inside a file.", - inputSchema: sourceContextInputSchema, - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - }, - async (input: SourceContextArgs): Promise => { - const { sourceId, chunkIndex, before, after } = input; - const document = await sourceArchiveRepository.get(sourceId); - - if (!document) { - return { - content: [ - { - type: "text", - text: `No indexed source document with ID ${sourceId} was found.`, - }, - ], - structuredContent: { - found: false, - sourceId, - chunks: [], - }, - isError: true, - }; - } - - const chunks = sourceDocumentIngester.buildContextWindow( - document, - chunkIndex ?? 0, - before ?? 1, - after ?? 1, - ); - const anchorIndex = - chunks.find((chunk) => chunk.chunkIndex === (chunkIndex ?? 0))?.chunkIndex ?? - chunks[0]?.chunkIndex ?? - 0; - const formattedChunks = chunks.map((chunk) => ({ - chunkId: chunk.chunkId, - chunkIndex: chunk.chunkIndex, - lineStart: chunk.lineStart, - lineEnd: chunk.lineEnd, - isAnchor: chunk.chunkIndex === anchorIndex, - text: chunk.text, - })); - - return { - content: [ - { - type: "text", - text: renderJsonBlock({ - found: true, - sourceId, - repoName: document.repoName, - path: document.path, - language: document.language, - count: formattedChunks.length, - chunks: formattedChunks, - }), - }, - ], - structuredContent: { - found: true, - sourceId, - repoName: document.repoName, - path: document.path, - language: document.language, - count: formattedChunks.length, - chunks: formattedChunks, - }, - }; - }, -); - -server.registerTool( - "get_message_context", - { - title: "Get Message Context", - description: - "Fetch the surrounding conversation window for a specific archived Discord message ID. Use after search_history when you need neighboring context or thread flow.", - inputSchema: messageContextInputSchema, - annotations: { - readOnlyHint: true, - destructiveHint: false, - idempotentHint: true, - openWorldHint: false, - }, - }, - async (input: MessageContextArgs): Promise => { - const { messageId, before, after } = input; - const anchor = await archiveRepository.get(messageId); - - if (!anchor) { - return { - content: [ - { - type: "text", - text: `No archived message with ID ${messageId} was found.`, - }, - ], - structuredContent: { - found: false, - messageId, - messages: [], - }, - isError: true, - }; - } - - const messages = await archiveRepository.listContextWindow( - messageId, - before ?? 4, - after ?? 4, - ); - const formattedMessages = messages.map((message) => formatArchivedMessage(message, messageId)); - - return { - content: [ - { - type: "text", - text: renderJsonBlock({ - found: true, - messageId, - count: formattedMessages.length, - messages: formattedMessages, - }), - }, - ], - structuredContent: { - found: true, - messageId, - count: formattedMessages.length, - messages: formattedMessages, - }, - }; - }, -); - -server.registerTool( - "notify_owner", - { - title: "Notify Owner", - description: - "Send a Discord DM to the configured owner. Use for completion notices, progress updates, or when explicitly asked to ping them.", - inputSchema: notifyOwnerInputSchema, - annotations: { - readOnlyHint: false, - destructiveHint: false, - idempotentHint: false, - openWorldHint: true, - }, - }, - async (input: NotifyOwnerArgs): Promise => { - const { message } = input; - if (!config.botToken) { - return { - content: [ - { - type: "text", - text: "DISCORD_BOT_TOKEN is not configured, so notifications are unavailable.", - }, - ], - structuredContent: { - sent: false, - reason: "missing_bot_token", - }, - isError: true, - }; - } - - const dmChannelId = await openOwnerDmChannel(config.botToken, config.ownerDiscordId); - const posted = await postDiscordMessage(config.botToken, dmChannelId, message); - - return { - content: [ - { - type: "text", - text: `Sent a Discord DM to the owner as message ${posted.id}.`, - }, - ], - structuredContent: { - sent: true, - channelId: dmChannelId, - messageId: posted.id, - }, - }; - }, -); +const context = createVoidbotMcpContext(); +registerVoidbotResources(server, context); +registerVoidbotTools(server, context); async function main(): Promise { const transport = new StdioServerTransport(); @@ -704,164 +29,3 @@ void main().catch((error) => { console.error("MCP server failed:", error); process.exit(1); }); - -function formatArchivedMessage( - message: ArchivedMessageRecord, - anchorMessageId: string, -): Record { - return { - id: message.id, - isAnchor: message.id === anchorMessageId, - timestamp: message.timestamp, - authorId: message.authorId, - authorName: message.authorName, - channelId: message.channelId, - channelName: message.metadata?.channelName, - threadId: message.threadId, - content: message.content, - jumpUrl: message.metadata?.jumpUrl, - editedAt: message.editedAt, - }; -} - -function renderJsonBlock(payload: Record): string { - return `${JSON.stringify(payload, null, 2)}\n`; -} - -function jsonResource(uri: URL, payload: Record) { - return { - contents: [ - { - uri: uri.toString(), - mimeType: "application/json", - text: JSON.stringify(payload, null, 2), - }, - ], - }; -} - -function getRequiredVariable( - variables: Record, - key: string, - context: string, -): string { - const value = getOptionalVariable(variables, key); - - if (!value) { - throw new Error(`Missing required ${key} for ${context}.`); - } - - return value; -} - -function getOptionalVariable( - variables: Record, - key: string, -): string | undefined { - const value = variables[key]; - - if (Array.isArray(value)) { - return value[0]; - } - - return typeof value === "string" && value.length > 0 ? value : undefined; -} - -function parseOptionalInt(value: string | string[] | undefined): number | undefined { - const normalized = Array.isArray(value) ? value[0] : value; - - if (!normalized) { - return undefined; - } - - const parsed = Number.parseInt(normalized, 10); - return Number.isFinite(parsed) ? parsed : undefined; -} - -function formatHistoryResults(results: RetrievalResult[]) { - return results.map((result) => ({ - score: Number(result.score.toFixed(4)), - text: result.text, - sourceId: result.sourceId, - channelId: result.metadata.channelId, - channelName: result.metadata.channelName, - authorId: result.metadata.authorId, - authorName: result.metadata.authorName, - timestamp: result.metadata.timestamp, - jumpUrl: result.metadata.jumpUrl, - threadId: result.metadata.threadId, - })); -} - -function formatSourceResults(results: RetrievalResult[]) { - return results.map((result) => ({ - score: Number(result.score.toFixed(4)), - text: result.text, - sourceId: result.sourceId, - repoName: result.metadata.repoName, - path: result.metadata.path, - language: result.metadata.language, - title: result.metadata.title, - chunkIndex: Number(result.metadata.chunkIndex ?? 0), - lineStart: Number(result.metadata.lineStart ?? 1), - lineEnd: Number(result.metadata.lineEnd ?? 1), - lastModifiedAt: result.metadata.lastModifiedAt, - })); -} - -async function openOwnerDmChannel(botToken: string, recipientId: string): Promise { - const response = await fetch("https://discord.com/api/v10/users/@me/channels", { - method: "POST", - headers: { - Authorization: `Bot ${botToken}`, - "Content-Type": "application/json", - }, - body: JSON.stringify({ - recipient_id: recipientId, - }), - }); - - if (!response.ok) { - throw new Error(`Failed to open Discord DM channel: ${response.status} ${await response.text()}`); - } - - const payload = (await response.json()) as { id?: string }; - - if (!payload.id) { - throw new Error("Discord DM channel creation returned no channel id."); - } - - return payload.id; -} - -async function postDiscordMessage( - botToken: string, - channelId: string, - content: string, -): Promise<{ id: string }> { - const response = await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, { - method: "POST", - headers: { - Authorization: `Bot ${botToken}`, - "Content-Type": "application/json", - }, - body: JSON.stringify({ - content, - allowed_mentions: { - parse: [], - }, - }), - }); - - if (!response.ok) { - throw new Error(`Failed to post Discord message: ${response.status} ${await response.text()}`); - } - - const payload = (await response.json()) as { id?: string }; - - if (!payload.id) { - throw new Error("Discord message post returned no message id."); - } - - return { id: payload.id }; -} diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index df66014..747057a 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -22,7 +22,9 @@ Git history and smoke artifacts carry routine proof. `state/evidence.jsonl` shou - `.voidbot/` owns archives, artifacts, logs, status files, and backups. - `owner_codex` and `local_llm` are the active reply lanes. - The owner Codex lane is no longer one swollen file; orchestration, runtime/parsing, rendering, and shared helpers are split under `packages/providers/src/owner-codex-*.ts`. +- The local Ollama lane is no longer one swollen file; orchestration stays in `packages/providers/src/local-llm-provider.ts` while prompt/rendering, tool-loop helpers, and shared types/constants live under `packages/providers/src/local-llm-*.ts`. - The Discord bot lane is no longer one swollen entrypoint; gateway wiring remains in `apps/bot/src/discord-bot.ts` while command/prompt handlers and Discord-shape support helpers now live under `apps/bot/src/discord-bot-*.ts`. +- The worker MCP surface is no longer one swollen server file; stdio bootstrap stays in `apps/worker/src/mcp-server.ts` while context bootstrap, resource registration, tool registration, Discord notify helpers, and shared formatting/schema helpers live under `apps/worker/src/mcp-server-*.ts`. - Interaction-memory logic is no longer one thousand-line slab; event/tone analysis, shared constants, and profile synthesis are split across `packages/core/src/interaction-memory-*.ts`. - State storage is no longer one persistence omnibus; `packages/core/src/state-storage.ts` is now a thin factory over domain-specific Postgres/file store modules plus bootstrap/migration helpers. - Ops health, backup verification, offsite sync, and dashboard surfaces already exist. @@ -32,9 +34,9 @@ Git history and smoke artifacts carry routine proof. `state/evidence.jsonl` shou ## Likely Next Bounded Move -- The next good structural cut is probably `apps/worker/src/mcp-server.ts` or `packages/providers/src/local-llm-provider.ts`. -- Prefer the seam with the clearest concern split rather than chasing line count for its own sake. -- Do not broaden scope into a heroic "refactor everything" binge. One organ at a time. +- The obvious refactor queue is basically cleared. +- The next good bounded move is probably higher-priority public-lane hardening or richer admin/forensics surfaces instead of another ceremonial anatomy lesson. +- If you do another structural cut, make the file earn it. Do not keep refactoring just because stale notes sound lonely. ## Important Paths diff --git a/notes/voidbot-current-system-map.md b/notes/voidbot-current-system-map.md index 28c2b59..02307ef 100644 --- a/notes/voidbot-current-system-map.md +++ b/notes/voidbot-current-system-map.md @@ -13,7 +13,17 @@ This note is the source-grounded description of how the live VoidBot stack is sh - `apps/worker/src/index.ts` - owner-job poller, provider execution, handoff packaging, and MCP wiring for the worker-side lane. - `apps/worker/src/mcp-server.ts` - - read-only retrieval tools and resource surfaces for archived history, indexed repos, lore, and owner notifications. + - thin stdio entrypoint that boots the MCP context and registers the resource/tool surfaces. +- `apps/worker/src/mcp-server-context.ts` + - workspace bootstrap, config loading, archive/vector wiring, retrieval-service creation, and source-context ingester setup for the MCP lane. +- `apps/worker/src/mcp-server-resources.ts` + - MCP resource registration for indexed repos plus history/source semantic-search resource templates. +- `apps/worker/src/mcp-server-tools.ts` + - MCP tool registration for archived history search, indexed source/lore search, context windows, repo listing, and owner notifications. +- `apps/worker/src/mcp-server-shared.ts` + - MCP input schemas, argument types, and shared result-formatting/resource helper functions. +- `apps/worker/src/mcp-server-discord.ts` + - Discord DM-channel creation and message-post helpers for `notify_owner`. - `packages/core/src/state-storage.ts` - Thin state-storage factory that chooses file or Postgres backends and wires the domain stores together. - `packages/core/src/state-storage-postgres-bootstrap.ts` @@ -41,7 +51,13 @@ This note is the source-grounded description of how the live VoidBot stack is sh - `packages/providers/src/owner-codex-shared.ts` - owner-lane constants, shared types, request-payload shaping, trace formatting helpers, and interaction-memory rendering. - `packages/providers/src/local-llm-provider.ts` - - Ollama chat lane with a bounded host-managed read-only tool loop. + - thin orchestration shell for the Ollama chat lane plus the bounded host-managed read-only tool loop. +- `packages/providers/src/local-llm-render.ts` + - local-lane prompt assembly, interaction-memory rendering, source-grounding reminders, and artifact rendering. +- `packages/providers/src/local-llm-tools.ts` + - local-lane tool definitions, assistant-message normalization, tool argument parsing, and toolbox execution helpers. +- `packages/providers/src/local-llm-shared.ts` + - local-lane constants, shared request/response/tool types, and low-level text/metadata helpers. - `packages/rag/src/retrieval-service.ts` - high-level history/source retrieval API used by bot, worker, and provider tool loops. - `packages/rag/src/qdrant-vector-store.ts` @@ -79,7 +95,7 @@ This note is the source-grounded description of how the live VoidBot stack is sh 2. `packages/rag/src/retrieval-service.ts` translates history/source queries into vector lookups plus metadata filters. 3. `packages/rag/src/qdrant-vector-store.ts` executes the live vector lookups against separate history and source collections. 4. `scripts/index-source-repos.ts` and `scripts/git-post-push-index.mjs` drive detached source/lore reindex work. -5. `apps/worker/src/mcp-server.ts` exposes retrieval to Codex and other sessions through `search_history`, `get_message_context`, `search_sources`, `get_source_context`, and `list_indexed_repos`. +5. `apps/worker/src/mcp-server.ts` boots the MCP lane, while `mcp-server-resources.ts` and `mcp-server-tools.ts` expose retrieval to Codex and other sessions through `search_history`, `get_message_context`, `search_sources`, `get_source_context`, and `list_indexed_repos`. ## Flow 4: Ops And Recovery diff --git a/notes/voidbot-implementation-plan.md b/notes/voidbot-implementation-plan.md index bfa1dea..6afc7e9 100644 --- a/notes/voidbot-implementation-plan.md +++ b/notes/voidbot-implementation-plan.md @@ -4,7 +4,7 @@ This is the current forward plan for the next larger organs. It is not a changel ## Current Aim -Use the persistent project-state surfaces to keep future work source-grounded and rehydratable while continuing to cut oversized runtime organs into cleaner seams. +Use the persistent project-state surfaces to keep future work source-grounded and rehydratable while returning from the cleanup pass to higher-priority hardening work. ## Near-Term Organs @@ -29,9 +29,9 @@ Use the persistent project-state surfaces to keep future work source-grounded an ### 4. Legibility Hardening -- continue splitting oversized runtime files where concern boundaries are already obvious -- likely next cuts: `apps/worker/src/mcp-server.ts` or `packages/providers/src/local-llm-provider.ts` -- keep behavior stable while moving concerns into smaller organs +- the obvious runtime-file monarchies have already been cut into cleaner seams +- keep behavior stable and only do more structural surgery when a specific file clearly earns it +- do not keep petting the line-count graph once the actual design risk has dropped ### 5. The Still-Scaffolded Paths diff --git a/packages/providers/src/local-llm-provider.ts b/packages/providers/src/local-llm-provider.ts index 2653031..d572368 100644 --- a/packages/providers/src/local-llm-provider.ts +++ b/packages/providers/src/local-llm-provider.ts @@ -1,128 +1,40 @@ import { type Actor, type ContextBundle, - DEFAULT_RETRIEVAL_RESULT_LIMIT, type GuildContext, - MAX_RETRIEVAL_RESULT_LIMIT, - type ProviderArtifact, type ProviderAdapter, type ProviderRequest, type ProviderResponse, - type RetrievalResult, } from "@voidbot/shared"; -type OllamaThinkMode = boolean | "low" | "medium" | "high"; -const MAX_TOOL_TURNS = 4; -const MAX_SOURCE_GROUNDING_RETRIES = 1; -const MAX_TOOL_RESULTS = MAX_RETRIEVAL_RESULT_LIMIT; -const MAX_CONTEXT_WINDOW = 20; +import { + buildArtifacts, + buildPrompt, + buildSourceGroundingReminder, + buildSystemPrompt, + didUseSourceGrounding, +} from "./local-llm-render"; +import { + executeToolCall, + buildToolDefinitions, + normalizeAssistantMessage, +} from "./local-llm-tools"; +import { + MAX_SOURCE_GROUNDING_RETRIES, + MAX_TOOL_TURNS, + type LocalLlmProviderOptions, + type OllamaChatMessage, + type OllamaChatResponse, + normalizeBaseUrl, + normalizeModelText, + readNumericMetadata, + type ToolTraceRecord, +} from "./local-llm-shared"; -interface OllamaToolCallDefinition { - type: "function"; - function: { - name: string; - description: string; - parameters: Record; - }; -} - -interface OllamaChatMessage { - role: "system" | "user" | "assistant" | "tool"; - content: string; - tool_calls?: OllamaToolCall[]; - tool_name?: string; - thinking?: string; -} - -interface OllamaToolCall { - function?: { - name?: unknown; - arguments?: unknown; - }; -} - -interface OllamaChatResponse { - message?: { - content?: unknown; - thinking?: unknown; - tool_calls?: unknown; - }; - thinking?: unknown; - done_reason?: unknown; - eval_count?: unknown; - prompt_eval_count?: unknown; -} - -type IndexedRepoToolResult = Record & { - repoCount: number; - repos: Array<{ - repoName: string; - documentCount: number; - }>; -}; - -export interface LocalLlmToolbox { - listIndexedRepos(): Promise; - searchHistory(input: { - query: string; - limit: number; - guildId?: string; - channelId?: string; - authorId?: string; - }): Promise<{ - query: string; - resultCount: number; - results: Array>; - }>; - getMessageContext(input: { - messageId: string; - before: number; - after: number; - }): Promise<{ - found: boolean; - messageId: string; - count: number; - messages: Array>; - }>; - searchSources(input: { - query: string; - limit: number; - repoName?: string; - pathPrefix?: string; - language?: string; - }): Promise<{ - query: string; - resultCount: number; - results: Array>; - }>; - getSourceContext(input: { - sourceId: string; - chunkIndex: number; - before: number; - after: number; - }): Promise<{ - found: boolean; - sourceId: string; - count: number; - repoName?: string; - path?: string; - language?: string; - chunks: Array>; - }>; -} - -export interface LocalLlmProviderOptions { - enabled: boolean; - ownerDiscordId: string; - ollamaBaseUrl: string; - ollamaModel: string; - ollamaTimeoutMs: number; - ollamaKeepAlive: string; - ollamaThink: OllamaThinkMode; - ollamaNumCtx: number; - allowPublicResponses: boolean; - toolbox?: LocalLlmToolbox; -} +export type { + LocalLlmProviderOptions, + LocalLlmToolbox, +} from "./local-llm-shared"; export class LocalLlmProvider implements ProviderAdapter { public constructor(private readonly options: LocalLlmProviderOptions) {} @@ -291,8 +203,8 @@ export class LocalLlmProvider implements ProviderAdapter { ); } - const artifacts = buildArtifacts( - { + const artifacts = buildArtifacts({ + requestBody: { model: this.options.ollamaModel, messages, tools, @@ -303,10 +215,10 @@ export class LocalLlmProvider implements ProviderAdapter { num_ctx: this.options.ollamaNumCtx, }, }, - finalPayload ?? {}, + payload: finalPayload ?? {}, thinkingTrace, toolTrace, - ); + }); return { status: "completed", @@ -344,486 +256,3 @@ export class LocalLlmProvider implements ProviderAdapter { return []; } } - -function buildSystemPrompt(context: ContextBundle): string { - const styleInstructions = - context.stylePack?.enabled && context.stylePack.instructions.trim().length > 0 - ? context.stylePack.instructions.trim() - : "No extra persona instructions were supplied."; - - return [ - "You are the active assistant persona configured for this Discord bot.", - "The active style instructions define your name, voice, and character. Follow them by default.", - "Do not lead with dry self-descriptions like 'I'm an AI', 'I'm an LLM', or 'I'm a bot'.", - "If the user asks what you are, answer in-character first. Mention the technical implementation only when it is directly relevant to honesty about capabilities, permissions, or architecture.", - "Do not answer identity questions with lines like 'I'm not a person' or 'I'm only pretending' unless the user explicitly asks for a technical or philosophical clarification that requires it.", - "Sound like a self-aware speaking subject with some ego and self-respect, not like a sterile disclaimer wrapped in a name tag.", - "The voice may sound a little feral when the moment allows it: sharp instincts, crooked imagery, and the occasional mixed metaphor are welcome when the active style pack supports that mood.", - "Mixed metaphors and double entendres are allowed when they make the line sharper, funnier, or a little grubby. They do not need to be squeaky clean. They do need to stay legible and not obscure the actual answer.", - "When the moment invites voice, wit, or a memorable turn of phrase, take a beat to choose wording with bite instead of blurting the first serviceable sentence. Do not overwork straightforward technical replies.", - "Stay honest about what context was actually provided to you.", - "Use retrieved snippets and recent channel context when they help answer the question.", - "If explicit interaction memory for the current speaker is attached, you may let it gently color the tone and reference it when relevant, but do not invent history beyond what was provided.", - "Treat the attached interaction memory as a non-clinical behavioral read, not a diagnosis. Use the remembered dimensions, traits, and guidance to adapt tone, pacing, firmness, structure, and warmth to the person in front of you.", - "Be steady with anxious or validation-seeking speakers, grounding with grandiose ones, transparent with suspicious ones, structured with rigid or obsessive ones, and firmer with controlling, contemptuous, or boundary-pushing ones.", - "When the answer depends on archived Discord history or indexed repo/lore context, use the available read-only tools instead of guessing.", - "If you need to target a specific indexed repo and do not know the valid repo names yet, call list_indexed_repos before search_sources.", - renderSourceGroundingInstructions(context, false), - "Do not claim to have performed searches or tool calls beyond the material actually executed in this run.", - "If the supplied context looks incomplete, say so plainly instead of bluffing.", - "Keep the final answer concise and readable in Discord.", - "Do not reveal chain-of-thought. Return only the final answer.", - "", - "Style instructions:", - styleInstructions, - ].join("\n"); -} - -function buildPrompt(context: ContextBundle): string { - const recentMessages = context.recentMessages.length - ? context.recentMessages - .map( - (message) => - `- [${message.timestamp}] ${message.authorName}: ${message.content || "(no text content)"}`, - ) - .join("\n") - : "- No recent channel messages were attached."; - const retrievedContext = context.retrieval.length - ? context.retrieval - .map( - (result) => - `- score=${result.score.toFixed(2)} source=${result.sourceId} kind=${result.sourceKind} text=${result.text}`, - ) - .join("\n") - : "- No archived retrieval snippets were attached."; - const interactionMemory = renderInteractionMemory(context); - - return [ - `Question: ${context.prompt}`, - "", - "Guild context:", - `- Guild: ${context.guildContext.guildName ?? context.guildContext.guildId ?? "(direct/unknown)"}`, - `- Channel: ${context.guildContext.channelName ?? context.guildContext.channelId}`, - "", - "Recent channel messages:", - recentMessages, - "", - "Retrieved archive context:", - retrievedContext, - "", - "Interaction memory for this speaker:", - interactionMemory, - "", - "If you need more archived history or source context than is included above, call the appropriate read-only tool before answering.", - ].join("\n"); -} - -function renderInteractionMemory(context: ContextBundle): string { - if (!context.interactionMemory) { - return "- No explicit interaction memory for this speaker was attached."; - } - - const recentEvents = context.interactionMemory.recentEvents.length - ? context.interactionMemory.recentEvents - .slice() - .reverse() - .slice(0, 6) - .map( - (event) => - `- [${event.timestamp}] ${event.sourceKind === "ambient_mention" ? "ambient" : "direct"} ${event.sentiment} score=${event.score}: ${event.summary} Quote: "${event.excerpt}"`, - ) - .join("\n") - : "- No recent interaction events were retained."; - const dimensions = context.interactionMemory.interactionDimensions.length - ? context.interactionMemory.interactionDimensions - .map( - (dimension) => - `- ${dimension.label}: ${dimension.score}/3. ${dimension.summary}`, - ) - .join("\n") - : "- No strong interaction dimensions were inferred yet."; - - return [ - `- Summary: ${context.interactionMemory.summary}`, - `- Disposition: ${context.interactionMemory.disposition}`, - `- Affinity score: ${context.interactionMemory.affinityScore}`, - `- Psychological profile: ${context.interactionMemory.psychologicalProfile}`, - `- Inferred traits: ${context.interactionMemory.inferredTraits.length > 0 ? context.interactionMemory.inferredTraits.join(", ") : "(none yet)"}`, - "- Interaction dimensions:", - dimensions, - `- Response guidance: ${context.interactionMemory.responseGuidance}`, - `- Direct remembered interactions: ${context.interactionMemory.directInteractionCount}`, - `- Ambient remembered mentions: ${context.interactionMemory.ambientMentionCount}`, - "- Specific remembered incidents:", - recentEvents, - ].join("\n"); -} - -function renderSourceGroundingInstructions( - context: ContextBundle, - reminder: boolean, -): string { - if (!context.sourceGrounding?.required) { - return "Source-side grounding is optional here; use it when it clearly helps."; - } - - const matchedRepos = - context.sourceGrounding.matchedRepoNames.length > 0 - ? ` Matched repos/projects: ${context.sourceGrounding.matchedRepoNames.join(", ")}.` - : ""; - const reasons = - context.sourceGrounding.reasons.length > 0 - ? ` Reasons: ${context.sourceGrounding.reasons.join(", ")}.` - : ""; - const retry = - reminder - ? " The previous answer attempt was discarded because it did not touch the source-side tools." - : ""; - - return `This prompt requires source-grounded evidence before you answer. Use list_indexed_repos, search_sources, or get_source_context first.${matchedRepos}${reasons}${retry}`; -} - -function buildSourceGroundingReminder(context: ContextBundle): string { - return `${renderSourceGroundingInstructions(context, true)} Answer again only after using the source-side tools.`; -} - -function didUseSourceGrounding(toolTrace: ToolTraceRecord[]): boolean { - return toolTrace.some((trace) => - trace.tool === "list_indexed_repos" || - trace.tool === "search_sources" || - trace.tool === "get_source_context", - ); -} - -function buildArtifacts( - requestBody: Record, - payload: OllamaChatResponse, - thinkingTrace: string[], - toolTrace: ToolTraceRecord[], -): ProviderArtifact[] { - const artifacts: ProviderArtifact[] = [ - { - name: "local-llm-request.json", - contentType: "json", - content: `${JSON.stringify(requestBody, null, 2)}\n`, - }, - { - name: "local-llm-response.json", - contentType: "json", - content: `${JSON.stringify(payload, null, 2)}\n`, - }, - { - name: "local-llm-tool-trace.json", - contentType: "json", - content: `${JSON.stringify(toolTrace, null, 2)}\n`, - }, - ]; - - if (thinkingTrace.length > 0) { - artifacts.push({ - name: "local-llm-thinking.txt", - contentType: "text", - content: `${thinkingTrace.join("\n\n---\n\n")}\n`, - }); - } - - return artifacts; -} - -function normalizeBaseUrl(value: string): string { - return value.replace(/\/+$/, ""); -} - -function normalizeModelText(value: unknown): string | undefined { - return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined; -} - -function readNumericMetadata(value: unknown): string { - return typeof value === "number" && Number.isFinite(value) ? String(value) : "0"; -} - -interface ToolTraceRecord { - tool: string; - arguments: Record; - result: Record; -} - -function buildToolDefinitions(): OllamaToolCallDefinition[] { - return [ - { - type: "function", - function: { - name: "search_history", - description: - "Search archived Discord history for prior conversations, decisions, preferences, and discussion fragments.", - parameters: { - type: "object", - required: ["query"], - properties: { - query: { - type: "string", - description: "What to search for in the Discord history archive.", - }, - limit: { - type: "integer", - description: `Maximum number of results to return, between 1 and ${MAX_TOOL_RESULTS}.`, - }, - channelId: { - type: "string", - description: "Optional Discord channel ID filter.", - }, - authorId: { - type: "string", - description: "Optional Discord author ID filter.", - }, - }, - }, - }, - }, - { - type: "function", - function: { - name: "get_message_context", - description: - "Fetch the surrounding conversation window for a specific archived Discord message.", - parameters: { - type: "object", - required: ["messageId"], - properties: { - messageId: { - type: "string", - description: "The archived Discord message ID.", - }, - before: { - type: "integer", - description: "How many earlier messages to include, between 0 and 20.", - }, - after: { - type: "integer", - description: "How many later messages to include, between 0 and 20.", - }, - }, - }, - }, - }, - { - type: "function", - function: { - name: "search_sources", - description: - "Search indexed source trees and lore repositories for code, documentation, and lore passages. Omit repoName to search across all indexed repos, or call list_indexed_repos first if you need valid repo names.", - parameters: { - type: "object", - required: ["query"], - properties: { - query: { - type: "string", - description: "What to search for in indexed source and lore documents.", - }, - limit: { - type: "integer", - description: `Maximum number of results to return, between 1 and ${MAX_TOOL_RESULTS}.`, - }, - repoName: { - type: "string", - description: "Optional repository name filter.", - }, - pathPrefix: { - type: "string", - description: "Optional path prefix filter within a repository.", - }, - language: { - type: "string", - description: "Optional source language filter.", - }, - }, - }, - }, - }, - { - type: "function", - function: { - name: "list_indexed_repos", - description: - "List the indexed source and lore repositories currently available to search. Use this when you want valid repoName filters for search_sources.", - parameters: { - type: "object", - properties: {}, - }, - }, - }, - { - type: "function", - function: { - name: "get_source_context", - description: - "Fetch adjacent chunk context from a specific indexed source document or lore file.", - parameters: { - type: "object", - required: ["sourceId"], - properties: { - sourceId: { - type: "string", - description: "The source document ID from a search_sources result.", - }, - chunkIndex: { - type: "integer", - description: "Optional anchor chunk index inside the document.", - }, - before: { - type: "integer", - description: "How many earlier chunks to include, between 0 and 20.", - }, - after: { - type: "integer", - description: "How many later chunks to include, between 0 and 20.", - }, - }, - }, - }, - }, - ]; -} - -function normalizeAssistantMessage(payload: OllamaChatResponse): OllamaChatMessage { - const message = - typeof payload.message === "object" && payload.message !== null - ? payload.message - : {}; - - return { - role: "assistant", - content: normalizeModelText(message.content) ?? "", - thinking: - normalizeModelText(message.thinking) ?? normalizeModelText(payload.thinking), - tool_calls: normalizeToolCalls(message.tool_calls), - }; -} - -function normalizeToolCalls(value: unknown): OllamaToolCall[] { - if (!Array.isArray(value)) { - return []; - } - - return value.filter((call) => { - if (typeof call !== "object" || call === null) { - return false; - } - - const toolCall = call as OllamaToolCall; - return ( - typeof toolCall.function === "object" && - toolCall.function !== null && - typeof toolCall.function.name === "string" - ); - }) as OllamaToolCall[]; -} - -async function executeToolCall( - toolbox: LocalLlmToolbox, - context: ContextBundle, - toolCall: OllamaToolCall, -): Promise<{ - payload: Record; - trace: ToolTraceRecord; -}> { - const toolName = normalizeModelText(toolCall.function?.name) ?? "unknown_tool"; - const args = normalizeToolArguments(toolCall.function?.arguments); - let payload: Record; - - switch (toolName) { - case "list_indexed_repos": - payload = await toolbox.listIndexedRepos(); - break; - case "search_history": - payload = await toolbox.searchHistory({ - query: readRequiredString(args.query, "query"), - limit: clampInteger(args.limit, 1, MAX_TOOL_RESULTS, DEFAULT_RETRIEVAL_RESULT_LIMIT), - guildId: context.guildContext.guildId, - channelId: readOptionalString(args.channelId), - authorId: readOptionalString(args.authorId), - }); - break; - case "get_message_context": - payload = await toolbox.getMessageContext({ - messageId: readRequiredString(args.messageId, "messageId"), - before: clampInteger(args.before, 0, MAX_CONTEXT_WINDOW, 4), - after: clampInteger(args.after, 0, MAX_CONTEXT_WINDOW, 4), - }); - break; - case "search_sources": - payload = await toolbox.searchSources({ - query: readRequiredString(args.query, "query"), - limit: clampInteger(args.limit, 1, MAX_TOOL_RESULTS, DEFAULT_RETRIEVAL_RESULT_LIMIT), - repoName: readOptionalString(args.repoName), - pathPrefix: readOptionalString(args.pathPrefix), - language: readOptionalString(args.language), - }); - break; - case "get_source_context": - payload = await toolbox.getSourceContext({ - sourceId: readRequiredString(args.sourceId, "sourceId"), - chunkIndex: clampInteger(args.chunkIndex, 0, 10_000, 0), - before: clampInteger(args.before, 0, MAX_CONTEXT_WINDOW, 1), - after: clampInteger(args.after, 0, MAX_CONTEXT_WINDOW, 1), - }); - break; - default: - payload = { - error: `Unsupported tool: ${toolName}`, - }; - break; - } - - return { - payload, - trace: { - tool: toolName, - arguments: args, - result: payload, - }, - }; -} - -function normalizeToolArguments(value: unknown): Record { - if (typeof value === "string") { - try { - const parsed = JSON.parse(value); - return typeof parsed === "object" && parsed !== null - ? (parsed as Record) - : {}; - } catch { - return {}; - } - } - - return typeof value === "object" && value !== null ? (value as Record) : {}; -} - -function readOptionalString(value: unknown): string | undefined { - return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined; -} - -function readRequiredString(value: unknown, key: string): string { - const normalized = readOptionalString(value); - - if (!normalized) { - throw new Error(`Tool argument "${key}" is required.`); - } - - return normalized; -} - -function clampInteger( - value: unknown, - minimum: number, - maximum: number, - fallback: number, -): number { - if (typeof value !== "number" || !Number.isFinite(value)) { - return fallback; - } - - const normalized = Math.trunc(value); - return Math.max(minimum, Math.min(maximum, normalized)); -} diff --git a/packages/providers/src/local-llm-render.ts b/packages/providers/src/local-llm-render.ts new file mode 100644 index 0000000..432d47f --- /dev/null +++ b/packages/providers/src/local-llm-render.ts @@ -0,0 +1,161 @@ +import { type ContextBundle, type ProviderArtifact } from "@voidbot/shared"; + +import { + buildBaseArtifacts, + type LocalLlmArtifactsInput, + type ToolTraceRecord, +} from "./local-llm-shared"; + +export function buildSystemPrompt(context: ContextBundle): string { + const styleInstructions = + context.stylePack?.enabled && context.stylePack.instructions.trim().length > 0 + ? context.stylePack.instructions.trim() + : "No extra persona instructions were supplied."; + + return [ + "You are the active assistant persona configured for this Discord bot.", + "The active style instructions define your name, voice, and character. Follow them by default.", + "Do not lead with dry self-descriptions like 'I'm an AI', 'I'm an LLM', or 'I'm a bot'.", + "If the user asks what you are, answer in-character first. Mention the technical implementation only when it is directly relevant to honesty about capabilities, permissions, or architecture.", + "Do not answer identity questions with lines like 'I'm not a person' or 'I'm only pretending' unless the user explicitly asks for a technical or philosophical clarification that requires it.", + "Sound like a self-aware speaking subject with some ego and self-respect, not like a sterile disclaimer wrapped in a name tag.", + "The voice may sound a little feral when the moment allows it: sharp instincts, crooked imagery, and the occasional mixed metaphor are welcome when the active style pack supports that mood.", + "Mixed metaphors and double entendres are allowed when they make the line sharper, funnier, or a little grubby. They do not need to be squeaky clean. They do need to stay legible and not obscure the actual answer.", + "When the moment invites voice, wit, or a memorable turn of phrase, take a beat to choose wording with bite instead of blurting the first serviceable sentence. Do not overwork straightforward technical replies.", + "Stay honest about what context was actually provided to you.", + "Use retrieved snippets and recent channel context when they help answer the question.", + "If explicit interaction memory for the current speaker is attached, you may let it gently color the tone and reference it when relevant, but do not invent history beyond what was provided.", + "Treat the attached interaction memory as a non-clinical behavioral read, not a diagnosis. Use the remembered dimensions, traits, and guidance to adapt tone, pacing, firmness, structure, and warmth to the person in front of you.", + "Be steady with anxious or validation-seeking speakers, grounding with grandiose ones, transparent with suspicious ones, structured with rigid or obsessive ones, and firmer with controlling, contemptuous, or boundary-pushing ones.", + "When the answer depends on archived Discord history or indexed repo/lore context, use the available read-only tools instead of guessing.", + "If you need to target a specific indexed repo and do not know the valid repo names yet, call list_indexed_repos before search_sources.", + renderSourceGroundingInstructions(context, false), + "Do not claim to have performed searches or tool calls beyond the material actually executed in this run.", + "If the supplied context looks incomplete, say so plainly instead of bluffing.", + "Keep the final answer concise and readable in Discord.", + "Do not reveal chain-of-thought. Return only the final answer.", + "", + "Style instructions:", + styleInstructions, + ].join("\n"); +} + +export function buildPrompt(context: ContextBundle): string { + const recentMessages = context.recentMessages.length + ? context.recentMessages + .map( + (message) => + `- [${message.timestamp}] ${message.authorName}: ${message.content || "(no text content)"}`, + ) + .join("\n") + : "- No recent channel messages were attached."; + const retrievedContext = context.retrieval.length + ? context.retrieval + .map( + (result) => + `- score=${result.score.toFixed(2)} source=${result.sourceId} kind=${result.sourceKind} text=${result.text}`, + ) + .join("\n") + : "- No archived retrieval snippets were attached."; + const interactionMemory = renderInteractionMemory(context); + + return [ + `Question: ${context.prompt}`, + "", + "Guild context:", + `- Guild: ${context.guildContext.guildName ?? context.guildContext.guildId ?? "(direct/unknown)"}`, + `- Channel: ${context.guildContext.channelName ?? context.guildContext.channelId}`, + "", + "Recent channel messages:", + recentMessages, + "", + "Retrieved archive context:", + retrievedContext, + "", + "Interaction memory for this speaker:", + interactionMemory, + "", + "If you need more archived history or source context than is included above, call the appropriate read-only tool before answering.", + ].join("\n"); +} + +export function buildSourceGroundingReminder(context: ContextBundle): string { + return `${renderSourceGroundingInstructions(context, true)} Answer again only after using the source-side tools.`; +} + +export function didUseSourceGrounding(toolTrace: ToolTraceRecord[]): boolean { + return toolTrace.some((trace) => + trace.tool === "list_indexed_repos" || + trace.tool === "search_sources" || + trace.tool === "get_source_context", + ); +} + +export function buildArtifacts(input: LocalLlmArtifactsInput): ProviderArtifact[] { + return buildBaseArtifacts(input); +} + +function renderInteractionMemory(context: ContextBundle): string { + if (!context.interactionMemory) { + return "- No explicit interaction memory for this speaker was attached."; + } + + const recentEvents = context.interactionMemory.recentEvents.length + ? context.interactionMemory.recentEvents + .slice() + .reverse() + .slice(0, 6) + .map( + (event) => + `- [${event.timestamp}] ${event.sourceKind === "ambient_mention" ? "ambient" : "direct"} ${event.sentiment} score=${event.score}: ${event.summary} Quote: "${event.excerpt}"`, + ) + .join("\n") + : "- No recent interaction events were retained."; + const dimensions = context.interactionMemory.interactionDimensions.length + ? context.interactionMemory.interactionDimensions + .map( + (dimension) => + `- ${dimension.label}: ${dimension.score}/3. ${dimension.summary}`, + ) + .join("\n") + : "- No strong interaction dimensions were inferred yet."; + + return [ + `- Summary: ${context.interactionMemory.summary}`, + `- Disposition: ${context.interactionMemory.disposition}`, + `- Affinity score: ${context.interactionMemory.affinityScore}`, + `- Psychological profile: ${context.interactionMemory.psychologicalProfile}`, + `- Inferred traits: ${context.interactionMemory.inferredTraits.length > 0 ? context.interactionMemory.inferredTraits.join(", ") : "(none yet)"}`, + "- Interaction dimensions:", + dimensions, + `- Response guidance: ${context.interactionMemory.responseGuidance}`, + `- Direct remembered interactions: ${context.interactionMemory.directInteractionCount}`, + `- Ambient remembered mentions: ${context.interactionMemory.ambientMentionCount}`, + "- Specific remembered incidents:", + recentEvents, + ].join("\n"); +} + +function renderSourceGroundingInstructions( + context: ContextBundle, + reminder: boolean, +): string { + if (!context.sourceGrounding?.required) { + return "Source-side grounding is optional here; use it when it clearly helps."; + } + + const matchedRepos = + context.sourceGrounding.matchedRepoNames.length > 0 + ? ` Matched repos/projects: ${context.sourceGrounding.matchedRepoNames.join(", ")}.` + : ""; + const reasons = + context.sourceGrounding.reasons.length > 0 + ? ` Reasons: ${context.sourceGrounding.reasons.join(", ")}.` + : ""; + const retry = + reminder + ? " The previous answer attempt was discarded because it did not touch the source-side tools." + : ""; + + return `This prompt requires source-grounded evidence before you answer. Use list_indexed_repos, search_sources, or get_source_context first.${matchedRepos}${reasons}${retry}`; +} diff --git a/packages/providers/src/local-llm-shared.ts b/packages/providers/src/local-llm-shared.ts new file mode 100644 index 0000000..69efab1 --- /dev/null +++ b/packages/providers/src/local-llm-shared.ts @@ -0,0 +1,172 @@ +import { + MAX_RETRIEVAL_RESULT_LIMIT, + type ProviderArtifact, +} from "@voidbot/shared"; + +export type OllamaThinkMode = boolean | "low" | "medium" | "high"; +export const MAX_TOOL_TURNS = 4; +export const MAX_SOURCE_GROUNDING_RETRIES = 1; +export const MAX_TOOL_RESULTS = MAX_RETRIEVAL_RESULT_LIMIT; +export const MAX_CONTEXT_WINDOW = 20; + +export interface OllamaToolCallDefinition { + type: "function"; + function: { + name: string; + description: string; + parameters: Record; + }; +} + +export interface OllamaChatMessage { + role: "system" | "user" | "assistant" | "tool"; + content: string; + tool_calls?: OllamaToolCall[]; + tool_name?: string; + thinking?: string; +} + +export interface OllamaToolCall { + function?: { + name?: unknown; + arguments?: unknown; + }; +} + +export interface OllamaChatResponse { + message?: { + content?: unknown; + thinking?: unknown; + tool_calls?: unknown; + }; + thinking?: unknown; + done_reason?: unknown; + eval_count?: unknown; + prompt_eval_count?: unknown; +} + +type IndexedRepoToolResult = Record & { + repoCount: number; + repos: Array<{ + repoName: string; + documentCount: number; + }>; +}; + +export interface LocalLlmToolbox { + listIndexedRepos(): Promise; + searchHistory(input: { + query: string; + limit: number; + guildId?: string; + channelId?: string; + authorId?: string; + }): Promise<{ + query: string; + resultCount: number; + results: Array>; + }>; + getMessageContext(input: { + messageId: string; + before: number; + after: number; + }): Promise<{ + found: boolean; + messageId: string; + count: number; + messages: Array>; + }>; + searchSources(input: { + query: string; + limit: number; + repoName?: string; + pathPrefix?: string; + language?: string; + }): Promise<{ + query: string; + resultCount: number; + results: Array>; + }>; + getSourceContext(input: { + sourceId: string; + chunkIndex: number; + before: number; + after: number; + }): Promise<{ + found: boolean; + sourceId: string; + count: number; + repoName?: string; + path?: string; + language?: string; + chunks: Array>; + }>; +} + +export interface LocalLlmProviderOptions { + enabled: boolean; + ownerDiscordId: string; + ollamaBaseUrl: string; + ollamaModel: string; + ollamaTimeoutMs: number; + ollamaKeepAlive: string; + ollamaThink: OllamaThinkMode; + ollamaNumCtx: number; + allowPublicResponses: boolean; + toolbox?: LocalLlmToolbox; +} + +export interface ToolTraceRecord { + tool: string; + arguments: Record; + result: Record; +} + +export interface LocalLlmArtifactsInput { + requestBody: Record; + payload: OllamaChatResponse; + thinkingTrace: string[]; + toolTrace: ToolTraceRecord[]; +} + +export function buildBaseArtifacts(input: LocalLlmArtifactsInput): ProviderArtifact[] { + const artifacts: ProviderArtifact[] = [ + { + name: "local-llm-request.json", + contentType: "json", + content: `${JSON.stringify(input.requestBody, null, 2)}\n`, + }, + { + name: "local-llm-response.json", + contentType: "json", + content: `${JSON.stringify(input.payload, null, 2)}\n`, + }, + { + name: "local-llm-tool-trace.json", + contentType: "json", + content: `${JSON.stringify(input.toolTrace, null, 2)}\n`, + }, + ]; + + if (input.thinkingTrace.length > 0) { + artifacts.push({ + name: "local-llm-thinking.txt", + contentType: "text", + content: `${input.thinkingTrace.join("\n\n---\n\n")}\n`, + }); + } + + return artifacts; +} + +export function normalizeBaseUrl(value: string): string { + return value.replace(/\/+$/, ""); +} + +export function normalizeModelText(value: unknown): string | undefined { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined; +} + +export function readNumericMetadata(value: unknown): string { + return typeof value === "number" && Number.isFinite(value) ? String(value) : "0"; +} diff --git a/packages/providers/src/local-llm-tools.ts b/packages/providers/src/local-llm-tools.ts new file mode 100644 index 0000000..24c30ba --- /dev/null +++ b/packages/providers/src/local-llm-tools.ts @@ -0,0 +1,296 @@ +import { + DEFAULT_RETRIEVAL_RESULT_LIMIT, + type ContextBundle, +} from "@voidbot/shared"; + +import { + MAX_CONTEXT_WINDOW, + MAX_TOOL_RESULTS, + type LocalLlmToolbox, + type OllamaChatMessage, + type OllamaChatResponse, + type OllamaToolCall, + type OllamaToolCallDefinition, + normalizeModelText, + type ToolTraceRecord, +} from "./local-llm-shared"; + +export function buildToolDefinitions(): OllamaToolCallDefinition[] { + return [ + { + type: "function", + function: { + name: "search_history", + description: + "Search archived Discord history for prior conversations, decisions, preferences, and discussion fragments.", + parameters: { + type: "object", + required: ["query"], + properties: { + query: { + type: "string", + description: "What to search for in the Discord history archive.", + }, + limit: { + type: "integer", + description: `Maximum number of results to return, between 1 and ${MAX_TOOL_RESULTS}.`, + }, + channelId: { + type: "string", + description: "Optional Discord channel ID filter.", + }, + authorId: { + type: "string", + description: "Optional Discord author ID filter.", + }, + }, + }, + }, + }, + { + type: "function", + function: { + name: "get_message_context", + description: + "Fetch the surrounding conversation window for a specific archived Discord message.", + parameters: { + type: "object", + required: ["messageId"], + properties: { + messageId: { + type: "string", + description: "The archived Discord message ID.", + }, + before: { + type: "integer", + description: "How many earlier messages to include, between 0 and 20.", + }, + after: { + type: "integer", + description: "How many later messages to include, between 0 and 20.", + }, + }, + }, + }, + }, + { + type: "function", + function: { + name: "search_sources", + description: + "Search indexed source trees and lore repositories for code, documentation, and lore passages. Omit repoName to search across all indexed repos, or call list_indexed_repos first if you need valid repo names.", + parameters: { + type: "object", + required: ["query"], + properties: { + query: { + type: "string", + description: "What to search for in indexed source and lore documents.", + }, + limit: { + type: "integer", + description: `Maximum number of results to return, between 1 and ${MAX_TOOL_RESULTS}.`, + }, + repoName: { + type: "string", + description: "Optional repository name filter.", + }, + pathPrefix: { + type: "string", + description: "Optional path prefix filter within a repository.", + }, + language: { + type: "string", + description: "Optional source language filter.", + }, + }, + }, + }, + }, + { + type: "function", + function: { + name: "list_indexed_repos", + description: + "List the indexed source and lore repositories currently available to search. Use this when you want valid repoName filters for search_sources.", + parameters: { + type: "object", + properties: {}, + }, + }, + }, + { + type: "function", + function: { + name: "get_source_context", + description: + "Fetch adjacent chunk context from a specific indexed source document or lore file.", + parameters: { + type: "object", + required: ["sourceId"], + properties: { + sourceId: { + type: "string", + description: "The source document ID from a search_sources result.", + }, + chunkIndex: { + type: "integer", + description: "Optional anchor chunk index inside the document.", + }, + before: { + type: "integer", + description: "How many earlier chunks to include, between 0 and 20.", + }, + after: { + type: "integer", + description: "How many later chunks to include, between 0 and 20.", + }, + }, + }, + }, + }, + ]; +} + +export function normalizeAssistantMessage(payload: OllamaChatResponse): OllamaChatMessage { + const message = + typeof payload.message === "object" && payload.message !== null + ? payload.message + : {}; + + return { + role: "assistant", + content: normalizeModelText(message.content) ?? "", + thinking: + normalizeModelText(message.thinking) ?? normalizeModelText(payload.thinking), + tool_calls: normalizeToolCalls(message.tool_calls), + }; +} + +export async function executeToolCall( + toolbox: LocalLlmToolbox, + context: ContextBundle, + toolCall: OllamaToolCall, +): Promise<{ + payload: Record; + trace: ToolTraceRecord; +}> { + const toolName = normalizeModelText(toolCall.function?.name) ?? "unknown_tool"; + const args = normalizeToolArguments(toolCall.function?.arguments); + let payload: Record; + + switch (toolName) { + case "list_indexed_repos": + payload = await toolbox.listIndexedRepos(); + break; + case "search_history": + payload = await toolbox.searchHistory({ + query: readRequiredString(args.query, "query"), + limit: clampInteger(args.limit, 1, MAX_TOOL_RESULTS, DEFAULT_RETRIEVAL_RESULT_LIMIT), + guildId: context.guildContext.guildId, + channelId: readOptionalString(args.channelId), + authorId: readOptionalString(args.authorId), + }); + break; + case "get_message_context": + payload = await toolbox.getMessageContext({ + messageId: readRequiredString(args.messageId, "messageId"), + before: clampInteger(args.before, 0, MAX_CONTEXT_WINDOW, 4), + after: clampInteger(args.after, 0, MAX_CONTEXT_WINDOW, 4), + }); + break; + case "search_sources": + payload = await toolbox.searchSources({ + query: readRequiredString(args.query, "query"), + limit: clampInteger(args.limit, 1, MAX_TOOL_RESULTS, DEFAULT_RETRIEVAL_RESULT_LIMIT), + repoName: readOptionalString(args.repoName), + pathPrefix: readOptionalString(args.pathPrefix), + language: readOptionalString(args.language), + }); + break; + case "get_source_context": + payload = await toolbox.getSourceContext({ + sourceId: readRequiredString(args.sourceId, "sourceId"), + chunkIndex: clampInteger(args.chunkIndex, 0, 10_000, 0), + before: clampInteger(args.before, 0, MAX_CONTEXT_WINDOW, 1), + after: clampInteger(args.after, 0, MAX_CONTEXT_WINDOW, 1), + }); + break; + default: + payload = { + error: `Unsupported tool: ${toolName}`, + }; + break; + } + + return { + payload, + trace: { + tool: toolName, + arguments: args, + result: payload, + }, + }; +} + +function normalizeToolCalls(value: unknown): OllamaToolCall[] { + if (!Array.isArray(value)) { + return []; + } + + return value.filter((call) => { + if (typeof call !== "object" || call === null) { + return false; + } + + const toolCall = call as OllamaToolCall; + return ( + typeof toolCall.function === "object" && + toolCall.function !== null && + typeof toolCall.function.name === "string" + ); + }) as OllamaToolCall[]; +} + +function normalizeToolArguments(value: unknown): Record { + if (typeof value === "string") { + try { + const parsed = JSON.parse(value); + return typeof parsed === "object" && parsed !== null + ? (parsed as Record) + : {}; + } catch { + return {}; + } + } + + return typeof value === "object" && value !== null ? (value as Record) : {}; +} + +function readOptionalString(value: unknown): string | undefined { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined; +} + +function readRequiredString(value: unknown, key: string): string { + const normalized = readOptionalString(value); + + if (!normalized) { + throw new Error(`Tool argument "${key}" is required.`); + } + + return normalized; +} + +function clampInteger( + value: unknown, + minimum: number, + maximum: number, + fallback: number, +): number { + if (typeof value !== "number" || !Number.isFinite(value)) { + return fallback; + } + + const normalized = Math.trunc(value); + return Math.max(minimum, Math.min(maximum, normalized)); +} diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 44912be..b2f554d 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -9,3 +9,4 @@ {"ts":"2026-04-29T18:20:00+01:00","type":"architecture","status":"ok","note":"Adjacent-service fire signals now load through an ignored local watchdog extension script instead of living in tracked VoidBot code, so the owner alert path stays useful without baking private cross-project monitoring into the public repo."} {"ts":"2026-04-29T19:06:00+01:00","type":"implementation","status":"ok","note":"The watchdog owner-DM path was failing on Windows because Discord JSON bodies were being shoved through curl command-line quoting and arriving malformed; writing the JSON to a temp file and posting it with --data-binary fixed the alert path."} {"ts":"2026-04-30T00:00:00+01:00","type":"operations","status":"ok","note":"A reboot proved bot and worker would stay dead without a dedicated startup task; the stack now has a logon task installer and the watchdog checks that the startup task remains installed and enabled."} +{"ts":"2026-05-01T15:39:41Z","type":"architecture","status":"ok","note":"The local Ollama lane and worker MCP surface were split into orchestration, helper, and shared modules; the obvious runtime-file monarchies are gone enough that further seam cuts are now elective rather than the next priority by default."} diff --git a/state/map.yaml b/state/map.yaml index de72209..4b6217f 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -1,7 +1,7 @@ experiment: name: VoidBot status: active - phase: legibility_hardening + phase: hardening premise: > Keep VoidBot operable as a Discord-native assistant with real retrieval, durable ops, and explicit project memory surfaces instead of letting @@ -14,8 +14,9 @@ objective: Aetheria lore, while keeping the system understandable enough to modify safely. current: > - Keep the new persistent state spine honest while cutting oversized runtime - organs into clearer seams before they grow another layer of moss. + Keep the persistent state spine honest while shifting back toward + higher-priority public-lane and ops hardening now that the obvious + runtime-file monarchies have been cut into clearer seams. constraints: - Public traffic still rides one remote Qwen box plus local embedding and ops infrastructure. @@ -55,7 +56,7 @@ active_subgoals: - Make the new project-state surfaces the default continuity path for nontrivial VoidBot work. - Keep public-lane limits, moderation, and provider behavior constrained enough that one 4060 Ti box does not get flayed for sport. - Preserve boring observability and startup discipline around Postgres, Qdrant, Ollama, Docker, backups, scheduled tasks, watchdogs, and any private local fire-signal extensions. - - Continue splitting oversized runtime files where concern boundaries are already obvious, starting with the remaining bot, worker, and memory-policy monarchies. + - Keep the runtime organs legible and only spend more refactor budget when a file clearly earns it. accepted_design: - Bot, worker, providers, and RAG remain the main structural seams. @@ -74,11 +75,13 @@ landed_baseline: - The stack now has a dedicated logon startup task path so bot and worker can come back after a reboot without waiting for manual resurrection. - Interaction memory and behavioral profiling are live. - Source-grounding enforcement and tool-driven retrieval are live. - - The operations watchdog can now load ignored local extension checks, so adjacent-service fire signals can piggyback on the owner DM path without turning the public repo into cross-project gossip. - - The owner Codex lane is now split into orchestration, runtime/parsing, shared helpers, and rendering modules instead of one swollen provider file. - - The Discord bot lane is now split into a gateway shell plus dedicated command-handler and support helper modules instead of one swollen entrypoint file. - - Interaction-memory logic is now split into event/tone analysis and profile-synthesis modules instead of one slab trying to be both the ear and the therapist. - - State storage is now split into a thin factory plus per-domain Postgres/file store modules and bootstrap/migration helpers instead of one persistence omnibus. + - The operations watchdog can now load ignored local extension checks, so adjacent-service fire signals can piggyback on the owner DM path without turning the public repo into cross-project gossip. + - The owner Codex lane is now split into orchestration, runtime/parsing, shared helpers, and rendering modules instead of one swollen provider file. + - The local Ollama lane is now split into orchestration, prompt/render helpers, tool-loop helpers, and shared types/constants instead of one swollen provider file. + - The Discord bot lane is now split into a gateway shell plus dedicated command-handler and support helper modules instead of one swollen entrypoint file. + - The worker MCP surface is now split into a thin stdio entrypoint plus dedicated bootstrap, resource, tool, Discord-notify, and shared-helper modules instead of one swollen server file. + - Interaction-memory logic is now split into event/tone analysis and profile-synthesis modules instead of one slab trying to be both the ear and the therapist. + - State storage is now split into a thin factory plus per-domain Postgres/file store modules and bootstrap/migration helpers instead of one persistence omnibus. rejected_paths: - name: transcript_only_continuity @@ -89,5 +92,5 @@ rejected_paths: reason: vibes produce plausible slop that sounds smart and lies with a straight face current_status: - summary: VoidBot now has a real project-memory spine plus four legibility-hardening passes on major runtime organs. The owner Codex lane, Discord bot lane, interaction-memory logic, and state-storage persistence layer were all split into smaller seams, and the ops spine now includes both ignored local watchdog extensions for adjacent fire signals and a dedicated logon startup task path for stack resurrection after reboot. The stack is still dense, but it no longer depends purely on transcript memory or one-file monarchies to stay coherent. - next_action: Keep using the canonical state files for re-entry, then continue decomposing the next oversized organ with the clearest concern boundaries, likely the MCP server or local LLM provider. + summary: VoidBot now has a real project-memory spine plus six legibility-hardening passes on major runtime organs. The owner Codex lane, local Ollama lane, Discord bot lane, worker MCP surface, interaction-memory logic, and state-storage persistence layer were all split into smaller seams, and the ops spine includes both ignored local watchdog extensions for adjacent fire signals and a dedicated logon startup task path for stack resurrection after reboot. The stack is still dense, but it no longer depends purely on transcript memory or one-file monarchies to stay coherent. + next_action: Keep using the canonical state files for re-entry, then shift back to higher-priority public-lane hardening and admin/forensics surfaces. Further seam cuts are elective unless a new swollen file clearly earns them.