@andespindola/brainlink 1.0.5 → 1.0.7

package/dist/mcp/tools/read-tools.js

@@ -0,0 +1,537 @@
+import { z } from 'zod';
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
+import { buildContextPackage, readContextDataSignature } from '../../application/build-context.js';
+import { getGraph } from '../../application/get-graph.js';
+import { getGraphContexts } from '../../application/get-graph-contexts.js';
+import { explainSearchResults, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
+import { buildActionableDoctor } from '../../application/operational-workflows.js';
+import { searchKnowledge } from '../../application/search-knowledge.js';
+import { findSimilarNotes } from '../../application/find-similar-notes.js';
+import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { clearContextPacks, listContextPacks } from '../../infrastructure/context-packs.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, touchContextSession } from '../../infrastructure/session-state.js';
+import { getRuntimeMetadata } from '../runtime.js';
+import { agentInput, contextStrategyInput, ensureBootstrapReady, ensureContextReady, jsonResult, optionalPositiveInteger, positiveInteger, resolveExecutionContext, searchModeInput, vaultInput } from './shared.js';
+export const contextInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    ...contextStrategyInput,
+    query: z.string().min(1).describe('Task or question to retrieve Brainlink context for.'),
+    limit: optionalPositiveInteger().describe('Maximum search results before context selection.'),
+    tokens: optionalPositiveInteger().describe('Maximum estimated context tokens.')
+};
+export const contextPacksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    action: z.enum(['list', 'clear']).optional().default('list').describe('Action to perform on persisted CAG context packs.'),
+    staleOnly: z.boolean().optional().default(false).describe('When clearing, remove only packs stale for the current index and volatile-memory signature.')
+};
+export const searchInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Search query.'),
+    limit: optionalPositiveInteger().describe('Maximum result count.')
+};
+export const explainInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z.string().min(1).describe('Search query to explain.'),
+    limit: optionalPositiveInteger().describe('Maximum result count.')
+};
+export const similarNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    title: z.string().min(1).optional().describe('Title of the note to find neighbors for. Use agent to disambiguate.'),
+    path: z.string().min(1).optional().describe('Vault-relative or absolute path of the note to find neighbors for.'),
+    limit: optionalPositiveInteger().describe('Maximum number of similar notes to return. Defaults to the configured search limit.')
+};
+export const validateInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const doctorActionsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const graphInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const graphContextsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const brokenLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const suggestLinksInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).optional().describe('Content to inspect for Context Link suggestions. Required unless broken=true.'),
+    broken: z.boolean().optional().default(false).describe('Suggest fixes for unresolved wiki links instead of content links.'),
+    limit: positiveInteger(5).describe('Maximum suggestions to return.')
+};
+export const orphansInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const statsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const versionInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const recommendationsInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    ...contextStrategyInput,
+    query: z.string().min(1).optional().describe('Optional current task query to generate context-focused recommendations.'),
+    limit: optionalPositiveInteger().describe('Optional context limit override for generated recommendations.'),
+    tokens: optionalPositiveInteger().describe('Optional context token budget override for generated recommendations.')
+};
+export const contextTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_context');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const tokens = input.tokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode, strategy, context.defaults.defaultContextCacheTtlMs);
+    const contextSession = await touchContextSession(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        strategy,
+        limit,
+        tokens,
+        contextSession,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...contextPackage
+    });
+};
+export const contextPacksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const dataSignature = await readContextDataSignature(context.vault);
+    if (input.action === 'clear') {
+        const result = await clearContextPacks(context.vault, {
+            staleOnly: input.staleOnly === true,
+            dataSignature
+        });
+        return jsonResult({
+            vault: context.vault,
+            agent: context.agent,
+            dataSignature,
+            action: 'clear',
+            staleOnly: input.staleOnly === true,
+            ...result
+        });
+    }
+    const packs = await listContextPacks(context.vault, dataSignature);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        dataSignature,
+        action: 'list',
+        packs
+    });
+};
+export const searchTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_search');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_search');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const results = await searchKnowledge(context.vault, input.query, limit, context.agent, mode);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        query: input.query,
+        limit,
+        mode,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        results
+    });
+};
+export const similarNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_similar_notes');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const result = await findSimilarNotes(context.vault, {
+        title: input.title,
+        path: input.path,
+        agentId: context.agent,
+        limit,
+        mode
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        limit,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...result
+    });
+};
+export const explainTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_explain');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_explain');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const results = await explainSearchResults(context.vault, input.query, limit, context.agent, mode);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        query: input.query,
+        limit,
+        mode,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        results
+    });
+};
+export const validateTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_validate');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_validate');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const validation = await validateVault(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        ...validation
+    });
+};
+export const doctorActionsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_doctor_actions');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_doctor_actions');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const report = await buildActionableDoctor(context.vault);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        ...report
+    });
+};
+export const graphTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_graph');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const graph = await getGraph(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        ...graph
+    });
+};
+export const graphContextsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_graph_contexts');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_graph_contexts');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const contexts = await getGraphContexts(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        contexts
+    });
+};
+export const brokenLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_broken_links');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_broken_links');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        brokenLinks
+    });
+};
+export const suggestLinksTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_suggest_links');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_suggest_links');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    if (input.broken) {
+        const suggestions = await suggestBrokenLinkFixes(context.vault, context.agent, input.limit);
+        return jsonResult({
+            vault: context.vault,
+            agent: context.agent,
+            mode: 'broken-links',
+            ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+            ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+            suggestions
+        });
+    }
+    if (!input.content || input.content.trim().length === 0) {
+        throw new Error('content is required when broken=false.');
+    }
+    const suggestions = await suggestContextLinks(context.vault, input.content, context.agent, input.limit);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        mode: 'content',
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        suggestions
+    });
+};
+export const orphansTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_orphans');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_orphans');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const orphans = await getOrphansReport(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        orphans
+    });
+};
+export const statsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_stats');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const contextReadiness = await ensureContextReady(context, input, 'brainlink_stats');
+    if (contextReadiness.preflight) {
+        return contextReadiness.preflight;
+    }
+    const stats = await getStats(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
+        ...(contextReadiness.context ? { contextReadiness: contextReadiness.context } : {}),
+        stats
+    });
+};
+export const versionTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        runtime: getRuntimeMetadata()
+    });
+};
+export const recommendationsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const policy = await getBootstrapPolicy();
+    const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const contextStatus = await getContextSessionStatus(context.vault, context.agent);
+    const stats = await getStats(context.vault, context.agent);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(input.strategy, context.defaults.defaultContextStrategy);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const tokens = input.tokens ?? context.defaults.defaultContextTokens;
+    const query = input.query?.trim();
+    const recommendations = [
+        ...(policy.enforceBootstrap && (!policy.autoBootstrapOnRead || !policy.autoBootstrapOnStartup)
+            ? [
+                {
+                    tool: 'brainlink_policy',
+                    reason: 'Enable fully automatic bootstrap for plug-and-play agent usage.',
+                    args: {
+                        preset: 'fully-auto'
+                    }
+                }
+            ]
+            : []),
+        ...(!bootstrapStatus.ready && !policy.autoBootstrapOnRead
+            ? [
+                {
+                    tool: 'brainlink_bootstrap',
+                    reason: 'Bootstrap is required before read tools when auto-bootstrap-on-read is disabled.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        mode,
+                        strategy,
+                        ...(query ? { query } : {})
+                    }
+                }
+            ]
+            : []),
+        ...(policy.enforceContextFirst && !contextStatus.ready
+            ? [
+                {
+                    tool: 'brainlink_context',
+                    reason: 'Context-first policy is enabled. Load context before other read operations.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        query: query ?? '<task>',
+                        mode,
+                        strategy,
+                        limit,
+                        tokens
+                    }
+                }
+            ]
+            : []),
+        ...(stats.documentCount === 0
+            ? [
+                {
+                    tool: 'brainlink_add_note',
+                    reason: 'Seed the vault with a first durable note so retrieval can return useful context.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        title: 'Architecture',
+                        content: 'Seed durable memory with explicit [[links]] and #tags.'
+                    }
+                },
+                {
+                    tool: 'brainlink_index',
+                    reason: 'Rebuild index after writing the first notes.',
+                    args: {
+                        vault: context.vault
+                    }
+                }
+            ]
+            : []),
+        {
+            tool: 'brainlink_context',
+            reason: 'Retrieve grounded memory context before responding.',
+            args: {
+                vault: context.vault,
+                ...(context.agent ? { agent: context.agent } : {}),
+                query: query ?? '<task>',
+                mode,
+                strategy,
+                limit,
+                tokens
+            }
+        },
+        {
+            tool: 'brainlink_dedupe',
+            reason: 'Detect and resolve duplicate durable notes to keep memory quality high.',
+            args: {
+                vault: context.vault,
+                ...(context.agent ? { agent: context.agent } : {}),
+                limit: 10,
+                minScore: 0.92,
+                semantic: true
+            }
+        },
+        {
+            tool: 'brainlink_add_note',
+            reason: 'Persist durable outcomes after task completion (write responses include connectivity metadata).',
+            args: {
+                vault: context.vault,
+                ...(context.agent ? { agent: context.agent } : {}),
+                title: 'Task Update',
+                content: 'Durable findings connected to [[existing notes]].'
+            }
+        }
+    ];
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        defaults: {
+            mode,
+            strategy,
+            limit,
+            tokens
+        },
+        contextStrategies: [
+            {
+                strategy: 'rag',
+                useWhen: 'Use for fresh retrieval and context assembly from the current index.'
+            },
+            {
+                strategy: 'cag',
+                useWhen: 'Use for repeated or stable task context so Brainlink can reuse a fresh persisted context pack.'
+            },
+            {
+                strategy: 'auto',
+                useWhen: 'Use when the agent wants Brainlink to choose CAG on fresh pack hits and RAG otherwise.'
+            }
+        ],
+        policy,
+        bootstrapStatus,
+        contextStatus,
+        stats,
+        recommendations
+    });
+};