@autorag/librarian 2.13.1 → 2.13.3

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

@@ -1,7 +1,6 @@
 /**
  * Shared {@link DatasourceSkill} implementation for connector-backed
- * datasources (Slack, Discord, Notion, GitHub, Google Drive,
- * local mail exports, RSS/news).
+ * datasources (GitHub, cloud drives, RSS/news, Spotlight).
  *
  * Composition: a trusted {@link DatasourceConnector} fetches documents, a
  * {@link DatasourceChunkStore} persists and lexically indexes them, and this

package/dist/datasource/connector.d.ts

@@ -1,7 +1,6 @@
 /**
- * Connector contract shared by the built-in datasource skills (Slack, Discord,
- * Notion, GitHub, Google Drive, local mail exports,
- * RSS/news).
+ * Connector contract shared by the built-in datasource skills (GitHub,
+ * cloud drives, RSS/news, Spotlight).
  *
  * A *connector* is the trusted, server-configured bridge to one external
  * system. It fetches documents for indexing and NEVER throws — every failure

package/dist/datasource/index.d.ts

@@ -14,13 +14,12 @@ export { HISTER_SKILL_TYPE, HisterClient, type HisterClientOptions, HisterSkill,
 export { LarkClient, type LarkClientOptions, LarkSkill, type LarkSkillOptions } from "./skills/lark/index.js";
 export type { LazykatokFailureReason, LazykatokHit, LazykatokOptions, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSkillClient, LazykatokSkillOptions, } from "./skills/lazykatok/index.js";
 export { LazykatokBm25Method, LazykatokClient, LazykatokHybridMethod, LazykatokSkill, } from "./skills/lazykatok/index.js";
-export { MailExportConnector, type MailExportConnectorOptions, MailExportSkill, type MailExportSkillOptions, } from "./skills/mail-export/index.js";
 export { MAILCRAWL_MODES, MailcrawlClient, type MailcrawlFailure, type MailcrawlFailureReason, type MailcrawlIndexInfo, MailcrawlMethod, type MailcrawlOptions, type MailcrawlSearchHit, type MailcrawlSearchMode, type MailcrawlSearchResult, MailcrawlSkill, type MailcrawlSyncInfo, type MailcrawlSyncResult, } from "./skills/mailcrawl/index.js";
 export { NotcrawlClient, type NotcrawlOptions, NotionSkill, type NotionSkillOptions, } from "./skills/notion/index.js";
 export { ObsidianBm25Method, type ObsidianMethodOptions, ObsidianSemanticMethod, ObsidianSkill, type ObsidianSkillOptions, } from "./skills/obsidian/index.js";
 export { RssConnector, type RssConnectorOptions, type RssFeedConfig, RssSkill, type RssSkillOptions, } from "./skills/rss/index.js";
 export { SlackSkill, type SlackSkillOptions, SlacrawlClient, type SlacrawlOptions, } from "./skills/slack/index.js";
-export { SpotlightConnector, type SpotlightConnectorOptions, SpotlightSkill, type SpotlightSkillOptions, } from "./skills/spotlight/index.js";
+export { SpotlightConnector, type SpotlightConnectorFailure, type SpotlightConnectorOptions, type SpotlightConnectorResult, 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 { DatasourceDiagnostic, DatasourceDiagnosticCode, DatasourceIndexFail, DatasourceIndexOk, DatasourceIndexOptions, DatasourceIndexResult, DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription, } from "./types.js";

package/dist/datasource/skills/hister/client.d.ts

@@ -69,11 +69,11 @@ export declare class HisterClient {
  * Wrap a free-text question as a Hister query confined to web pages.
  *
  * Hister ANDs bare terms, so a natural-language question would match almost nothing. Plain words become one
- * alternation group `(a|b|c)`. That pipe is Hister's only OR: the word `OR` is not an operator there, it is searched
- * as the literal English word, which matches most English pages. Hister's own syntax (quoted phrases,
- * `field:value`, wildcards, negation) passes through untouched, and a query using any of it is sent with its plain
- * words ANDed, exactly as written. A `sort:` directive is hoisted out of the group because Hister only honours it at
- * the top level.
+ * alternation group `(a|b|c)`, while uppercase `AND`/`OR`/`NOT` tokens in natural-language questions are stripped by
+ * {@link normalizeTerm} so Hister 0.21+'s boolean operator parser never rejects casual English phrasing. Hister's own
+ * syntax (quoted phrases, `field:value`, wildcards, negation) passes through untouched, and a query using any of it is
+ * sent with its plain words ANDed, exactly as written. A `sort:` directive is hoisted out of the group because Hister
+ * only honours it at the top level.
  */
 export declare function buildWebQuery(question: string, domain?: string): string | undefined;
 /** Hister snippets carry `<mark>` highlights and HTML entities; the model reads plain text. */

