@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/working/offload.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID, createHash } from "node:crypto";
+import { isForeignAbsolutePath, resolveRegistryConfig } from "../../resolver.js";
+import { appendWorkingStep, compressStepLog, readWorkingSteps } from "./step-log.js";
+import { buildAnnotatedCanvas, readWorkingCanvas, writeWorkingCanvas } from "./canvas.js";
+function defaultWorkspacePath() {
+    return resolveRegistryConfig().localRoot ?? process.cwd();
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function pathSegment(value) {
+    return encodeURIComponent(value.trim() || "default");
+}
+export function detectTokenPressure(estimatedTokens, contextWindowTokens) {
+    if (contextWindowTokens <= 0)
+        return "none";
+    const fillRatio = estimatedTokens / contextWindowTokens;
+    if (fillRatio > 0.85)
+        return "aggressive";
+    if (fillRatio > 0.5)
+        return "mild";
+    return "none";
+}
+function getWorkspaceId(workspacePath) {
+    if (!workspacePath)
+        return "global";
+    if (isWorkspaceId(workspacePath)) {
+        return workspacePath;
+    }
+    if (isForeignAbsolutePath(workspacePath)) {
+        return createHash("sha256").update(workspacePath).digest("hex").slice(0, 12);
+    }
+    try {
+        const resolved = path.resolve(workspacePath);
+        return createHash("sha256").update(resolved).digest("hex").slice(0, 12);
+    }
+    catch {
+        return createHash("sha256").update(workspacePath).digest("hex").slice(0, 12);
+    }
+}
+function isWorkspaceId(value) {
+    return value === "global" || /^[a-f0-9]{12}$/i.test(value);
+}
+export function getWorkingMemoryDir(workspacePath, userId, sessionKey) {
+    // Working memory is per-session ephemeral state. It lives ENTIRELY under
+    // the user home — never inside the project tree — so the workspace stays
+    // clean and so two clones of the same repo don't share state.
+    //
+    // Why not write to `<workspace>/.brainrouter/work/`? Two reasons:
+    //   1. Pollution: the brainrouter CLI's migration archives anything that
+    //      isn't `<workspace>/.brainrouter/workflows/` into
+    //      `<workspace>/.brainrouter.migrated/` on each launch — so the
+    //      MCP would re-create the dir, the CLI would re-archive it, and the
+    //      user would see both folders reappear on every session.
+    //   2. Misuse: a non-absolute `workspacePath` like "global" (a skill
+    //      scope token) would resolve relative to the MCP process cwd and
+    //      build a phantom `<cwd>/global/.brainrouter/work/` that has
+    //      nothing to do with any real workspace.
+    //
+    // Layout: ~/.brainrouter/work/<userId>/<workspaceId>/<sessionKey>/
+    const root = path.join(os.homedir(), ".brainrouter");
+    const workspaceId = getWorkspaceId(workspacePath);
+    const targetDir = path.join(root, "work", pathSegment(userId), workspaceId);
+    try {
+        fs.mkdirSync(targetDir, { recursive: true });
+    }
+    catch {
+        // Best-effort. If the home dir is unwritable the next write call will
+        // surface the error with a useful path.
+    }
+    return path.join(targetDir, pathSegment(sessionKey));
+}
+function refPathFor(workDir, nodeId) {
+    return path.join(workDir, "refs", `${nodeId}.md`);
+}
+function writeState(workDir, state) {
+    fs.mkdirSync(workDir, { recursive: true });
+    fs.writeFileSync(path.join(workDir, "state.json"), JSON.stringify(state, null, 2), "utf8");
+}
+function buildState(sessionKey, workDir, steps, pressureLevel, contextWindowTokens, estimatedTokens) {
+    const recentSteps = pressureLevel === "none" ? steps.slice(-10) : steps.slice(-5);
+    const currentNode = recentSteps.at(-1);
+    return {
+        sessionKey,
+        workDir,
+        pressureLevel,
+        contextWindowTokens,
+        estimatedTokens,
+        injectedState: {
+            currentNode,
+            recentSteps,
+            refs: recentSteps
+                .filter((step) => step.refPath)
+                .map((step) => ({ nodeId: step.nodeId, refPath: step.refPath, title: step.title })),
+            rawPayloadsIncluded: false,
+        },
+        updatedAt: new Date().toISOString(),
+    };
+}
+export function offloadWorkingPayload(input) {
+    const workDir = getWorkingMemoryDir(input.workspacePath, input.userId, input.sessionKey);
+    const refsDir = path.join(workDir, "refs");
+    fs.mkdirSync(refsDir, { recursive: true });
+    const nodeId = `w${Date.now()}-${randomUUID().slice(0, 8)}`;
+    const absoluteRefPath = refPathFor(workDir, nodeId);
+    // Stored as a display-friendly path relative to the user home (where
+    // workDir now always lives). We don't reconstruct the workspace prefix
+    // here because the working-memory tree no longer touches the workspace.
+    const relativeRefPath = path.relative(os.homedir(), absoluteRefPath);
+    const observedAt = new Date().toISOString();
+    const tokenEstimate = estimateTokens(input.payload);
+    const estimatedTokens = input.estimatedTokens ?? tokenEstimate;
+    const contextWindowTokens = input.contextWindowTokens ?? 128_000;
+    const pressureLevel = input.forceAggressive
+        ? "aggressive"
+        : detectTokenPressure(estimatedTokens, contextWindowTokens);
+    fs.writeFileSync(absoluteRefPath, [
+        `# ${input.title ?? "Working Memory Ref"}`,
+        "",
+        `- nodeId: ${nodeId}`,
+        `- kind: ${input.kind ?? "tool_output"}`,
+        `- observedAt: ${observedAt}`,
+        "",
+        input.payload,
+    ].join("\n"), "utf8");
+    appendWorkingStep(workDir, {
+        nodeId,
+        title: input.title ?? "Working payload offloaded",
+        summary: input.summary ?? input.payload.slice(0, 240),
+        kind: input.kind ?? "tool_output",
+        createdAt: observedAt,
+        refPath: relativeRefPath,
+        tokenEstimate,
+    });
+    const steps = pressureLevel === "none"
+        ? readWorkingSteps(workDir)
+        : compressStepLog(workDir, 5).steps;
+    const canvas = writeWorkingCanvas(workDir, steps);
+    const state = buildState(input.sessionKey, workDir, steps, pressureLevel, contextWindowTokens, estimatedTokens);
+    writeState(workDir, state);
+    return { nodeId, refPath: absoluteRefPath, pressureLevel, canvas, state };
+}
+export function getWorkingContext(workspacePath, userId, sessionKey, options) {
+    const workDir = getWorkingMemoryDir(workspacePath, userId, sessionKey);
+    fs.mkdirSync(path.join(workDir, "refs"), { recursive: true });
+    const estimatedTokens = options?.estimatedTokens ?? 0;
+    const contextWindowTokens = options?.contextWindowTokens ?? 128_000;
+    const pressureLevel = detectTokenPressure(estimatedTokens, contextWindowTokens);
+    const steps = pressureLevel === "none"
+        ? readWorkingSteps(workDir)
+        : compressStepLog(workDir, 5).steps;
+    const canvas = steps.length > 0 ? writeWorkingCanvas(workDir, steps) : readWorkingCanvas(workDir);
+    const annotatedCanvas = options?.activeNodeId ? buildAnnotatedCanvas(steps, options.activeNodeId) : undefined;
+    const state = buildState(sessionKey, workDir, steps, pressureLevel, contextWindowTokens, estimatedTokens);
+    writeState(workDir, state);
+    const refPath = options?.nodeId ? refPathFor(workDir, options.nodeId) : undefined;
+    const ref = refPath && fs.existsSync(refPath)
+        ? { nodeId: options.nodeId, path: refPath, content: fs.readFileSync(refPath, "utf8") }
+        : undefined;
+    return { sessionKey, workDir, canvas: annotatedCanvas ?? canvas, annotatedCanvas, state, steps, ref };
+}
+export function resetWorkingMemory(workspacePath, userId, sessionKey) {
+    const workDir = getWorkingMemoryDir(workspacePath, userId, sessionKey);
+    const deleted = fs.existsSync(workDir);
+    fs.rmSync(workDir, { recursive: true, force: true });
+    return { deleted, workDir };
+}
+export function listActiveSessions(userId) {
+    const root = path.join(os.homedir(), ".brainrouter", "work", pathSegment(userId));
+    if (!fs.existsSync(root))
+        return [];
+    const results = [];
+    try {
+        const workspaceIds = fs.readdirSync(root);
+        for (const workspaceId of workspaceIds) {
+            const workspacePath = path.join(root, workspaceId);
+            if (!fs.statSync(workspacePath).isDirectory())
+                continue;
+            const sessionKeys = fs.readdirSync(workspacePath);
+            for (const sessionKey of sessionKeys) {
+                const sessionPath = path.join(workspacePath, sessionKey);
+                if (!fs.statSync(sessionPath).isDirectory())
+                    continue;
+                let updatedAt = new Date(fs.statSync(sessionPath).mtime).toISOString();
+                try {
+                    const stateFile = path.join(sessionPath, "state.json");
+                    if (fs.existsSync(stateFile)) {
+                        const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+                        if (state.updatedAt)
+                            updatedAt = state.updatedAt;
+                    }
+                }
+                catch {
+                    // Ignore
+                }
+                results.push({
+                    sessionKey: decodeURIComponent(sessionKey),
+                    workspaceId,
+                    updatedAt,
+                });
+            }
+        }
+    }
+    catch {
+        // Ignore
+    }
+    return results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}

package/dist/memory/working/step-log.d.ts

@@ -0,0 +1,16 @@
+export interface WorkingStep {
+    nodeId: string;
+    title: string;
+    summary: string;
+    kind: string;
+    createdAt: string;
+    refPath?: string;
+    tokenEstimate: number;
+}
+export interface StepLogCompressionResult {
+    steps: WorkingStep[];
+    compressed: boolean;
+}
+export declare function appendWorkingStep(workDir: string, step: WorkingStep): void;
+export declare function readWorkingSteps(workDir: string): WorkingStep[];
+export declare function compressStepLog(workDir: string, keepLast?: number): StepLogCompressionResult;

package/dist/memory/working/step-log.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+export function appendWorkingStep(workDir, step) {
+    fs.mkdirSync(workDir, { recursive: true });
+    fs.appendFileSync(path.join(workDir, "steps.jsonl"), `${JSON.stringify(step)}\n`, "utf8");
+}
+export function readWorkingSteps(workDir) {
+    const stepsPath = path.join(workDir, "steps.jsonl");
+    if (!fs.existsSync(stepsPath))
+        return [];
+    return fs.readFileSync(stepsPath, "utf8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export function compressStepLog(workDir, keepLast = 5) {
+    const steps = readWorkingSteps(workDir);
+    if (steps.length <= keepLast) {
+        return { steps, compressed: false };
+    }
+    const archived = steps.slice(0, -keepLast);
+    const retained = steps.slice(-keepLast);
+    const archiveStep = {
+        nodeId: `summary-${Date.now()}`,
+        title: `Compressed ${archived.length} earlier steps`,
+        summary: archived.map((step) => `${step.title}: ${step.summary}`).join(" | "),
+        kind: "compressed_summary",
+        createdAt: new Date().toISOString(),
+        tokenEstimate: archived.reduce((total, step) => total + step.tokenEstimate, 0),
+    };
+    const nextSteps = [archiveStep, ...retained];
+    fs.writeFileSync(path.join(workDir, "steps.jsonl"), `${nextSteps.map((step) => JSON.stringify(step)).join("\n")}\n`, "utf8");
+    return { steps: nextSteps, compressed: true };
+}

package/dist/registry.d.ts

@@ -0,0 +1,34 @@
+import type { SkillManifest, DocManifest, PersonaManifest, ReferenceManifest, RegistryConfig, SkillScope, DocCategory } from './types.js';
+export declare class Registry {
+    private skills;
+    private docs;
+    private personas;
+    private references;
+    private config;
+    constructor(config: RegistryConfig);
+    /** Scan all roots and populate the in-memory manifests. */
+    build(): void;
+    private indexSkills;
+    private indexPersonas;
+    private indexReferences;
+    private indexDocs;
+    /** Re-scan after a write operation. */
+    refresh(): void;
+    getSkill(name: string): SkillManifest | undefined;
+    listSkills(category?: string, scope?: SkillScope | 'all'): SkillManifest[];
+    searchSkills(query: string, scope?: SkillScope | 'all'): Array<SkillManifest & {
+        relevance: string;
+    }>;
+    getDoc(name: string): DocManifest | undefined;
+    listDocs(category?: DocCategory): DocManifest[];
+    getPersona(name: string): PersonaManifest | undefined;
+    listPersonas(): PersonaManifest[];
+    getReference(name: string): ReferenceManifest | undefined;
+    listReferences(): ReferenceManifest[];
+    /** The resolved local root (for write operations). */
+    getLocalRoot(): string | undefined;
+    /** The global root (BrainRouter repo). */
+    getGlobalRoot(): string;
+    /** The local project name. */
+    getLocalProjectName(): string | undefined;
+}

package/dist/registry.js

@@ -0,0 +1,305 @@
+// ─────────────────────────────────────────────
+// BrainRouter MCP Server — Dual Registry
+// Scans global + local roots, merges manifests.
+// Local always shadows global on name conflict.
+// ─────────────────────────────────────────────
+import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { join, relative, basename } from 'path';
+import matter from 'gray-matter';
+// ─── Helpers ────────────────────────────────
+/**
+ * Recursively find all files matching a filename in a directory.
+ */
+function findFiles(dir, filename) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    function walk(current) {
+        for (const entry of readdirSync(current)) {
+            const full = join(current, entry);
+            try {
+                const stat = statSync(full);
+                if (stat.isDirectory()) {
+                    walk(full);
+                }
+                else if (entry === filename) {
+                    results.push(full);
+                }
+            }
+            catch {
+                // Skip unreadable entries
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+/**
+ * Find all direct .md files in a directory (non-recursive).
+ */
+function findMdFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.md'))
+        .map((f) => join(dir, f));
+}
+/**
+ * Derive the category from a skill file path.
+ * e.g. .../skills/agent/bootstrap-skill/SKILL.md → "agent"
+ */
+function deriveCategory(filePath, skillsRoot) {
+    const rel = relative(skillsRoot, filePath);
+    const parts = rel.split('/');
+    return parts.length >= 2 ? parts[0] : 'uncategorized';
+}
+/**
+ * Parse frontmatter from a SKILL.md. Returns name + description.
+ */
+function parseSkillFrontmatter(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const { data } = matter(raw);
+        if (data.name && data.description) {
+            return {
+                name: String(data.name),
+                description: String(data.description),
+                category: data.category ? String(data.category) : undefined
+            };
+        }
+    }
+    catch {
+        // Skip unparseable files
+    }
+    return null;
+}
+/**
+ * Derive the doc category from its file path.
+ * e.g. .../docs/api/API.md → "api"
+ */
+function deriveDocCategory(filePath, docsRoot) {
+    const rel = relative(docsRoot, filePath);
+    const parts = rel.split('/');
+    const cat = parts.length >= 2 ? parts[0].toLowerCase() : 'other';
+    const valid = ['api', 'design', 'schema', 'deployment', 'hooks', 'strategy'];
+    return valid.includes(cat) ? cat : 'other';
+}
+/**
+ * Derive a doc name from its file path.
+ * e.g. .../docs/api/API.md → "api"
+ */
+function deriveDocName(filePath) {
+    return basename(filePath, '.md').toLowerCase();
+}
+// ─── Registry Class ──────────────────────────
+export class Registry {
+    skills = new Map();
+    docs = new Map();
+    personas = new Map();
+    references = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // ─── Build ──────────────────────────────
+    /** Scan all roots and populate the in-memory manifests. */
+    build() {
+        this.skills.clear();
+        this.docs.clear();
+        this.personas.clear();
+        this.references.clear();
+        // 1. Index global skills (BrainRouter repo) first
+        this.indexSkills(this.config.globalRoot, 'global');
+        this.indexPersonas(this.config.globalRoot);
+        this.indexReferences(this.config.globalRoot);
+        // 2. Index local skills — these shadow global on name conflict
+        if (this.config.localRoot && this.config.localRoot !== this.config.globalRoot) {
+            this.indexSkills(this.config.localRoot, 'local');
+            this.indexPersonas(this.config.localRoot);
+            this.indexReferences(this.config.localRoot);
+        }
+        // Local docs (project-specific source-of-truth)
+        if (this.config.localRoot) {
+            this.indexDocs(this.config.localRoot);
+        }
+    }
+    // ─── Indexing ───────────────────────────
+    indexSkills(root, scope) {
+        const universalSkillsDir = join(root, 'skills');
+        const projectSkillsDir = join(root, 'projects');
+        // Index Universal Skills
+        if (existsSync(universalSkillsDir)) {
+            const skillFiles = findFiles(universalSkillsDir, 'SKILL.md');
+            for (const filePath of skillFiles) {
+                const meta = parseSkillFrontmatter(filePath);
+                if (!meta)
+                    continue;
+                const category = deriveCategory(filePath, universalSkillsDir);
+                this.skills.set(meta.name, {
+                    name: meta.name,
+                    category,
+                    description: meta.description,
+                    filePath,
+                    scope,
+                });
+            }
+        }
+        // Index Project-Specific Skills
+        if (existsSync(projectSkillsDir)) {
+            const skillFiles = findFiles(projectSkillsDir, 'SKILL.md');
+            for (const filePath of skillFiles) {
+                const meta = parseSkillFrontmatter(filePath);
+                if (!meta)
+                    continue;
+                const rel = relative(projectSkillsDir, filePath);
+                const parts = rel.split('/');
+                // project should normally always exist since parts > 1 for valid structure
+                const project = parts.length > 0 ? parts[0] : '';
+                // New structure: <project>/skills/<category>/<name>/SKILL.md
+                // parts[0]=project, parts[1]=skills, parts[2]=category, parts[3]=name
+                const category = meta.category || (parts.length >= 4 ? parts[2] : 'api');
+                this.skills.set(meta.name, {
+                    name: meta.name,
+                    category,
+                    project,
+                    description: meta.description,
+                    filePath,
+                    scope,
+                });
+            }
+        }
+    }
+    indexPersonas(root) {
+        const agentsDir = join(root, 'agents');
+        const files = findMdFiles(agentsDir);
+        for (const filePath of files) {
+            const name = basename(filePath, '.md');
+            if (name === 'README')
+                continue;
+            this.personas.set(name, { name, filePath });
+        }
+    }
+    indexReferences(root) {
+        const refsDir = join(root, 'references');
+        const files = findMdFiles(refsDir);
+        for (const filePath of files) {
+            const name = basename(filePath, '.md');
+            this.references.set(name, { name, filePath });
+        }
+    }
+    indexDocs(root) {
+        const docsDir = join(root, 'docs');
+        if (!existsSync(docsDir))
+            return;
+        // Recursively find all .md files under docs/
+        function walkDocs(dir, results) {
+            if (!existsSync(dir))
+                return;
+            for (const entry of readdirSync(dir)) {
+                const full = join(dir, entry);
+                try {
+                    const stat = statSync(full);
+                    if (stat.isDirectory()) {
+                        walkDocs(full, results);
+                    }
+                    else if (entry.endsWith('.md')) {
+                        results.push(full);
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        const docFiles = [];
+        walkDocs(docsDir, docFiles);
+        for (const filePath of docFiles) {
+            const name = deriveDocName(filePath);
+            const category = deriveDocCategory(filePath, docsDir);
+            const stat = statSync(filePath);
+            this.docs.set(name, {
+                name,
+                category,
+                filePath,
+                lastModified: stat.mtime,
+            });
+        }
+    }
+    // ─── Refresh ────────────────────────────
+    /** Re-scan after a write operation. */
+    refresh() {
+        this.build();
+    }
+    // ─── Queries ────────────────────────────
+    getSkill(name) {
+        const skill = this.skills.get(name);
+        if (!skill)
+            return undefined;
+        // Filter by project: allow if universal (!skill.project) or matches current project
+        if (this.config.localProjectName && skill.project && skill.project !== this.config.localProjectName) {
+            return undefined;
+        }
+        return skill;
+    }
+    listSkills(category, scope) {
+        let all = Array.from(this.skills.values());
+        // Filter by project
+        if (this.config.localProjectName) {
+            all = all.filter((s) => !s.project || s.project === this.config.localProjectName);
+        }
+        if (category)
+            all = all.filter((s) => s.category === category);
+        if (scope && scope !== 'all')
+            all = all.filter((s) => s.scope === scope);
+        return all.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    }
+    searchSkills(query, scope) {
+        const q = query.toLowerCase();
+        let all = Array.from(this.skills.values());
+        // Filter by project
+        if (this.config.localProjectName) {
+            all = all.filter((s) => !s.project || s.project === this.config.localProjectName);
+        }
+        if (scope && scope !== 'all')
+            all = all.filter((s) => s.scope === scope);
+        return all
+            .filter((s) => s.name.includes(q) ||
+            s.description.toLowerCase().includes(q) ||
+            s.category.includes(q))
+            .map((s) => ({
+            ...s,
+            relevance: s.name.includes(q) ? 'name match' : s.description.toLowerCase().includes(q) ? 'description match' : 'category match',
+        }));
+    }
+    getDoc(name) {
+        return this.docs.get(name);
+    }
+    listDocs(category) {
+        let all = Array.from(this.docs.values());
+        if (category)
+            all = all.filter((d) => d.category === category);
+        return all.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    }
+    getPersona(name) {
+        return this.personas.get(name);
+    }
+    listPersonas() {
+        return Array.from(this.personas.values());
+    }
+    getReference(name) {
+        return this.references.get(name);
+    }
+    listReferences() {
+        return Array.from(this.references.values());
+    }
+    /** The resolved local root (for write operations). */
+    getLocalRoot() {
+        return this.config.localRoot;
+    }
+    /** The global root (BrainRouter repo). */
+    getGlobalRoot() {
+        return this.config.globalRoot;
+    }
+    /** The local project name. */
+    getLocalProjectName() {
+        return this.config.localProjectName;
+    }
+}

package/dist/resolver.d.ts

@@ -0,0 +1,17 @@
+import type { RegistryConfig, BrainRouterConfig } from './types.js';
+export declare function isForeignAbsolutePath(workspacePath: string | undefined): boolean;
+export declare function getSafeWorkspacePath(workspacePath: string): string;
+/**
+ * Read and parse brainrouter.config.json from a directory, if present.
+ */
+export declare function readBrainRouterConfig(dir: string): BrainRouterConfig;
+/**
+ * Resolve the final RegistryConfig.
+ *
+ * Priority:
+ *   1. --root <path> CLI flag
+ *   2. BRAINROUTER_LOCAL_ROOT env var
+ *   3. Auto-detect by walking up from CWD
+ *   4. Fallback: single-repo mode (localRoot = globalRoot)
+ */
+export declare function resolveRegistryConfig(): RegistryConfig;