abb-opencode-local-rag 0.1.0

package/dist/pdf-visual/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/pdf-visual/renderer.ts"],"names":[],"mappings":"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"}

package/dist/pdf-visual/types.d.ts

@@ -0,0 +1,62 @@
+import { AppError } from '../utils/errors.js';
+/**
+ * Error raised by any module on the visual ingest path. Carries the offending
+ * 1-based page number so callers can correlate it with the page list.
+ */
+export declare class VlmError extends AppError {
+    readonly pageNum: number;
+    constructor(message: string, options: {
+        cause?: Error;
+        pageNum: number;
+    });
+}
+/**
+ * Visual-quality profile selector. Each profile resolves to a self-contained
+ * captioner implementation under `captioners/`. `fast` ports the original
+ * SmolVLM-256M / IDEFICS3 captioner (lightweight default, ~250 MB cache);
+ * `quality` ports the Qwen2.5-VL-3B-Instruct-ONNX captioner (~2.9 GB cache,
+ * ~2× per-page inference, higher fidelity on figures with in-image text).
+ */
+export declare const QUALITY_PROFILES: readonly ['fast', 'quality'];
+export type QualityProfile = (typeof QUALITY_PROFILES)[number];
+/**
+ * Captioner configuration. The model identifier is no longer caller-tunable;
+ * it is resolved inside the selected `profile` so that prompt, chat template,
+ * processor signature, generation options, and model class stay coherent per
+ * profile.
+ */
+export interface CaptionerConfig {
+    /** Visual-quality profile — selects the underlying VLM family. */
+    profile: QualityProfile;
+    /** Model cache directory (shared with the embedder via `env.cacheDir`). */
+    cacheDir: string;
+    /** Execution device passed through to Transformers.js model loading. */
+    device?: string | undefined;
+}
+/**
+ * Captioner public surface. Returns the caption string or `null` when the
+ * model produced an empty result (after control-char stripping + whitespace
+ * trim). A `null` return signals the orchestrator to skip this page without
+ * raising — only model load / image decode / generation failures throw.
+ */
+export interface Captioner {
+    caption(pngBytes: Uint8Array, pageNum: number): Promise<string | null>;
+}
+export type VisualBBox = [number, number, number, number];
+export type VisualEvidence = 'raster' | 'vector';
+export interface DetectedVisualRegion {
+    pageNum: number;
+    detectionIndex: number;
+    bbox: VisualBBox;
+    evidence: VisualEvidence;
+}
+export type VisualImageMimeType = 'image/png' | 'image/jpeg';
+export interface ImageRendition {
+    bytes: Uint8Array;
+    mimeType: VisualImageMimeType;
+}
+export interface ProcessedVisualRegion extends DetectedVisualRegion {
+    caption: string | null;
+    rendition?: ImageRendition;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/pdf-visual/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/pdf-visual/types.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7C;;;GAGG;AACH,qBAAa,QAAS,SAAQ,QAAQ;IACpC,SAAgB,OAAO,EAAE,MAAM,CAAA;IAE/B,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAIvE;CACF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,YAAI,MAAM,EAAE,SAAS,CAAU,CAAA;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,OAAO,EAAE,cAAc,CAAA;IACvB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACvE;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAEzD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAEhD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,cAAc,CAAA;CACzB;AAED,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,YAAY,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,CAAA;IACjB,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,CAAC,EAAE,cAAc,CAAA;CAC3B"}

package/dist/pdf-visual/types.js

@@ -0,0 +1,32 @@
+// Shared types for the `pdf-visual` package.
+//
+// `VlmError` is the package-wide named error for the visual ingest path.
+// `renderer.ts`, `captioner.ts`, and the orchestrator (`index.ts`) import it
+// from this single source. It joins the shared `AppError` taxonomy (taxonomy
+// only — name/message/cause behavior is unchanged) and additionally carries
+// the offending page number.
+//
+// `CaptionerConfig` / `Captioner` are the captioner's public interface,
+// shared across the visual ingest modules.
+import { AppError } from '../utils/errors.js';
+/**
+ * Error raised by any module on the visual ingest path. Carries the offending
+ * 1-based page number so callers can correlate it with the page list.
+ */
+export class VlmError extends AppError {
+    pageNum;
+    constructor(message, options) {
+        super(message, 'pdf-visual', 'internal', options.cause);
+        this.name = 'VlmError';
+        this.pageNum = options.pageNum;
+    }
+}
+/**
+ * Visual-quality profile selector. Each profile resolves to a self-contained
+ * captioner implementation under `captioners/`. `fast` ports the original
+ * SmolVLM-256M / IDEFICS3 captioner (lightweight default, ~250 MB cache);
+ * `quality` ports the Qwen2.5-VL-3B-Instruct-ONNX captioner (~2.9 GB cache,
+ * ~2× per-page inference, higher fidelity on figures with in-image text).
+ */
+export const QUALITY_PROFILES = ['fast', 'quality'];
+//# sourceMappingURL=types.js.map

package/dist/pdf-visual/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/pdf-visual/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,6BAA6B;AAC7B,EAAE;AACF,wEAAwE;AACxE,2CAA2C;AAE3C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7C;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,QAAQ;IACpB,OAAO,CAAQ;IAE/B,YAAY,OAAe,EAAE,OAA2C;QACtE,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QACvD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAA;QACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IAChC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,CAAU,CAAA"}

package/dist/server/error-utils.d.ts

@@ -0,0 +1,79 @@
+import type { Annotations } from '@modelcontextprotocol/sdk/types.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Shape of a single MCP content block used by RAG server handlers. Mirrors
+ * only the SDK text/image shapes needed by this server — defined here rather
+ * than using the SDK's widely-imported content union so unrelated SDK
+ * additions do not widen handler signatures later.
+ */
+export type RagTextContentBlock = {
+    type: 'text';
+    text: string;
+    annotations?: Annotations;
+};
+export type RagImageContentBlock = {
+    type: 'image';
+    data: string;
+    mimeType: 'image/png' | 'image/jpeg';
+    annotations?: Annotations;
+};
+export type RagContentBlock = RagTextContentBlock | RagImageContentBlock;
+/**
+ * Append config-warning blocks to an existing content array. Returns the
+ * same `content` reference for chainability (handlers typically build the
+ * array first, then call this once before returning).
+ */
+export declare function appendConfigWarnings<T extends RagContentBlock[]>(content: T, warnings: readonly string[]): T;
+/**
+ * Build a diagnostic content block exposing the supplied config-error
+ * message. Used by `status` when the server is in degraded mode (invalid
+ * `BASE_DIRS`) so the user can read the error via the MCP response without
+ * inspecting stderr.
+ */
+export declare function buildConfigErrorBlock(message: string): RagTextContentBlock;
+/**
+ * Context supplied by each handler to {@link toMcpError}, encoding that
+ * handler's client-message policy. `prefix` is the operation prefix applied to
+ * the generic/native fallback message (e.g. `'Failed to ingest file'`).
+ * Prefix-less handlers (`query_documents`/`list_files`/`status`) omit it.
+ */
+export type ToMcpErrorContext = {
+    prefix?: string;
+};
+/**
+ * Build the controlled, type-appropriate message sent to the MCP client.
+ *
+ * Returns only the error's `.message`, regardless of `NODE_ENV`: the client
+ * boundary never receives a stack trace or the raw `.cause` chain, so internal
+ * details cannot leak to the client even in development. Full diagnostics
+ * (stack + cause chain) belong in {@link formatErrorForLog} (stderr only).
+ */
+export declare function formatErrorForClient(error: unknown): string;
+/**
+ * Build the full diagnostic string for stderr logging: every link of the
+ * `.cause` chain (via {@link getCauseChain}) followed by its stack. Never sent
+ * to the client — this is the log-side counterpart of
+ * {@link formatErrorForClient}.
+ */
+export declare function formatErrorForLog(error: unknown): string;
+/**
+ * Log an error to stderr with its operation context and full cause chain.
+ * The only side-effecting boundary function — the formatters are pure so they
+ * can be composed without emitting logs.
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Map an arbitrary handler error to an `McpError` for the client boundary.
+ *
+ * - An existing `McpError` passes through unchanged (preserves hand-built
+ *   input-validation codes).
+ * - A recognized `AppError` maps by its `kind`: `validation`/`config` →
+ *   `InvalidParams`, everything else → `InternalError`. Its own message is used
+ *   raw — **no** operation prefix is applied, even when `context.prefix` is set
+ *   (e.g. `DatabaseError` stays prefix-less).
+ * - Any other value (native `Error` or non-`Error`) maps to `InternalError`,
+ *   and `context.prefix`, when present, is prepended to the controlled
+ *   client message. The raw cause chain is never included.
+ */
+export declare function toMcpError(error: unknown, context: ToMcpErrorContext): McpError;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/server/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/server/error-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAA;AACrE,OAAO,EAAa,QAAQ,EAAE,MAAM,oCAAoC,CAAA;AAGxE;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,WAAW,GAAG,YAAY,CAAA;IACpC,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;AA+CxE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,eAAe,EAAE,EAC9D,OAAO,EAAE,CAAC,EACV,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,CAAC,CAIH;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAM1E;AAuBD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAc/E"}

package/dist/server/error-utils.js

@@ -0,0 +1,148 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { getCauseChain, isAppError } from '../utils/errors.js';
+/**
+ * Annotations applied to config-warning blocks. The audience covers both
+ * the assistant (so it can decide to mention the warning to the user) and
+ * the user (so MCP clients that render annotations visibly know to surface
+ * it). Priority 0.3 keeps the block secondary to the primary tool result.
+ */
+const WARNING_ANNOTATIONS = {
+    audience: ['user', 'assistant'],
+    priority: 0.3,
+};
+/**
+ * Annotations applied to the config-error diagnostic block on `status`. The
+ * priority is raised relative to a warning because a config error means the
+ * server is degraded — `status` is the only tool still callable, and the
+ * user needs to see the error message to recover.
+ */
+const CONFIG_ERROR_ANNOTATIONS = {
+    audience: ['user', 'assistant'],
+    priority: 0.9,
+};
+/**
+ * Build the (zero or one) warning content block for the supplied warnings.
+ *
+ * Returns `[]` when no warnings exist so the caller can spread the result
+ * unconditionally without producing a spurious block. The single emitted
+ * block joins all warnings with ` | ` so MCP clients display them together
+ * — the per-warning structured form lives in the configuration layer
+ * (`BaseDirsConfigWarning`); here we render a single user-facing string.
+ *
+ * Centralizing this in one helper keeps the warning content shape consistent
+ * across handlers. Every handler must use this helper.
+ */
+function buildConfigWarningBlocks(warnings) {
+    if (warnings.length === 0)
+        return [];
+    return [
+        {
+            type: 'text',
+            text: `Warning: Tell the user about this configuration issue. ${warnings.join(' | ')}`,
+            annotations: WARNING_ANNOTATIONS,
+        },
+    ];
+}
+/**
+ * Append config-warning blocks to an existing content array. Returns the
+ * same `content` reference for chainability (handlers typically build the
+ * array first, then call this once before returning).
+ */
+export function appendConfigWarnings(content, warnings) {
+    const blocks = content;
+    blocks.push(...buildConfigWarningBlocks(warnings));
+    return content;
+}
+/**
+ * Build a diagnostic content block exposing the supplied config-error
+ * message. Used by `status` when the server is in degraded mode (invalid
+ * `BASE_DIRS`) so the user can read the error via the MCP response without
+ * inspecting stderr.
+ */
+export function buildConfigErrorBlock(message) {
+    return {
+        type: 'text',
+        text: `Configuration error: Tell the user to fix this. ${message}`,
+        annotations: CONFIG_ERROR_ANNOTATIONS,
+    };
+}
+/**
+ * Coerce an arbitrary thrown value into an `Error`. Preserves a real `Error`
+ * unchanged (so its `name`/`cause`/`stack` survive); reconstructs from a
+ * `{ message: string }` shape; otherwise stringifies. Centralized so every
+ * boundary function shares one normalization rule.
+ */
+function toError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (error !== null &&
+        typeof error === 'object' &&
+        'message' in error &&
+        typeof error.message === 'string') {
+        return new Error(error.message);
+    }
+    return new Error(String(error));
+}
+/**
+ * Build the controlled, type-appropriate message sent to the MCP client.
+ *
+ * Returns only the error's `.message`, regardless of `NODE_ENV`: the client
+ * boundary never receives a stack trace or the raw `.cause` chain, so internal
+ * details cannot leak to the client even in development. Full diagnostics
+ * (stack + cause chain) belong in {@link formatErrorForLog} (stderr only).
+ */
+export function formatErrorForClient(error) {
+    return toError(error).message;
+}
+/**
+ * Build the full diagnostic string for stderr logging: every link of the
+ * `.cause` chain (via {@link getCauseChain}) followed by its stack. Never sent
+ * to the client — this is the log-side counterpart of
+ * {@link formatErrorForClient}.
+ */
+export function formatErrorForLog(error) {
+    const err = toError(error);
+    return getCauseChain(err)
+        .map((link, index) => {
+        const header = index === 0 ? '' : 'Caused by: ';
+        return `${header}${link.stack || `${link.name}: ${link.message}`}`;
+    })
+        .join('\n');
+}
+/**
+ * Log an error to stderr with its operation context and full cause chain.
+ * The only side-effecting boundary function — the formatters are pure so they
+ * can be composed without emitting logs.
+ */
+export function logError(context, error) {
+    console.error(`[${context}] ${formatErrorForLog(error)}`);
+}
+/**
+ * Map an arbitrary handler error to an `McpError` for the client boundary.
+ *
+ * - An existing `McpError` passes through unchanged (preserves hand-built
+ *   input-validation codes).
+ * - A recognized `AppError` maps by its `kind`: `validation`/`config` →
+ *   `InvalidParams`, everything else → `InternalError`. Its own message is used
+ *   raw — **no** operation prefix is applied, even when `context.prefix` is set
+ *   (e.g. `DatabaseError` stays prefix-less).
+ * - Any other value (native `Error` or non-`Error`) maps to `InternalError`,
+ *   and `context.prefix`, when present, is prepended to the controlled
+ *   client message. The raw cause chain is never included.
+ */
+export function toMcpError(error, context) {
+    if (error instanceof McpError) {
+        return error;
+    }
+    if (isAppError(error)) {
+        const code = error.kind === 'validation' || error.kind === 'config'
+            ? ErrorCode.InvalidParams
+            : ErrorCode.InternalError;
+        return new McpError(code, formatErrorForClient(error));
+    }
+    const message = formatErrorForClient(error);
+    const clientMessage = context.prefix !== undefined ? `${context.prefix}: ${message}` : message;
+    return new McpError(ErrorCode.InternalError, clientMessage);
+}
+//# sourceMappingURL=error-utils.js.map