package/dist/datasource/skills/hister/setup.d.ts

@@ -41,6 +41,11 @@ export interface HisterServiceDeps {
         readonly semanticEnabled?: boolean;
         readonly reason?: string;
     }>;
+    /** Reload a running Hister server's config (`hister reload`, v0.21.0+). Preferred over restarting the service. */
+    readonly reload?: (baseUrl: string) => Promise<{
+        readonly ok: boolean;
+        readonly reason?: string;
+    }>;
     /** Restart the Hister service. Omitted means the operator must do it. */
     readonly restart?: () => Promise<{
         readonly ok: boolean;

package/dist/datasource/skills/mailcrawl/types.d.ts

@@ -13,7 +13,21 @@ export interface MailcrawlOptions {
     readonly backend?: string;
     readonly source?: string;
     readonly fixture?: string;
+    /** `source: "files"` (mailcrawl 0.3.0+): `.eml` files, `.mbox`/`.mbx` archives, Apple Mail bundles, or directories. */
+    readonly paths?: readonly string[];
     readonly himalayaConfig?: string;
+    /** Envelopes fetched per IMAP window (`--page-size`). */
+    readonly pageSize?: number;
+    /** Simultaneous message reads during Himalaya sync (`--concurrency`, mailcrawl 0.3.0+). */
+    readonly concurrency?: number;
+    /** Per-message read deadline in milliseconds (`--read-timeout`, mailcrawl 0.3.0+). */
+    readonly readTimeoutMs?: number;
+    /** Categories re-included over mailcrawl's default exclusions (`--include-category`, mailcrawl 0.3.0+). */
+    readonly includeCategories?: readonly string[];
+    /** Categories excluded from sync (`--exclude-category`, mailcrawl 0.3.0+). */
+    readonly excludeCategories?: readonly string[];
+    /** Force vector store rebuild on `index` (`--rebuild`, mailcrawl 0.3.0+). */
+    readonly rebuildIndex?: boolean;
     /**
      * Applies to every operation. `sync`/`index` additionally honor
      * `indexTimeoutMs`, because a 0.2.0 native index run is not interactive.
@@ -45,7 +59,11 @@ export interface MailcrawlSyncInfo {
     readonly deleted?: number;
     readonly unchanged?: number;
     readonly chunksAdded?: number;
+    readonly excluded?: number;
+    readonly files?: number;
+    readonly filesRead?: number;
     readonly archiveRevision?: string;
+    readonly account?: string;
     readonly messages: number;
 }
 export interface MailcrawlIndexInfo {

package/dist/datasource/skills/spotlight/connector.d.ts

@@ -1,23 +1,10 @@
-/**
- * macOS Spotlight connector (issue #1350).
- *
- * Runs the built-in `mdfind` CLI for trusted, server-configured Spotlight
- * queries and hydrates text content for chunking. No external installs —
- * Spotlight ships with macOS. **macOS only**: on any other platform the
- * connector reports `unavailable` before spawning anything.
- *
- * Full Disk Access: Spotlight returns hits for protected locations (Mail,
- * Messages, Safari data, parts of ~/Library) but reading those files fails
- * with EPERM/EACCES unless the process running AutoRAG (the terminal app or
- * host binary) has Full Disk Access under System Settings -> Privacy &
- * Security. When every content read is denied this maps to the `permission`
- * failure reason with opaque FDA guidance; partial denials surface as
- * count-only warnings. Full absolute paths are exposed in document metadata
- * (`path`) so results stay traceable back to the file on disk — privacy is
- * the operator's responsibility (run AutoRAG with a local LLM if paths must
- * not leave the machine).
- */
-import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+import type { ConnectorFetchFail, ConnectorFetchOk } from "../../connector.js";
+export interface SpotlightConnectorFailure extends ConnectorFetchFail {
+    readonly stderr?: string;
+    readonly stdout?: string;
+    readonly code?: number | null;
+}
+export type SpotlightConnectorResult = ConnectorFetchOk | SpotlightConnectorFailure;
 export interface ProcessRunResult {
     readonly ok: boolean;
     readonly stdout: string;
@@ -30,13 +17,13 @@ export interface ProcessRunResult {
 export type ProcessRunner = (command: string, args: readonly string[], timeoutMs: number) => Promise<ProcessRunResult>;
 export type FileReader = (path: string) => Promise<string>;
 export interface SpotlightConnectorOptions {
-    /** Trusted Spotlight query strings passed to `mdfind`. Required. */
+    /** Trusted Spotlight filters AND-ed with each user query. Required. */
     readonly queries?: readonly string[];
     /** Trusted directory restricting every query (`mdfind -onlyin`). */
     readonly onlyIn?: string;
     /** Hits kept per query after dedupe. Default 100. */
     readonly maxResultsPerQuery?: number;
-    /** Total documents hydrated per fetch. Default 300. */
+    /** Maximum documents hydrated by one live search. Default 300. */
     readonly maxDocuments?: number;
     /** Characters kept per document body. Default 100000. */
     readonly maxContentChars?: number;
@@ -51,11 +38,16 @@ export interface SpotlightConnectorOptions {
     /** Injectable file reader; defaults to utf8 `fs.readFile`. */
     readonly readFile?: FileReader;
 }
-export declare class SpotlightConnector implements DatasourceConnector {
+/** Executes live Spotlight queries. macOS owns indexing; no local snapshot is collected. */
+export declare class SpotlightConnector {
     private readonly options;
     private readonly run;
     private readonly readFile;
     private readonly platform;
     constructor(options?: SpotlightConnectorOptions);
-    fetch(): Promise<ConnectorFetchResult>;
+    /** Refresh-time health check only: never runs `mdfind` or hydrates files. */
+    probe(): Promise<SpotlightConnectorResult>;
+    /** Search the current macOS Spotlight index and hydrate only the requested hits. */
+    search(query: string, limit?: number, acceptDocument?: (docId: string) => boolean): Promise<SpotlightConnectorResult>;
+    private readinessFailure;
 }

package/dist/datasource/skills/spotlight/index.d.ts

@@ -1,2 +1,2 @@
-export { type FileReader, type ProcessRunner, type ProcessRunResult, SpotlightConnector, type SpotlightConnectorOptions, } from "./connector.js";
-export { SPOTLIGHT_SKILL_DEFINITION, SpotlightSkill, type SpotlightSkillOptions } from "./skill.js";
+export { type FileReader, type ProcessRunner, type ProcessRunResult, SpotlightConnector, type SpotlightConnectorFailure, type SpotlightConnectorOptions, type SpotlightConnectorResult, } from "./connector.js";
+export { SpotlightSkill, type SpotlightSkillOptions } from "./skill.js";

package/dist/datasource/skills/spotlight/skill.d.ts

@@ -1,20 +1,33 @@
-/**
- * macOS Spotlight datasource skill (issue #1350).
- *
- * Thin composition of {@link SpotlightConnector} with the shared
- * {@link ConnectorDatasourceSkill} base. The skill is **macOS only** and
- * needs no external installs — it drives the built-in `mdfind` CLI. The
- * manifest carries operator guidance for mdfind/mdls/mdutil and the Full
- * Disk Access requirement.
- */
-import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
 import { SpotlightConnector, type SpotlightConnectorOptions } from "./connector.js";
-export declare const SPOTLIGHT_SKILL_DEFINITION: ConnectorSkillDefinition;
-export interface SpotlightSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+export interface SpotlightSkillOptions {
+    /** Config alias used as the independent datasource/skill identity. */
+    readonly skillName?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly tags?: readonly string[];
     /** Trusted connector configuration; a pre-built connector wins. */
     readonly connector?: SpotlightConnector;
     readonly connectorOptions?: SpotlightConnectorOptions;
 }
-export declare class SpotlightSkill extends ConnectorDatasourceSkill {
+/** Live macOS Spotlight datasource. Refresh probes readiness; retrieval runs `mdfind`. */
+export declare class SpotlightSkill implements DatasourceSkill {
+    private readonly connector;
+    private readonly skillName;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private lastIndexedAt;
+    private lastError;
     constructor(options?: SpotlightSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    search(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    private fail;
+    private note;
 }