@hiveai/mcp 0.4.5 → 0.6.0

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { HaivePaths } from '@hiveai/core';
+import { HaivePaths, ConfidenceLevel } from '@hiveai/core';
+import { z } from 'zod';
 
 interface HaiveContext {
     paths: HaivePaths;
@@ -22,6 +23,491 @@ declare class SessionTracker {
     private registerShutdownHandler;
 }
 
+declare const GetBriefingInputSchema: {
+    task: z.ZodOptional<z.ZodString>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    max_tokens: z.ZodDefault<z.ZodNumber>;
+    max_memories: z.ZodDefault<z.ZodNumber>;
+    include_project_context: z.ZodDefault<z.ZodBoolean>;
+    include_module_contexts: z.ZodDefault<z.ZodBoolean>;
+    semantic: z.ZodDefault<z.ZodBoolean>;
+    include_stale: z.ZodDefault<z.ZodBoolean>;
+    track: z.ZodDefault<z.ZodBoolean>;
+    format: z.ZodDefault<z.ZodEnum<["full", "compact"]>>;
+    symbols: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    min_semantic_score: z.ZodDefault<z.ZodNumber>;
+};
+type GetBriefingInput = {
+    [K in keyof typeof GetBriefingInputSchema]: z.infer<(typeof GetBriefingInputSchema)[K]>;
+};
+interface BriefingMemory {
+    id: string;
+    scope: string;
+    type: string;
+    module?: string;
+    tags: string[];
+    status: string;
+    confidence: ConfidenceLevel;
+    /** Present when confidence is 'low' or 'unverified' — AI should weight this memory cautiously. */
+    unverified?: true;
+    read_count: number;
+    reasons: Array<"anchor" | "module" | "domain" | "semantic">;
+    match_quality: "exact" | "partial" | "semantic";
+    semantic_score?: number;
+    body: string;
+    file_path: string;
+}
+interface CodeMapSymbolHit {
+    symbol: string;
+    /** files that export this symbol */
+    locations: Array<{
+        file: string;
+        kind: string;
+        line: number;
+        description?: string;
+    }>;
+}
+interface ActionRequiredItem {
+    /** Memory id containing the alert */
+    id: string;
+    /** Short human-readable summary of the issue */
+    summary: string;
+    /**
+     * The exact message to show the developer before doing anything.
+     * Copy-paste this verbatim — do NOT paraphrase or act before confirmation.
+     */
+    developer_message: string;
+}
+interface BriefingOutput {
+    task?: string;
+    search_mode: "semantic" | "literal_fallback" | "literal";
+    match_quality_note?: string;
+    inferred_modules: string[];
+    last_session?: {
+        id: string;
+        scope: string;
+        revision_count: number;
+        body: string;
+    };
+    project_context: {
+        content: string;
+        truncated: boolean;
+        is_template?: boolean;
+        auto_generated?: boolean;
+    } | null;
+    module_contexts: Array<{
+        name: string;
+        content: string;
+        truncated: boolean;
+    }>;
+    memories: BriefingMemory[];
+    symbol_locations?: CodeMapSymbolHit[];
+    /**
+     * Memories that require explicit human confirmation before any code action.
+     * IMPORTANT: for each item, show developer_message to the developer and
+     * wait for explicit approval before modifying any code.
+     * These are surfaced separately from memories to make them impossible to miss.
+     */
+    action_required: ActionRequiredItem[];
+    decay_warnings: string[];
+    setup_warnings: string[];
+    /**
+     * True when this briefing carries little actionable signal:
+     * - project-context.md is still the default template
+     * - no memories matched the task (or none exist at all)
+     * - no previous session recap
+     * Clients can use this flag to skip surfacing a near-empty briefing to the model.
+     */
+    low_value?: true;
+    /**
+     * Short, action-oriented hints surfaced to the agent based on the briefing payload.
+     * Examples: "haive is uninitialized — use Read/Grep directly", "gotcha memories present — read first".
+     * Always non-empty when low_value=true.
+     */
+    hints?: string[];
+    estimated_tokens: number;
+    budget: {
+        max_tokens: number;
+        spent: {
+            project: number;
+            modules: number;
+            memories: number;
+        };
+    };
+}
+declare function getBriefing(input: GetBriefingInput, ctx: HaiveContext): Promise<BriefingOutput>;
+
+declare const CodeMapInputSchema: {
+    file: z.ZodOptional<z.ZodString>;
+    symbol: z.ZodOptional<z.ZodString>;
+    paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    max_files: z.ZodDefault<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+};
+type CodeMapInput = {
+    [K in keyof typeof CodeMapInputSchema]: z.infer<(typeof CodeMapInputSchema)[K]>;
+};
+interface CodeMapToolOutput {
+    available: boolean;
+    generated_at?: string;
+    total_files?: number;
+    files: Array<{
+        path: string;
+        summary?: string;
+        loc: number;
+        exports: Array<{
+            name: string;
+            kind: string;
+            description?: string;
+            line: number;
+        }>;
+    }>;
+    /** Number of matched files dropped due to max_files / max_tokens. */
+    truncated?: number;
+    /** True when at least one file was dropped to fit the token budget. */
+    budget_clipped?: true;
+    notice?: string;
+}
+declare function codeMapTool(input: CodeMapInput, ctx: HaiveContext): Promise<CodeMapToolOutput>;
+
+declare const GetRecapInputSchema: {
+    scope: z.ZodDefault<z.ZodEnum<["personal", "team", "any"]>>;
+};
+type GetRecapInput = {
+    [K in keyof typeof GetRecapInputSchema]: z.infer<(typeof GetRecapInputSchema)[K]>;
+};
+interface GetRecapOutput {
+    recap: {
+        id: string;
+        scope: string;
+        revision_count: number;
+        created_at: string;
+        body: string;
+    } | null;
+    notice?: string;
+}
+/**
+ * Lightweight alternative to get_briefing when you ONLY need the previous
+ * session recap (e.g. resuming a long task between sessions). Skips project
+ * context, modules, and memory ranking — pays only the recap's token cost.
+ */
+declare function getRecap(input: GetRecapInput, ctx: HaiveContext): Promise<GetRecapOutput>;
+
+declare const MemRelevantToInputSchema: {
+    task: z.ZodString;
+    files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    min_semantic_score: z.ZodDefault<z.ZodNumber>;
+    format: z.ZodDefault<z.ZodEnum<["full", "compact"]>>;
+};
+type MemRelevantToInput = {
+    [K in keyof typeof MemRelevantToInputSchema]: z.infer<(typeof MemRelevantToInputSchema)[K]>;
+};
+interface MemRelevantToOutput {
+    task: string;
+    search_mode: "semantic" | "literal_fallback" | "literal";
+    memories: BriefingMemory[];
+    hints?: string[];
+    /**
+     * True when the search returned zero memories — clients can skip surfacing
+     * an empty payload to the model.
+     */
+    empty?: true;
+}
+/**
+ * One-shot ranked memories for a task. Use instead of get_briefing when you
+ * already have project context loaded and only want the relevant memory layer.
+ *
+ * Runs the same ranking (anchor / module / literal / semantic) as get_briefing
+ * but skips project_context, module_contexts, action_required, etc. — paying
+ * only the cost of the memory bodies you actually get back.
+ */
+declare function memRelevantTo(input: MemRelevantToInput, ctx: HaiveContext): Promise<MemRelevantToOutput>;
+
+declare const CodeSearchInputSchema: {
+    query: z.ZodString;
+    k: z.ZodDefault<z.ZodNumber>;
+    min_score: z.ZodDefault<z.ZodNumber>;
+};
+type CodeSearchInput = {
+    [K in keyof typeof CodeSearchInputSchema]: z.infer<(typeof CodeSearchInputSchema)[K]>;
+};
+interface CodeSearchHit {
+    file: string;
+    name: string;
+    kind: string;
+    line: number;
+    description?: string;
+    score: number;
+}
+interface CodeSearchOutput {
+    available: boolean;
+    hits: CodeSearchHit[];
+    notice?: string;
+}
+declare function codeSearch(input: CodeSearchInput, ctx: HaiveContext): Promise<CodeSearchOutput>;
+
+declare const WhyThisFileInputSchema: {
+    path: z.ZodString;
+    git_log_limit: z.ZodDefault<z.ZodNumber>;
+    memory_limit: z.ZodDefault<z.ZodNumber>;
+};
+type WhyThisFileInput = {
+    [K in keyof typeof WhyThisFileInputSchema]: z.infer<(typeof WhyThisFileInputSchema)[K]>;
+};
+interface WhyThisFileOutput {
+    file: string;
+    exists: boolean;
+    recent_commits: Array<{
+        sha: string;
+        author: string;
+        relative_date: string;
+        subject: string;
+    }>;
+    memories: Array<{
+        id: string;
+        type: string;
+        scope: string;
+        confidence: string;
+        body_preview: string;
+    }>;
+    code_map_entry: {
+        summary?: string;
+        loc: number;
+        exports: Array<{
+            name: string;
+            kind: string;
+            line: number;
+            description?: string;
+        }>;
+    } | null;
+    hints?: string[];
+}
+/**
+ * One-shot file-context lookup: combines recent git history, memories anchored
+ * to the path, and the code-map entry. Designed to answer "why is this file
+ * the way it is?" in a single call instead of 3-4 manual ones.
+ */
+declare function whyThisFile(input: WhyThisFileInput, ctx: HaiveContext): Promise<WhyThisFileOutput>;
+
+declare const AntiPatternsCheckInputSchema: {
+    diff: z.ZodOptional<z.ZodString>;
+    paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    semantic: z.ZodDefault<z.ZodBoolean>;
+};
+type AntiPatternsCheckInput = {
+    [K in keyof typeof AntiPatternsCheckInputSchema]: z.infer<(typeof AntiPatternsCheckInputSchema)[K]>;
+};
+interface AntiPatternsWarning {
+    id: string;
+    type: "attempt" | "gotcha";
+    scope: string;
+    confidence: string;
+    body_preview: string;
+    reasons: Array<"anchor" | "literal" | "semantic">;
+    semantic_score?: number;
+}
+interface AntiPatternsCheckOutput {
+    /** Total number of attempt+gotcha memories that exist in this project. */
+    scanned: number;
+    warnings: AntiPatternsWarning[];
+    notice?: string;
+}
+/**
+ * Scan a diff (or set of paths) against documented attempt/gotcha memories.
+ * Surfaces "you are about to repeat a known mistake" warnings BEFORE you commit.
+ *
+ * Matching strategy:
+ *   1. Anchor — memories anchored to any of the changed paths
+ *   2. Literal — tokens from the diff overlap with memory body
+ *   3. Semantic — cosine similarity (when enabled and index available)
+ */
+declare function antiPatternsCheck(input: AntiPatternsCheckInput, ctx: HaiveContext): Promise<AntiPatternsCheckOutput>;
+
+declare const MemDistillInputSchema: {
+    since_days: z.ZodDefault<z.ZodNumber>;
+    min_cluster: z.ZodDefault<z.ZodNumber>;
+    type_filter: z.ZodDefault<z.ZodEnum<["gotcha", "attempt", "all"]>>;
+    scope: z.ZodDefault<z.ZodEnum<["personal", "team", "module", "any"]>>;
+};
+type MemDistillInput = {
+    [K in keyof typeof MemDistillInputSchema]: z.infer<(typeof MemDistillInputSchema)[K]>;
+};
+interface DistillCluster {
+    suggested_topic: string;
+    suggested_type: "convention" | "gotcha";
+    member_ids: string[];
+    overlapping_paths: string[];
+    common_keywords: string[];
+    sample_titles: string[];
+    /** ISO date of the latest member */
+    latest_at: string;
+}
+interface MemDistillOutput {
+    scanned: number;
+    /** Memories that didn't fit any cluster (kept here so callers can inspect singletons). */
+    singletons: number;
+    clusters: DistillCluster[];
+    notice?: string;
+}
+/**
+ * Cluster recurring observations / attempts so a human can collapse N similar
+ * memories into one richer convention/gotcha. Uses cheap heuristics (anchor
+ * path overlap + body keyword overlap) — no embeddings needed.
+ *
+ * Output is *advisory*: nothing is written to disk. The caller (CLI / human)
+ * decides whether to mem_save the consolidated form.
+ */
+declare function memDistill(input: MemDistillInput, ctx: HaiveContext): Promise<MemDistillOutput>;
+
+declare const WhyThisDecisionInputSchema: {
+    id: z.ZodString;
+    git_log_limit: z.ZodDefault<z.ZodNumber>;
+};
+type WhyThisDecisionInput = {
+    [K in keyof typeof WhyThisDecisionInputSchema]: z.infer<(typeof WhyThisDecisionInputSchema)[K]>;
+};
+interface WhyThisDecisionOutput {
+    found: boolean;
+    decision?: {
+        id: string;
+        type: string;
+        scope: string;
+        status: string;
+        confidence: string;
+        body: string;
+        created_at: string;
+    };
+    /** Memories explicitly linked via related_ids on the decision (or vice versa). */
+    related: Array<{
+        id: string;
+        type: string;
+        scope: string;
+        confidence: string;
+        body_preview: string;
+        relation: "explicit" | "back-link";
+    }>;
+    /** Other memories anchored to overlapping paths — implicit context. */
+    path_neighbors: Array<{
+        id: string;
+        type: string;
+        scope: string;
+        confidence: string;
+        overlap: string[];
+        body_preview: string;
+    }>;
+    /** Recent git commits touching any of the decision's anchored paths. */
+    recent_commits: Array<{
+        path: string;
+        sha: string;
+        author: string;
+        relative_date: string;
+        subject: string;
+    }>;
+    hints?: string[];
+    notice?: string;
+}
+/**
+ * Trace the genealogy of a `decision` memory: the decision itself + memories
+ * explicitly linked to it + memories anchored to overlapping paths + recent
+ * commits touching those paths. One call instead of 4-5 manual lookups.
+ *
+ * Works on any memory type, but is optimized for `decision` and `architecture`.
+ */
+declare function whyThisDecision(input: WhyThisDecisionInput, ctx: HaiveContext): Promise<WhyThisDecisionOutput>;
+
+declare const MemConflictsInputSchema: {
+    id: z.ZodString;
+    min_score: z.ZodDefault<z.ZodNumber>;
+    semantic: z.ZodDefault<z.ZodBoolean>;
+};
+type MemConflictsInput = {
+    [K in keyof typeof MemConflictsInputSchema]: z.infer<(typeof MemConflictsInputSchema)[K]>;
+};
+type ConflictReason = "opposite-status" | "attempt-vs-convention-same-paths" | "polarity-keywords" | "explicit-contradiction-tag";
+interface ConflictHit {
+    id: string;
+    type: string;
+    scope: string;
+    status: string;
+    confidence: string;
+    body_preview: string;
+    similarity: number | null;
+    reasons: ConflictReason[];
+    shared_paths: string[];
+}
+interface MemConflictsOutput {
+    found: boolean;
+    target?: {
+        id: string;
+        type: string;
+        status: string;
+    };
+    scanned: number;
+    conflicts: ConflictHit[];
+    notice?: string;
+}
+/**
+ * Find memories that potentially CONTRADICT the given memory. Useful before
+ * relying on a memory's advice — surfaces "another memory says the opposite".
+ *
+ * Detection layers (any of these triggers a hit):
+ *   - Opposite status: target is validated, neighbor is rejected — for the same topic
+ *   - Type mismatch on overlapping paths: an `attempt` (don't do X) coexists with
+ *     a `convention` (do X) anchored to overlapping paths
+ *   - Polarity keywords: target says "use X" while a semantic neighbor says "don't use X"
+ *   - Explicit contradiction tag (#contradicts:<id>) in either body
+ */
+declare function memConflicts(input: MemConflictsInput, ctx: HaiveContext): Promise<MemConflictsOutput>;
+
+declare const PreCommitCheckInputSchema: {
+    diff: z.ZodOptional<z.ZodString>;
+    paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    block_on: z.ZodDefault<z.ZodEnum<["any", "high-confidence", "never"]>>;
+    semantic: z.ZodDefault<z.ZodBoolean>;
+};
+type PreCommitCheckInput = {
+    [K in keyof typeof PreCommitCheckInputSchema]: z.infer<(typeof PreCommitCheckInputSchema)[K]>;
+};
+interface PreCommitCheckOutput {
+    /** True when at least one finding meets the configured block_on threshold. */
+    should_block: boolean;
+    /** Per-section summary; clients should surface the warnings + reasons to the user. */
+    summary: {
+        anti_patterns: number;
+        relevant_memories: number;
+        stale_anchors: number;
+    };
+    warnings: AntiPatternsWarning[];
+    /** Memories anchored to the touched files — convention reminders for the change author. */
+    relevant_memories: Array<{
+        id: string;
+        type: string;
+        confidence: string;
+        body_preview: string;
+    }>;
+    /** Memories whose anchored paths overlap with the diff AND are now stale — likely outdated knowledge. */
+    stale_anchors: Array<{
+        id: string;
+        paths: string[];
+        body_preview: string;
+    }>;
+    notice?: string;
+}
+/**
+ * One-shot "should I block this commit?" check.
+ *
+ * Combines three signals into a single call agents and git hooks can consume:
+ *   1. anti_patterns_check — known gotchas/attempts that match the diff
+ *   2. mem_for_files — conventions/decisions anchored to touched files
+ *   3. mem_verify — memories whose anchors are stale (knowledge may be wrong)
+ *
+ * Returns should_block per the configured threshold, plus the raw findings so
+ * the caller can render them. CLI wrapper: `haive precommit`.
+ */
+declare function preCommitCheck(input: PreCommitCheckInput, ctx: HaiveContext): Promise<PreCommitCheckOutput>;
+
 declare const SERVER_NAME = "haive";
 declare const SERVER_VERSION: string;
 declare function createHaiveServer(options?: CreateContextOptions): {
@@ -30,4 +516,4 @@ declare function createHaiveServer(options?: CreateContextOptions): {
     tracker: SessionTracker;
 };
 
-export { SERVER_NAME, SERVER_VERSION, createHaiveServer };
+export { type AntiPatternsCheckInput, type AntiPatternsCheckOutput, type BriefingOutput, type CodeMapInput, type CodeMapToolOutput, type CodeSearchInput, type CodeSearchOutput, type GetBriefingInput, type GetRecapInput, type GetRecapOutput, type MemConflictsInput, type MemConflictsOutput, type MemDistillInput, type MemDistillOutput, type MemRelevantToInput, type MemRelevantToOutput, type PreCommitCheckInput, type PreCommitCheckOutput, SERVER_NAME, SERVER_VERSION, type WhyThisDecisionInput, type WhyThisDecisionOutput, type WhyThisFileInput, type WhyThisFileOutput, antiPatternsCheck, codeMapTool, codeSearch, createHaiveServer, getBriefing, getRecap, memConflicts, memDistill, memRelevantTo, preCommitCheck, whyThisDecision, whyThisFile };