@praneeth_54/agentdoctor 1.0.0 → 1.1.1

package/dist/core/understanding/shared/tokens.js

@@ -0,0 +1,141 @@
+/** Path / name segments ignored when mining domain tokens. */
+export const DOMAIN_STOP_SEGMENTS = new Set([
+    "",
+    "src",
+    "lib",
+    "libs",
+    "app",
+    "apps",
+    "packages",
+    "package",
+    "modules",
+    "module",
+    "internal",
+    "cmd",
+    "bin",
+    "dist",
+    "build",
+    "out",
+    "public",
+    "static",
+    "assets",
+    "styles",
+    "css",
+    "js",
+    "ts",
+    "tsx",
+    "jsx",
+    "mjs",
+    "cjs",
+    "py",
+    "go",
+    "rs",
+    "java",
+    "kt",
+    "php",
+    "rb",
+    "dart",
+    "test",
+    "tests",
+    "spec",
+    "specs",
+    "__tests__",
+    "fixtures",
+    "mocks",
+    "mock",
+    "stub",
+    "stubs",
+    "types",
+    "type",
+    "typings",
+    "interfaces",
+    "interface",
+    "utils",
+    "util",
+    "helpers",
+    "helper",
+    "common",
+    "shared",
+    "core",
+    "index",
+    "main",
+    "init",
+    "config",
+    "configs",
+    "constants",
+    "constant",
+    "models",
+    "model",
+    "dto",
+    "entity",
+    "entities",
+    "repository",
+    "repositories",
+    "service",
+    "services",
+    "controller",
+    "controllers",
+    "handler",
+    "handlers",
+    "middleware",
+    "route",
+    "routes",
+    "router",
+    "api",
+    "v1",
+    "v2",
+    "v3",
+    "http",
+    "grpc",
+    "graphql",
+    "component",
+    "components",
+    "hook",
+    "hooks",
+    "page",
+    "pages",
+    "view",
+    "views",
+    "provider",
+    "providers",
+    "store",
+    "stores",
+    "context",
+    "contexts",
+    "domain",
+    "domains",
+    "feature",
+    "features",
+    "node_modules",
+    "vendor",
+]);
+/**
+ * Split a relative path into lowercase semantic tokens.
+ * Deterministic: camelCase, snake_case, kebab-case, path segments.
+ */
+export function tokenizeRelativePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    const withoutExt = normalized.replace(/\.[a-z0-9]+$/i, "");
+    const rawParts = withoutExt.split(/[/_.-]+/);
+    const tokens = [];
+    for (const part of rawParts) {
+        if (!part) {
+            continue;
+        }
+        const camelParts = part.split(/(?<=[a-z0-9])(?=[A-Z])/);
+        for (const piece of camelParts) {
+            const token = piece.toLowerCase();
+            if (token.length < 2) {
+                continue;
+            }
+            if (DOMAIN_STOP_SEGMENTS.has(token)) {
+                continue;
+            }
+            if (/^\d+$/.test(token)) {
+                continue;
+            }
+            tokens.push(token);
+        }
+    }
+    return tokens;
+}

package/dist/core/understanding/snapshot/identity.d.ts

@@ -0,0 +1,24 @@
+import type { ProjectModel } from "../model/types.js";
+/**
+ * Identity of one deterministic understanding snapshot.
+ * contentHash ignores timestamps so structural equality is detectable across rebuild clocks.
+ */
+export interface SnapshotIdentity {
+    id: string;
+    contentHash: string;
+    compilerVersion: string;
+    schemaVersion: string;
+    projectName: string;
+    generatedAt: string;
+    domainCount: number;
+    entrypointCount: number;
+    dependencyCount: number;
+    relationshipCount: number;
+    architectureCount: number;
+}
+export declare function computeContentHash(model: ProjectModel): string;
+export declare function createSnapshotIdentity(model: ProjectModel, options?: {
+    generatedAt?: string;
+}): SnapshotIdentity;
+/** Convenience hash of the full serialized model (includes timestamps). */
+export declare function hashSerializedModel(model: ProjectModel): string;

package/dist/core/understanding/snapshot/identity.js

