@andespindola/brainlink 1.0.5 → 1.0.7

package/dist/mcp/tools/shared.js

@@ -0,0 +1,216 @@
+import { basename, extname } from 'node:path';
+import { z } from 'zod';
+import { resolveAgentRuntimeDefaults, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { loadBrainlinkConfig } from '../../infrastructure/config.js';
+import { assertVaultAllowed } from '../../infrastructure/file-system-vault.js';
+import { indexVault } from '../../application/index-vault.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
+export const positiveInteger = (fallback) => z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .transform((value) => value ?? fallback);
+export const optionalPositiveInteger = () => z
+    .number()
+    .int()
+    .positive()
+    .optional();
+export const vaultInput = {
+    vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
+};
+export const agentInput = {
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Agent memory namespace. Omit to use Brainlink.config defaultAgent, otherwise read all agent namespaces.')
+};
+export const searchModeInput = {
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
+};
+export const contextStrategyInput = {
+    strategy: z
+        .enum(['rag', 'cag', 'auto'])
+        .optional()
+        .describe('Context strategy per call. Use rag for fresh retrieval assembly, cag to reuse persisted context packs when fresh, or auto to choose CAG on fresh pack hits and RAG otherwise. Defaults to the Brainlink config value.')
+};
+export 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,
+        defaults
+    };
+};
+export const inferTitleFromPath = (filePath) => {
+    const extension = extname(filePath);
+    const fromFileName = basename(filePath, extension);
+    return fromFileName
+        .trim()
+        .replace(/[-_]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+export const isTruthy = (value) => value !== false;
+export const jsonResult = (value) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify(value, null, 2)
+        }
+    ],
+    structuredContent: value
+});
+export const preflightResult = (value) => jsonResult({
+    preflightRequired: true,
+    ...value
+});
+export const withNextActions = (value, nextActions) => ({
+    ...value,
+    nextActions
+});
+export 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 strategy = sanitizeContextStrategy(typeof input.strategy === 'string' ? input.strategy : undefined, 'rag');
+    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,
+        strategy
+    };
+    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 ensureContextReady = async (context, input, toolName) => {
+    const policy = await getBootstrapPolicy();
+    if (!policy.enforceContextFirst) {
+        return {
+            context: {
+                policy,
+                statusBefore: {
+                    ready: true,
+                    stale: false
+                },
+                reason: 'Context-first enforcement is disabled by policy.'
+            }
+        };
+    }
+    const status = await getContextSessionStatus(context.vault, context.agent);
+    if (status.ready) {
+        return {
+            context: {
+                policy,
+                statusBefore: status,
+                reason: 'Context session is already fresh for this vault/agent.'
+            }
+        };
+    }
+    const queryFromInput = typeof input.query === 'string' && input.query.trim().length > 0
+        ? input.query
+        : typeof input.contextQuery === 'string' && input.contextQuery.trim().length > 0
+            ? input.contextQuery
+            : '<task>';
+    const mode = sanitizeSearchMode(typeof input.mode === 'string' ? input.mode : undefined, context.defaults.defaultSearchMode);
+    const strategy = sanitizeContextStrategy(typeof input.strategy === 'string' ? input.strategy : undefined, context.defaults.defaultContextStrategy);
+    const limit = typeof input.limit === 'number' && Number.isFinite(input.limit) && input.limit > 0
+        ? input.limit
+        : typeof input.contextLimit === 'number' && Number.isFinite(input.contextLimit) && input.contextLimit > 0
+            ? input.contextLimit
+            : context.defaults.defaultSearchLimit;
+    const tokens = typeof input.tokens === 'number' && Number.isFinite(input.tokens) && input.tokens > 0
+        ? input.tokens
+        : typeof input.contextTokens === 'number' && Number.isFinite(input.contextTokens) && input.contextTokens > 0
+            ? input.contextTokens
+            : context.defaults.defaultContextTokens;
+    const contextArgs = {
+        vault: context.vault,
+        ...(context.agent ? { agent: context.agent } : {}),
+        query: queryFromInput,
+        mode,
+        strategy,
+        limit,
+        tokens
+    };
+    const nextActions = [
+        {
+            tool: 'brainlink_context',
+            reason: 'Context must be loaded first so Brainlink is the primary retrieval source before other read tools.',
+            args: contextArgs
+        }
+    ];
+    return {
+        preflight: preflightResult(withNextActions({
+            vault: context.vault,
+            agent: context.agent,
+            blockedTool: toolName,
+            policy,
+            contextStatus: status,
+            guidance: 'Run brainlink_context first for this vault/agent before other read tools so answers are grounded on Brainlink context.',
+            contextArgs
+        }, nextActions))
+    };
+};

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

