suture-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,634 @@
+import Database$1 from 'better-sqlite3';
+import { z } from 'zod';
+import { Readable, Writable } from 'node:stream';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+type StructuredMemory = {
+    kind: "summary";
+    text: string;
+} | {
+    kind: "event";
+    what: string;
+    when?: string;
+} | {
+    kind: "insight";
+    claim: string;
+    confidence: number;
+} | {
+    kind: "decision";
+    choice: string;
+    rationale: string;
+} | {
+    kind: "entity";
+    name: string;
+    attributes: Record<string, unknown>;
+};
+type EvidenceRef = {
+    kind: "file";
+    path: string;
+    lineStart?: number;
+    lineEnd?: number;
+} | {
+    kind: "package";
+    path: string;
+    key: string;
+} | {
+    kind: "github";
+    url: string;
+    refType?: "repo" | "commit" | "pull_request" | "issue" | "file";
+} | {
+    kind: "agent";
+    source: string;
+};
+interface Provenance {
+    sourceType: "mcp" | "cli" | "discovery" | "github" | "import";
+    source: string;
+    evidence?: EvidenceRef[];
+}
+interface Entity {
+    id: string;
+    name: string;
+    kind: string;
+    attributes: Record<string, unknown>;
+}
+interface Relation {
+    fromId: string;
+    toId: string;
+    label: string;
+    validFrom: Date;
+    validTo: Date | null;
+}
+interface Episode {
+    id: string;
+    projectId?: string;
+    content: StructuredMemory;
+    entities: Entity[];
+    edges: Relation[];
+    validFrom: Date;
+    validTo: Date | null;
+    tier: "core" | "recall" | "archive";
+    rir: {
+        recency: number;
+        importance: number;
+        relevance: number;
+    };
+    source: string;
+    confidence?: number;
+    status?: "active" | "invalidated" | "blocked" | "stale" | "superseded";
+    visibility?: "local" | "team";
+    tags?: string[];
+    provenance?: Provenance;
+    curationReason?: string;
+    pinned?: boolean;
+}
+interface CuratorProvider {
+    scoreImportance(content: StructuredMemory): Promise<number>;
+    extractEntities(content: StructuredMemory): Promise<Entity[]>;
+}
+
+interface EpisodeRow {
+    id: string;
+    projectId?: string | null;
+    content: string;
+    entities: string;
+    edges: string;
+    validFrom: number;
+    validTo: number | null;
+    tier: string;
+    rir: string;
+    source: string;
+    confidence?: number | null;
+    status?: string | null;
+    visibility?: string | null;
+    tags?: string | null;
+    provenance?: string | null;
+    curationReason?: string | null;
+    pinned?: number | null;
+}
+declare class SqliteSubstrate {
+    private db;
+    constructor(path: string);
+    private migrate;
+    upsert(episode: Episode): void;
+    invalidate(id: string, validTo: Date): void;
+    listByTier(tier: "core" | "recall" | "archive"): Episode[];
+    listAll(): Episode[];
+    listActiveByIds(ids: string[]): Episode[];
+    listAllRaw(): EpisodeRow[];
+    transaction<T>(fn: () => T): T;
+    raw(): Database$1.Database;
+    close(): void;
+}
+
+declare class SessionGate {
+    private readonly seen;
+    private readonly sentinel;
+    constructor(stateDir: string);
+    shouldInject(contentHash: string): boolean;
+    markInjected(contentHash: string): void;
+    forceReinject(): void;
+}
+
+declare class Fts5Index {
+    private db;
+    constructor(db: Database$1.Database);
+    index(episode: Episode): void;
+    search(query: string, limit?: number): string[];
+    remove(id: string): void;
+    clear(): void;
+}
+
+type Database = Database$1.Database;
+declare class MemoryGraph {
+    private db;
+    constructor(db: Database);
+    index(episode: Episode): void;
+    search(entityName: string, limit?: number): string[];
+    getRelations(entityId: string): Relation[];
+    remove(episodeId: string): void;
+    clear(): void;
+}
+
+interface CodeSymbol {
+    name: string;
+    kind: "function" | "class" | "interface" | "type" | "variable";
+    filePath: string;
+    line: number;
+}
+declare class CodeGraph {
+    private db;
+    private parser;
+    constructor(db: Database$1.Database);
+    private ensureSchema;
+    indexFile(filePath: string, source: string): void;
+    search(query: string, limit?: number): CodeSymbol[];
+    countSymbolsForFile(filePath: string): number;
+    removeFile(filePath: string): void;
+}
+
+interface SearchResult {
+    episodeIds: string[];
+    codeSymbols: CodeSymbol[];
+    source: "graph" | "code" | "fts5" | "combined";
+}
+declare class SearchRouter {
+    private memory;
+    private code;
+    private fts;
+    constructor(memory: MemoryGraph, code: CodeGraph, fts: Fts5Index);
+    search(query: string, limit?: number): SearchResult;
+}
+
+declare class RirScorer {
+    recency(createdAt: Date): number;
+    importance(content: StructuredMemory): number;
+    relevance(content: StructuredMemory, goal?: string): number;
+    score(episode: Episode): {
+        recency: number;
+        importance: number;
+        relevance: number;
+    };
+}
+
+declare class SemanticCurator implements CuratorProvider {
+    scoreImportance(content: StructuredMemory): Promise<number>;
+    extractEntities(content: StructuredMemory): Promise<Entity[]>;
+}
+
+declare class AgentCurator implements CuratorProvider {
+    private provider;
+    private fallback;
+    constructor(provider: CuratorProvider, fallback: SemanticCurator);
+    scoreImportance(content: StructuredMemory): Promise<number>;
+    extractEntities(content: StructuredMemory): Promise<Entity[]>;
+}
+
+declare class IndexManager {
+    private memory;
+    private code;
+    private fts;
+    constructor(memory: MemoryGraph, code: CodeGraph, fts: Fts5Index);
+    indexEpisode(episode: Episode): void;
+    removeEpisode(episodeId: string): void;
+    rebuildEpisodes(episodes: Episode[]): void;
+    indexCodeFile(filePath: string, source: string): void;
+    removeCodeFile(filePath: string): void;
+}
+
+interface CurationSummary {
+    promoted: number;
+    retained: number;
+    archived: number;
+    deleted: number;
+    actions: Array<{
+        action: string;
+        detail: string;
+        projectId?: string;
+    }>;
+}
+declare class TierManager {
+    private substrate;
+    private scorer;
+    private curator;
+    private indexes?;
+    constructor(substrate: SqliteSubstrate, scorer: RirScorer, curator: CuratorProvider, indexes?: IndexManager | undefined);
+    runCuration(): Promise<CurationSummary>;
+    getCoreBlock(): string;
+}
+
+interface SecurityScanResult {
+    blocked: boolean;
+    reasons: string[];
+    redactedText: string;
+}
+declare class SecurityScanner {
+    scanText(text: string): SecurityScanResult;
+    isIgnoredPath(filePath: string): boolean;
+    canExportTo(targetPath: string, stateDir: string): boolean;
+}
+
+type DiscoveryFindingType = "language" | "framework" | "package_manager" | "script" | "command" | "entrypoint" | "test_strategy" | "directory_role" | "key_module" | "convention" | "architecture_note" | "decision" | "risk" | "dependency" | "deployment_note";
+type DiscoveryFindingStatus = "auto_accepted" | "queued" | "blocked" | "rejected" | "stale" | "superseded";
+interface DiscoveryFindingInput {
+    type: DiscoveryFindingType;
+    claim: string;
+    payload?: Record<string, unknown>;
+    evidence?: EvidenceRef[];
+    confidence?: number;
+    source?: string;
+    freshness?: "fresh" | "unknown" | "stale";
+}
+interface DiscoveryFinding extends Required<DiscoveryFindingInput> {
+    id: string;
+    sessionId: string;
+    projectId: string;
+    risk: "low" | "medium" | "high";
+    status: DiscoveryFindingStatus;
+    createdAt: Date;
+    reason: string;
+}
+interface DiscoverySession {
+    id: string;
+    projectId: string;
+    rootPath: string;
+    startedBy: string;
+    startedAt: Date;
+    status: "active" | "applied" | "stale";
+    scanSummary: Record<string, unknown>;
+    coverage: DiscoveryCoverage;
+    policyVersion: string;
+}
+interface DiscoveryCoverage {
+    languages: number;
+    scripts: number;
+    entrypoints: number;
+    tests: number;
+    docs: number;
+    queued: number;
+    blocked: number;
+    accepted: number;
+}
+interface DiscoveryPolicyDecision {
+    status: DiscoveryFindingStatus;
+    risk: "low" | "medium" | "high";
+    reason: string;
+}
+
+declare class DiscoveryPolicy {
+    private security;
+    readonly version = "2026-05-secure-project-map";
+    constructor(security?: SecurityScanner);
+    decide(input: DiscoveryFindingInput): DiscoveryPolicyDecision;
+}
+
+declare class DiscoveryEngine {
+    private substrate;
+    private policy;
+    private security;
+    constructor(substrate: SqliteSubstrate, policy?: DiscoveryPolicy, security?: SecurityScanner);
+    start(rootPath: string, startedBy?: string, projectId?: string): DiscoverySession;
+    getSession(sessionId: string): DiscoverySession | null;
+    findings(sessionId: string): DiscoveryFinding[];
+    submit(sessionId: string, input: DiscoveryFindingInput): DiscoveryFinding;
+    scan(sessionId: string): DiscoveryFinding[];
+    status(sessionId: string): {
+        session: DiscoverySession;
+        findings: DiscoveryFinding[];
+        coverage: DiscoveryCoverage;
+    };
+    refresh(sessionId: string): DiscoverySession;
+    private updateCoverage;
+    private coverageFor;
+}
+
+declare const CurationActionSchema: z.ZodObject<{
+    at: z.ZodString;
+    action: z.ZodString;
+    detail: z.ZodString;
+    projectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TelemetryStatsSchema: z.ZodObject<{
+    tokensSaved: z.ZodDefault<z.ZodNumber>;
+    contextRotationsAvoided: z.ZodDefault<z.ZodNumber>;
+    totalInjections: z.ZodDefault<z.ZodNumber>;
+    toolUsage: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    memoriesCreated: z.ZodDefault<z.ZodNumber>;
+    activeContextTokens: z.ZodDefault<z.ZodNumber>;
+    indexedFiles: z.ZodDefault<z.ZodNumber>;
+    skippedUnchangedFiles: z.ZodDefault<z.ZodNumber>;
+    codeSymbolsIndexed: z.ZodDefault<z.ZodNumber>;
+    projectFactsAccepted: z.ZodDefault<z.ZodNumber>;
+    projectFactsQueued: z.ZodDefault<z.ZodNumber>;
+    projectFactsRejected: z.ZodDefault<z.ZodNumber>;
+    projectFactsStale: z.ZodDefault<z.ZodNumber>;
+    projectFactsSuperseded: z.ZodDefault<z.ZodNumber>;
+    estimatedTokensCached: z.ZodDefault<z.ZodNumber>;
+    estimatedTokensAvoidedFromRereads: z.ZodDefault<z.ZodNumber>;
+    searchHitsServedFromSubstrate: z.ZodDefault<z.ZodNumber>;
+    skippedDuplicateInjections: z.ZodDefault<z.ZodNumber>;
+    recentTokenSavings: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    recentCurationActions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        action: z.ZodString;
+        detail: z.ZodString;
+        projectId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    lastUpdate: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type TelemetryStats = z.infer<typeof TelemetryStatsSchema>;
+type CurationAction = z.infer<typeof CurationActionSchema>;
+interface CostEstimate {
+    modelProfile: string;
+    inputCostPerMillion: number;
+    estimatedTokens: number;
+    estimatedUsd: number;
+    formula: string;
+}
+declare const MODEL_COST_PROFILES: Record<string, number>;
+declare class TelemetryService {
+    private statePath?;
+    private stats;
+    constructor(statePath?: string | undefined);
+    private load;
+    save(): void;
+    recordToolUsage(toolName: string): void;
+    recordSavings(tokens: number): void;
+    recordMemoryCreated(): void;
+    recordInjection(tokens: number): void;
+    recordSkippedInjection(): void;
+    recordIndexing(summary: {
+        indexedFiles?: number;
+        skippedFiles?: number;
+        symbols?: number;
+        accepted?: number;
+        queued?: number;
+        rejected?: number;
+        stale?: number;
+        superseded?: number;
+        tokensCached?: number;
+        tokensAvoidedFromRereads?: number;
+    }): void;
+    recordSearchHits(count: number): void;
+    recordCurationAction(action: Omit<CurationAction, "at">): void;
+    getStats(): TelemetryStats;
+    estimateCostSavings(modelProfile?: string, inputCostPerMillion?: number): CostEstimate;
+}
+
+interface RememberInput {
+    content: string;
+    kind?: StructuredMemory["kind"];
+    source?: string;
+    projectId?: string;
+    evidence?: EvidenceRef[];
+    tags?: string[];
+    confidence?: number;
+    sourceType?: Provenance["sourceType"];
+}
+interface HydratedSearchResult extends SearchResult {
+    episodes: Episode[];
+    warnings: string[];
+}
+declare class MemoryStore {
+    private substrate;
+    private indexes;
+    private router;
+    private curator;
+    private security;
+    private telemetry?;
+    constructor(substrate: SqliteSubstrate, indexes: IndexManager, router: SearchRouter, curator: CuratorProvider, security?: SecurityScanner, telemetry?: TelemetryService | undefined);
+    remember(input: RememberInput): Promise<Episode>;
+    forget(id: string): boolean;
+    search(query: string, limit?: number): HydratedSearchResult;
+    listActive(): Episode[];
+    exportActive(targetPath: string, stateDir: string): number;
+    indexCodeFile(filePath: string, source: string): void;
+}
+
+type ToolResult = {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+};
+interface ToolDef {
+    name: string;
+    description: string;
+    schema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+interface ToolServices {
+    memoryStore?: MemoryStore;
+    discovery?: DiscoveryEngine;
+    curator?: CuratorProvider;
+    stateDir?: string;
+    telemetry?: TelemetryService;
+}
+declare function makeTools(substrate: SqliteSubstrate, gate: SessionGate, router: SearchRouter, tierManager: TierManager, memory: MemoryGraph, code: CodeGraph, fts: Fts5Index, services?: ToolServices): ToolDef[];
+
+interface McpServerIo {
+    stdin?: Readable;
+    stdout?: Writable;
+}
+interface McpServerHandle {
+    close: () => Promise<void>;
+}
+declare function startMcpServer(stateDirInput: string, io?: McpServerIo): Promise<McpServerHandle>;
+
+declare class VizServer {
+    private substrate;
+    private tierManager;
+    private router;
+    private port;
+    private server;
+    constructor(substrate: SqliteSubstrate, tierManager: TierManager, router: SearchRouter, port?: number);
+    listen(): void;
+    close(): void;
+    private route;
+    private memoryGraphData;
+}
+
+interface ProjectIndexPlan {
+    projectId: string;
+    fingerprint: string;
+    identity: ProjectIdentity;
+    existingIndex: ExistingProjectIndex | null;
+    projectPath: string;
+    scanPatterns: string[];
+    ignoredPaths: string[];
+    manifestFiles: string[];
+    codeFiles: string[];
+    findings: DiscoveryFindingInput[];
+    estimatedTokensToCache: number;
+    estimatedTokensAvoidedFromRereads: number;
+}
+interface ProjectIdentity {
+    packageName?: string;
+    gitRemote?: string;
+    rootPath: string;
+    basis: string[];
+}
+interface ExistingProjectIndex {
+    projectId: string;
+    fingerprint: string;
+    rootPath: string;
+    packageName?: string;
+    gitRemote?: string;
+    indexedFiles: number;
+    codeSymbols: number;
+    lastIndexedAt: string;
+    sameRoot: boolean;
+}
+interface ProjectIndexResult {
+    projectId: string;
+    fingerprint: string;
+    existingIndex: ExistingProjectIndex | null;
+    projectPath: string;
+    sessionId: string;
+    accepted: number;
+    queued: number;
+    blocked: number;
+    applied: number;
+    skippedDuplicateFacts: number;
+    indexedFiles: number;
+    skippedFiles: number;
+    codeSymbolsIndexed: number;
+    estimatedTokensCached: number;
+    estimatedTokensAvoidedFromRereads: number;
+    curationActions: number;
+    findings: DiscoveryFinding[];
+}
+interface ProjectIndexApplyOptions {
+    enabledFindingIndexes?: number[];
+}
+declare class ProjectIndexer {
+    private substrate;
+    private memoryStore;
+    private codeGraph;
+    private tierManager;
+    private telemetry?;
+    private security;
+    constructor(substrate: SqliteSubstrate, memoryStore: MemoryStore, codeGraph: CodeGraph, tierManager: TierManager, telemetry?: TelemetryService | undefined, security?: SecurityScanner);
+    preview(projectPath: string): ProjectIndexPlan;
+    apply(projectPath: string, options?: ProjectIndexApplyOptions): Promise<ProjectIndexResult>;
+    private hasExistingFact;
+    private getExistingIndex;
+    private recordProjectIndex;
+}
+
+declare function registerDiscoveryPrompts(server: McpServer): void;
+
+interface SyncOperation {
+    id: string;
+    projectId: string;
+    kind: "remember" | "forget" | "discovery" | "curate";
+    createdAt: number;
+    payload: unknown;
+}
+interface EncryptedSyncRecord {
+    operationId: string;
+    projectId: string;
+    algorithm: "aes-256-gcm";
+    nonce: string;
+    ciphertext: string;
+    authTag: string;
+    createdAt: number;
+}
+declare class EncryptedSyncLog {
+    encrypt(operation: SyncOperation, key: Buffer): EncryptedSyncRecord;
+    decrypt(record: EncryptedSyncRecord, key: Buffer): SyncOperation;
+}
+
+interface GitHubReference {
+    owner: string;
+    repo: string;
+    kind: "repo" | "commit" | "pull_request" | "issue" | "file";
+    value?: string | number;
+    path?: string;
+}
+declare function githubEvidence(ref: GitHubReference): EvidenceRef;
+
+type HookDecisionKind = "inject_memory" | "inject_setup_signal" | "skip_unchanged" | "skip_empty";
+interface HookSessionInput {
+    projectPath: string;
+    sessionId: string;
+    client?: string;
+    format?: "claude-json" | "json" | "text";
+    budget?: number;
+}
+interface HookDecision {
+    kind: HookDecisionKind;
+    projectId: string;
+    sessionId: string;
+    client: string;
+    hash: string;
+    content: string;
+    reason: string;
+    forced: boolean;
+}
+interface ClaudeHookOutput {
+    hookSpecificOutput: {
+        hookEventName: "SessionStart";
+        additionalContext?: string;
+    };
+}
+declare class HookService {
+    private substrate;
+    private tierManager;
+    private memoryStore;
+    constructor(substrate: SqliteSubstrate, tierManager: TierManager, memoryStore: MemoryStore);
+    decideSessionStart(input: HookSessionInput): HookDecision;
+    preCompact(input: HookSessionInput): {
+        projectId: string;
+        sessionId: string;
+        client: string;
+        flagged: true;
+    };
+    postCompact(input: HookSessionInput & {
+        summary?: string;
+        summaryFile?: string;
+    }): Promise<{
+        projectId: string;
+        sessionId: string;
+        client: string;
+        stored: boolean;
+    }>;
+    status(input: HookSessionInput): {
+        projectId: string;
+        sessionId: string;
+        client: string;
+        lastHash: string | null;
+        reinjectPending: boolean;
+        acceptedFindings: number;
+    };
+    formatDecision(decision: HookDecision, format?: "claude-json" | "json" | "text"): string;
+    private memoryBlock;
+    private acceptedFindings;
+    private lastHash;
+    private recordInjection;
+    private hasReinjectFlag;
+    private consumeReinjectFlag;
+}
+
+declare const VERSION = "0.1.0";
+
+export { AgentCurator, type ClaudeHookOutput, CodeGraph, type CodeSymbol, type CostEstimate, type CurationAction, type CuratorProvider, type DiscoveryCoverage, DiscoveryEngine, type DiscoveryFinding, type DiscoveryFindingInput, type DiscoveryFindingStatus, type DiscoveryFindingType, DiscoveryPolicy, type DiscoveryPolicyDecision, type DiscoverySession, EncryptedSyncLog, type EncryptedSyncRecord, type Entity, type Episode, type EvidenceRef, type ExistingProjectIndex, Fts5Index, type GitHubReference, type HookDecision, type HookDecisionKind, HookService, type HookSessionInput, type HydratedSearchResult, IndexManager, MODEL_COST_PROFILES, MemoryGraph, MemoryStore, type ProjectIdentity, type ProjectIndexApplyOptions, type ProjectIndexPlan, type ProjectIndexResult, ProjectIndexer, type Provenance, type Relation, type RememberInput, RirScorer, type SearchResult, SearchRouter, SecurityScanner, SemanticCurator, SessionGate, SqliteSubstrate, type StructuredMemory, type SyncOperation, TelemetryService, type TelemetryStats, TelemetryStatsSchema, TierManager, type ToolDef, VERSION, VizServer, githubEvidence, makeTools, registerDiscoveryPrompts, startMcpServer };