@@ -0,0 +1,79 @@
+import { createHash } from "node:crypto";
+import { serializeProjectModel } from "../model/serializer.js";
+import { UNDERSTANDING_COMPILER_VERSION } from "../model/version.js";
+function structuralPayload(model) {
+    return {
+        schemaVersion: model.metadata.schemaVersion,
+        compilerVersion: model.compilerMetadata.compilerVersion,
+        projectName: model.metadata.project.name,
+        domains: model.domains.map((d) => ({
+            name: d.name,
+            paths: d.paths,
+            confidence: d.confidence,
+            evidence: d.evidence,
+        })),
+        entrypoints: model.entrypoints.map((e) => ({
+            framework: e.framework,
+            file: e.file,
+            confidence: e.confidence,
+            evidence: e.evidence,
+        })),
+        dependencies: model.dependencies.map((d) => ({
+            from: d.from,
+            to: d.to,
+            type: d.type,
+            confidence: d.confidence,
+            evidence: d.evidence,
+        })),
+        relationships: model.relationships.map((r) => ({
+            source: r.source,
+            target: r.target,
+            relationship: r.relationship,
+            strength: r.strength,
+            bidirectional: r.bidirectional,
+            confidence: r.confidence,
+            evidence: r.evidence,
+        })),
+        architectures: model.architectures.map((a) => ({
+            pattern: a.pattern,
+            matchedRules: a.matchedRules,
+            conflictingEvidence: a.conflictingEvidence,
+            unknowns: a.unknowns,
+            confidence: a.confidence,
+            evidence: a.evidence,
+        })),
+    };
+}
+export function computeContentHash(model) {
+    const json = JSON.stringify(structuralPayload(model));
+    return createHash("sha256").update(json).digest("hex").slice(0, 32);
+}
+export function createSnapshotIdentity(model, options = {}) {
+    const contentHash = computeContentHash(model);
+    const generatedAt = options.generatedAt ?? model.compilerMetadata.generatedAt;
+    const id = createHash("sha256")
+        .update(contentHash)
+        .update("\0")
+        .update(generatedAt)
+        .update("\0")
+        .update(UNDERSTANDING_COMPILER_VERSION)
+        .digest("hex")
+        .slice(0, 24);
+    return {
+        id: `snap_${id}`,
+        contentHash,
+        compilerVersion: model.compilerMetadata.compilerVersion,
+        schemaVersion: model.metadata.schemaVersion,
+        projectName: model.metadata.project.name,
+        generatedAt,
+        domainCount: model.domains.length,
+        entrypointCount: model.entrypoints.length,
+        dependencyCount: model.dependencies.length,
+        relationshipCount: model.relationships.length,
+        architectureCount: model.architectures.length,
+    };
+}
+/** Convenience hash of the full serialized model (includes timestamps). */
+export function hashSerializedModel(model) {
+    return createHash("sha256").update(serializeProjectModel(model)).digest("hex").slice(0, 32);
+}

package/dist/core/understanding/snapshot/index.d.ts

@@ -0,0 +1,2 @@
+export { computeContentHash, createSnapshotIdentity, hashSerializedModel } from "./identity.js";
+export type { SnapshotIdentity } from "./identity.js";

package/dist/core/understanding/snapshot/index.js

@@ -0,0 +1 @@
+export { computeContentHash, createSnapshotIdentity, hashSerializedModel } from "./identity.js";

package/dist/core/understanding/types/index.d.ts

@@ -0,0 +1,22 @@
+export type UnderstandingConfidence = number;
+export interface UnderstandingEvidence {
+    path: string;
+}
+export interface DomainMatch {
+    name: string;
+    confidence: UnderstandingConfidence;
+    evidence: string[];
+}
+export interface DomainDiscoveryResult {
+    domains: DomainMatch[];
+    timingMs: number;
+    filesConsidered: number;
+}
+export interface DomainDiscoveryOptions {
+    /** Repository root. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Minimum confidence to include a domain (0–1). Default 0.5. */
+    minConfidence?: number;
+    /** Minimum distinct evidence paths required. Default 1. */
+    minEvidence?: number;
+}

package/dist/core/understanding/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/core/understanding/understand/formatter.d.ts

@@ -0,0 +1,10 @@
+import type { UnderstandSection, UnderstandSnapshot } from "./types.js";
+/**
+ * Assemble a deterministic plain-text report from an UnderstandSnapshot.
+ */
+export declare function formatUnderstandReport(snapshot: UnderstandSnapshot, options: {
+    maxItems: number;
+}): {
+    text: string;
+    sections: UnderstandSection[];
+};