package/dist/server/error-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.js","sourceRoot":"","sources":["../../src/server/error-utils.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -0,0 +1,258 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { type RagContentBlock, type RagTextContentBlock } from './error-utils.js';
+import type { IngestDataInput, ListFilesInput, QueryDocumentsInput, RAGServerConfig, SyncStartInput, SyncStatusInput } from './types.js';
+type QueryContent = [RagTextContentBlock, ...RagContentBlock[]];
+/** RAG server compliant with MCP Protocol */
+export declare class RAGServer {
+    private readonly server;
+    private readonly vectorStore;
+    private readonly embedder;
+    private readonly chunker;
+    private readonly parser;
+    private readonly dbPath;
+    /**
+     * One or more allowed document base directories — REALPATH-normalized
+     * (the validation/security domain). Passed to `DocumentParser` as the
+     * security boundary. NOT used for `list_files` scanning/display; that uses
+     * the NORMAL-path `rawBaseDirs` below. Normalized from either the legacy
+     * `{ baseDir }` config shape or the new `{ baseDirs }` shape so downstream
+     * readers do not need to branch on shape.
+     */
+    private readonly baseDirs;
+    /**
+     * Normal-path (resolve()) roots, index-aligned with `baseDirs`, for
+     * user-facing `list_files` scan/display. Falls back to `baseDirs` for legacy
+     * `{ baseDir }` callers. See {@link BaseDirsConfig} for the path policy.
+     */
+    private readonly rawBaseDirs;
+    /** Legacy single-root accessor for `rawBaseDirs`. Derived from `rawBaseDirs[0]`. */
+    private readonly rawBaseDir;
+    private readonly cacheDir;
+    private readonly excludePaths;
+    private readonly configWarnings;
+    /**
+     * Structured base-dirs resolution error. When non-null, the server is in
+     * degraded mode: `status` remains callable so the user can diagnose the
+     * problem via MCP, while root-dependent tools should surface this error
+     * before doing DB or filesystem work. See `resolveBaseDirs` for the error
+     * semantics.
+     */
+    private readonly configError;
+    private readonly minChunkLength;
+    /**
+     * Configured byte ceiling for one ingested file. The parser enforces it for
+     * parsing; sync also needs it before hashing, where nothing else bounds the
+     * read.
+     */
+    private readonly maxFileSize;
+    private readonly device;
+    private readonly storeImages;
+    /**
+     * The one current-or-latest sync job this process retains (SYNC-006). A new
+     * `sync_start` replaces a terminal record, so the older id becomes unknown,
+     * and process exit simply discards it: there is no history, persistence,
+     * eviction policy, or recovery.
+     */
+    private syncJob;
+    /**
+     * True while one external mutation is in flight (SYNC-007). A request-scoped
+     * mutation clears it when the request completes; a sync keeps it until its
+     * job reaches a terminal state.
+     */
+    private mutationInFlight;
+    constructor(config: RAGServerConfig);
+    /**
+     * Fail-fast guard for root-dependent tools. When a {@link BaseDirsConfigError}
+     * is stored on the instance the server is in degraded mode (invalid
+     * `BASE_DIRS` — see `resolveBaseDirs`) and every root-dependent tool MUST
+     * reject BEFORE any DB / embedder / parser access so the user sees the
+     * configuration problem unambiguously. Throws the stored
+     * {@link BaseDirsConfigError} (kind `config`) so the central dispatcher
+     * mapper renders it as `McpError(InvalidParams)` — error→code ownership
+     * stays in exactly one place instead of being hand-built here.
+     *
+     * `status` deliberately does NOT call this helper; it remains callable in
+     * degraded mode and exposes the error via a diagnostic content block so
+     * the user can recover via MCP without inspecting stderr.
+     */
+    private assertConfigOk;
+    /**
+     * Append the centralized config-warning blocks to a handler response.
+     * Every tool handler funnels through this method so the warning shape
+     * stays in exactly one place (design-doc-mandated countermeasure for the
+     * "warning shape changes touch many handlers" risk).
+     */
+    private withWarnings;
+    /**
+     * Take the single external-mutation slot, or describe the overlap.
+     *
+     * Returns `null` when the slot was free (the caller now holds it), otherwise
+     * the responsive overlap result: an ordinary tool result with `isError: true`
+     * rather than a thrown error, so it never passes through `toMcpError`. When a
+     * sync holds the guard the message names its job id and points at
+     * `sync_status`, which is the only way for the caller to learn when to retry.
+     */
+    private acquireMutation;
+    private releaseMutation;
+    /**
+     * Set up MCP handlers
+     */
+    private setupHandlers;
+    /**
+     * Initialization
+     */
+    initialize(): Promise<void>;
+    /**
+     * query_documents tool handler
+     */
+    handleQueryDocuments(args: QueryDocumentsInput): Promise<{
+        content: QueryContent;
+    }>;
+    /**
+     * ingest_file tool handler (re-ingestion support, transaction processing, rollback capability)
+     *
+     * `options.skipOptimize` is internal: sync compacts once per run, so its reuse
+     * of this handler must not compact once per file (a 100-file sync would
+     * otherwise perform 101 compactions). The `ingest_file` and `ingest_data` tools
+     * omit it and keep compacting per call, which is the behavior they always had.
+     */
+    handleIngestFile(raw: unknown, options?: {
+        skipOptimize?: boolean;
+        images?: boolean;
+    }): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    private ingestFile;
+    /**
+     * ingest_data tool handler
+     * Saves raw content to raw-data directory and calls handleIngestFile internally
+     *
+     * For HTML content:
+     * - Parses HTML and extracts main content using Readability
+     * - Converts to Markdown for better chunking
+     * - Saves as .md file
+     */
+    handleIngestData(args: IngestDataInput): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /**
+     * list_files tool handler
+     *
+     * Scans the normal-path roots (`this.rawBaseDirs`) so scanned paths match the
+     * resolve()-stored DB keys (see {@link BaseDirsConfig} for the path policy).
+     *
+     * Scans every effective base directory (`this.rawBaseDirs`) for supported
+     * files and cross-references with ingested documents. Multi-root contract:
+     * - Returns top-level `baseDirs` (all effective roots in normal-path space,
+     *   nested-root-pruned by `resolveBaseDirs`).
+     * - Preserves legacy top-level `baseDir = rawBaseDirs[0]` for clients written
+     *   against the single-root shape.
+     * - Annotates each file entry with the producing `baseDir`.
+     * - De-duplicates exact duplicate file paths across roots (first occurrence
+     *   wins, preserving root iteration order).
+     * - Preserves raw-data / orphaned DB entries under `sources` with no
+     *   producing-root annotation.
+     * - Excludes `dbPath` and `cacheDir` uniformly across every root.
+     */
+    handleListFiles(input?: ListFilesInput): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /**
+     * status tool handler
+     */
+    handleStatus(): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /**
+     * delete_file tool handler
+     * Deletes chunks from VectorDB and physical raw-data files
+     * Supports both filePath (for ingest_file) and source (for ingest_data)
+     */
+    handleDeleteFile(raw: unknown): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /**
+     * read_chunk_neighbors tool handler
+     * Returns chunks around a target chunkIndex within a single ingested document.
+     * Context-expansion utility — not a search tool. Mirrors handleDeleteFile's
+     * dual-input (filePath XOR source) resolution pattern.
+     */
+    handleReadChunkNeighbors(raw: unknown): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /** Resolve the shared filePath/source reference without changing its DB-key spelling. */
+    private resolveDocumentTarget;
+    /**
+     * sync_start tool handler
+     *
+     * Registers the one current job, schedules the run, and answers with its id
+     * without waiting for any of it: the caller polls `sync_status` (SYNC-006).
+     * The scheduled promise is deliberately floating — an unexpected rejection is
+     * captured into the job record instead of escaping, and the run holds the
+     * external-mutation guard until it is terminal.
+     */
+    handleSyncStart(input: SyncStartInput): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /**
+     * sync_status tool handler
+     *
+     * Read-only, so it stays callable while a sync holds the mutation guard. Any
+     * id other than the current one is unknown: the record was replaced by a newer
+     * `sync_start` or lost with a previous server process.
+     */
+    handleSyncStatus(input: SyncStatusInput): Promise<{
+        content: RagTextContentBlock[];
+    }>;
+    /** Patch the current job, ignoring a write aimed at a record already replaced. */
+    private updateSyncJob;
+    /**
+     * The scheduled body of one sync job: supply the real collaborators to the
+     * shared core (`src/features/sync.ts`) and fold its result into the pollable
+     * record. Planning, prune eligibility, and the stop-on-first-error policy stay
+     * in the core; path classification and depth therefore match the CLI exactly.
+     */
+    private runSyncJob;
+    /**
+     * Sync's `ingestFile` collaborator uses the same typed ingestion operation as
+     * `ingest_file`, preserving its backup and rollback semantics while returning
+     * only the chunk count the sync core needs. A zero-chunk file is reported as
+     * `empty`; the typed operation rejects it before delete, leaving prior rows
+     * unchanged.
+     *
+     * Compaction is the second difference: the sync core runs one `optimize()` for
+     * the whole run, so the per-file one is skipped here. A rollback still compacts
+     * — that path restores rows and then aborts the run, so no later `optimize()`
+     * follows it.
+     */
+    private ingestFileForSync;
+    /**
+     * Serve this instance's tool registration over `transport`.
+     *
+     * Exposed because the registration itself — not a re-registered copy of it —
+     * is what an MCP client talks to, and `this.server` is private. `run()` passes
+     * the stdio transport; a test passes an in-memory pair.
+     *
+     * One instance serves at most one client: the sync job record and the mutation
+     * slot are per-process, so a transport that multiplexed clients would share one
+     * caller's job state and one caller's write lock with every other caller.
+     */
+    connect(transport: Transport): Promise<void>;
+    /**
+     * Start the server
+     */
+    run(): Promise<void>;
+    /**
+     * Stop the server and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Generate MCP server instructions automatically based on the configured
+     * base directories. A single root equal to the current working directory
+     * means the server indexes the current project; any other roots mean it
+     * indexes shared/common directories.
+     */
+    private generateInstructions;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}