@autorag/librarian 2.3.0 → 2.4.1

package/dist/cli/tui-commands.d.ts

@@ -0,0 +1,16 @@
+import type { SlashCommand } from "@earendil-works/pi-tui";
+import type { TuiSessionStore } from "./tui-session-store.js";
+export type ParsedSlashCommand = {
+    kind: "incomplete";
+} | {
+    kind: "quit";
+} | {
+    kind: "resume";
+    sessionId: string | undefined;
+} | {
+    kind: "unknown";
+    name: string;
+};
+export declare function parseSlashCommand(input: string): ParsedSlashCommand | undefined;
+export declare function createTuiSlashCommands(store: TuiSessionStore): SlashCommand[];
+export declare function renderSlashHelp(): string;

package/dist/cli/tui-session-store.d.ts

@@ -0,0 +1,16 @@
+export interface TuiSessionRecord {
+    readonly id: string;
+    readonly query: string;
+    readonly answer: string;
+    readonly trace: string;
+    readonly updatedAt: number;
+}
+export interface TuiSessionStore {
+    list(): readonly TuiSessionRecord[];
+    get(id: string): TuiSessionRecord | undefined;
+    save(session: TuiSessionRecord): void;
+}
+export declare function createFileTuiSessionStore(path: string): TuiSessionStore;
+export declare function createMergedTuiSessionStore(...stores: readonly TuiSessionStore[]): TuiSessionStore;
+export declare function renderTuiSessionList(sessions: readonly TuiSessionRecord[]): string;
+export declare function renderRestoredTuiSession(session: TuiSessionRecord): string;

package/dist/datasource/access-context.d.ts

@@ -2,8 +2,8 @@
  * Trusted, server-bound access context for the datasource layer.
  *
  * Constructed from server-supplied allow-tags and allow-scopes ONLY — never