package/dist/core/understanding/understand/formatter.js

@@ -0,0 +1,115 @@
+import { formatConfidence } from "./summary.js";
+function take(items, maxItems) {
+    return items.slice(0, maxItems);
+}
+function bullet(lines) {
+    return lines.map((line) => `- ${line}`);
+}
+/**
+ * Assemble a deterministic plain-text report from an UnderstandSnapshot.
+ */
+export function formatUnderstandReport(snapshot, options) {
+    const { maxItems } = options;
+    const { repository, domains, entrypoints, architectures, dependencies, relationships, statistics, } = snapshot;
+    const sections = [];
+    sections.push({
+        title: "Repository Overview",
+        lines: [
+            `Project: ${repository.projectName}`,
+            `Schema: ${repository.schemaVersion}`,
+            `Compiler: ${repository.compilerVersion}`,
+            `Generated At: ${repository.generatedAt}`,
+            `Frameworks: ${repository.frameworks.length > 0 ? repository.frameworks.join(", ") : "(none)"}`,
+            `Top Domains: ${repository.topDomains.length > 0 ? repository.topDomains.join(", ") : "(none)"}`,
+            `Top Architectures: ${repository.topArchitectures.length > 0 ? repository.topArchitectures.join(", ") : "(none)"}`,
+        ],
+    });
+    sections.push({
+        title: "Detected Domains",
+        lines: domains.count === 0
+            ? ["(none)"]
+            : bullet(take(domains.domains, maxItems).map((domain) => `${domain.name} (confidence=${formatConfidence(domain.confidence)}, paths=${domain.paths.length})`)),
+    });
+    sections.push({
+        title: "Primary Entry Points",
+        lines: entrypoints.count === 0
+            ? ["(none)"]
+            : bullet(take(entrypoints.entrypoints, maxItems).map((entry) => `${entry.framework}: ${entry.file} (confidence=${formatConfidence(entry.confidence)})`)),
+    });
+    sections.push({
+        title: "Detected Architecture",
+        lines: architectures.count === 0
+            ? ["(none)"]
+            : bullet(take(architectures.architectures, maxItems).map((arch) => {
+                const conflicts = arch.conflictingEvidence.length > 0
+                    ? `; conflicts=${arch.conflictingEvidence.length}`
+                    : "";
+                return `${arch.pattern} (confidence=${formatConfidence(arch.confidence)}, rules=${arch.matchedRules.length}${conflicts})`;
+            })),
+    });
+    sections.push({
+        title: "Dependency Highlights",
+        lines: dependencies.count === 0
+            ? ["(none)"]
+            : bullet(take(dependencies.dependencies, maxItems).map((dep) => `${dep.from} -[${dep.type}]-> ${dep.to} (confidence=${formatConfidence(dep.confidence)})`)),
+    });
+    sections.push({
+        title: "Relationship Highlights",
+        lines: relationships.count === 0
+            ? ["(none)"]
+            : bullet(take(relationships.relationships, maxItems).map((rel) => `${rel.source} -[${rel.relationship}/${rel.strength}]-> ${rel.target} (confidence=${formatConfidence(rel.confidence)})`)),
+    });
+    const stats = statistics.summary.statistics;
+    sections.push({
+        title: "Compiler Confidence",
+        lines: [
+            `Average Confidence: ${formatConfidence(stats.averageConfidence)}`,
+            `Repository Summary Confidence: ${formatConfidence(repository.statistics.averageConfidence)}`,
+            `Domains: ${stats.domainCount}`,
+            `Entrypoints: ${stats.entrypointCount}`,
+            `Dependencies: ${stats.dependencyCount}`,
+            `Relationships: ${stats.relationshipCount}`,
+            `Architectures: ${stats.architectureCount}`,
+        ],
+    });
+    sections.push({
+        title: "Statistics",
+        lines: [
+            `Evidence Count: ${stats.evidenceCount}`,
+            `Pass Timing (ms): domains=${stats.passTimingMs.domains}, entrypoints=${stats.passTimingMs.entrypoints}, dependencies=${stats.passTimingMs.dependencies}, relationships=${stats.passTimingMs.relationships}, architectures=${stats.passTimingMs.architectures}`,
+            `Queries Executed: ${snapshot.queryCount}`,
+        ],
+    });
+    const evidenceLines = [];
+    for (const domain of take(domains.domains, Math.min(3, maxItems))) {
+        for (const item of take(domain.evidence, 2)) {
+            evidenceLines.push(`domain:${domain.name}: ${item}`);
+        }
+    }
+    for (const entry of take(entrypoints.entrypoints, Math.min(3, maxItems))) {
+        for (const item of take(entry.evidence, 1)) {
+            evidenceLines.push(`entrypoint:${entry.file}: ${item}`);
+        }
+    }
+    for (const arch of take(architectures.architectures, Math.min(3, maxItems))) {
+        for (const item of take(arch.matchedRules, 1)) {
+            evidenceLines.push(`architecture:${arch.pattern}: ${item}`);
+        }
+    }
+    sections.push({
+        title: "Evidence Summary",
+        lines: evidenceLines.length === 0 ? ["(none)"] : bullet(evidenceLines),
+    });
+    sections.push({
+        title: "Unknowns",
+        lines: snapshot.unknowns.length === 0 ? ["(none)"] : bullet(take(snapshot.unknowns, maxItems)),
+    });
+    sections.push({
+        title: "Limitations",
+        lines: bullet([...snapshot.limitations]),
+    });
+    const text = sections
+        .map((section) => `${section.title}\n${section.lines.join("\n")}`)
+        .join("\n\n");
+    return { text: `${text}\n`, sections };
+}

