@autorag/librarian 2.7.0 → 2.9.0

package/dist/datasource/chunk-store.d.ts

@@ -57,12 +57,8 @@ export declare class DatasourceChunkStore {
     hierarchies(): readonly (readonly string[])[];
     /**
      * BM25-style lexical search over the stored chunks. Empty queries and
-     * empty stores return `[]`; this method never throws.
-     *
-     * Terms match document tokens exactly or as a prefix (min 2 chars), so
-     * agglutinative suffixes — Korean particles/endings (인증서 → 인증서를) and
-     * English inflections (index → indexing) — still rank. Prefix hits are
-     * slightly discounted against exact hits.
+     * empty stores return `[]`; this method never throws. Scoring is delegated
+     * to {@link bm25Scores}.
      */
     search(query: string, topK: number): readonly ScoredChunk[];
     private persist;

package/dist/datasource/connector-skill.d.ts

@@ -14,8 +14,8 @@
  *  - Constructed only from trusted, server-supplied configuration.
  *  - Sources are stable slash-hierarchical paths `/<skill>/<instance>/…`.
  *  - `index()` never throws; failures surface as traceable diagnostics.
- *  - Retrieval honors `scope` and `allowedScopes` narrowing; tool arguments
- *    can never widen access (enforced upstream by DatasourceAccessContext).
+ *  - Retrieval honors the ordinary query `scope`; results are slash-hierarchical
+ *    opaque sources with no `#` fragment.
  *  - Results and metadata may carry real file paths or account identifiers;
  *    privacy is the operator's responsibility (use a local LLM).
  */
@@ -111,6 +111,5 @@ export declare class ConnectorLexicalMethod implements RetrievalMethod {
     constructor(options: ConnectorLexicalMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-    private matchesScope;
 }
 export {};

package/dist/datasource/index.d.ts

@@ -1,4 +1,3 @@
-export { DatasourceAccessContext, type DatasourceAccessContextOptions } from "./access-context.js";
 export { type AliasDatasourceSkillOptions, AliasedDatasourceSkill } from "./aliased-skill.js";
 export { DatasourceChunkStore, type DatasourceChunkStoreOptions, datasourceChunkStorePath, type ScoredChunk, type StoredChunk, } from "./chunk-store.js";
 export { boundDiagnosticText, type ConnectorDocument, type ConnectorFailureReason, type ConnectorFetchFail, type ConnectorFetchOk, type ConnectorFetchResult, connectorFailureToDiagnosticCode, type DatasourceConnector, sanitizeIdSegment, } from "./connector.js";
@@ -6,8 +5,7 @@ export { ConnectorDatasourceSkill, ConnectorLexicalMethod, type ConnectorSkillDe
 export { mapDatasourceDiagnostic, mapDatasourceDiagnostics } from "./diagnostics.js";
 export { type CronParseResult, isDue, parseCronExpr } from "./polling.js";
 export { DatasourceSkillRegistry, type RegisteredDatasourceSkill } from "./registry.js";
-export { DatasourceResultFilter, type ResultsByMethod } from "./result-filter.js";
-export { buildDatasourceChunkSource, buildDatasourceInstanceSource, DATASOURCE_CHUNKS_SEGMENT, datasourceSourceHasFragment, datasourceSourcePath, isDatasourceSource, matchesDatasourceScope, matchesVirtualPathScope, normalizeVirtualPath, } from "./scope.js";
+export { buildDatasourceChunkSource, buildDatasourceInstanceSource, DATASOURCE_CHUNKS_SEGMENT, datasourceSourceHasFragment, datasourceSourcePath, filterDatasourceScope, isDatasourceSource, matchesDatasourceScope, matchesVirtualPathScope, normalizeVirtualPath, type ResultsByMethod, } from "./scope.js";
 export { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOptions, RcloneConnector, type RcloneConnectorOptions, type RcloneRunner, type RcloneRunResult, } from "./skills/cloud-drive/index.js";
 export { DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_MODE, DiscrawlClient, type DiscrawlFailureReason, DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, DiscrawlSemanticMethod, DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./skills/discrawl/index.js";
 export { BUILTIN_DATASOURCE_SKILL_NAMES, type BuildDatasourceSkillsResult, buildDatasourceSkills, type DatasourceSkillConfig, type DatasourcesConfig, } from "./skills/factory.js";
@@ -24,4 +22,4 @@ export { SlackSkill, type SlackSkillOptions, SlacrawlClient, type SlacrawlOption
 export { SpotlightConnector, type SpotlightConnectorOptions, SpotlightSkill, type SpotlightSkillOptions, } from "./skills/spotlight/index.js";
 export { TelecrawlClient, type TelecrawlOptions, TelecrawlSkill, type TelecrawlSkillOptions, } from "./skills/telecrawl/index.js";
 export { WacrawlClient, type WacrawlOptions, WacrawlSkill, type WacrawlSkillOptions } from "./skills/wacrawl/index.js";
-export type { DatasourceAccessible, DatasourceDiagnostic, DatasourceDiagnosticCode, DatasourceIndexFail, DatasourceIndexOk, DatasourceIndexResult, DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription, } from "./types.js";
+export type { DatasourceDiagnostic, DatasourceDiagnosticCode, DatasourceIndexFail, DatasourceIndexOk, DatasourceIndexResult, DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription, } from "./types.js";

package/dist/datasource/registry.d.ts

@@ -3,14 +3,13 @@
  *
  * Skills are constructed from trusted, server-supplied configuration and
  * registered here so the retrieval pipeline can enumerate them, look them up
- * by tag, and resolve the concrete instances a given access context permits.
+ * by tag (descriptive metadata), and resolve the concrete instances they expose.
  *
- * The registry never grants access: {@link resolveInstances} only *narrows*
- * the registered skills to those a {@link DatasourceAccessContext} already
- * allows. Model/tool arguments are not consulted.
+ * Every configured/connected datasource is searchable without permission setup;
+ * there is no access context. The ordinary query `scope` narrows results later
+ * in the pipeline, not here. Model/tool arguments are not consulted.
  */
 import type { RetrievalMethod } from "../retrieval/types.js";
-import type { DatasourceAccessContext } from "./access-context.js";
 import type { DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor } from "./types.js";
 /** A registered skill paired with its cached descriptor. */
 export interface RegisteredDatasourceSkill {
@@ -30,23 +29,22 @@ export declare class DatasourceSkillRegistry {
     register(skill: DatasourceSkill): void;
     /** All registered skills in insertion order. */
     list(): readonly RegisteredDatasourceSkill[];
-    /** Skills whose descriptor carries the given tag. */
+    /** Skills whose descriptor carries the given tag (descriptive metadata). */
     byTag(tag: string): readonly RegisteredDatasourceSkill[];
     /** Look up a registered skill by id, or `undefined`. */
     get(id: string): RegisteredDatasourceSkill | undefined;
     /**
-     * Resolve the concrete datasource instances reachable under `ctx`.
+     * Resolve every configured datasource instance.
      *
-     * Only skills whose descriptor {@link DatasourceAccessContext.isAccessible}
-     * allows contribute instances, and only their declared instance ids are
+     * All registered skills contribute, and only their declared instance ids are
      * materialized. Each instance carries its opaque slash-hierarchical
      * {@link DatasourceInstance.sourcePath} (e.g. `/kakao/acct-1`), built from
      * the trusted skill name and instance id — never from model input.
      */
-    resolveInstances(ctx: DatasourceAccessContext): readonly DatasourceInstance[];
+    resolveInstances(): readonly DatasourceInstance[];
     /**
-     * Convenience: all retrieval methods exposed by accessible skills, for
-     * feeding the shared retriever. Methods from denied skills are excluded.
+     * All retrieval methods exposed by registered skills, for feeding the shared
+     * retriever.
      */
-    accessibleMethods(ctx: DatasourceAccessContext): readonly RetrievalMethod[];
+    retrievalMethods(): readonly RetrievalMethod[];
 }

package/dist/datasource/scope.d.ts

@@ -9,6 +9,9 @@
  * `src/retrieval/scope.ts` so datasource scopes compose with the existing
  * retrieval scope grammar (globs, leading-slash normalization).
  */
+import type { RetrievalMethod, RetrievalResult } from "../retrieval/types.js";
+/** Per-method retrieval results keyed by method name. */
+export type ResultsByMethod = Map<string, RetrievalResult[]>;
 /** Path segment separating an instance root from its chunk sub-namespace. */
 export declare const DATASOURCE_CHUNKS_SEGMENT = "chunks";
 /**
@@ -35,4 +38,20 @@ export declare function isDatasourceSource(source: string): boolean;
  * scope matcher so globs and leading-slash normalization behave identically.
  */
 export declare function matchesDatasourceScope(source: string, scope: string | undefined): boolean;
+/**
+ * Narrow a per-method result map by the ordinary query `scope`.
+ *
+ * This is the only post-retrieval narrowing left in the datasource layer: every
+ * configured datasource is searchable without permission setup. Methods whose
+ * descriptor has no `datasourceId` (plain retrieval methods such as `posix`) and
+ * datasource methods that do not advertise the `scoped` capability pass through
+ * untouched. Scope-capable datasource methods keep only the results whose
+ * source matches `scope`; `undefined` scope matches every valid source, and
+ * sources containing a `#` fragment are always rejected.
+ *
+ * Result entries for methods not present in `methods` are passed through
+ * unchanged (they cannot be classified). A new map is returned; the input is
+ * not mutated.
+ */
+export declare function filterDatasourceScope(byMethod: ResultsByMethod, methods: readonly RetrievalMethod[], scope?: string): ResultsByMethod;
 export { matchesVirtualPathScope, normalizeVirtualPath } from "../retrieval/scope.js";

package/dist/datasource/skills/github-gist/index.d.ts

@@ -1,3 +1,3 @@
 export { GitHubGistConnector, type GitHubGistConnectorOptions } from "./connector.js";
-export { createGatewayGistEmbedder, type GatewayGistEmbedderOptions, type GistEmbedder, type GistEmbeddingIdentity, GistSemanticIndex, GitHubGistSemanticMethod, } from "./semantic.js";
+export { GistSemanticIndex, GitHubGistSemanticMethod } from "./semantic.js";
 export { GITHUB_GIST_SKILL_DEFINITION, type GitHubGistSemanticOptions, GitHubGistSkill, type GitHubGistSkillOptions, gistDatasourceDir, } from "./skill.js";

package/dist/datasource/skills/github-gist/semantic.d.ts

@@ -9,19 +9,9 @@
  * `cachedOnly`, then `POST /v1/embeddings`); tests inject a stub. Every
  * failure degrades — indexing stays lexical-only and retrieval returns [].
  */
-import type { ProfileId } from "../../../embedding-runtime/types.js";
+import type { Embedder } from "../../../embedding-runtime/gateway-embedder.js";
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
 import type { DatasourceChunkStore, StoredChunk } from "../../chunk-store.js";
-export interface GistEmbeddingIdentity {
-    readonly provider: string;
-    readonly model: string;
-    readonly dimension: number;
-}
-/** Embedder contract: identity is async because the gateway resolves it lazily. */
-export interface GistEmbedder {
-    identity(): Promise<GistEmbeddingIdentity>;
-    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
-}
 export interface GistSemanticSyncOk {
     readonly ok: true;
     /** Number of chunks (re-)embedded in this sync. */
@@ -44,7 +34,7 @@ export declare class GistSemanticIndex {
      * Embed new/changed chunks, prune removed ones, and persist. Never throws;
      * an embedder failure leaves prior entries intact and reports ok:false.
      */
-    sync(chunks: readonly StoredChunk[], embedder: GistEmbedder): Promise<GistSemanticSyncOk | GistSemanticSyncFail>;
+    sync(chunks: readonly StoredChunk[], embedder: Embedder): Promise<GistSemanticSyncOk | GistSemanticSyncFail>;
     /** Cosine-ranked chunk ids for a query vector. Never throws. */
     searchByVector(queryVector: readonly number[], topK: number): readonly {
         chunkId: string;
@@ -60,7 +50,7 @@ export interface GitHubGistSemanticMethodOptions {
     readonly tags: readonly string[];
     readonly store: DatasourceChunkStore;
     readonly index: GistSemanticIndex;
-    readonly embedder: GistEmbedder;
+    readonly embedder: Embedder;
 }
 /** Cosine similarity retrieval over the gist vector sidecar. Never throws. */
 export declare class GitHubGistSemanticMethod implements RetrievalMethod {
@@ -68,35 +58,4 @@ export declare class GitHubGistSemanticMethod implements RetrievalMethod {
     constructor(options: GitHubGistSemanticMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-    private matchesScope;
 }
-export interface GatewayGistEmbedderOptions {
-    /** Runtime resolver; defaults to the shared embedding-runtime ensureRuntime. */
-    readonly runtime?: {
-        ensureRuntime(input?: {
-            profileId?: ProfileId;
-            cachedOnly?: boolean;
-        }): Promise<{
-            baseUrl: string;
-            identity: {
-                provider: string;
-                model: string;
-                dimension: number;
-            };
-        }>;
-    };
-    readonly profileId?: ProfileId;
-    readonly fetchImpl?: typeof fetch;
-}
-/**
- * Production embedder backed by the loopback autorag-gateway. The runtime is
- * ensured lazily with `cachedOnly` so semantic retrieval never triggers a
- * model download; an unprimed cache surfaces as a sync/retrieve degrade.
- */
-/**
- * Texts per `/v1/embeddings` call. The llama.cpp upstream rejects very large
- * batches (HTTP 413 on a full-archive sync), so embedding fans out in
- * bounded sequential batches while preserving input order.
- */
-export declare const GIST_EMBED_BATCH_SIZE = 32;
-export declare function createGatewayGistEmbedder(options?: GatewayGistEmbedderOptions): GistEmbedder;

package/dist/datasource/skills/github-gist/skill.d.ts

@@ -7,19 +7,19 @@
  * through the loopback embedding gateway. Embedding failures degrade to a
  * `semantic-unavailable` warning — indexing and lexical retrieval continue.
  */
+import { type Embedder, type GatewayEmbedderOptions } from "../../../embedding-runtime/gateway-embedder.js";
 import type { RetrievalMethod } from "../../../retrieval/types.js";
 import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
 import type { DatasourceIndexResult } from "../../types.js";
 import { GitHubGistConnector, type GitHubGistConnectorOptions } from "./connector.js";
-import { type GatewayGistEmbedderOptions, type GistEmbedder } from "./semantic.js";
 export declare const GITHUB_GIST_SKILL_DEFINITION: ConnectorSkillDefinition;
 export declare function gistDatasourceDir(workspaceRoot: string, skillName: string, instanceId: string): string;
 export interface GitHubGistSemanticOptions {
     /** Set false to run lexical-only. Default true. */
     readonly enabled?: boolean;
     /** Injected embedder (tests); defaults to the loopback gateway embedder. */
-    readonly embedder?: GistEmbedder;
-    readonly embedderOptions?: GatewayGistEmbedderOptions;
+    readonly embedder?: Embedder;
+    readonly embedderOptions?: GatewayEmbedderOptions;
     /** Vector sidecar path override; defaults under `.autorag/datasources/…`. */
     readonly statePath?: string;
 }

package/dist/datasource/types.d.ts

@@ -4,27 +4,24 @@
  * A *datasource* is an external, server-bound source of retrieval evidence
  * (e.g. a KakaoTalk export reached through the external `lazykatok` CLI). The
  * datasource layer sits *on top of* the existing retrieval pipeline: it owns
- * access gating and slash-hierarchical source naming, while actual retrieval
- * still flows through {@link RetrievalMethod} instances returned by a skill.
+ * slash-hierarchical source naming, while actual retrieval still flows through
+ * {@link RetrievalMethod} instances returned by a skill.
  *
- * Security invariants (enforced by {@link DatasourceAccessContext}):
- *  - Access is **default-deny**: when no trusted allow-tags are configured,
- *    every datasource descriptor and source is denied.
- *  - Deny is always an explicit `false` boolean / predicate return — never
- *    `undefined`-as-deny.
- *  - Model/tool arguments never grant access. Only the trusted server-supplied
- *    {@link DatasourceAccessContext} can authorize a datasource.
- *  - Datasource sources are slash-hierarchical opaque paths when the skill
- *    supports the `scoped` capability; skills without that capability may
- *    expose another opaque identity format.
+ * Every configured/connected datasource is searchable without permission
+ * setup: there is no tag/scope authorization layer. The ordinary query `scope`
+ * narrows results after retrieval (see `filterDatasourceScope`), and skill
+ * descriptor `tags` are descriptive metadata only — never authority.
+ * Datasource sources are slash-hierarchical opaque paths for skills that
+ * advertise the `scoped` capability; skills without it may expose another
+ * opaque identity format.
  */
 import type { RetrievalMethod } from "../retrieval/types.js";
 export type { RetrievalMethod } from "../retrieval/types.js";
 /**
  * Descriptor for a datasource skill (e.g. KakaoTalk via `lazykatok`).
  *
- * Structurally compatible with {@link RetrievalMethodDescriptor} so that
- * retrieval method descriptors can be gated by the same access context.
+ * Structurally compatible with {@link RetrievalMethodDescriptor}: retrieval
+ * method descriptors carry the same `datasourceId`/`tags`/`capabilities` fields.
  */
 export interface DatasourceSkillDescriptor {
     /** Stable skill name, e.g. `"kakao"`. */
@@ -37,8 +34,8 @@ export interface DatasourceSkillDescriptor {
     /** Capability tags such as `"chat"`, `"external-cli"`, `"polling"`. */
     readonly capabilities: readonly string[];
     /**
-     * Authorization tags. A descriptor is accessible only when at least one tag
-     * intersects the trusted allow-tags on the access context.
+     * Descriptive tags such as `"chat"` or `"external-cli"`. Metadata only —
+     * never used to authorize or narrow access.
      */
     readonly tags: readonly string[];
     readonly status: "active" | "stub";
@@ -47,7 +44,7 @@ export interface DatasourceSkillDescriptor {
     /**
      * Set when this descriptor describes a datasource-backed surface.
      * Non-datasource descriptors (e.g. plain `posix` retrieval methods) leave
-     * this undefined and are passed through by the access context.
+     * this undefined.
      */
     readonly datasourceId?: string;
     /** Optional primary instance id for single-instance skills. */
@@ -55,17 +52,6 @@ export interface DatasourceSkillDescriptor {
     /** Optional list of instance ids this skill reports. */
     readonly instances?: readonly string[];
 }
-/**
- * Minimal structural shape required to gate a descriptor by access context.
- * Both {@link DatasourceSkillDescriptor} and `RetrievalMethodDescriptor`
- * satisfy this interface structurally.
- */
-export interface DatasourceAccessible {
-    readonly datasourceId?: string;
-    readonly tags?: readonly string[];
-    /** Capability names such as `scoped`; absent means no source-scope support. */
-    readonly capabilities?: readonly string[];
-}
 /**
  * A pluggable datasource skill. Skills are server-bound: they are constructed
  * with trusted configuration and never derive authority from model/tool args.

package/dist/embedding-runtime/gateway-embedder.d.ts

@@ -0,0 +1,41 @@
+import type { ProfileId } from "./types.js";
+export interface EmbeddingIdentity {
+    readonly provider: string;
+    readonly model: string;
+    readonly dimension: number;
+}
+/** Embedder contract: identity is async because the gateway resolves it lazily. */
+export interface Embedder {
+    identity(): Promise<EmbeddingIdentity>;
+    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
+}
+export interface GatewayEmbedderOptions {
+    /** Runtime resolver; defaults to the shared embedding-runtime ensureRuntime. */
+    readonly runtime?: {
+        ensureRuntime(input?: {
+            profileId?: ProfileId;
+            cachedOnly?: boolean;
+        }): Promise<{
+            baseUrl: string;
+            identity: {
+                provider: string;
+                model: string;
+                dimension: number;
+            };
+        }>;
+    };
+    readonly profileId?: ProfileId;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Texts per `/v1/embeddings` call. The llama.cpp upstream rejects very large
+ * batches (HTTP 413 on a full-archive sync), so embedding fans out in
+ * bounded sequential batches while preserving input order.
+ */
+export declare const EMBED_BATCH_SIZE = 32;
+/**
+ * Production embedder backed by the loopback autorag-gateway. The runtime is
+ * ensured lazily with `cachedOnly` so embedding never triggers a model
+ * download; an unprimed cache surfaces as a caller-side degrade.
+ */
+export declare function createGatewayEmbedder(options?: GatewayEmbedderOptions): Embedder;

package/dist/everything/bundle.d.ts

@@ -6,6 +6,12 @@
  * and nothing is installed system-wide.
  */
 export type EverythingArch = "x64" | "arm64";
+/**
+ * `"install"` extracts and verifies the pinned binaries when the workspace
+ * cache is missing or invalid; `"cached"` returns only an already extracted,
+ * hash-verified cache entry and never writes to disk.
+ */
+export type EverythingBinaryResolutionMode = "cached" | "install";
 export interface EverythingArchAssets {
     readonly everythingArchive: string;
     readonly everythingArchiveSha256: string;
@@ -31,6 +37,8 @@ export interface EnsureEverythingBinariesOptions {
     readonly bundleDir?: string;
     /** Bundle manifest. Defaults to `<bundleDir>/manifest.json`. */
     readonly manifest?: EverythingBundleManifest;
+    /** Defaults to `"install"`; `"cached"` is the read-only resolution a query uses. */
+    readonly mode?: EverythingBinaryResolutionMode;
 }
 export type EnsureEverythingBinariesResult = {
     readonly ok: true;
@@ -39,7 +47,7 @@ export type EnsureEverythingBinariesResult = {
     readonly source: "cached" | "installed";
 } | {
     readonly ok: false;
-    readonly reason: "unsupported-platform" | "bundle-missing" | "install-failed";
+    readonly reason: "unsupported-platform" | "bundle-missing" | "install-failed" | "not-installed";
     readonly message: string;
 };
 /**
@@ -56,7 +64,11 @@ export declare function everythingBinaryPaths(root: string, version: string, arc
 };
 export declare function loadEverythingBundleManifest(bundleDir: string): EverythingBundleManifest;
 /**
- * Extract and verify the bundled Everything + ES binaries for this Windows
- * host. Never throws: every failure is reported with its underlying message.
+ * Resolve the bundled Everything + ES binaries for this Windows host. Never
+ * throws: every failure is reported with its underlying message. `mode:
+ * "install"` (default) extracts and verifies them from the bundled ZIPs when
+ * the workspace cache is missing or invalid; `mode: "cached"` is read-only and
+ * reports `not-installed` instead of writing so a query can only use verified,
+ * already-extracted binaries.
  */
 export declare function ensureEverythingBinaries(options: EnsureEverythingBinariesOptions): Promise<EnsureEverythingBinariesResult>;

package/dist/everything/client.d.ts

@@ -1,4 +1,4 @@
-import { type EnsureEverythingBinariesResult } from "./bundle.js";
+import { type EnsureEverythingBinariesResult, type EverythingBinaryResolutionMode } from "./bundle.js";
 /**
  * Drives a private, user-level Everything instance per AutoRAG workspace.
  *
@@ -32,7 +32,7 @@ export interface EverythingSearchRequest {
     readonly offset?: number;
     readonly maxResults?: number;
 }
-export type EverythingFailureReason = "unsupported-platform" | "bundle-missing" | "install-failed" | "startup-failed" | "index-failed" | "search-failed";
+export type EverythingFailureReason = "unsupported-platform" | "bundle-missing" | "install-failed" | "not-installed" | "not-running" | "startup-failed" | "index-failed" | "search-failed";
 export interface EverythingFailure {
     readonly ok: false;
     readonly reason: EverythingFailureReason;
@@ -70,7 +70,12 @@ export interface EverythingClientOptions extends EverythingOptions {
     /** Folders Everything indexes (the configured search paths). */
     readonly folders: readonly string[];
     readonly platform?: NodeJS.Platform;
-    readonly resolveBinaries?: () => Promise<EnsureEverythingBinariesResult>;
+    /**
+     * Resolve the bundled executables. `"cached"` (queries and stop) must
+     * return only already extracted, hash-verified binaries; `"install"`
+     * (refresh/index) may extract them. Defaults to `ensureEverythingBinaries`.
+     */
+    readonly resolveBinaries?: (mode: EverythingBinaryResolutionMode) => Promise<EnsureEverythingBinariesResult>;
     readonly run?: EverythingRunner;
     readonly launch?: EverythingLauncher;
     readonly pollIntervalMs?: number;
@@ -105,16 +110,28 @@ export declare class EverythingClient {
     private operation;
     constructor(options: EverythingClientOptions);
     isSupported(): boolean;
-    /** Start the instance when needed and search it. */
+    /**
+     * Search the running instance. Read-only: never starts Everything, waits
+     * for it to index, or installs its binaries (refresh does that), so a query
+     * never pays startup or extraction cost. A cold cache reports
+     * `not-installed` with a refresh hint instead.
+     */
     search(request: EverythingSearchRequest): Promise<EverythingSearchResult>;
     /**
      * (Re)write the folder configuration, restart the instance so Everything
      * loads it, and wait until the database finished indexing.
      */
     index(): Promise<EverythingIndexResult>;
-    /** Exit this workspace's Everything instance if it is running. */
+    /** Exit this workspace's Everything instance if it is running. Never installs binaries. */
     stop(): Promise<void>;
     private serialize;
+    /**
+     * Resolve the ES + Everything executables. `"cached"` reads only the
+     * already extracted, hash-verified workspace cache and never writes;
+     * `"install"` (refresh/index) may extract from the bundled ZIPs. Only a
+     * verified resolution is memoized, so a cached-mode miss never poisons the
+     * install-mode resolution that refresh depends on.
+     */
     private resolveBinaries;
     private ensureRunning;
     /** Exit code 0 only when the instance answered with its version. */

package/dist/everything/index.d.ts

@@ -1,2 +1,2 @@
-export { type EnsureEverythingBinariesOptions, type EnsureEverythingBinariesResult, type EverythingArch, type EverythingArchAssets, type EverythingBundleManifest, ensureEverythingBinaries, everythingArch, everythingBinaryPaths, loadEverythingBundleManifest, resolveEverythingBundleDir, } from "./bundle.js";
+export { type EnsureEverythingBinariesOptions, type EnsureEverythingBinariesResult, type EverythingArch, type EverythingArchAssets, type EverythingBinaryResolutionMode, type EverythingBundleManifest, ensureEverythingBinaries, everythingArch, everythingBinaryPaths, loadEverythingBundleManifest, resolveEverythingBundleDir, } from "./bundle.js";
 export { buildEverythingIni, buildEverythingSearchArgs, EverythingClient, type EverythingClientOptions, type EverythingEntry, type EverythingFailure, type EverythingFailureReason, type EverythingIndexResult, type EverythingLauncher, type EverythingOptions, type EverythingRunner, type EverythingRunResult, type EverythingSearchRequest, type EverythingSearchResult, type EverythingSort, everythingInstanceName, parseEverythingJson, } from "./client.js";

package/dist/filesystem/name-search.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Literal (never regex) file-name search over configured filesystem roots.
+ *
+ * This is a discovery-only backend: it walks directories directly and never
+ * consults a parsed mirror/index, so a name can be found before any refresh
+ * has run. It never opens file contents — only directory listings are read.
+ *
+ * Path safety is the whole point of this module:
+ * - configured roots are `realpath`-pinned; missing roots degrade to a
+ *   diagnostic instead of an exception;
+ * - `request.root` may only select a configured root or a real subdirectory
+ *   *inside* one (realpath containment), so it can never widen scope;
+ * - child symlinks are never followed, so a symlink inside a root cannot leak
+ *   results from outside it;
+ * - when nothing can be searched, the result is an empty page plus a warning
+ *   diagnostic, never an arbitrary global `/` scan.
+ */
+/** A single matched entry, with its canonical absolute filesystem path. */
+export interface FileNameSearchMatch {
+    readonly path: string;
+    readonly type: "file" | "folder";
+}
+/** A non-fatal problem encountered while resolving or walking roots. */
+export interface FileNameSearchDiagnostic {
+    readonly code: string;
+    readonly severity: "warning";
+    readonly source: string;
+    readonly message: string;
+}
+export interface FileNameSearchRequest {
+    readonly query: string;
+    /** Configured root or subdirectory (absolute or root-relative) to limit the walk to. */
+    readonly root?: string;
+    /** Match the query against the path relative to the search root instead of the file name. */
+    readonly matchPath?: boolean;
+    /** Case-sensitive matching. Defaults to case-insensitive. */
+    readonly matchCase?: boolean;
+    readonly kind?: "files" | "folders";
+    readonly maxResults?: number;
+    readonly offset?: number;
+    readonly signal?: AbortSignal;
+}
+export interface FileNameSearchResult {
+    readonly ok: true;
+    readonly backend: "filesystem" | "everything";
+    readonly results: readonly FileNameSearchMatch[];
+    readonly truncated: boolean;
+    readonly diagnostics: readonly FileNameSearchDiagnostic[];
+}
+/** Resolve one requested root inside the configured roots for backend routing. */
+export declare function resolveConfiguredFileSearchRoot(roots: readonly string[], requestRoot: string): Promise<string | undefined>;
+/**
+ * Keep provider-returned file-name hits inside configured roots and exclusions.
+ * Revalidates lstat/realpath so an external index cannot widen MCP scope.
+ */
+export declare function filterFileNameSearchMatches(roots: readonly string[], candidates: readonly FileNameSearchMatch[], excludePaths?: readonly string[]): Promise<FileNameSearchMatch[]>;
+export declare function searchFileNames(roots: readonly string[], request: FileNameSearchRequest, excludePaths?: readonly string[]): Promise<FileNameSearchResult>;

package/dist/fsearch/client.d.ts

@@ -90,6 +90,8 @@ export interface FSearchClientOptions extends FSearchOptions {
     readonly root: string;
     /** Folders FSearch indexes (the configured search paths). */
     readonly folders: readonly string[];
+    /** Additional configured folders omitted from the index. */
+    readonly excludeFolders?: readonly string[];
     readonly platform?: NodeJS.Platform;
     readonly run?: FSearchRunner;
     readonly launch?: FSearchLauncher;
@@ -144,7 +146,11 @@ export declare class FSearchClient {
     private operation;
     constructor(options: FSearchClientOptions);
     isSupported(): boolean;
-    /** Search the workspace database, building it on first use; walks when fsearch-cli is missing. */
+    /**
+     * Search the prebuilt workspace database. Read-only: a missing database is
+     * never built here (refresh does that), so a query never pays for indexing.
+     * Without fsearch-cli or a database, it walks the configured folders.
+     */
     search(request: FSearchSearchRequest): Promise<FSearchSearchResult>;
     /** (Re)build the database over the configured folders and keep the watch daemon live. */
     index(): Promise<FSearchIndexResult>;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AutoRAGAgent, type AutoRAGAgentOptions, type AutoRAGRefreshComponentStatus, type AutoRAGRefreshOptions, type AutoRAGRefreshResult, type AutoRAGRefreshStatus, type AutoRAGWatchRefreshHandle, type AutoRAGWatchRefreshOptions, type AutoRefreshOptions, type RefreshMethod, } from "./agent/agent.js";
-export { type AutoRAGResultsDetails, createEmitResultsTool, EMIT_AUTORAG_RESULTS_TOOL_NAME, emitResultsSchema, type SearchDocumentDiagnostic, type SearchDocumentDiagnosticCode, type SearchDocumentDiagnosticSeverity, type SearchDocumentsResponse, type SearchDocumentsStreamEvent, type SearchDocumentWarning, } from "./agent/index.js";
+export { type AutoRAGResultsDetails, createEmitResultsTool, EMIT_AUTORAG_RESULTS_TOOL_NAME, emitResultsSchema, reportSchema, type SearchDocumentDiagnostic, type SearchDocumentDiagnosticCode, type SearchDocumentDiagnosticSeverity, type SearchDocumentsResponse, type SearchDocumentsStreamEvent, type SearchDocumentWarning, } from "./agent/index.js";
 export { buildSystemPrompt, type SystemPromptConfig } from "./agent/system-prompt.js";
 export { AutoRAGLite, type AutoRAGLiteOptions, buildAgentOptions, type CliConfig, createAutoRAGLite, type ResolveConfigInput, resolveConfig, resolveConfigReadOnly, writeConfigObject, writeDefaultConfig, } from "./core.js";
 export * from "./datasource/index.js";
@@ -8,6 +8,7 @@ export * from "./everything/index.js";
 export * from "./fsearch/index.js";
 export * from "./jikji/index.js";
 export * from "./manifest/index.js";
+export { type AutoRAGMcpServerOptions, createAutoRAGMcpServer } from "./mcp/server.js";
 export * from "./memory/index.js";
 export * from "./minsync/index.js";
 export * from "./mirror/index.js";