@autorag/librarian 2.10.5 → 2.11.0

package/dist/datasource/embedding-env.d.ts

@@ -0,0 +1,29 @@
+import type { EmbedderEndpoint, ManagedEmbedder } from "../embedding/embedder.js";
+/**
+ * Pointing an external CLI that embeds for itself (mailcrawl, lazykatok) at the same backend as the rest of
+ * AutoRAG. The CLI keeps ownership of its archive and vector store; AutoRAG only tells it where the vectors
+ * come from, through the environment variables the CLI documents. A remote key travels as the value of the
+ * variable the operator's `minSync.embedder.apiKeyEnv` names, to that one child only.
+ */
+/** An endpoint whose vector length is known; the CLIs require it up front. */
+export interface ResolvedEmbeddingEndpoint extends EmbedderEndpoint {
+    readonly dimension: number;
+}
+export type EmbeddingEndpointSource = () => Promise<ResolvedEmbeddingEndpoint | undefined>;
+/**
+ * The shared embedder as an endpoint source. Probes only: it never starts a daemon. `undefined` means the
+ * embedder would run in-process, which an external CLI cannot reach.
+ */
+export declare function embeddingEndpointSource(embedder: ManagedEmbedder): EmbeddingEndpointSource;
+/**
+ * mailcrawl's `openai` and `tei` providers (0.2.2+). Identity is provider + model + dimension, so moving a
+ * server keeps its vectors, while switching backend rebuilds the index on the next `mailcrawl index`.
+ * mailcrawl accepts a non-loopback endpoint only over https with an explicit opt-in, which is set here
+ * because the operator configured that remote themselves.
+ */
+export declare function mailcrawlEmbeddingEnv(endpoint: ResolvedEmbeddingEndpoint, parentEnv?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * lazykatok's OpenAI-compatible embedder (0.3.3+). It speaks `POST /v1/embeddings` only, so a TEI endpoint
+ * cannot be offered and lazykatok keeps its own embedder, as discrawl does.
+ */
+export declare function lazykatokEmbeddingEnv(endpoint: ResolvedEmbeddingEndpoint, parentEnv?: NodeJS.ProcessEnv): Record<string, string> | undefined;

package/dist/datasource/errors.d.ts

@@ -6,7 +6,7 @@
  * pipeline reports the surface as unsearched and hands the operator the CLI's
  * own words: failure kind, exit status, and stderr verbatim.
  */
-/** The failure payload every datasource CLI client returns (lazykatok, discrawl, qmd, …). */
+/** The failure payload every datasource CLI client returns (lazykatok, discrawl, mailcrawl, …). */
 export interface DatasourceCliFailure {
     readonly reason: string;
     readonly stderr?: string;

package/dist/datasource/index.d.ts

@@ -10,13 +10,14 @@ export { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOpti
 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";
 export { GitHubConnector, type GitHubConnectorOptions, GitHubSkill, type GitHubSkillOptions, } from "./skills/github/index.js";
+export { HISTER_SKILL_TYPE, HisterClient, type HisterClientOptions, HisterSkill, type HisterSkillOptions, } from "./skills/hister/index.js";
 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, LazykatokSemanticMethod, 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, ObsidianSemanticMethod, ObsidianSkill, type ObsidianSkillClient, type ObsidianSkillOptions, QmdClient, type QmdOptions, type QmdSearchHit, type QmdSearchMode, type QmdSearchResult, } from "./skills/obsidian/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";

package/dist/datasource/sidecar/config.d.ts

@@ -12,6 +12,7 @@
  * The sidecar's own database always lives under the AutoRAG workspace, one file
  * per datasource instance, never next to (or inside) the crawler's archive.
  */
+import type { Embedder } from "../../embedding/embedder.js";
 import type { CrawlerDescriptor } from "./descriptors.js";
 import type { CrawlerSidecarOptions } from "./index.js";
 export interface ResolveSidecarInput {
@@ -22,5 +23,7 @@ export interface ResolveSidecarInput {
     readonly instanceId: string;
     /** Where the crawler keeps its archive when the user did not say. */
     readonly defaultCrawlerDb: string;
+    /** The embedder shared with the rest of AutoRAG. Without one the sidecar is lexical-only. */
+    readonly embedder?: Embedder;
 }
 export declare function resolveSidecarOptions(input: ResolveSidecarInput): CrawlerSidecarOptions | undefined;

package/dist/datasource/sidecar/index.d.ts

@@ -11,7 +11,7 @@
  * Everything crawler-specific lives in a {@link CrawlerDescriptor}; this file
  * is shared by every crawler.
  */
-import type { Embedder } from "../../embedding-runtime/gateway-embedder.js";
+import type { Embedder } from "../../embedding/embedder.js";
 import type { CrawlerDescriptor } from "./descriptors.js";
 export interface SidecarHit {
     readonly key: string;

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

@@ -13,6 +13,7 @@ export declare class DiscrawlClient {
     private readonly options;
     constructor(options?: DiscrawlOptions);
     configureEmbeddings(runtime: DiscrawlEmbeddingRuntime): Promise<DiscrawlEmbeddingConfigResult>;
+    private resolveRuntime;
     prepareEmbeddings(): Promise<boolean>;
     metadata(signal?: AbortSignal): Promise<DiscrawlMetadataResult>;
     doctor(signal?: AbortSignal): Promise<DiscrawlDoctorResult>;

package/dist/datasource/skills/discrawl/embedding.d.ts

@@ -0,0 +1,17 @@
+import type { EmbedderEndpoint } from "../../../embedding/embedder.js";
+import type { DiscrawlEmbeddingRuntime } from "./types.js";
+/**
+ * discrawl keeps `openai_compatible` embeddings off ("requires API key env ...") unless the variable its
+ * config names is non-empty, while `minsync serve` has no authentication and ignores the value. For the
+ * local daemon AutoRAG therefore names a variable of its own and supplies this fixed, non-secret placeholder
+ * to the discrawl child only. It is never a credential and never read from the operator's environment.
+ */
+export declare const LOCAL_EMBEDDING_KEY_ENV = "AUTORAG_LOCAL_EMBEDDING_KEY";
+export declare const LOCAL_EMBEDDING_KEY_PLACEHOLDER = "local";
+/**
+ * What discrawl's own `[search.embeddings]` section should say so that it embeds through the same backend
+ * as the rest of AutoRAG. discrawl speaks OpenAI `POST {base_url}/embeddings` only (its provider name is
+ * `openai_compatible`, with an underscore), so a TEI endpoint cannot be offered and discrawl keeps its own
+ * configuration. A remote key travels as the name of an environment variable, never as a value.
+ */
+export declare function discrawlEmbeddingRuntimeFor(endpoint: EmbedderEndpoint | undefined): DiscrawlEmbeddingRuntime | undefined;

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

@@ -43,7 +43,12 @@ export interface DiscrawlEmbeddingRuntime {
     readonly provider: string;
     readonly model: string;
     readonly baseUrl: string;
-    readonly dimensions: number;
+    /** Omitted when the endpoint's dimension is not known; discrawl infers it from the first response. */
+    readonly dimensions?: number;
+    /** Name of the environment variable that holds the bearer token (remote endpoints). Never the token. */
+    readonly apiKeyEnv?: string;
+    /** A non-secret placeholder for a keyless local daemon, passed to the child only. Never set for a remote endpoint. */
+    readonly apiKeyValue?: string;
     readonly identity?: string;
 }
 export interface DiscrawlEmbeddingConfigResult {
@@ -78,8 +83,11 @@ export interface DiscrawlOptions {
     readonly guildId?: string;
     /** Embedding provider understood by the native discrawl configuration. */
     readonly embeddingProvider?: string;
-    /** AutoRAG-owned runtime to write into a managed workspace config. */
-    readonly embeddingRuntime?: DiscrawlEmbeddingRuntime;
+    /**
+     * Where discrawl should embed, written into a managed workspace config. A function is evaluated on each
+     * `prepareEmbeddings`, because the endpoint of a `minsync serve` daemon exists only while it runs.
+     */
+    readonly embeddingRuntime?: DiscrawlEmbeddingRuntime | (() => Promise<DiscrawlEmbeddingRuntime | undefined>);
     /**
      * Embedding model understood by the native discrawl configuration.
      * English-only models are accepted but reported through a diagnostic.

package/dist/datasource/skills/factory.d.ts

@@ -7,8 +7,11 @@
  * configuration path. Unknown skill names and disabled entries are skipped
  * and reported so setup surfaces actionable (but path-opaque) feedback.
  */
+import type { Embedder } from "../../embedding/embedder.js";
+import type { EmbeddingEndpointSource } from "../embedding-env.js";
 import type { DatasourceSkill } from "../types.js";
 import { type DiscrawlEmbeddingRuntime } from "./discrawl/index.js";
+import { type ObsidianMinSyncOptions } from "./obsidian/index.js";
 /** One configured datasource entry (the trusted `datasources.<name>` value). */
 export interface DatasourceSkillConfig {
     readonly enabled?: boolean;
@@ -34,6 +37,19 @@ export interface BuildDatasourceSkillsResult {
     /** Names that were configured but not recognized. */
     readonly unknown: readonly string[];
 }
+/**
+ * What the shared embedding backend gives a datasource. AutoRAG-owned semantic stores (chat sidecars, the
+ * gist vector index) call the `embedder`; an external CLI that embeds for itself (discrawl) is pointed at the
+ * same backend through `discrawl`.
+ */
+export interface DatasourceEmbeddingOptions {
+    readonly embedder?: Embedder;
+    readonly discrawl?: DiscrawlEmbeddingRuntime | (() => Promise<DiscrawlEmbeddingRuntime | undefined>);
+    /** For CLIs that embed for themselves through env (mailcrawl, lazykatok): where the shared backend is. */
+    readonly cliEndpoint?: EmbeddingEndpointSource;
+    /** MinSync binary, embedder and chunking shared with the local-file index; vault indexes run on it too. */
+    readonly minSync?: ObsidianMinSyncOptions;
+}
 /** Skill names this factory can build. */
 export declare const BUILTIN_DATASOURCE_SKILL_NAMES: readonly string[];
 /**
@@ -42,4 +58,4 @@ export declare const BUILTIN_DATASOURCE_SKILL_NAMES: readonly string[];
  * collected in `unknown` (never thrown) so callers can surface setup
  * feedback without failing agent construction.
  */
-export declare function buildDatasourceSkills(config: DatasourcesConfig | undefined, workspaceRoot?: string, embeddingRuntime?: DiscrawlEmbeddingRuntime): BuildDatasourceSkillsResult;
+export declare function buildDatasourceSkills(config: DatasourcesConfig | undefined, workspaceRoot?: string, embedding?: DatasourceEmbeddingOptions): BuildDatasourceSkillsResult;

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

@@ -4,12 +4,12 @@
  * A small persisted vector sidecar (`vectors.json`) mirrors the chunk store:
  * entries are keyed by chunk id with a content hash so unchanged chunks are
  * never re-embedded, removed chunks are pruned, and an embedding-identity
- * change (provider/model/dimension) forces a full re-embed. The default
- * embedder talks to the loopback autorag-gateway (`ensureRuntime` with
- * `cachedOnly`, then `POST /v1/embeddings`); tests inject a stub. Every
- * failure degrades — indexing stays lexical-only and retrieval returns [].
+ * change (provider/model/dimension) forces a full re-embed. The embedder is
+ * the one AutoRAG shares with every consumer (MinSync's daemon or in-process
+ * engine, or the configured remote endpoint). Every failure degrades —
+ * indexing stays lexical-only and retrieval returns [].
  */
-import type { Embedder } from "../../../embedding-runtime/gateway-embedder.js";
+import type { Embedder } from "../../../embedding/embedder.js";
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
 import type { DatasourceChunkStore, StoredChunk } from "../../chunk-store.js";
 export interface GistSemanticSyncOk {

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

@@ -7,7 +7,7 @@
  * 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 { Embedder } from "../../../embedding/embedder.js";
 import type { RetrievalMethod } from "../../../retrieval/types.js";
 import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
 import type { DatasourceIndexOptions, DatasourceIndexResult } from "../../types.js";
@@ -17,9 +17,8 @@ export declare function gistDatasourceDir(workspaceRoot: string, skillName: stri
 export interface GitHubGistSemanticOptions {
     /** Set false to run lexical-only. Default true. */
     readonly enabled?: boolean;
-    /** Injected embedder (tests); defaults to the loopback gateway embedder. */
+    /** The embedder shared with the rest of AutoRAG. Without one the gist index is lexical-only. */
     readonly embedder?: Embedder;
-    readonly embedderOptions?: GatewayEmbedderOptions;
     /** Vector sidecar path override; defaults under `.autorag/datasources/…`. */
     readonly statePath?: string;
 }

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

@@ -0,0 +1,83 @@
+/**
+ * HTTP client for a running Hister server (https://github.com/asciimoo/hister, AGPL-3.0).
+ *
+ * Hister is a separate program. AutoRAG never links, embeds, copies, or modifies its code: this file speaks
+ * Hister's public `GET /search` and `GET /api/config` JSON endpoints over HTTP, exactly like Hister's own
+ * `hister search` CLI. Hister owns its index, its browser-extension capture, its credentials, and its embeddings.
+ */
+export interface HisterClientOptions {
+    /** Hister server, default `http://127.0.0.1:4433`. */
+    readonly baseUrl?: string;
+    /** Name of the environment variable holding Hister's `app.access_token`. The token itself is never configured. */
+    readonly tokenEnv?: string;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export interface HisterHit {
+    readonly url: string;
+    readonly domain: string;
+    readonly title: string;
+    /** Highlighted-mark-free snippet (or the matched semantic chunk). */
+    readonly snippet: string;
+    readonly score: number;
+    /** Epoch ms of the last visit/update. */
+    readonly updatedAt: number | undefined;
+    readonly addedAt: number | undefined;
+    readonly language: string | undefined;
+    readonly description: string | undefined;
+}
+export type HisterFailureKind = "unavailable" | "auth" | "http" | "invalid-output" | "semantic-disabled";
+export interface HisterFailure {
+    readonly ok: false;
+    readonly kind: HisterFailureKind;
+    /** Verbatim: HTTP status and body, or the connection error. */
+    readonly message: string;
+}
+export type HisterResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | HisterFailure;
+export interface HisterSearchOptions {
+    readonly topK?: number;
+    readonly signal?: AbortSignal;
+    /** Restrict to one domain (exact match, Hister `domain:`). */
+    readonly domain?: string;
+}
+export declare class HisterClient {
+    readonly baseUrl: string;
+    private readonly tokenEnv;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly env;
+    constructor(options?: HisterClientOptions);
+    /** Lexical search over web pages only. */
+    searchLexical(query: string, options?: HisterSearchOptions): Promise<HisterResult<readonly HisterHit[]>>;
+    /**
+     * Semantic search. Hister embeds the query itself through the endpoint the operator configured on the server;
+     * AutoRAG sends only the question text. `semantic_hits` carry the matched chunk and similarity.
+     */
+    searchSemantic(query: string, options?: HisterSearchOptions): Promise<HisterResult<readonly HisterHit[]>>;
+    /** Count documents matching a Hister query. */
+    count(text: string, signal?: AbortSignal): Promise<HisterResult<number>>;
+    /** Reachability and authentication probe. Returns Hister's `/api/config` body. */
+    config(signal?: AbortSignal): Promise<HisterResult<Record<string, unknown>>>;
+    private search;
+    private request;
+}
+/**
+ * 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.
+ */
+export declare function buildWebQuery(question: string, domain?: string): string | undefined;
+/** Hister snippets carry `<mark>` highlights and HTML entities; the model reads plain text. */
+export declare function plainSnippet(snippet: string): string;
+/** Stable, opaque id for one page: the same URL always maps to the same chunk id. */
+export declare function pageId(url: string): string;
+export declare function isLoopback(hostname: string): boolean;

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

@@ -0,0 +1,64 @@
+/**
+ * Sharing AutoRAG's embedding backend with Hister.
+ *
+ * Hister keeps its own vector store and embeds with whatever `semantic_search` in its config.yml names, so the
+ * only way the two can use one model is to copy the shared endpoint (the `minsync serve` daemon by default) into
+ * that block. Mismatched models are not an error anywhere: the vectors simply do not line up and results degrade
+ * silently. This module derives the block from {@link ResolvedEmbeddingEndpoint}, reads what Hister currently has,
+ * and rewrites only the six keys involved. Hister itself is never modified; its config.yml is its documented
+ * interface.
+ *
+ * `yaml` is a dev dependency of this package, so the file is edited line by line. Only the `semantic_search`
+ * block's own keys are touched and every other byte is preserved; the tests compare the result with a real YAML
+ * parser.
+ */
+import type { ResolvedEmbeddingEndpoint } from "../../embedding-env.js";
+/** The `semantic_search` keys that must agree with the shared embedding backend. */
+export interface HisterSemanticSettings {
+    readonly enable: boolean;
+    readonly embedding_endpoint: string;
+    readonly embedding_model: string;
+    readonly dimensions: number;
+    readonly query_prefix: string;
+    readonly document_prefix: string;
+}
+export type HisterSemanticKey = keyof HisterSemanticSettings;
+/**
+ * What Hister uses when its config does not say (v0.20.0 `config.go`): semantic search off, an Ollama endpoint, and
+ * a `query: ` prefix. Used only to report a missing key; the apply step always writes every key.
+ */
+export declare const HISTER_SEMANTIC_DEFAULTS: HisterSemanticSettings;
+export type DeriveResult = {
+    readonly ok: true;
+    readonly settings: HisterSemanticSettings;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The settings that make Hister embed exactly like AutoRAG does. Refuses what Hister cannot do faithfully:
+ * - a TEI endpoint (Hister only calls the OpenAI `/v1/embeddings` route);
+ * - a remote endpoint (browsing text would leave the machine, and Hister's config would have to hold the key).
+ */
+export declare function deriveHisterSemanticSettings(endpoint: ResolvedEmbeddingEndpoint): DeriveResult;
+export declare function differingSemanticKeys(current: HisterSemanticSettings, wanted: HisterSemanticSettings): readonly HisterSemanticKey[];
+export declare function reindexRequired(changed: readonly HisterSemanticKey[]): boolean;
+export type ReadResult = {
+    readonly ok: true;
+    readonly settings: HisterSemanticSettings;
+    /** Keys the file sets itself; the rest are Hister's defaults. */
+    readonly explicit: readonly HisterSemanticKey[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function readHisterSemanticSettings(text: string): ReadResult;
+export type ApplyResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Set every {@link KEYS} entry inside `semantic_search`, creating the block when it is absent. */
+export declare function applyHisterSemanticSettings(text: string, settings: HisterSemanticSettings): ApplyResult;

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

@@ -0,0 +1,2 @@
+export { buildWebQuery, HisterClient, type HisterClientOptions, type HisterFailure, type HisterFailureKind, type HisterHit, type HisterResult, type HisterSearchOptions, pageId, } from "./client.js";
+export { HISTER_SKILL_TYPE, HisterSkill, type HisterSkillOptions } from "./skill.js";

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

@@ -0,0 +1,87 @@
+/**
+ * `autorag setup` support for the Hister datasource: is Hister installed and running, and does it embed with the
+ * same model as the rest of AutoRAG?
+ *
+ * Detection never writes anything. Writing Hister's config and restarting its service only happen when the operator
+ * passes `--sync-hister`, because that file and that login item belong to Hister and its operator. Hister is never
+ * modified; this only edits its documented config.yml, keeps a backup first, and restarts the service the same way
+ * the operator would.
+ */
+import type { ManagedEmbedder } from "../../../embedding/embedder.js";
+import { type HisterSemanticKey } from "./embedding.js";
+export interface HisterSetupEmbedding {
+    /** Hister's config already matches the shared embedding backend. */
+    readonly inSync: boolean;
+    /** `semantic_search` keys that differ from the shared backend, sorted. */
+    readonly differs: readonly HisterSemanticKey[];
+    /** Hister's config file was rewritten by this run. */
+    readonly applied: boolean;
+    /** Hister must be restarted to read the new config (it was not, or could not be). */
+    readonly restartRequired?: boolean;
+    /** Existing pages must be re-embedded (`hister reindex`) and that was not done. */
+    readonly reindexRequired?: boolean;
+    readonly reason?: string;
+}
+export interface HisterSetupReport {
+    readonly datasource: string;
+    readonly installed: boolean;
+    readonly running?: boolean;
+    readonly configPath?: string;
+    readonly embedding?: HisterSetupEmbedding;
+    readonly reason?: string;
+    /** What the operator (or an agent) should run next. */
+    readonly remediation?: string;
+}
+export interface HisterServiceDeps {
+    /** Hister's config.yml path, or undefined when it cannot be determined. */
+    readonly configPath?: () => string | undefined;
+    /** `GET /api/config` against the datasource's baseUrl. */
+    readonly health?: (baseUrl: string) => Promise<{
+        readonly reachable: boolean;
+        readonly semanticEnabled?: boolean;
+        readonly reason?: string;
+    }>;
+    /** Restart the Hister service. Omitted means the operator must do it. */
+    readonly restart?: () => Promise<{
+        readonly ok: boolean;
+        readonly reason?: string;
+    }>;
+    /** `hister reindex` against the running server. Omitted means the operator must do it. */
+    readonly reindex?: (baseUrl: string) => Promise<{
+        readonly ok: boolean;
+        readonly reason?: string;
+    }>;
+    readonly now?: () => number;
+    /** Pause between polls while a restarted server comes up. Tests replace it. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** How long to wait for a restarted server before giving up on the reindex. Default 30s. */
+    readonly waitMs?: number;
+}
+interface HisterEntry {
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly semantic: boolean;
+    readonly tokenEnv?: string;
+}
+/** The first configured `hister` datasource (by template `type` or by name), with its connector options. */
+export declare function findHisterEntries(raw: Record<string, unknown>): readonly HisterEntry[];
+/** Where Hister reads its config on this platform, in the order Hister itself searches (docs/configuration). */
+export declare function defaultHisterConfigPath(env: NodeJS.ProcessEnv, exists?: (path: string) => boolean, platform?: NodeJS.Platform, home?: string): string | undefined;
+/** The real service deps. Restart is only offered where a service manager is known: Homebrew on macOS/Linux. */
+export declare function systemHisterDeps(env: NodeJS.ProcessEnv, hister: string | undefined): HisterServiceDeps;
+/**
+ * Probe Hister for every configured `hister` datasource. Writes only when `sync` is true, and then only Hister's own
+ * config.yml (after a backup), followed by the service restart and reindex the change needs.
+ */
+export declare function setupHister(options: {
+    readonly entries: readonly HisterEntry[];
+    readonly embedder: ManagedEmbedder;
+    readonly executable: (name: string) => string | undefined;
+    readonly deps: HisterServiceDeps;
+    readonly sync: boolean;
+    readonly assertLockOwned?: () => void;
+}): Promise<{
+    readonly reports: readonly HisterSetupReport[];
+    readonly changed: boolean;
+}>;
+export {};

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

@@ -0,0 +1,63 @@
+/**
+ * Browser web-history datasource backed by a running Hister server.
+ *
+ * Hister (https://github.com/asciimoo/hister, AGPL-3.0-or-later) is a separate program. It captures the pages a
+ * Chromium or Firefox browser visits (through its own extension), keeps the full text, and owns the lexical and
+ * semantic indexes, incremental updates, and credentials. AutoRAG only sends search requests to its public HTTP
+ * API and maps the answers. It does not link, embed, bundle, copy, or modify Hister, and never hides that Hister
+ * is the backend: the manifest names it, its license, and its source.
+ *
+ * Web pages only: every query is confined to `type:web`, and any document Hister reports with another type
+ * (watched local files, remote file snapshots) is dropped. Local directory indexing in Hister is never used.
+ */
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceIndexOptions, DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { HisterClient, type HisterClientOptions } from "./client.js";
+export declare const HISTER_SKILL_TYPE = "hister-web-history";
+export interface HisterSkillOptions extends HisterClientOptions {
+    readonly client?: HisterClient;
+    readonly datasourceId?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly tags?: readonly string[];
+    /**
+     * Also register Hister's semantic search. Requires `semantic_search.enable` and an embedding endpoint in the
+     * Hister server config; Hister embeds the query text through the endpoint the operator chose there.
+     */
+    readonly semantic?: boolean;
+}
+type Mode = "lexical" | "semantic";
+export declare class HisterSkill implements DatasourceSkill {
+    private readonly datasourceId;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private readonly semantic;
+    private readonly client;
+    /** A bad `baseUrl` or token setup is reported through `index()`/search, never thrown out of config loading. */
+    private readonly configError;
+    private lastIndexedAt;
+    private lastError;
+    constructor(options?: HisterSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    /**
+     * Hister indexes pages itself the moment the browser extension sends them, so there is nothing to copy.
+     * `index()` is a read-only probe: reachability, authentication, how many web pages are searchable, and whether
+     * Hister also holds non-web documents that this datasource will never return.
+     */
+    index(options?: DatasourceIndexOptions): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    search(mode: Mode, query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    /** Opaque, stable identity: `/<id>/<instance>/pages/<domain>/<hash of the URL>`. */
+    private sourceFor;
+    private toResult;
+    /** Does the scope reach this datasource at all, and can it be pushed down to Hister as `domain:`? */
+    private scopeTarget;
+    private failFrom;
+    private fail;
+    private note;
+}
+export {};

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

@@ -1,4 +1,5 @@
 import type { RetrievalOptions } from "../../../retrieval/types.js";
+import type { EmbeddingEndpointSource } from "../../embedding-env.js";
 /**
  * Search modes accepted by the external `lazykatok search` subcommand.
  *
@@ -43,6 +44,13 @@ export interface LazykatokOptions {
     readonly source?: string;
     /** Environment overrides merged on top of `process.env` for the child. */
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Where lazykatok gets its vectors. When set, `index` and the semantic and hybrid searches run lazykatok's
+     * OpenAI-compatible embedder against the endpoint it returns (a `minsync serve` daemon or the operator's
+     * remote), and lazykatok's own fastembed model is never used; with no endpoint, or a TEI one, those commands
+     * fail instead. Without it lazykatok keeps whatever embedder its own environment selects.
+     */
+    readonly embeddingEndpoint?: EmbeddingEndpointSource;
 }
 export declare const DEFAULT_LAZYKATOK_BINARY = "lazykatok";
 export declare const DEFAULT_LAZYKATOK_TIMEOUT_MS = 60000;
@@ -65,7 +73,7 @@ export declare const DEFAULT_LAZYKATOK_OPTIONS: {
  * every method returns a discriminated union with `ok: false` and one of these
  * reasons.
  */
-export type LazykatokFailureReason = "binary-missing" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape";
+export type LazykatokFailureReason = "binary-missing" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape" | "embedding-unavailable";
 /** Common failure payload shared by every method result union. */
 export interface LazykatokFailure {
     readonly ok: false;

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

@@ -1,3 +1,4 @@
+import type { EmbeddingEndpointSource } from "../../embedding-env.js";
 export type MailcrawlSearchMode = "keyword" | "bm25" | "semantic" | "hybrid";
 export interface MailcrawlSearchOptions {
     readonly topK?: number;
@@ -22,8 +23,15 @@ export interface MailcrawlOptions {
     readonly indexTimeoutMs?: number;
     readonly maxBufferBytes?: number;
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Where mailcrawl gets its vectors. When set, `index` and the semantic and hybrid searches run mailcrawl's
+     * `openai`/`tei` provider against the endpoint it returns (a `minsync serve` daemon or the operator's remote),
+     * and mailcrawl's own native model is never used; with no endpoint those commands fail instead. Without it
+     * mailcrawl keeps whatever embedder its own environment selects.
+     */
+    readonly embeddingEndpoint?: EmbeddingEndpointSource;
 }
-export type MailcrawlFailureReason = "binary-missing" | "not-configured" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-output" | "remote-embedding-rejected";
+export type MailcrawlFailureReason = "binary-missing" | "not-configured" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-output" | "remote-embedding-rejected" | "embedding-unavailable";
 export interface MailcrawlFailure {
     readonly ok: false;
     readonly reason: MailcrawlFailureReason;

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

@@ -1,6 +1,4 @@
-export { QmdClient } from "./client.js";
-export { ObsidianBm25Method, type ObsidianMethodOptions, type ObsidianSearchClient, ObsidianSemanticMethod, } from "./methods.js";
-export { obsidianDatasourceRoot, obsidianQmdCacheDir, obsidianQmdConfigDir, obsidianSourcePath, parseObsidianSourcePath, stripEdgeDashes, toQmdCollectionName, } from "./paths.js";
-export { ObsidianSkill, type ObsidianSkillClient, type ObsidianSkillOptions } from "./skill.js";
-export type { QmdEmbedResult, QmdEnsureResult, QmdFailureReason, QmdOptions, QmdSearchHit, QmdSearchMode, QmdSearchOptions, QmdSearchResult, QmdUpdateResult, } from "./types.js";
-export { DEFAULT_QMD_BINARY, DEFAULT_QMD_MAX_BUFFER_BYTES, DEFAULT_QMD_TIMEOUT_MS, } from "./types.js";
+export { ObsidianBm25Method, type ObsidianMethodOptions, ObsidianSemanticMethod } from "./methods.js";
+export { encodeSourceSegment, obsidianDatasourceDir, obsidianInstanceSource, obsidianMinSyncWorkspace, obsidianNoteSource, } from "./paths.js";
+export { ObsidianSkill, type ObsidianSkillOptions } from "./skill.js";
+export type { ObsidianMinSyncOptions, ObsidianSearchMode } from "./vault-index.js";

package/dist/datasource/skills/obsidian/methods.d.ts

@@ -1,26 +1,22 @@
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
-import type { QmdSearchMode, QmdSearchOptions, QmdSearchResult } from "./types.js";
-export interface ObsidianSearchClient {
-    search(mode: QmdSearchMode, query: string, options?: QmdSearchOptions): Promise<QmdSearchResult>;
-}
+import type { ObsidianSearchMode, ObsidianVaultIndex } from "./vault-index.js";
 export interface ObsidianMethodOptions {
-    readonly client: ObsidianSearchClient;
-    readonly instanceId: string;
-    readonly tags?: readonly string[];
+    readonly index: ObsidianVaultIndex;
+    readonly tags: readonly string[];
 }
-export declare class ObsidianBm25Method implements RetrievalMethod {
-    private readonly client;
-    private readonly instanceId;
+/** One MinSync query mode over one vault. A failure reaches the pipeline verbatim and is reported as unsearched. */
+declare class ObsidianMinSyncMethod implements RetrievalMethod {
+    private readonly index;
     private readonly tags;
-    constructor(options: ObsidianMethodOptions);
+    private readonly mode;
+    constructor(mode: ObsidianSearchMode, options: ObsidianMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
-export declare class ObsidianSemanticMethod implements RetrievalMethod {
-    private readonly client;
-    private readonly instanceId;
-    private readonly tags;
+export declare class ObsidianBm25Method extends ObsidianMinSyncMethod {
+    constructor(options: ObsidianMethodOptions);
+}
+export declare class ObsidianSemanticMethod extends ObsidianMinSyncMethod {
     constructor(options: ObsidianMethodOptions);
-    describe(): RetrievalMethodDescriptor;
-    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
+export {};