package/dist/core/understanding/understand/index.d.ts

@@ -0,0 +1,4 @@
+export { UnderstandService, createUnderstandService, understandAsText } from "./service.js";
+export { formatUnderstandReport } from "./formatter.js";
+export { UNDERSTAND_LIMITATIONS, collectUnknowns, formatConfidence } from "./summary.js";
+export type { UnderstandResult, UnderstandSection, UnderstandSnapshot, UnderstandServiceOptions, UnderstandEngine, } from "./types.js";

package/dist/core/understanding/understand/index.js

@@ -0,0 +1,3 @@
+export { UnderstandService, createUnderstandService, understandAsText } from "./service.js";
+export { formatUnderstandReport } from "./formatter.js";
+export { UNDERSTAND_LIMITATIONS, collectUnknowns, formatConfidence } from "./summary.js";

package/dist/core/understanding/understand/service.d.ts

@@ -0,0 +1,17 @@
+import type { UnderstandEngine, UnderstandResult, UnderstandServiceOptions } from "./types.js";
+/**
+ * First vertical-slice consumer of the Software Understanding Compiler.
+ * Reads exclusively through QueryEngine — never ProjectModel, never compiler passes.
+ */
+export declare class UnderstandService {
+    private readonly engine;
+    private readonly maxItems;
+    constructor(engine: UnderstandEngine, options?: UnderstandServiceOptions);
+    /**
+     * Produce a deterministic human-readable repository understanding report.
+     */
+    summarize(): UnderstandResult;
+}
+export declare function createUnderstandService(engine: UnderstandEngine, options?: UnderstandServiceOptions): UnderstandService;
+/** Convenience: run understand and return plain text only. */
+export declare function understandAsText(engine: UnderstandEngine, options?: UnderstandServiceOptions): string;

package/dist/core/understanding/understand/service.js