- * from model or tool arguments. Enforces default-deny semantics and uses
- * explicit boolean `false` for every deny decision (never `undefined`).
+ * from model or tool arguments. Tags authorize datasource skills; scopes are
+ * applied only to skills that advertise the `scoped` capability.
  */
 import type { DatasourceAccessible } from "./types.js";
 export interface DatasourceAccessContextOptions {
@@ -35,15 +35,9 @@ export declare class DatasourceAccessContext {
      */
     isAccessible(descriptor: DatasourceAccessible): boolean;
     /**
-     * Build a predicate that filters source paths by trusted allow-scopes,
-     * intersected with an optional user-supplied scope (the model/tool view).
-     *
-     * The predicate always returns an explicit boolean. On default-deny it
-     * returns `() => false`. Sources containing a `#` fragment are denied
-     * (datasource sources are slash-hierarchical only).
-     *
-     * @param userScope Optional user/model-requested scope; when provided a
-     *   source must match BOTH a trusted allow-scope AND the user scope.
+     * Scope-capable datasource results are filtered by trusted and user scopes.
+     * Datasources without the `scoped` capability bypass this predicate and
+     * are authorized only at the skill/tag level.
      */
-    allowedSourcesPredicate(userScope?: string): (source: string) => boolean;
+    allowedSourcesPredicate(_userScope?: string): (source: string) => boolean;
 }

package/dist/datasource/crawler-types.d.ts

@@ -42,6 +42,8 @@ export interface CrawlerCliOptions {
     readonly timeoutMs?: number;
     readonly maxBufferBytes?: number;
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Working directory for the native CLI process, when explicitly needed. */
+    readonly workspacePath?: string;
 }
 export interface CrawlerProfile {
     readonly binaryName: string;

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

@@ -0,0 +1,17 @@
+import type { RetrievalMethod } from "../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "./types.js";
+/**
+ * Adds operator-authored context to a configured datasource without changing
+ * its backend, access identity, or retrieval methods.
+ */
+export declare class DescribedDatasourceSkill implements DatasourceSkill {
+    private readonly skill;
+    private readonly description;
+    constructor(skill: DatasourceSkill, description: string);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+}

package/dist/datasource/index.d.ts

@@ -8,15 +8,15 @@ 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 { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOptions, } from "./skills/cloud-drive/index.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, DEFAULT_DISCRAWL_SOURCE, DiscrawlClient, type DiscrawlFailureReason, DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, DiscrawlSemanticMethod, DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions, type DiscrawlSourceKind, 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 { GDriveConnector, type GDriveConnectorOptions, GDriveSkill, type GDriveSkillOptions, } from "./skills/gdrive/index.js";
 export { GitHubConnector, type GitHubConnectorOptions, GitHubSkill, type GitHubSkillOptions, } from "./skills/github/index.js";
 export { GmailConnector, type GmailConnectorOptions, GmailSkill, type GmailSkillOptions, } from "./skills/gmail/index.js";
 export type { KatokFailureReason, KatokHit, KatokOptions, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSkillClient, KatokSkillOptions, } from "./skills/katok/index.js";
-export { KatokBm25Method, KatokClient, KatokSemanticMethod, KatokSkill } from "./skills/katok/index.js";
+export { KatokBm25Method, KatokClient, KatokSemanticMethod, KatokSkill, } from "./skills/katok/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 { RssConnector, type RssConnectorOptions, type RssFeedConfig, RssSkill, type RssSkillOptions, } from "./skills/rss/index.js";

package/dist/datasource/result-filter.d.ts

@@ -6,7 +6,8 @@
  * takes the per-method result map and the {@link RetrievalMethod}s that
  * produced it, then for every datasource-backed method either drops all of
  * its results (when the trusted access context denies the descriptor) or
- * keeps only the sources the context allows for the current user scope.
+ * keeps only the sources the context allows for the current user scope when
+ * the method advertises the `scoped` capability.
  *
  * Non-datasource methods (those whose descriptor has no `datasourceId`) pass
  * through completely untouched — they are gated by their own retrieval

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

@@ -0,0 +1,9 @@
+import type { ClawGalleryIndexResult, ClawGalleryOptions, ClawGallerySearchMode, ClawGallerySearchOptions, ClawGallerySearchResult, ClawGalleryVdrResult } from "./types.js";
+export declare class ClawGalleryClient {
+    private readonly options;
+    constructor(options?: ClawGalleryOptions);
+    bootstrap(signal?: AbortSignal): Promise<ClawGalleryIndexResult>;
+    syncVisual(signal?: AbortSignal): Promise<ClawGalleryVdrResult>;
+    search(mode: ClawGallerySearchMode, query: string, options?: ClawGallerySearchOptions): Promise<ClawGallerySearchResult>;
+    private run;
+}

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

@@ -0,0 +1,5 @@
+export { ClawGalleryClient } from "./client.js";
+export { ClawGalleryMethod, type ClawGalleryMethodOptions, type ClawGallerySearchClient } from "./methods.js";
+export { CLAWGALLERY_DATASOURCE_ID, CLAWGALLERY_SOURCE_KIND, clawGallerySourcePath, parseClawGallerySourcePath, } from "./paths.js";
+export { ClawGallerySkill, type ClawGallerySkillClient, type ClawGallerySkillOptions } from "./skill.js";
+export type { ClawGalleryFailure, ClawGalleryFailureReason, ClawGalleryHit, ClawGalleryIndexInfo, ClawGalleryIndexResult, ClawGalleryOptions, ClawGallerySearchMode, ClawGallerySearchOptions, ClawGallerySearchResult, ClawGalleryVdrBackend, ClawGalleryVdrInfo, ClawGalleryVdrResult, } from "./types.js";

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

@@ -0,0 +1,19 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { ClawGallerySearchMode, ClawGallerySearchOptions, ClawGallerySearchResult } from "./types.js";
+export interface ClawGallerySearchClient {
+    search(mode: ClawGallerySearchMode, query: string, options?: ClawGallerySearchOptions): Promise<ClawGallerySearchResult>;
+}
+export interface ClawGalleryMethodOptions {
+    readonly client: ClawGallerySearchClient;
+    readonly instanceId: string;
+    readonly tags?: readonly string[];
+}
+export declare class ClawGalleryMethod implements RetrievalMethod {
+    private readonly mode;
+    private readonly client;
+    private readonly instanceId;
+    private readonly tags;
+    constructor(mode: ClawGallerySearchMode, client: ClawGallerySearchClient, instanceId: string, tags: readonly string[]);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}

package/dist/datasource/skills/clawgallery/paths.d.ts

@@ -0,0 +1,7 @@
+export declare const CLAWGALLERY_DATASOURCE_ID = "clawgallery";
+export declare const CLAWGALLERY_SOURCE_KIND = "screenshots";
+export declare function clawGallerySourcePath(instanceId: string, imageId: string): string;
+export declare function parseClawGallerySourcePath(source: string): {
+    readonly instanceId: string;
+    readonly imageId: string;
+} | undefined;

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

@@ -0,0 +1,35 @@
+import type { RetrievalMethod } from "../../../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { type ClawGallerySearchClient } from "./methods.js";
+import type { ClawGalleryIndexResult, ClawGalleryOptions, ClawGallerySearchMode, ClawGalleryVdrResult } from "./types.js";
+export interface ClawGallerySkillClient extends ClawGallerySearchClient {
+    bootstrap(): Promise<ClawGalleryIndexResult>;
+    syncVisual(): Promise<ClawGalleryVdrResult>;
+}
+export interface ClawGallerySkillOptions {
+    readonly client: ClawGallerySkillClient;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly pollingIntervalMs?: number;
+    readonly tags?: readonly string[];
+    readonly defaultMode?: ClawGallerySearchMode;
+    readonly syncVisual?: boolean;
+    readonly vdrBackend?: ClawGalleryOptions["vdrBackend"];
+}
+export declare class ClawGallerySkill implements DatasourceSkill {
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private readonly mode;
+    private readonly interval;
+    private readonly sync;
+    private lastIndexedAt;
+    private readonly options;
+    constructor(options: ClawGallerySkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+}

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

@@ -0,0 +1,58 @@
+import type { RetrievalOptions } from "../../../retrieval/types.js";
+export type ClawGallerySearchMode = "keyword" | "lexical" | "embedding" | "hybrid";
+export type ClawGalleryVdrBackend = "mlx" | "jina-mlx" | "vsplade";
+export interface ClawGalleryOptions {
+    readonly binaryPath?: string;
+    readonly timeoutMs?: number;
+    readonly maxBufferBytes?: number;
+    readonly configDir?: string;
+    readonly path?: string;
+    readonly syncVisual?: boolean;
+    readonly vdrBackend?: ClawGalleryVdrBackend;
+    readonly defaultMode?: ClawGallerySearchMode;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export type ClawGalleryFailureReason = "binary-missing" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape";
+export interface ClawGalleryFailure {
+    readonly ok: false;
+    readonly reason: ClawGalleryFailureReason;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+}
+export interface ClawGalleryOk<T> {
+    readonly ok: true;
+    readonly data: T;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export interface ClawGalleryHit {
+    readonly imageId: string;
+    readonly content: string;
+    readonly score: number;
+    readonly path?: string;
+    readonly title?: string;
+    readonly caption?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ClawGalleryIndexInfo {
+    readonly indexed: number;
+    readonly skipped: number;
+    readonly pruned: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ClawGalleryVdrInfo {
+    readonly processed: number;
+    readonly skipped: number;
+    readonly failed: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export type ClawGalleryIndexResult = ClawGalleryOk<ClawGalleryIndexInfo> | ClawGalleryFailure;
+export type ClawGalleryVdrResult = ClawGalleryOk<ClawGalleryVdrInfo> | ClawGalleryFailure;
+export type ClawGallerySearchResult = (ClawGalleryOk<{
+    readonly hits: readonly ClawGalleryHit[];
+}> & {
+    readonly hits: readonly ClawGalleryHit[];
+}) | ClawGalleryFailure;
+export type ClawGallerySearchOptions = RetrievalOptions;

package/dist/datasource/skills/cloud-drive/index.d.ts

@@ -1 +1,2 @@
+export { RcloneConnector, type RcloneConnectorOptions, type RcloneRunner, type RcloneRunResult, } from "./rclone-connector.js";
 export { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOptions, } from "./skill.js";

package/dist/datasource/skills/{gdrive → cloud-drive}/rclone-connector.d.ts

@@ -6,6 +6,7 @@
  * manifest is published only after every changed file is available, so search
  * can continue using the previous completed snapshot after an interrupted run.
  */
+import type { DefaultParserRegistryOptions } from "../../../parser/defaults.js";
 import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
 export interface RcloneRunResult {
     readonly ok: boolean;
@@ -32,6 +33,9 @@ export interface RcloneConnectorOptions {
     readonly dryRun?: boolean;
     readonly timeoutMs?: number;
     readonly runner?: RcloneRunner;
+    /** Explicit operator-owned rclone.conf path, passed read-only. */
+    readonly configPath?: string;
+    readonly parserOptions?: DefaultParserRegistryOptions;
 }
 export declare class RcloneConnector implements DatasourceConnector {
     private readonly options;

package/dist/datasource/skills/cloud-drive/skill.d.ts

@@ -1,6 +1,6 @@
 import type { DatasourceConnector } from "../../connector.js";
 import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
-import { type RcloneConnectorOptions } from "../gdrive/rclone-connector.js";
+import { type RcloneConnectorOptions } from "./rclone-connector.js";
 export declare const CLOUD_DRIVE_SKILL_DEFINITION: ConnectorSkillDefinition;
 export interface CloudDriveSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
     /** Unique model-visible datasource name for this configured connection. */

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

@@ -64,21 +64,17 @@ export interface DiscrawlOptions {
      * AutoRAG never rewrites an explicit config.
      */
     readonly configPath?: string;
-    /** Workspace root used to compute the default discrawl workspace path. */
+    /** Retained for source compatibility; native discrawl defaults are used. */
     readonly root?: string;
     /** Explicit workspace directory overriding the computed default. */
     readonly workspacePath?: string;
     /** Restrict search and sync to one guild id. */
     readonly guildId?: string;
-    /**
-     * Embedding provider written to AutoRAG's workspace-local discrawl config.
-     * Defaults to `ollama`; explicit operator-owned config files are untouched.
-     */
+    /** Embedding provider understood by the native discrawl configuration. */
     readonly embeddingProvider?: string;
     /**
-     * Embedding model discrawl should use for semantic/hybrid search. Defaults
-     * to {@link DEFAULT_DISCRAWL_EMBEDDING_MODEL}. English-only models are
-     * accepted but reported through a diagnostic.
+     * Embedding model understood by the native discrawl configuration.
+     * English-only models are accepted but reported through a diagnostic.
      */
     readonly embeddingModel?: string;
     /**

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

@@ -11,6 +11,8 @@ import type { DatasourceSkill } from "../types.js";
 /** One configured datasource entry (the trusted `datasources.<name>` value). */
 export interface DatasourceSkillConfig {
     readonly enabled?: boolean;
+    /** Operator-authored context shown to the agent for this connection. */
+    readonly description?: string;
     /** Built-in datasource template used when the config key is a connection alias. */
     readonly type?: string;
     readonly instanceId?: string;

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

@@ -1,3 +1,2 @@
 export { GmailConnector, type GmailConnectorOptions } from "./connector.js";
-export { HimalayaConnector, type HimalayaConnectorOptions, type HimalayaRunner, type HimalayaRunResult, } from "./himalaya-connector.js";
 export { GMAIL_SKILL_DEFINITION, GmailSkill, type GmailSkillOptions } from "./skill.js";

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

@@ -14,7 +14,7 @@ export declare const GMAIL_SKILL_DEFINITION: ConnectorSkillDefinition;
 export interface GmailSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
     /**
      * Trusted pre-built connector; wins over {@link connectorOptions}. Accepts
-     * any mail-backed connector (Gmail REST or the himalaya CLI bridge).
+     * any compatible mail-backed connector.
      */
     readonly connector?: DatasourceConnector;
     readonly connectorOptions?: GmailConnectorOptions;

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

@@ -14,8 +14,9 @@ export interface KatokMethodOptions {
 }
 /**
  * Lexical (BM25) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in keyword mode. All client failures collapse to an empty
- * result set; retrieval never throws.
+ * `katok` CLI in keyword mode. Katok does not expose source scopes; access is
+ * controlled at the datasource/tag level. All client failures collapse to an
+ * empty result set; retrieval never throws.
  */
 export declare class KatokBm25Method implements RetrievalMethod {
     private readonly client;
@@ -27,8 +28,9 @@ export declare class KatokBm25Method implements RetrievalMethod {
 }
 /**
  * Semantic (vector) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in semantic mode. All client failures collapse to an empty
- * result set; retrieval never throws.
+ * `katok` CLI in semantic mode. Katok does not expose source scopes; access is
+ * controlled at the datasource/tag level. All client failures collapse to an
+ * empty result set; retrieval never throws.
  */
 export declare class KatokSemanticMethod implements RetrievalMethod {
     private readonly client;

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

@@ -7,14 +7,6 @@ import type { RetrievalOptions } from "../../../retrieval/types.js";
  * - `hybrid`   — fused semantic + keyword scores.
  */
 export type KatokSearchMode = "semantic" | "keyword" | "hybrid";
-/**
- * Where the `katok` CLI reads KakaoTalk data from.
- *
- * - `macos`   — live KakaoTalk install on macOS (the CLI owns DB access; this
- *               client never touches the DB directly).
- * - `fixture` — a frozen fixture directory (used for tests / dry runs).
- */
-export type KatokSourceKind = "macos" | "fixture";
 /**
  * Configuration for {@link KatokClient}. All fields optional; sensible defaults
  * mirror the jikji client. The client spawns the `katok` binary as a child
@@ -23,34 +15,24 @@ export type KatokSourceKind = "macos" | "fixture";
 export interface KatokOptions {
     /** Explicit path to the `katok` binary. Defaults to a bare `katok` PATH lookup. */
     readonly binaryPath?: string;
-    /** Spawn timeout in milliseconds. Default 10_000. */
+    /** Spawn timeout in milliseconds. Default 60_000 (sync/index over large archives can be slow). */
     readonly timeoutMs?: number;
     /** Max stdout/stderr bytes retained. Default 1_048_576 (1 MiB). */
     readonly maxBufferBytes?: number;
-    /** Data source for the CLI. Default `macos`. */
-    readonly source?: KatokSourceKind;
-    /** Path to a fixture directory; required when `source === "fixture"`. */
-    readonly fixturePath?: string;
-    /**
-     * Explicit katok workspace directory (the `.autorag/datasources/katok`
-     * root). When omitted, computed from {@link KatokOptions.root} (or
-     * `process.cwd()`) via the paths helper.
-     */
+    /** Explicit native katok data directory, passed as `--data-dir`. */
     readonly workspacePath?: string;
-    /** Workspace root used to compute the default katok workspace path. */
-    readonly root?: string;
+    /** Explicit operator-owned configuration/workspace transport. */
+    readonly configPath?: string;
     /** Environment overrides merged on top of `process.env` for the child. */
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 export declare const DEFAULT_KATOK_BINARY = "katok";
-export declare const DEFAULT_KATOK_TIMEOUT_MS = 10000;
+export declare const DEFAULT_KATOK_TIMEOUT_MS = 60000;
 export declare const DEFAULT_KATOK_MAX_BUFFER_BYTES = 1048576;
-export declare const DEFAULT_KATOK_SOURCE: KatokSourceKind;
 export declare const DEFAULT_KATOK_OPTIONS: {
     readonly binaryPath: "katok";
-    readonly timeoutMs: 10000;
+    readonly timeoutMs: 60000;
     readonly maxBufferBytes: 1048576;
-    readonly source: "macos";
 };
 /**
  * Reasons a katok CLI invocation can fail. The client never throws for these —
@@ -140,7 +122,7 @@ export type KatokParentResult = KatokOk<KatokChunk> | KatokFailure;
 /**
  * Search-specific options. Reuses the shared {@link RetrievalOptions} so the
  * KatokSkill retrieval method can pass its options straight through. The
- * client maps `topK` and `scope` to CLI flags; other fields are accepted but
- * not currently forwarded.
+ * client maps `topK` to the native CLI limit flag; other fields are handled
+ * by the retrieval layer or are not supported by katok.
  */
 export type KatokSearchOptions = RetrievalOptions;

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

@@ -0,0 +1,15 @@
+import type { MailcrawlFailure, MailcrawlIndexInfo, MailcrawlOk, MailcrawlOptions, MailcrawlSearchMode, MailcrawlSearchOptions, MailcrawlSearchResult, MailcrawlSyncResult } from "./types.js";
+export interface MailcrawlSearchClient {
+    search(mode: MailcrawlSearchMode, query: string, options?: MailcrawlSearchOptions): Promise<MailcrawlSearchResult>;
+}
+export interface MailcrawlIndexClient extends MailcrawlSearchClient {
+    index(signal?: AbortSignal): Promise<MailcrawlOk<MailcrawlIndexInfo> | MailcrawlFailure>;
+}
+export declare class MailcrawlClient implements MailcrawlSearchClient {
+    private readonly options;
+    constructor(options?: MailcrawlOptions);
+    sync(signal?: AbortSignal): Promise<MailcrawlSyncResult>;
+    search(mode: MailcrawlSearchMode, query: string, options?: MailcrawlSearchOptions): Promise<MailcrawlSearchResult>;
+    private run;
+    index(signal?: AbortSignal): Promise<MailcrawlOk<MailcrawlIndexInfo> | MailcrawlFailure>;
+}

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

@@ -0,0 +1,2 @@
+export declare function validateMailcrawlInstanceId(instanceId: string): void;
+export declare function ensurePrivateMailcrawlDataDir(path: string): void;

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

@@ -0,0 +1,4 @@
+export { MailcrawlClient, type MailcrawlIndexClient, type MailcrawlSearchClient } from "./client.js";
+export { MAILCRAWL_MODES, MailcrawlMethod } from "./methods.js";
+export { MailcrawlSkill, type MailcrawlSkillClient, type MailcrawlSkillOptions } from "./skill.js";
+export type { MailcrawlFailure, MailcrawlFailureReason, MailcrawlIndexInfo, MailcrawlOptions, MailcrawlSearchHit, MailcrawlSearchMode, MailcrawlSearchOptions, MailcrawlSearchResult, MailcrawlSyncInfo, MailcrawlSyncResult, } from "./types.js";

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

@@ -0,0 +1,15 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { MailcrawlSearchClient } from "./client.js";
+import type { MailcrawlSearchMode } from "./types.js";
+export declare class MailcrawlMethod implements RetrievalMethod {
+    private readonly client;
+    private readonly mode;
+    private readonly instanceId;
+    private readonly tags;
+    private readonly account;
+    private readonly mailbox;
+    constructor(client: MailcrawlSearchClient, mode: MailcrawlSearchMode, instanceId: string, tags: readonly string[], account?: string, mailbox?: string);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+export declare const MAILCRAWL_MODES: readonly MailcrawlSearchMode[];

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

@@ -0,0 +1,34 @@
+import type { RetrievalMethod } from "../../../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { type MailcrawlIndexClient } from "./client.js";
+import type { MailcrawlOptions, MailcrawlSyncResult } from "./types.js";
+export interface MailcrawlSkillClient extends MailcrawlIndexClient {
+    sync(signal?: AbortSignal): Promise<MailcrawlSyncResult>;
+}
+export interface MailcrawlSkillOptions extends MailcrawlOptions {
+    readonly client?: MailcrawlSkillClient;
+    readonly datasourceId?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly pollingIntervalMs?: number;
+    readonly tags?: readonly string[];
+    readonly connectorOptions?: MailcrawlOptions;
+}
+export declare class MailcrawlSkill implements DatasourceSkill {
+    private readonly client;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly interval;
+    private readonly tags;
+    private readonly account;
+    private readonly mailbox;
+    private lastIndexedAt;
+    constructor(options?: MailcrawlSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    private fail;
+}

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

@@ -0,0 +1,71 @@
+export type MailcrawlSearchMode = "keyword" | "bm25" | "semantic" | "hybrid";
+export interface MailcrawlSearchOptions {
+    readonly topK?: number;
+    readonly signal?: AbortSignal;
+}
+export interface MailcrawlOptions {
+    readonly binaryPath?: string;
+    readonly instanceId?: string;
+    readonly dataDir?: string;
+    readonly account?: string;
+    readonly mailbox?: string;
+    readonly backend?: string;
+    readonly source?: string;
+    readonly fixture?: string;
+    readonly himalayaConfig?: string;
+    readonly timeoutMs?: number;
+    readonly maxBufferBytes?: number;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+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 interface MailcrawlFailure {
+    readonly ok: false;
+    readonly reason: MailcrawlFailureReason;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number | null;
+}
+export interface MailcrawlSyncInfo {
+    readonly added?: number;
+    readonly updated?: number;
+    readonly deleted?: number;
+    readonly unchanged?: number;
+    readonly chunksAdded?: number;
+    readonly archiveRevision?: string;
+    readonly messages: number;
+}
+export interface MailcrawlIndexInfo {
+    readonly embedded?: number;
+    readonly reused?: number;
+    readonly generation?: string;
+}
+export interface MailcrawlSearchHit {
+    readonly chunkId: string;
+    readonly messageId: string;
+    readonly threadId: string;
+    readonly accountId: string;
+    readonly mailbox: string;
+    readonly subject: string;
+    readonly from: string;
+    readonly to: readonly string[];
+    readonly date: string;
+    readonly snippet: string;
+    readonly score: number;
+    readonly mode: MailcrawlSearchMode;
+}
+export interface MailcrawlOk<T> {
+    readonly ok: true;
+    readonly data: T;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export interface MailcrawlSearchOk {
+    readonly ok: true;
+    readonly hits: readonly MailcrawlSearchHit[];
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export type MailcrawlSyncResult = MailcrawlOk<MailcrawlSyncInfo> | MailcrawlFailure;
+export type MailcrawlSearchResult = MailcrawlSearchOk | MailcrawlFailure;

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

@@ -20,6 +20,7 @@ export interface ObsidianSkillOptions {
     readonly workspaceRoot?: string;
     readonly collectionName?: string;
     readonly timeoutMs?: number;
+    readonly configPath?: string;
     readonly connectorOptions?: {
         readonly vaultPath?: string;
     };

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

@@ -27,6 +27,8 @@ export interface QmdOptions {
     readonly collectionName?: string;
     /** Environment overrides merged on top of a restricted process env. */
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Explicit operator-owned qmd config directory, never rewritten. */
+    readonly configPath?: string;
 }
 export declare const DEFAULT_QMD_BINARY = "qmd";
 export declare const DEFAULT_QMD_TIMEOUT_MS = 60000;