@andespindola/brainlink 0.1.0-beta.8 → 0.1.0-beta.9

package/dist/mcp/startup.js

@@ -0,0 +1,35 @@
+import { indexVault } from '../application/index-vault.js';
+import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+import { getBootstrapPolicy, touchBootstrapSession } from '../infrastructure/session-state.js';
+export const runStartupBootstrap = async () => {
+    try {
+        const policy = await getBootstrapPolicy();
+        if (!policy.autoBootstrapOnStartup) {
+            return {
+                attempted: false,
+                skipped: true,
+                reason: 'autoBootstrapOnStartup=false'
+            };
+        }
+        const config = await loadBrainlinkConfig();
+        const vault = assertVaultAllowed(config.vault, config.allowedVaults);
+        const agent = config.defaultAgent;
+        const index = await indexVault(vault);
+        await touchBootstrapSession(vault, agent);
+        return {
+            attempted: true,
+            skipped: false,
+            vault,
+            agent: agent ?? '*',
+            index
+        };
+    }
+    catch (error) {
+        return {
+            attempted: true,
+            skipped: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+};

package/dist/mcp/tools.js

@@ -2,20 +2,26 @@ import { readFile } from 'node:fs/promises';
 import { basename, extname } from 'node:path';
 import { z } from 'zod';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
-import { addNote } from '../application/add-note.js';
+import { addNoteWithMetadata } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
 import { getGraph } from '../application/get-graph.js';
 import { indexVault } from '../application/index-vault.js';
 import { searchKnowledge } from '../application/search-knowledge.js';
-import { sanitizeSearchMode } from '../infrastructure/config.js';
+import { resolveAgentRuntimeDefaults, sanitizeSearchMode } from '../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, setBootstrapPolicy, touchBootstrapSession } from '../infrastructure/session-state.js';
 const positiveInteger = (fallback) => z
     .number()
     .int()
     .positive()
     .optional()
     .transform((value) => value ?? fallback);
+const optionalPositiveInteger = () => z
+    .number()
+    .int()
+    .positive()
+    .optional();
 const vaultInput = {
     vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
 };
@@ -33,10 +39,12 @@ const resolveExecutionContext = async (input) => {
     const config = await loadBrainlinkConfig();
     const vault = await assertVaultAllowed(input.vault ?? config.vault, config.allowedVaults);
     const agent = input.agent ?? config.defaultAgent;
+    const defaults = resolveAgentRuntimeDefaults(config, agent);
     return {
         config,
         vault,
-        agent
+        agent,
+        defaults
     };
 };
 const inferTitleFromPath = (filePath) => {
@@ -58,20 +66,97 @@ const jsonResult = (value) => ({
     ],
     structuredContent: value
 });
+const preflightResult = (value) => jsonResult({
+    preflightRequired: true,
+    ...value
+});
+const withNextActions = (value, nextActions) => ({
+    ...value,
+    nextActions
+});
+const ensureBootstrapReady = async (context, input, toolName) => {
+    const policy = await getBootstrapPolicy();
+    if (!policy.enforceBootstrap) {
+        return {
+            bootstrap: {
+                autoBootstrapped: false,
+                policy,
+                statusBefore: {
+                    ready: true,
+                    stale: false
+                },
+                reason: 'Bootstrap enforcement is disabled by policy.'
+            }
+        };
+    }
+    const status = await getBootstrapSessionStatus(context.vault, context.agent);
+    if (status.ready) {
+        return {
+            bootstrap: {
+                autoBootstrapped: false,
+                policy,
+                statusBefore: status,
+                reason: 'Bootstrap session is already fresh for this vault/agent.'
+            }
+        };
+    }
+    if (policy.autoBootstrapOnRead) {
+        const index = await indexVault(context.vault);
+        const session = await touchBootstrapSession(context.vault, context.agent);
+        const statusAfter = await getBootstrapSessionStatus(context.vault, context.agent);
+        return {
+            bootstrap: {
+                autoBootstrapped: true,
+                policy,
+                statusBefore: status,
+                statusAfter,
+                session,
+                index,
+                reason: 'Auto-bootstrap was applied for this read call because bootstrap was missing or stale.'
+            }
+        };
+    }
+    const mode = typeof input.mode === 'string' && ['fts', 'semantic', 'hybrid'].includes(input.mode) ? input.mode : 'hybrid';
+    const query = typeof input.query === 'string' && input.query.trim().length > 0 ? input.query : undefined;
+    const bootstrapArgs = {
+        vault: context.vault,
+        ...(context.agent ? { agent: context.agent } : {}),
+        ...(query ? { query } : {}),
+        mode
+    };
+    const nextActions = [
+        {
+            tool: 'brainlink_bootstrap',
+            reason: 'Bootstrap is required before read tools so retrieval stays grounded in current vault state.',
+            args: bootstrapArgs
+        }
+    ];
+    return {
+        preflight: preflightResult(withNextActions({
+            vault: context.vault,
+            agent: context.agent,
+            blockedTool: toolName,
+            policy,
+            bootstrapStatus: status,
+            guidance: 'Run brainlink_bootstrap first for this vault/agent before using read tools. This keeps retrieval grounded and memory state consistent.',
+            bootstrapArgs
+        }, nextActions))
+    };
+};
 export const contextInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
     query: z.string().min(1).describe('Task or question to retrieve Brainlink context for.'),
-    limit: positiveInteger(12).describe('Maximum search results before context selection.'),
-    tokens: positiveInteger(2000).describe('Maximum estimated context tokens.')
+    limit: optionalPositiveInteger().describe('Maximum search results before context selection.'),
+    tokens: optionalPositiveInteger().describe('Maximum estimated context tokens.')
 };
 export const searchInputSchema = {
     ...vaultInput,
     ...agentInput,
     ...searchModeInput,
     query: z.string().min(1).describe('Search query.'),
-    limit: positiveInteger(10).describe('Maximum result count.')
+    limit: optionalPositiveInteger().describe('Maximum result count.')
 };
 export const addNoteInputSchema = {
     ...vaultInput,
@@ -120,37 +205,87 @@ export const syncInputSchema = {
     ...agentInput,
     contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
     mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
-    contextLimit: positiveInteger(12).describe('Context smoke result limit when contextQuery is provided.'),
-    contextTokens: positiveInteger(2000).describe('Context smoke token target when contextQuery is provided.')
+    contextLimit: optionalPositiveInteger().describe('Context smoke result limit when contextQuery is provided.'),
+    contextTokens: optionalPositiveInteger().describe('Context smoke token target when contextQuery is provided.')
+};
+export const bootstrapInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional task query. When provided, Brainlink also returns a context package in the same call.'),
+    limit: optionalPositiveInteger().describe('Context limit used when query is provided.'),
+    tokens: optionalPositiveInteger().describe('Context token target used when query is provided.')
+};
+export const policyInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    preset: z.enum(['fully-auto', 'strict']).optional().describe('Apply an opinionated policy preset before explicit overrides.'),
+    enforceBootstrap: z.boolean().optional().describe('Enable or disable bootstrap enforcement for MCP read tools.'),
+    autoBootstrapOnRead: z
+        .boolean()
+        .optional()
+        .describe('When bootstrap is missing/stale, run automatic bootstrap on read tools instead of returning preflight-required responses.'),
+    autoBootstrapOnStartup: z
+        .boolean()
+        .optional()
+        .describe('Run automatic bootstrap during MCP server startup using configured default vault/agent.'),
+    staleAfterMinutes: positiveInteger(120).describe('Bootstrap freshness window in minutes before read tools require a new bootstrap.')
+};
+export const recommendationsInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    ...searchModeInput,
+    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 mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
-    const contextPackage = await buildContextPackage(context.vault, input.query, input.limit, input.tokens, context.agent, mode);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_context');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    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);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
         mode,