@@ -0,0 +1,76 @@
+import { Queries } from "../query/engine.js";
+import { formatUnderstandReport } from "./formatter.js";
+import { UNDERSTAND_LIMITATIONS, collectUnknowns } from "./summary.js";
+const DEFAULT_MAX_ITEMS = 8;
+/**
+ * First vertical-slice consumer of the Software Understanding Compiler.
+ * Reads exclusively through QueryEngine — never ProjectModel, never compiler passes.
+ */
+export class UnderstandService {
+    engine;
+    maxItems;
+    constructor(engine, options = {}) {
+        this.engine = engine;
+        this.maxItems = options.maxItems ?? DEFAULT_MAX_ITEMS;
+    }
+    /**
+     * Produce a deterministic human-readable repository understanding report.
+     */
+    summarize() {
+        const started = performance.now();
+        const repository = this.engine.execute(Queries.repositorySummary());
+        const domains = this.engine.execute(Queries.listDomains());
+        const entrypoints = this.engine.execute(Queries.listEntrypoints());
+        const architectures = this.engine.execute(Queries.listArchitectures());
+        const dependencies = this.engine.execute(Queries.listDependencies());
+        const relationships = this.engine.execute(Queries.listRelationships());
+        const statistics = this.engine.execute(Queries.statistics());
+        const queryCount = 7;
+        const architectureUnknowns = architectures.result.architectures.flatMap((arch) => arch.unknowns);
+        const unknowns = collectUnknowns({
+            architectureUnknowns,
+            domainCount: domains.result.count,
+            entrypointCount: entrypoints.result.count,
+            architectureCount: architectures.result.count,
+            dependencyCount: dependencies.result.count,
+            relationshipCount: relationships.result.count,
+        });
+        const snapshot = {
+            repository: repository.result,
+            domains: domains.result,
+            entrypoints: entrypoints.result,
+            architectures: architectures.result,
+            dependencies: dependencies.result,
+            relationships: relationships.result,
+            statistics: statistics.result,
+            unknowns,
+            limitations: UNDERSTAND_LIMITATIONS,
+            queryCount,
+        };
+        const { text, sections } = formatUnderstandReport(snapshot, { maxItems: this.maxItems });
+        const confidence = Math.round(((repository.confidence +
+            domains.confidence +
+            entrypoints.confidence +
+            architectures.confidence +
+            dependencies.confidence +
+            relationships.confidence +
+            statistics.confidence) /
+            queryCount) *
+            100) / 100;
+        return {
+            text,
+            sections,
+            confidence,
+            executionTimeMs: Math.max(0, Math.round(performance.now() - started)),
+            queryCount,
+            snapshot,
+        };
+    }
+}
+export function createUnderstandService(engine, options) {
+    return new UnderstandService(engine, options);
+}
+/** Convenience: run understand and return plain text only. */
+export function understandAsText(engine, options) {
+    return createUnderstandService(engine, options).summarize().text;
+}

package/dist/core/understanding/understand/summary.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fixed, deterministic limitation statements for Compiler v0.1 understand output.
+ * Not generated by AI — static product honesty copy.
+ */
+export declare const UNDERSTAND_LIMITATIONS: readonly string[];
+export declare function collectUnknowns(options: {
+    architectureUnknowns: readonly string[];
+    domainCount: number;
+    entrypointCount: number;
+    architectureCount: number;
+    dependencyCount: number;
+    relationshipCount: number;
+}): string[];
+export declare function formatConfidence(value: number): string;

package/dist/core/understanding/understand/summary.js

@@ -0,0 +1,39 @@
+/**
+ * Fixed, deterministic limitation statements for Compiler v0.1 understand output.
+ * Not generated by AI — static product honesty copy.
+ */
+export const UNDERSTAND_LIMITATIONS = [
+    "Summary is assembled only from Query Engine results over an existing ProjectModel.",
+    "No repository scan, compiler pass, or source parse runs during understand.",
+    "No AI, LLM, or natural-language generation is used.",
+    "Architecture confidence is capped below certainty by the inference engine.",
+    "Absence of a signal means evidence was not found, not that the concept is impossible.",
+    "Explain/Trace/Verify capabilities are not included in this vertical slice.",
+];
+export function collectUnknowns(options) {
+    const unknowns = [];
+    for (const item of options.architectureUnknowns) {
+        if (!unknowns.includes(item)) {
+            unknowns.push(item);
+        }
+    }
+    if (options.domainCount === 0) {
+        unknowns.push("No domains were reported by the Query Engine.");
+    }
+    if (options.entrypointCount === 0) {
+        unknowns.push("No entry points were reported by the Query Engine.");
+    }
+    if (options.architectureCount === 0) {
+        unknowns.push("No architecture patterns were reported by the Query Engine.");
+    }
+    if (options.dependencyCount === 0) {
+        unknowns.push("No dependencies were reported by the Query Engine.");
+    }
+    if (options.relationshipCount === 0) {
+        unknowns.push("No relationships were reported by the Query Engine.");
+    }
+    return unknowns.sort((a, b) => a.localeCompare(b));
+}
+export function formatConfidence(value) {
+    return value.toFixed(2);
+}

package/dist/core/understanding/understand/types.d.ts

