@andespindola/brainlink 0.1.0-alpha.8 → 0.1.0-beta.0

package/dist/cli/commands/read-commands.js

@@ -20,8 +20,8 @@ export const registerReadCommands = (program) => {
         const resolved = await resolveOptions(options);
         const limit = parsePositiveInteger(options.limit ?? String(resolved.config.defaultSearchLimit), resolved.config.defaultSearchLimit);
         const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
-        const results = await searchKnowledge(resolved.vault, query, limit, options.agent, mode);
-        print(options.json, { query, agent: options.agent, limit, mode, results }, () => results
+        const results = await searchKnowledge(resolved.vault, query, limit, resolved.agent, mode);
+        print(options.json, { query, agent: resolved.agent, limit, mode, results }, () => results
             .map((result, index) => [`${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`, result.content].join('\n'))
             .join('\n\n'));
     });
@@ -33,7 +33,7 @@ export const registerReadCommands = (program) => {
         .description('list indexed wiki links')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const links = await listLinks(resolved.vault, options.agent);
+        const links = await listLinks(resolved.vault, resolved.agent);
         print(options.json, { links }, () => links
             .map((link) => {
             const target = link.toPath ? `${link.toTitle} (${link.toPath})` : `${link.toTitle} (unresolved)`;
@@ -50,7 +50,7 @@ export const registerReadCommands = (program) => {
         .description('list notes linking to a target note')
         .action(async (title, options) => {
         const resolved = await resolveOptions(options);
-        const backlinks = await listBacklinks(resolved.vault, title, options.agent);
+        const backlinks = await listBacklinks(resolved.vault, title, resolved.agent);
         print(options.json, { title, backlinks }, () => backlinks.map((link) => `${link.fromTitle} (${link.fromPath}) -> ${link.toTitle}`).join('\n'));
     });
     program
@@ -66,7 +66,7 @@ export const registerReadCommands = (program) => {
         .action(async (query, options) => {
         const resolved = await resolveOptions(options);
         const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
-        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? '12', 12), parsePositiveInteger(options.tokens ?? String(resolved.config.defaultContextTokens), resolved.config.defaultContextTokens), options.agent, mode);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? '12', 12), parsePositiveInteger(options.tokens ?? String(resolved.config.defaultContextTokens), resolved.config.defaultContextTokens), resolved.agent, mode);
         print(options.json, contextPackage, () => contextPackage.content);
     });
     program
@@ -77,7 +77,7 @@ export const registerReadCommands = (program) => {
         .description('print indexed graph data')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const graph = await getGraph(resolved.vault, options.agent);
+        const graph = await getGraph(resolved.vault, resolved.agent);
         print(options.json, graph, () => JSON.stringify(graph, null, 2));
     });
     program
@@ -98,7 +98,7 @@ export const registerReadCommands = (program) => {
         .description('print indexed vault statistics')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const stats = await getStats(resolved.vault, options.agent);
+        const stats = await getStats(resolved.vault, resolved.agent);
         print(options.json, stats, () => [
             `Documents: ${stats.documentCount}`,
             `Links: ${stats.linkCount}`,
@@ -116,7 +116,7 @@ export const registerReadCommands = (program) => {
         .description('list unresolved wiki links')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const brokenLinks = await getBrokenLinksReport(resolved.vault, options.agent);
+        const brokenLinks = await getBrokenLinksReport(resolved.vault, resolved.agent);
         print(options.json, { brokenLinks }, () => brokenLinks.length === 0
             ? 'No broken links found'
             : brokenLinks.map((link) => `${link.fromTitle} (${link.fromPath}) -> ${link.toTitle}`).join('\n'));
@@ -129,7 +129,7 @@ export const registerReadCommands = (program) => {
         .description('list indexed notes without incoming or outgoing links')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const orphans = await getOrphansReport(resolved.vault, options.agent);
+        const orphans = await getOrphansReport(resolved.vault, resolved.agent);
         print(options.json, { orphans }, () => orphans.length === 0 ? 'No orphan notes found' : orphans.map((node) => `${node.title} (${node.path})`).join('\n'));
     });
     program
@@ -140,7 +140,7 @@ export const registerReadCommands = (program) => {
         .description('validate indexed vault graph health')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const validation = await validateVault(resolved.vault, options.agent);
+        const validation = await validateVault(resolved.vault, resolved.agent);
         print(options.json, validation, () => validation.ok
             ? 'Vault validation passed'
             : `Vault validation failed: ${validation.brokenLinks.length} broken links, ${validation.orphans.length} orphan notes`);

package/dist/cli/commands/write-commands.js

@@ -22,16 +22,16 @@ export const registerWriteCommands = (program) => {
         .argument('<title>', 'note title')
         .requiredOption('-c, --content <content>', 'markdown content')
         .option('-v, --vault <vault>', 'vault directory')
-        .option('-a, --agent <agent>', 'agent memory namespace', 'shared')
+        .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--allow-sensitive', 'allow writing content that looks like a secret')
         .option('--json', 'print machine-readable JSON')
         .description('add a markdown note to the vault')
         .action(async (title, options) => {
         const resolved = await resolveOptions(options);
-        const path = await addNote(resolved.vault, title, options.content, options.agent, {
+        const path = await addNote(resolved.vault, title, options.content, resolved.agent, {
             allowSensitive: Boolean(options.allowSensitive)
         });
-        print(options.json, { title, agent: options.agent ?? 'shared', path }, () => `Created note at ${path}`);
+        print(options.json, { title, agent: resolved.agent ?? 'shared', path }, () => `Created note at ${path}`);
     });
     program
         .command('index')
@@ -89,7 +89,6 @@ export const registerWriteCommands = (program) => {
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
         .option('-w, --watch', 'watch markdown files and reindex on changes')
-        .option('--allow-public', 'allow binding the server to a non-loopback host')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
         .action(async (options) => {
@@ -99,8 +98,7 @@ export const registerWriteCommands = (program) => {
             host: options.host ?? resolved.config.host,
             port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
             shouldIndex: options.index,
-            shouldWatch: Boolean(options.watch),
-            allowPublic: Boolean(options.allowPublic)
+            shouldWatch: Boolean(options.watch)
         });
         print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
     });

package/dist/cli/runtime.js

@@ -10,7 +10,8 @@ export const resolveOptions = async (options) => {
     const allowedVault = assertVaultAllowed(vault, config.allowedVaults);
     return {
         config,
-        vault: allowedVault
+        vault: allowedVault,
+        agent: options.agent ?? config.defaultAgent
     };
 };
 export const print = (json, value, human) => {

package/dist/domain/agents.js

@@ -6,6 +6,7 @@ export const sanitizeAgentId = (agentId) => agentId
     .replace(/[^a-z0-9_-]+/g, '-')
     .replace(/^-+|-+$/g, '') || sharedAgentId;
 export const resolveAgentIdFromPath = (path) => {
-    const [scope, agentId] = path.split('/');
+    const normalizedPath = path.replace(/\\/g, '/');
+    const [scope, agentId] = normalizedPath.split('/');
     return scope === 'agents' && agentId ? sanitizeAgentId(agentId) : sharedAgentId;
 };

package/dist/domain/graph-layout.js

@@ -34,8 +34,17 @@ const groupKey = (node) => {
     return segments[0] ?? 'root';
 };
 const groupLabel = (key) => groupLabels[key] ?? key;
-const incrementDegree = (degrees, id) => new Map([...degrees, [id, (degrees.get(id) ?? 0) + 1]]);
-const countDegrees = (edges) => edges.reduce((degrees, edge) => (edge.target ? incrementDegree(incrementDegree(degrees, edge.source), edge.target) : incrementDegree(degrees, edge.source)), new Map());
+const incrementDegreeBy = (degrees, id, amount) => {
+    degrees.set(id, (degrees.get(id) ?? 0) + amount);
+    return degrees;
+};
+const edgeDegreeWeight = (edge) => Math.max(1, Math.min(edge.weight, 8));
+const countDegrees = (edges) => edges.reduce((degrees, edge) => {
+    const weight = edgeDegreeWeight(edge);
+    return edge.target
+        ? incrementDegreeBy(incrementDegreeBy(degrees, edge.source, weight), edge.target, weight)
+        : incrementDegreeBy(degrees, edge.source, weight);
+}, new Map());
 const uniqueIds = (ids) => Array.from(new Set(ids));
 const createAdjacency = (nodes, edges) => {
     const nodeIds = new Set(nodes.map((node) => node.id));
@@ -134,44 +143,96 @@ const createSegmentNodes = (segments, degrees, segmentCount) => ([segment, nodes
     });
 };
 const distanceBetween = (left, right) => Math.hypot(right.x - left.x, right.y - left.y);
-const separatePair = (minDistance, left, right) => {
+const resolveCollisionPair = (left, right, minDistance) => {
     const dx = right.x - left.x;
     const dy = right.y - left.y;
     const distance = Math.max(Math.hypot(dx, dy), 0.001);
     if (distance >= minDistance) {
-        return [left, right];
+        return;
     }
     const push = (minDistance - distance) / 2;
     const ux = dx / distance;
     const uy = dy / distance;
-    return [
-        {
-            ...left,
-            x: left.x - ux * push,
-            y: left.y - uy * push
-        },
-        {
-            ...right,
-            x: right.x + ux * push,
-            y: right.y + uy * push
+    left.x -= ux * push;
+    left.y -= uy * push;
+    right.x += ux * push;
+    right.y += uy * push;
+};
+const buildCollisionGrid = (nodes, cellSize) => {
+    const grid = new Map();
+    nodes.forEach((node, index) => {
+        const x = Math.floor(node.x / cellSize);
+        const y = Math.floor(node.y / cellSize);
+        const key = `${x},${y}`;
+        const bucket = grid.get(key);
+        if (bucket) {
+            bucket.push(index);
+            return;
         }
-    ];
+        grid.set(key, [index]);
+    });
+    return grid;
 };
-const relaxCollisions = (nodes, minDistance = 132, rounds = 32) => {
-    const relaxRound = (currentNodes) => currentNodes.reduce((resolvedNodes, node) => {
-        const resolved = resolvedNodes.reduce((state, previousNode) => {
-            const [nextPrevious, nextCurrent] = separatePair(minDistance, previousNode, state.current);
-            return {
-                previous: [...state.previous, nextPrevious],
-                current: nextCurrent
-            };
-        }, {
-            previous: [],
-            current: node
+const neighborCellKeys = (x, y) => [
+    `${x - 1},${y - 1}`,
+    `${x},${y - 1}`,
+    `${x + 1},${y - 1}`,
+    `${x - 1},${y}`,
+    `${x},${y}`,
+    `${x + 1},${y}`,
+    `${x - 1},${y + 1}`,
+    `${x},${y + 1}`,
+    `${x + 1},${y + 1}`
+];
+const resolveCollisionsSpatial = (nodes, minDistance) => {
+    const gridCellSize = minDistance * 1.05;
+    const grid = buildCollisionGrid(nodes, gridCellSize);
+    for (let index = 0; index < nodes.length; index += 1) {
+        const left = nodes[index];
+        const leftCellX = Math.floor(left.x / gridCellSize);
+        const leftCellY = Math.floor(left.y / gridCellSize);
+        neighborCellKeys(leftCellX, leftCellY).forEach((key) => {
+            const candidateIndices = grid.get(key) ?? [];
+            candidateIndices.forEach((candidateIndex) => {
+                if (candidateIndex <= index) {
+                    return;
+                }
+                resolveCollisionPair(left, nodes[candidateIndex], minDistance);
+            });
         });
-        return [...resolved.previous, resolved.current];
-    }, []);
-    return Array.from({ length: rounds }).reduce((currentNodes) => relaxRound(currentNodes), nodes);
+    }
+};
+const resolveCollisionsBrute = (nodes, minDistance) => {
+    for (let leftIndex = 0; leftIndex < nodes.length; leftIndex += 1) {
+        const left = nodes[leftIndex];
+        for (let rightIndex = leftIndex + 1; rightIndex < nodes.length; rightIndex += 1) {
+            resolveCollisionPair(left, nodes[rightIndex], minDistance);
+        }
+    }
+};
+const relaxCollisions = (nodes, minDistance = 132, rounds = 32) => {
+    if (nodes.length <= 1) {
+        return nodes;
+    }
+    const effectiveRounds = nodes.length > 1000
+        ? Math.min(rounds, 12)
+        : nodes.length > 500
+            ? Math.min(rounds, 20)
+            : Math.min(rounds, 26);
+    const layoutNodes = nodes.map((node) => ({
+        ...node,
+        x: Number.isFinite(node.x) ? node.x : 0,
+        y: Number.isFinite(node.y) ? node.y : 0
+    }));
+    for (let round = 0; round < effectiveRounds; round += 1) {
+        if (nodes.length <= 250) {
+            resolveCollisionsBrute(layoutNodes, minDistance);
+        }
+        else {
+            resolveCollisionsSpatial(layoutNodes, minDistance);
+        }
+    }
+    return layoutNodes;
 };
 export const createCauliflowerGraphLayout = (graph) => {
     const degrees = countDegrees(graph.edges);

package/dist/domain/markdown.js

@@ -6,8 +6,31 @@ const frontmatterPattern = /^---\n([\s\S]*?)\n---\n?/;
 const wikiLinkPattern = /\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|[^\]]+)?\]\]/g;
 const tagPattern = /(^|\s)#([A-Za-z0-9][A-Za-z0-9_-]*)/g;
 const headingPattern = /^#\s+(.+)$/m;
+const priorityRanks = {
+    low: 0,
+    normal: 1,
+    high: 2,
+    critical: 3
+};
+const priorityBoosts = {
+    low: 0,
+    normal: 1,
+    high: 3,
+    critical: 6
+};
+const priorityPatterns = [
+    ['critical', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:critical|critica|crítica|urgent|urgente|p0)\b/i],
+    ['critical', /#(?:critical|critica|crítica|urgent|urgente|p0)\b/i],
+    ['high', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:high|alta|important|importante|p1)\b/i],
+    ['high', /#(?:high-priority|important|importante|p1)\b/i],
+    ['normal', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:normal|medium|media|média|p2)\b/i],
+    ['normal', /#(?:normal-priority|medium-priority|p2)\b/i],
+    ['low', /\b(?:priority|prioridade|importance|importancia|importância)\s*[:=]\s*(?:low|baixa|p3)\b/i],
+    ['low', /#(?:low-priority|baixa-prioridade|p3)\b/i]
+];
 const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '');
 const unique = (values) => Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
+const maxPriority = (left, right) => priorityRanks[left] >= priorityRanks[right] ? left : right;
 const parseFrontmatter = (content) => {
     const match = content.match(frontmatterPattern);
     if (!match) {
@@ -24,6 +47,57 @@ const parseFrontmatter = (content) => {
 };
 const stripFrontmatter = (content) => content.replace(frontmatterPattern, '');
 const stripFencedCodeBlocks = (content) => content.replace(/```[\s\S]*?```/g, '').replace(/~~~[\s\S]*?~~~/g, '');
+const visibleMarkdownLines = (content) => content.split('\n').reduce((state, line) => {
+    const togglesFence = /^\s*(?:```|~~~)/.test(line);
+    const fenced = togglesFence ? !state.fenced : state.fenced;
+    state.lines.push({ content: line, fenced });
+    return {
+        lines: state.lines,
+        fenced
+    };
+}, {
+    lines: [],
+    fenced: false
+}).lines;
+const linePriority = (line) => priorityPatterns.find(([, pattern]) => pattern.test(line))?.[0] ?? null;
+const linkReferenceWeight = (line, priority) => {
+    const headingBoost = /^\s{0,3}#{1,6}\s+/.test(line) ? 2 : 0;
+    const taskBoost = /^\s*[-*]\s+\[[ x]\]/i.test(line) ? 1 : 0;
+    return 1 + (priority ? priorityBoosts[priority] : 0) + headingBoost + taskBoost;
+};
+export const extractWikiLinkReferences = (content) => visibleMarkdownLines(content)
+    .filter((line) => !line.fenced)
+    .flatMap((line) => {
+    const priority = linePriority(line.content);
+    const weight = linkReferenceWeight(line.content, priority);
+    return Array.from(line.content.matchAll(wikiLinkPattern), (match) => ({
+        title: normalizeTitle(match[1]),
+        weight,
+        priority
+    }));
+});
+const priorityFromWeight = (weight) => weight >= 8 ? 'critical' : weight >= 4 ? 'high' : 'normal';
+export const extractWikiLinkWeights = (content) => {
+    const weights = extractWikiLinkReferences(content).reduce((state, reference) => {
+        const titleKey = reference.title.toLowerCase();
+        const current = state.get(titleKey);
+        const weight = (current?.weight ?? 0) + reference.weight;
+        const explicitPriority = reference.priority
+            ? maxPriority(current?.priority ?? reference.priority, reference.priority)
+            : current?.priority;
+        const derivedPriority = priorityFromWeight(weight);
+        const priority = explicitPriority === 'low' && weight === 1
+            ? 'low'
+            : maxPriority(explicitPriority ?? derivedPriority, derivedPriority);
+        state.set(titleKey, {
+            title: current?.title ?? reference.title,
+            weight,
+            priority
+        });
+        return state;
+    }, new Map());
+    return Array.from(weights.values());
+};
 const extractTitle = (filePath, content, frontmatter) => {
     if (frontmatter.title) {
         return normalizeTitle(frontmatter.title);
@@ -34,8 +108,8 @@ const extractTitle = (filePath, content, frontmatter) => {
     }
     return normalizeTitle(basename(filePath));
 };
-export const extractWikiLinks = (content) => unique(Array.from(stripFencedCodeBlocks(content).matchAll(wikiLinkPattern), (match) => normalizeTitle(match[1])));
-export const extractTags = (content) => unique(Array.from(stripFencedCodeBlocks(content).matchAll(tagPattern), (match) => match[2]));
+export const extractWikiLinks = (content) => unique(extractWikiLinkReferences(content).map((reference) => reference.title));
+export const extractTags = (content) => unique(Array.from(stripFencedCodeBlocks(stripFrontmatter(content)).matchAll(tagPattern), (match) => match[2]));
 const normalizeChunkContent = (content) => content
     .split('\n')
     .map((line) => line.trim())
@@ -87,10 +161,13 @@ export const parseMarkdownDocument = (input) => {
 };
 export const createIndexedDocument = (document, titleToDocumentId, maxChunkCharacters = 1200) => {
     const chunks = splitIntoChunks(document.id, document.content, maxChunkCharacters);
+    const linkWeights = new Map(extractWikiLinkWeights(document.content).map((link) => [link.title.toLowerCase(), link]));
     const links = document.links.map((toTitle) => ({
         fromDocumentId: document.id,
         toTitle,
-        toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null
+        toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null,
+        weight: linkWeights.get(toTitle.toLowerCase())?.weight ?? 1,
+        priority: linkWeights.get(toTitle.toLowerCase())?.priority ?? 'normal'
     }));
     return {
         document,

package/dist/infrastructure/bucket-vault.js

@@ -0,0 +1,171 @@
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { posix } from 'node:path';
+import { getBrainlinkHomePath } from './paths.js';
+const directoryMode = 0o700;
+const fileMode = 0o600;
+const bucketScheme = 's3:';
+const manifestPath = '.brainlink/bucket-manifest.json';
+const excludedSegments = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
+export const isBucketVaultUri = (value) => value.trim().toLowerCase().startsWith('s3://');
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, '');
+const normalizePrefix = (value) => trimSlashes(posix.normalize(trimSlashes(value))).replace(/^\.$/, '');
+export const parseBucketVaultUri = (uri) => {
+    const parsed = new URL(uri);
+    if (parsed.protocol !== bucketScheme || !parsed.hostname) {
+        throw new Error(`Unsupported bucket vault URI: ${uri}. Use s3://bucket/prefix.`);
+    }
+    return {
+        uri: formatBucketVaultUri(parsed.hostname, normalizePrefix(decodeURIComponent(parsed.pathname))),
+        bucket: parsed.hostname,
+        prefix: normalizePrefix(decodeURIComponent(parsed.pathname))
+    };
+};
+export const formatBucketVaultUri = (bucket, prefix) => prefix ? `s3://${bucket}/${prefix}` : `s3://${bucket}`;
+export const getBucketVaultCachePath = (uri) => {
+    const hash = createHash('sha256').update(parseBucketVaultUri(uri).uri).digest('hex').slice(0, 24);
+    return join(getBrainlinkHomePath(), 'bucket-cache', hash);
+};
+const ensureDirectory = async (path) => {
+    await mkdir(path, { recursive: true, mode: directoryMode });
+    await chmod(path, directoryMode);
+};
+const isPathInside = (parent, child) => {
+    const path = relative(parent, child);
+    return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+};
+const toSafeRelativePath = (key) => {
+    const normalized = normalizePrefix(key);
+    if (!normalized || normalized.split('/').some((segment) => segment === '..' || excludedSegments.has(segment))) {
+        return null;
+    }
+    return normalized.endsWith('.md') ? normalized : null;
+};
+const toObjectKey = (reference, relativePath) => reference.prefix ? `${reference.prefix}/${relativePath}` : relativePath;
+const toRelativeObjectKey = (reference, objectKey) => {
+    const relativePath = reference.prefix
+        ? objectKey.startsWith(`${reference.prefix}/`)
+            ? objectKey.slice(reference.prefix.length + 1)
+            : null
+        : objectKey;
+    return relativePath ? toSafeRelativePath(relativePath) : null;
+};
+const createBucketClient = () => new S3Client({
+    region: process.env.AWS_REGION ?? process.env.BRAINLINK_S3_REGION ?? 'us-east-1',
+    endpoint: process.env.BRAINLINK_S3_ENDPOINT ?? process.env.AWS_ENDPOINT_URL,
+    forcePathStyle: process.env.BRAINLINK_S3_FORCE_PATH_STYLE === '1'
+});
+const streamToString = async (body) => {
+    if (body && typeof body === 'object' && 'transformToString' in body && typeof body.transformToString === 'function') {
+        return body.transformToString();
+    }
+    throw new Error('Unsupported S3 object body.');
+};
+const readManifest = async (cachePath) => {
+    try {
+        return JSON.parse(await readFile(join(cachePath, manifestPath), 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return {
+                uri: '',
+                keys: []
+            };
+        }
+        throw error;
+    }
+};
+const writeManifest = async (cachePath, manifest) => {
+    const path = join(cachePath, manifestPath);
+    await ensureDirectory(dirname(path));
+    await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: 'utf8', mode: fileMode });
+    await chmod(path, fileMode);
+};
+const listBucketMarkdownKeys = async (client, reference) => {
+    const keys = [];
+    let continuationToken;
+    do {
+        const result = await client.send(new ListObjectsV2Command({
+            Bucket: reference.bucket,
+            Prefix: reference.prefix ? `${reference.prefix}/` : undefined,
+            ContinuationToken: continuationToken
+        }));
+        keys.push(...(result.Contents ?? []).flatMap((object) => (object.Key ? [object.Key] : [])));
+        continuationToken = result.NextContinuationToken;
+    } while (continuationToken);
+    return keys.flatMap((key) => {
+        const relativePath = toRelativeObjectKey(reference, key);
+        return relativePath ? [relativePath] : [];
+    });
+};
+const removeStaleCachedFiles = async (cachePath, previousKeys, currentKeys) => {
+    await Promise.all(previousKeys
+        .filter((key) => !currentKeys.has(key))
+        .map(async (key) => {
+        const absolutePath = join(cachePath, key);
+        if (isPathInside(cachePath, absolutePath)) {
+            await rm(absolutePath, { force: true });
+        }
+    }));
+};
+const downloadMarkdownFiles = async (client, reference, cachePath, keys) => {
+    await Promise.all(keys.map(async (key) => {
+        const absolutePath = join(cachePath, key);
+        if (!isPathInside(cachePath, absolutePath)) {
+            throw new Error(`Refusing to cache bucket object outside vault cache: ${key}`);
+        }
+        const result = await client.send(new GetObjectCommand({
+            Bucket: reference.bucket,
+            Key: toObjectKey(reference, key)
+        }));
+        await ensureDirectory(dirname(absolutePath));
+        await writeFile(absolutePath, await streamToString(result.Body), { encoding: 'utf8', mode: fileMode });
+        await chmod(absolutePath, fileMode);
+    }));
+};
+export const syncBucketVaultToCache = async (uri) => {
+    const reference = parseBucketVaultUri(uri);
+    const cachePath = getBucketVaultCachePath(reference.uri);
+    const client = createBucketClient();
+    const previousManifest = await readManifest(cachePath);
+    const keys = await listBucketMarkdownKeys(client, reference);
+    const currentKeys = new Set(keys);
+    await ensureDirectory(join(cachePath, '.brainlink'));
+    await removeStaleCachedFiles(cachePath, previousManifest.uri === reference.uri ? previousManifest.keys : [], currentKeys);
+    await downloadMarkdownFiles(client, reference, cachePath, keys);
+    await writeManifest(cachePath, {
+        uri: reference.uri,
+        keys
+    });
+    return cachePath;
+};
+export const writeBucketMarkdownFile = async (uri, filename, content) => {
+    const reference = parseBucketVaultUri(uri);
+    const cachePath = getBucketVaultCachePath(reference.uri);
+    const relativePath = toSafeRelativePath(filename.endsWith('.md') ? filename : `${filename}.md`);
+    if (!relativePath) {
+        throw new Error(`Invalid bucket Markdown path: ${filename}`);
+    }
+    const absolutePath = join(cachePath, relativePath);
+    if (!isPathInside(cachePath, absolutePath)) {
+        throw new Error(`Refusing to write outside bucket cache: ${absolutePath}`);
+    }
+    await ensureDirectory(join(cachePath, '.brainlink'));
+    await ensureDirectory(dirname(absolutePath));
+    await writeFile(absolutePath, content, { encoding: 'utf8', mode: fileMode });
+    await chmod(absolutePath, fileMode);
+    await createBucketClient().send(new PutObjectCommand({
+        Bucket: reference.bucket,
+        Key: toObjectKey(reference, relativePath),
+        Body: content,
+        ContentType: 'text/markdown; charset=utf-8'
+    }));
+    const manifest = await readManifest(cachePath);
+    await writeManifest(cachePath, {
+        uri: reference.uri,
+        keys: Array.from(new Set([...manifest.keys, relativePath])).sort()
+    });
+    return `${reference.uri}/${relativePath}`;
+};

package/dist/infrastructure/config.js

@@ -1,11 +1,13 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { sanitizeAgentId } from '../domain/agents.js';
 import { getDefaultVaultPath } from './paths.js';
 export const defaultBrainlinkConfig = {
     vault: getDefaultVaultPath(),
     host: '127.0.0.1',
     port: 4321,
     allowedVaults: [],
+    defaultAgent: undefined,
     defaultSearchLimit: 10,
     defaultContextTokens: 2000,
     embeddingProvider: 'local',
@@ -40,6 +42,9 @@ const sanitizeConfig = (value) => ({
     ...defaultBrainlinkConfig,
     ...value,
     port: typeof value.port === 'number' && value.port > 0 ? value.port : defaultBrainlinkConfig.port,
+    defaultAgent: typeof value.defaultAgent === 'string' && value.defaultAgent.trim().length > 0
+        ? sanitizeAgentId(value.defaultAgent)
+        : defaultBrainlinkConfig.defaultAgent,
     defaultSearchLimit: typeof value.defaultSearchLimit === 'number' && value.defaultSearchLimit > 0
         ? value.defaultSearchLimit
         : defaultBrainlinkConfig.defaultSearchLimit,

package/dist/infrastructure/file-system-vault.js

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { resolvePath } from './paths.js';
+import { getBucketVaultCachePath, isBucketVaultUri, parseBucketVaultUri, syncBucketVaultToCache, writeBucketMarkdownFile } from './bucket-vault.js';
 const excludedDirectories = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
 const directoryMode = 0o700;
 const fileMode = 0o600;
@@ -15,30 +16,44 @@ const walkMarkdownFiles = async (directory) => {
     }));
     return nested.flat();
 };
-export const resolveVaultPath = (vaultPath) => resolvePath(vaultPath);
+export const resolveVaultPath = (vaultPath) => isBucketVaultUri(vaultPath) ? getBucketVaultCachePath(vaultPath) : resolvePath(vaultPath);
+export const isBucketVaultPath = (vaultPath) => isBucketVaultUri(vaultPath);
 const isPathInside = (parent, child) => {
     const path = relative(parent, child);
     return path === '' || (!path.startsWith('..') && !isAbsolute(path));
 };
+const isBucketPrefixInside = (parent, child) => parent === '' || child === parent || child.startsWith(`${parent}/`);
 const secureDirectory = async (path) => {
     await mkdir(path, { recursive: true, mode: directoryMode });
     await chmod(path, directoryMode);
 };
 export const assertVaultAllowed = (vaultPath, allowedVaults) => {
+    if (isBucketVaultUri(vaultPath)) {
+        const vault = parseBucketVaultUri(vaultPath);
+        const allowed = allowedVaults.filter(isBucketVaultUri).map(parseBucketVaultUri);
+        if (allowedVaults.length > 0 &&
+            !allowed.some((allowedVault) => vault.bucket === allowedVault.bucket && isBucketPrefixInside(allowedVault.prefix, vault.prefix))) {
+            throw new Error(`Vault path is not allowed: ${vault.uri}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
+        }
+        return vault.uri;
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
-    const allowed = allowedVaults.map(resolveVaultPath);
+    const allowed = allowedVaults.filter((allowedVault) => !isBucketVaultUri(allowedVault)).map(resolveVaultPath);
     if (allowed.length > 0 && !allowed.some((allowedPath) => isPathInside(allowedPath, absoluteVaultPath))) {
         throw new Error(`Vault path is not allowed: ${absoluteVaultPath}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
     }
     return absoluteVaultPath;
 };
 export const ensureVault = async (vaultPath) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return syncBucketVaultToCache(vaultPath);
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
     await secureDirectory(join(absoluteVaultPath, '.brainlink'));
     return absoluteVaultPath;
 };
 export const readMarkdownFiles = async (vaultPath) => {
-    const absoluteVaultPath = resolveVaultPath(vaultPath);
+    const absoluteVaultPath = await ensureVault(vaultPath);
     const paths = await walkMarkdownFiles(absoluteVaultPath);
     return Promise.all(paths.map(async (absolutePath) => {
         const [content, stats] = await Promise.all([readFile(absolutePath, 'utf8'), stat(absolutePath)]);
@@ -51,6 +66,9 @@ export const readMarkdownFiles = async (vaultPath) => {
     }));
 };
 export const writeMarkdownFile = async (vaultPath, filename, content) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return writeBucketMarkdownFile(vaultPath, filename, content);
+    }
     const absoluteVaultPath = await ensureVault(vaultPath);
     const absolutePath = resolve(absoluteVaultPath, filename.endsWith('.md') ? filename : `${filename}.md`);
     if (!isPathInside(absoluteVaultPath, absolutePath)) {