@@ -0,0 +1,353 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { addNoteWithMetadata } from '../../application/add-note.js';
+import { deleteNote } from '../../application/delete-note.js';
+import { scanDuplicateNotes } from '../../application/dedupe-notes.js';
+import { addInboxItem, listInboxItems, processInboxItems } from '../../application/inbox.js';
+import { indexVault } from '../../application/index-vault.js';
+import { buildRememberSuggestion } from '../../application/memory-suggestions.js';
+import { addVolatileMemory, clearVolatileMemory } from '../../infrastructure/volatile-memory.js';
+import { agentInput, inferTitleFromPath, isTruthy, jsonResult, optionalPositiveInteger, positiveInteger, resolveExecutionContext, vaultInput } from './shared.js';
+export const addNoteInputSchema = {
+    ...vaultInput,
+    title: z.string().min(1).describe('Markdown note title.'),
+    content: z
+        .string()
+        .min(1)
+        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
+    ...agentInput,
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.'),
+    autoContextLinks: z
+        .boolean()
+        .optional()
+        .describe('Automatically add canonical Context Links to the inferred visual context hub. Defaults to Brainlink config.')
+};
+export const rememberInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Optional note title. When omitted, Brainlink infers it from content.'),
+    content: z.string().min(1).describe('Memory content to capture as a durable Markdown note.'),
+    tags: z.array(z.string()).optional().default([]).describe('Extra tags to include.'),
+    links: z.array(z.string()).optional().default([]).describe('Explicit Context Links to include.'),
+    linkLimit: positiveInteger(5).describe('Maximum suggested Context Links to include.'),
+    dryRun: z.boolean().optional().default(false).describe('Preview inferred note without writing it.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
+};
+export const inboxAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z.string().min(1).describe('Quick memory content to store as an untriaged inbox note.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing inbox item.')
+};
+export const inboxListInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: positiveInteger(20).describe('Maximum inbox items to return.')
+};
+export const inboxProcessInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    limit: positiveInteger(10).describe('Maximum inbox items to inspect.')
+};
+export const deleteNoteInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Note title to delete. Use agent to disambiguate namespaced notes.'),
+    path: z.string().min(1).optional().describe('Vault-relative or absolute Markdown note path to delete.'),
+    confirm: z.boolean().describe('Must be true to confirm deletion.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after deletion. Defaults to true.')
+};
+export const addNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    notes: z
+        .array(z.object({
+        title: z.string().min(1).describe('Markdown note title.'),
+        content: z.string().min(1).describe('Durable Markdown memory. Include [[wiki links]] and #tags to connect it.')
+    }))
+        .min(1)
+        .max(100)
+        .describe('Notes to add in a single batch. The vault is reindexed once after all notes are written.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault once after writing all notes.'),
+    autoContextLinks: z
+        .boolean()
+        .optional()
+        .describe('Automatically add canonical Context Links to the inferred context hub. Defaults to Brainlink config.')
+};
+export const deleteNotesInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    notes: z
+        .array(z.object({
+        title: z.string().min(1).optional().describe('Note title to delete.'),
+        path: z.string().min(1).optional().describe('Vault-relative or absolute Markdown note path to delete.')
+    }))
+        .min(1)
+        .max(100)
+        .describe('Notes to delete in a single batch, each selected by exactly one of title or path.'),
+    confirm: z.boolean().describe('Must be true to confirm deletion of every listed note.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault once after all deletions.')
+};
+export const volatileAddInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    content: z
+        .string()
+        .min(1)
+        .describe('Temporary agent-decided memory. Use for current task state, hypotheses, transient user preferences and unconfirmed findings.'),
+    ttlMinutes: optionalPositiveInteger().describe('Minutes before this volatile memory expires. Defaults to 240.'),
+    tags: z.array(z.string()).optional().default([]).describe('Optional tags for volatile retrieval.')
+};
+export const volatileClearInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const addFileInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Optional note title override. If omitted, uses file name.'),
+    filePath: z.string().min(1).describe('Filesystem path to markdown or text file to ingest.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after ingesting file.'),
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
+};
+export const addNoteTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const shouldIndex = isTruthy(input.autoIndex);
+    const added = await addNoteWithMetadata(context.vault, input.title, input.content, context.agent, {
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: input.autoContextLinks ?? context.config.autoCanonicalContextLinks
+    });
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    const focusPath = added.path.includes('agents/') ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/') : undefined;
+    const possibleDuplicates = await scanDuplicateNotes(context.vault, {
+        agentId: context.agent,
+        focusPath,
+        limit: 5,
+        minSemanticScore: 0.92,
+        includeSemantic: true
+    });
+    return jsonResult({
+        vault: context.vault,
+        title: input.title,
+        agent: context.agent,
+        path: added.path,
+        writeConnectivity: {
+            autoLinked: added.autoLinked,
+            linkTarget: added.linkTarget,
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
+        },
+        possibleDuplicates,
+        ...(index ? { index } : {})
+    });
+};
+export const rememberTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const suggestion = await buildRememberSuggestion({
+        vaultPath: context.vault,
+        content: input.content,
+        agentId: context.agent,
+        title: input.title,
+        tags: input.tags,
+        links: input.links,
+        linkLimit: input.linkLimit
+    });
+    if (input.dryRun) {
+        return jsonResult({
+            dryRun: true,
+            vault: context.vault,
+            agent: context.agent,
+            suggestion
+        });
+    }
+    const added = await addNoteWithMetadata(context.vault, suggestion.title, suggestion.content, context.agent, {
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: false
+    });
+    const index = input.autoIndex ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        dryRun: false,
+        vault: context.vault,
+        agent: context.agent,
+        suggestion,
+        path: added.path,
+        ...(index ? { index } : {})
+    });
+};
+export const inboxAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await addInboxItem({
+        vaultPath: context.vault,
+        content: input.content,
+        agentId: context.agent,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        ...result
+    });
+};
+export const inboxListTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const items = await listInboxItems(context.vault, input.limit);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        items
+    });
+};
+export const inboxProcessTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const items = await processInboxItems({
+        vaultPath: context.vault,
+        agentId: context.agent,
+        limit: input.limit
+    });
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        items
+    });
+};
+export const deleteNoteTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const result = await deleteNote(context.vault, {
+        title: input.title,
+        path: input.path,
+        agentId: context.agent,
+        confirm: input.confirm,
+        autoIndex: input.autoIndex
+    });
+    return jsonResult({
+        vault: context.vault,
+        ...result
+    });
+};
+export const addNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const autoContextLinks = input.autoContextLinks ?? context.config.autoCanonicalContextLinks;
+    // Per-note isolation mirrors deleteNotesTool: one failing note (secret,
+    // validation, FS error) is reported without discarding the notes that did
+    // write or skipping the single end-of-batch reindex.
+    const notes = [];
+    for (const note of input.notes) {
+        try {
+            const added = await addNoteWithMetadata(context.vault, note.title, note.content, context.agent, {
+                allowSensitive: input.allowSensitive,
+                autoContextLinks
+            });
+            notes.push({
+                ok: true,
+                title: note.title,
+                path: added.path,
+                writeConnectivity: {
+                    autoLinked: added.autoLinked,
+                    linkTarget: added.linkTarget,
+                    context: added.context,
+                    hubCreated: added.hubCreated,
+                    guaranteedEdge: added.autoLinked
+                }
+            });
+        }
+        catch (error) {
+            notes.push({ ok: false, title: note.title, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const added = notes.filter((entry) => entry.ok === true).length;
+    const index = isTruthy(input.autoIndex) && added > 0 ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        added,
+        failed: notes.length - added,
+        notes,
+        ...(index ? { index } : {})
+    });
+};
+export const deleteNotesTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    if (!input.confirm) {
+        throw new Error('Refusing to delete notes without explicit confirmation.');
+    }
+    const results = [];
+    for (const note of input.notes) {
+        try {
+            // Defer indexing: reindex once after the whole batch instead of per note.
+            const result = await deleteNote(context.vault, {
+                title: note.title,
+                path: note.path,
+                agentId: context.agent,
+                confirm: true,
+                autoIndex: false
+            });
+            results.push({ ok: true, title: result.title, path: result.relativePath });
+        }
+        catch (error) {
+            results.push({ ok: false, selector: note, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const deleted = results.filter((entry) => entry.ok === true).length;
+    const index = isTruthy(input.autoIndex) && deleted > 0 ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        deleted,
+        failed: results.length - deleted,
+        results,
+        ...(index ? { index } : {})
+    });
+};
+export const volatileAddTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const entry = await addVolatileMemory(context.vault, input.content, context.agent ?? 'shared', input.ttlMinutes ?? 240, input.tags);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        volatile: true,
+        entry
+    });
+};
+export const volatileClearTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const cleared = await clearVolatileMemory(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        cleared
+    });
+};
+export const addFileTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const content = await readFile(input.filePath, 'utf8');
+    const inferredTitle = inferTitleFromPath(input.filePath);
+    const title = input.title ?? inferredTitle;
+    if (title == null || title.length === 0) {
+        throw new Error('Cannot infer note title from file path. Provide a title explicitly.');
+    }
+    const shouldIndex = isTruthy(input.autoIndex);
+    const added = await addNoteWithMetadata(context.vault, title, content, context.agent, {
+        allowSensitive: input.allowSensitive,
+        autoContextLinks: context.config.autoCanonicalContextLinks
+    });
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        title,
+        agent: context.agent,
+        filePath: input.filePath,
+        path: added.path,
+        writeConnectivity: {
+            autoLinked: added.autoLinked,
+            linkTarget: added.linkTarget,
+            context: added.context,
+            hubCreated: added.hubCreated,
+            guaranteedEdge: added.autoLinked
+        },
+        ...(index ? { index } : {})
+    });
+};