@@ -0,0 +1,31 @@
+import type { QueryEngine } from "../query/engine.js";
+import type { ListArchitecturesResult, ListDependenciesResult, ListDomainsResult, ListEntrypointsResult, ListRelationshipsResult, RepositorySummaryResult, StatisticsResult } from "../query/models.js";
+export interface UnderstandSection {
+    title: string;
+    lines: readonly string[];
+}
+export interface UnderstandSnapshot {
+    repository: RepositorySummaryResult;
+    domains: ListDomainsResult;
+    entrypoints: ListEntrypointsResult;
+    architectures: ListArchitecturesResult;
+    dependencies: ListDependenciesResult;
+    relationships: ListRelationshipsResult;
+    statistics: StatisticsResult;
+    unknowns: readonly string[];
+    limitations: readonly string[];
+    queryCount: number;
+}
+export interface UnderstandResult {
+    text: string;
+    sections: readonly UnderstandSection[];
+    confidence: number;
+    executionTimeMs: number;
+    queryCount: number;
+    snapshot: UnderstandSnapshot;
+}
+export interface UnderstandServiceOptions {
+    /** Max items per list section. Default 8. */
+    maxItems?: number;
+}
+export type UnderstandEngine = Pick<QueryEngine, "execute">;

package/dist/core/understanding/understand/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/brain/compile.d.ts

@@ -0,0 +1,9 @@
+import { type ProjectBrain } from "../../core/understanding/brain/index.js";
+export interface CompileBrainOptions {
+    previousClaims?: ProjectBrain["claims"];
+    generatedAt?: string;
+}
+/**
+ * Compile discovery passes → ProjectModel → ProjectBrain for an explicit root.
+ */
+export declare function compileProjectBrain(projectRoot: string, options?: CompileBrainOptions): Promise<ProjectBrain>;

package/dist/mcp/brain/compile.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { inferArchitectures } from "../../core/understanding/architecture/index.js";
+import { buildProjectBrain } from "../../core/understanding/brain/index.js";
+import { discoverDependencies } from "../../core/understanding/dependencies/index.js";
+import { discoverDomains } from "../../core/understanding/domain/index.js";
+import { discoverEntrypoints } from "../../core/understanding/entrypoints/index.js";
+import { buildProjectModel } from "../../core/understanding/model/index.js";
+import { discoverRelationships } from "../../core/understanding/relationships/index.js";
+/**
+ * Compile discovery passes → ProjectModel → ProjectBrain for an explicit root.
+ */
+export async function compileProjectBrain(projectRoot, options = {}) {
+    const domains = await discoverDomains({ cwd: projectRoot });
+    const entrypoints = await discoverEntrypoints({ cwd: projectRoot });
+    const dependencies = await discoverDependencies({ cwd: projectRoot });
+    const relationships = await discoverRelationships({
+        cwd: projectRoot,
+        domains,
+        entrypoints,
+        dependencies,
+    });
+    const architectures = inferArchitectures({
+        domains,
+        entrypoints,
+        dependencies,
+        relationships,
+    });
+    const model = buildProjectModel({
+        domains,
+        entrypoints,
+        dependencies,
+        relationships,
+        architectures,
+        projectName: path.basename(projectRoot),
+        ...(options.generatedAt !== undefined ? { generatedAt: options.generatedAt } : {}),
+    });
+    return buildProjectBrain(model, {
+        cwd: projectRoot,
+        ...(options.previousClaims !== undefined ? { previousClaims: options.previousClaims } : {}),
+        ...(options.generatedAt !== undefined ? { generatedAt: options.generatedAt } : {}),
+    });
+}

package/dist/mcp/brain/errors.d.ts

@@ -0,0 +1,12 @@
+export type BrainMcpErrorCode = "invalid_root" | "path_escape" | "brain_not_found" | "brain_corrupt" | "unsupported_query" | "invalid_argument" | "not_found" | "read_only" | "internal";
+export declare class BrainMcpError extends Error {
+    readonly code: BrainMcpErrorCode;
+    constructor(code: BrainMcpErrorCode, message: string);
+}
+export declare function toToolErrorPayload(error: unknown): {
+    ok: false;
+    error: {
+        code: BrainMcpErrorCode | "unknown";
+        message: string;
+    };
+};