+        limit,
+        tokens,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         ...contextPackage
     });
 };
 export const searchTool = async (input) => {
     const context = await resolveExecutionContext(input);
-    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
-    const results = await searchKnowledge(context.vault, input.query, input.limit, context.agent, mode);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_search');
+    if (readiness.preflight) {
+        return readiness.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: input.limit,
+        limit,
         mode,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         results
     });
 };
 export const addNoteTool = async (input) => {
     const context = await resolveExecutionContext(input);
     const shouldIndex = isTruthy(input.autoIndex);
-    const path = await addNote(context.vault, input.title, input.content, context.agent, {
+    const added = await addNoteWithMetadata(context.vault, input.title, input.content, context.agent, {
         allowSensitive: input.allowSensitive
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
@@ -158,7 +293,12 @@ export const addNoteTool = async (input) => {
         vault: context.vault,
         title: input.title,
         agent: context.agent,
-        path,
+        path: added.path,
+        writeConnectivity: {
+            autoLinked: added.autoLinked,
+            linkTarget: added.linkTarget,
+            guaranteedEdge: true
+        },
         ...(index ? { index } : {})
     });
 };
@@ -171,7 +311,7 @@ export const addFileTool = async (input) => {
         throw new Error('Cannot infer note title from file path. Provide a title explicitly.');
     }
     const shouldIndex = isTruthy(input.autoIndex);
-    const path = await addNote(context.vault, title, content, context.agent, {
+    const added = await addNoteWithMetadata(context.vault, title, content, context.agent, {
         allowSensitive: input.allowSensitive
     });
     const index = shouldIndex ? await indexVault(context.vault) : undefined;
@@ -180,7 +320,12 @@ export const addFileTool = async (input) => {
         title,
         agent: context.agent,
         filePath: input.filePath,
-        path,
+        path: added.path,
+        writeConnectivity: {
+            autoLinked: added.autoLinked,
+            linkTarget: added.linkTarget,
+            guaranteedEdge: true
+        },
         ...(index ? { index } : {})
     });
 };
@@ -194,51 +339,80 @@ export const indexTool = async (input) => {
 };
 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 validation = await validateVault(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         ...validation
     });
 };
 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 graph = await getGraph(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         ...graph
     });
 };
 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 brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         brokenLinks
     });
 };
 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 orphans = await getOrphansReport(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         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 stats = await getStats(context.vault, context.agent);
     return jsonResult({
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         stats
     });
 };
 export const syncTool = async (input) => {
     const context = await resolveExecutionContext(input);
+    const readiness = await ensureBootstrapReady(context, input, 'brainlink_sync');
+    if (readiness.preflight) {
+        return readiness.preflight;
+    }
     const index = await indexVault(context.vault);
     const stats = await getStats(context.vault, context.agent);
     const validation = await validateVault(context.vault, context.agent);
@@ -247,6 +421,7 @@ export const syncTool = async (input) => {
     const response = {
         vault: context.vault,
         agent: context.agent,
+        ...(readiness.bootstrap ? { bootstrap: readiness.bootstrap } : {}),
         index,
         stats,
         validation,
@@ -256,8 +431,10 @@ export const syncTool = async (input) => {
     if (!input.contextQuery) {
         return jsonResult(response);
     }
-    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
-    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, input.contextLimit, input.contextTokens, context.agent, mode);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const contextLimit = input.contextLimit ?? context.defaults.defaultSearchLimit;
+    const contextTokens = input.contextTokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, contextLimit, contextTokens, context.agent, mode);
     return jsonResult({
         ...response,
         context: {
@@ -266,3 +443,228 @@ export const syncTool = async (input) => {
         }
     });
 };
+export const bootstrapTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    const limit = input.limit ?? context.defaults.defaultSearchLimit;
+    const tokens = input.tokens ?? context.defaults.defaultContextTokens;
+    const contextPackage = input.query
+        ? await buildContextPackage(context.vault, input.query, limit, tokens, context.agent, mode)
+        : undefined;
+    const guidance = stats.documentCount === 0
+        ? 'Vault indexed with zero documents. Add durable notes with brainlink_add_note, then run brainlink_bootstrap again.'
+        : input.query
+            ? 'Use returned context as grounding baseline, then write durable updates with brainlink_add_note when needed.'
+            : 'Run brainlink_context with the current task query to retrieve grounded context before answering.';
+    const session = await touchBootstrapSession(context.vault, context.agent);
+    const policy = await getBootstrapPolicy();
+    const nextActions = stats.documentCount === 0
+        ? [
+            {
+                tool: 'brainlink_add_note',
+                reason: 'No indexed documents were found. Add durable Markdown memory first.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    title: 'Architecture',
+                    content: 'Durable memory with explicit [[links]] and #tags.'
+                }
+            },
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Re-run bootstrap after writing notes so context tools can work on fresh index state.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode
+                }
+            }
+        ]
+        : input.query
+            ? [
+                {
+                    tool: 'brainlink_add_note',
+                    reason: 'Persist relevant outcomes from this task as durable memory.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        title: 'Task Update',
+                        content: 'Summarize durable findings and connect with [[existing notes]].'
+                    }
+                }
+            ]
+            : [
+                {
+                    tool: 'brainlink_context',
+                    reason: 'Fetch grounded context for the current task.',
+                    args: {
+                        vault: context.vault,
+                        ...(context.agent ? { agent: context.agent } : {}),
+                        query: '<task>',
+                        mode,
+                        limit,
+                        tokens
+                    }
+                }
+            ];
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        mode,
+        limit,
+        tokens,
+        index,
+        stats,
+        validation,
+        policy,
+        session,
+        guidance,
+        ...(contextPackage ? { context: contextPackage } : {})
+    }, nextActions));
+};
+export const policyTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const presetPatch = input.preset === 'strict'
+        ? {
+            enforceBootstrap: true,
+            autoBootstrapOnRead: false,
+            autoBootstrapOnStartup: false
+        }
+        : input.preset === 'fully-auto'
+            ? {
+                enforceBootstrap: true,
+                autoBootstrapOnRead: true,
+                autoBootstrapOnStartup: true
+            }
+            : {};
+    const policy = input.preset !== undefined ||
+        typeof input.enforceBootstrap === 'boolean' ||
+        typeof input.autoBootstrapOnRead === 'boolean' ||
+        typeof input.autoBootstrapOnStartup === 'boolean' ||
+        typeof input.staleAfterMinutes === 'number'
+        ? await setBootstrapPolicy({
+            ...presetPatch,
+            ...(typeof input.enforceBootstrap === 'boolean' ? { enforceBootstrap: input.enforceBootstrap } : {}),
+            ...(typeof input.autoBootstrapOnRead === 'boolean' ? { autoBootstrapOnRead: input.autoBootstrapOnRead } : {}),
+            ...(typeof input.autoBootstrapOnStartup === 'boolean' ? { autoBootstrapOnStartup: input.autoBootstrapOnStartup } : {}),
+            ...(typeof input.staleAfterMinutes === 'number' ? { staleAfterMinutes: input.staleAfterMinutes } : {})
+        })
+        : await getBootstrapPolicy();
+    const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const nextActions = bootstrapStatus.ready
+        ? []
+        : [
+            {
+                tool: 'brainlink_bootstrap',
+                reason: 'Bootstrap status is not ready. Run bootstrap before using read tools.',
+                args: {
+                    vault: context.vault,
+                    ...(context.agent ? { agent: context.agent } : {}),
+                    mode: context.defaults.defaultSearchMode
+                }
+            }
+        ];
+    return jsonResult(withNextActions({
+        vault: context.vault,
+        agent: context.agent,
+        policy,
+        bootstrapStatus,
+        ...(input.preset ? { presetApplied: input.preset } : {})
+    }, nextActions));
+};
+export const recommendationsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const policy = await getBootstrapPolicy();
+    const bootstrapStatus = await getBootstrapSessionStatus(context.vault, context.agent);
+    const stats = await getStats(context.vault, context.agent);
+    const mode = sanitizeSearchMode(input.mode, context.defaults.defaultSearchMode);
+    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,
+                        ...(query ? { query } : {})
+                    }
+                }
+            ]
+            : []),
+        ...(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,
+                limit,
+                tokens
+            }
+        },
+        {
+            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,
+            limit,
+            tokens
+        },
+        policy,
+        bootstrapStatus,
+        stats,
+        recommendations
+    });
+};