@autorag/librarian 2.5.2 → 2.5.3

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 (katok, discrawl, qmd, …). */
+/** The failure payload every datasource CLI client returns (lazykatok, discrawl, qmd, …). */
 export interface DatasourceCliFailure {
     readonly reason: string;
     readonly stderr?: string;

package/dist/datasource/index.d.ts

@@ -12,8 +12,9 @@ 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 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 { 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";

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

@@ -26,7 +26,7 @@ export interface DiscrawlSkillOptions {
 /**
  * Discord datasource skill backed by the external `discrawl` CLI.
  *
- * Mirrors the katok model: the CLI owns the archive, the FTS5 index, and the
+ * Mirrors the lazykatok model: the CLI owns the archive, the FTS5 index, and the
  * vector index; AutoRAG only spawns it and maps results. AutoRAG never calls
  * the Discord API itself and never reads the Discord Desktop cache directly.
  *

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

@@ -24,14 +24,14 @@ export declare const ENGLISH_ONLY_EMBEDDING_MODELS: ReadonlySet<string>;
  * Default embedding model AutoRAG configures for workspace-managed discrawl
  * configs. `embeddinggemma`
  * (Gemma 3 300M, 768 dimensions) covers 100+ languages and matches the
- * EmbeddingGemma embedder katok uses for KakaoTalk, so every CLI-backed
+ * EmbeddingGemma embedder lazykatok uses for KakaoTalk, so every CLI-backed
  * datasource shares one local embedding model (served through Ollama).
  */
 export declare const DEFAULT_DISCRAWL_EMBEDDING_MODEL = "embeddinggemma";
 export declare const DEFAULT_DISCRAWL_EMBEDDING_PROVIDER = "ollama";
 /**
  * Configuration for the discrawl client. All fields optional; defaults mirror
- * the katok client. The client spawns the `discrawl` binary as a child process
+ * the lazykatok client. The client spawns the `discrawl` binary as a child process
  * — it never opens the Discord archive database directly.
  *
  * AutoRAG drives discrawl's local archive only: `wiretap` to import the

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

@@ -0,0 +1,38 @@
+/**
+ * GitHub Gist connector (issue #1588).
+ *
+ * Indexes the authenticated account's gists (public + secret, bounded by the
+ * token's scopes) through the GitHub REST API. Incremental: the gist list
+ * endpoint returns `id` + `updated_at` cheaply, so a persisted cursor map
+ * (`state.json`) decides which gists need a full content fetch and which
+ * disappeared (reported via `deletedDocIds`). Token resolution order:
+ * explicit `token` > `tokenEnv` (default `GITHUB_TOKEN`) > `gh auth token`
+ * when the gh CLI fallback is enabled. Never throws.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface GitHubGistConnectorOptions {
+    /** GitHub REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Personal access token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the token. Default `GITHUB_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** When true (default), fall back to `gh auth token` for auth. */
+    readonly ghCliFallback?: boolean;
+    /** Injectable gh-token resolver (tests); defaults to spawning `gh auth token`. */
+    readonly ghTokenRunner?: () => Promise<string | undefined>;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    /** Persisted incremental cursor; omitted ⇒ every fetch is a full sync. */
+    readonly statePath?: string;
+    readonly maxPages?: number;
+    readonly maxGists?: number;
+}
+export declare class GitHubGistConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: GitHubGistConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+    private resolveAuth;
+    private loadState;
+    private saveState;
+}

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

@@ -0,0 +1,3 @@
+export { GitHubGistConnector, type GitHubGistConnectorOptions } from "./connector.js";
+export { createGatewayGistEmbedder, type GatewayGistEmbedderOptions, type GistEmbedder, type GistEmbeddingIdentity, 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

@@ -0,0 +1,102 @@
+/**
+ * Semantic retrieval for the github-gist datasource (issue #1588).
+ *
+ * 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 [].
+ */
+import type { ProfileId } from "../../../embedding-runtime/types.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. */
+    readonly embedded: number;
+}
+export interface GistSemanticSyncFail {
+    readonly ok: false;
+    readonly message: string;
+}
+/** Persisted per-instance vector sidecar mirroring the chunk store. */
+export declare class GistSemanticIndex {
+    private readonly statePath;
+    private identity;
+    private entries;
+    private loaded;
+    constructor(options?: {
+        readonly statePath?: string;
+    });
+    /**
+     * 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>;
+    /** Cosine-ranked chunk ids for a query vector. Never throws. */
+    searchByVector(queryVector: readonly number[], topK: number): readonly {
+        chunkId: string;
+        score: number;
+    }[];
+    private ensureLoaded;
+    private persist;
+}
+export interface GitHubGistSemanticMethodOptions {
+    readonly skillName: string;
+    readonly skillType: string;
+    readonly instanceId: string;
+    readonly tags: readonly string[];
+    readonly store: DatasourceChunkStore;
+    readonly index: GistSemanticIndex;
+    readonly embedder: GistEmbedder;
+}
+/** Cosine similarity retrieval over the gist vector sidecar. Never throws. */
+export declare class GitHubGistSemanticMethod implements RetrievalMethod {
+    private readonly options;
+    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

@@ -0,0 +1,39 @@
+/**
+ * GitHub Gist datasource skill (issue #1588).
+ *
+ * Composition: {@link GitHubGistConnector} incrementally mirrors the
+ * authenticated account's gists into the shared chunk store (lexical BM25),
+ * and a {@link GistSemanticIndex} vector sidecar adds semantic retrieval
+ * through the loopback embedding gateway. Embedding failures degrade to a
+ * `semantic-unavailable` warning — indexing and lexical retrieval continue.
+ */
+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;
+    /** Vector sidecar path override; defaults under `.autorag/datasources/…`. */
+    readonly statePath?: string;
+}
+export interface GitHubGistSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: GitHubGistConnector;
+    readonly connectorOptions?: GitHubGistConnectorOptions;
+    readonly semantic?: GitHubGistSemanticOptions;
+}
+export declare class GitHubGistSkill extends ConnectorDatasourceSkill {
+    private readonly semanticIndex;
+    private readonly semanticEmbedder;
+    private readonly semanticMethod;
+    constructor(options?: GitHubGistSkillOptions);
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+}

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

@@ -0,0 +1,23 @@
+import { CrawlerCliClient } from "../../crawler-client.js";
+import type { CrawlerSearchResult } from "../../crawler-types.js";
+export interface LarkClientOptions {
+    readonly binaryPath?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs?: number;
+    readonly chatIds?: readonly string[];
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export declare class LarkClient {
+    private readonly version;
+    private readonly auth;
+    private readonly messages;
+    private readonly docs;
+    private readonly sleep;
+    constructor(options?: LarkClientOptions);
+    probeVersion(): Promise<CrawlerSearchResult | Awaited<ReturnType<CrawlerCliClient["sync"]>>>;
+    probeAuth(): Promise<Awaited<ReturnType<CrawlerCliClient["sync"]>>>;
+    searchMessages(query: string, topK: number | undefined): Promise<CrawlerSearchResult>;
+    searchDocs(query: string, topK: number | undefined): Promise<CrawlerSearchResult>;
+    private retry;
+}
+export declare function isSafeId(value: string): boolean;

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

@@ -0,0 +1,2 @@
+export { isSafeId, LarkClient, type LarkClientOptions } from "./client.js";
+export { LarkSkill, type LarkSkillOptions } from "./skill.js";

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

@@ -0,0 +1,36 @@
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { LarkClient, type LarkClientOptions } from "./client.js";
+export interface LarkSkillOptions extends LarkClientOptions {
+    readonly client?: LarkClient;
+    readonly datasourceId?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly tags?: readonly string[];
+    readonly embedderBaseUrl?: string;
+}
+type Surface = "messages" | "docs";
+export declare class LarkSkill implements DatasourceSkill {
+    private readonly client;
+    private readonly datasourceId;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private readonly chatIds;
+    private readonly embedderBaseUrl;
+    private lastIndexedAt;
+    private lastError;
+    constructor(options?: LarkSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    search(surface: Surface, query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    methodTags(surface: Surface): readonly string[];
+    private ok;
+    private fail;
+    private note;
+}
+export {};

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

@@ -0,0 +1,28 @@
+import type { LazykatokChunkResult, LazykatokContextResult, LazykatokDoctorResult, LazykatokIndexResult, LazykatokOptions, LazykatokParentResult, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSyncResult } from "./types.js";
+/**
+ * Thin external `lazykatok` CLI wrapper. Every method spawns the `lazykatok` binary as
+ * a child process, parses JSON from stdout, and returns a discriminated ok/fail
+ * union. No method throws for expected failures (missing binary, CLI nonzero
+ * exit, timeout, oversized output, or invalid JSON). The client never opens the
+ * KakaoTalk database directly.
+ */
+export declare class LazykatokClient {
+    private readonly options;
+    constructor(options?: LazykatokOptions);
+    doctor(signal?: AbortSignal): Promise<LazykatokDoctorResult>;
+    sync(signal?: AbortSignal): Promise<LazykatokSyncResult>;
+    index(signal?: AbortSignal): Promise<LazykatokIndexResult>;
+    search(mode: LazykatokSearchMode, query: string, options?: LazykatokSearchOptions): Promise<LazykatokSearchResult>;
+    chunkGet(chunkId: string, signal?: AbortSignal): Promise<LazykatokChunkResult>;
+    context(chunkId: string, signal?: AbortSignal): Promise<LazykatokContextResult>;
+    parent(chunkId: string, signal?: AbortSignal): Promise<LazykatokParentResult>;
+    /** Single retrieval pipeline: build env, spawn, parse-free raw result. */
+    private run;
+}
+/**
+ * `sync` argv for the configured source adapter. A bare `sync --json` makes the CLI
+ * fall back to its config file, whose default adapter is `fixture` and fails with
+ * "fixture source requires a JSONL path", so the live macOS adapter is named
+ * explicitly on darwin while other platforms defer to the CLI's own config.
+ */
+export declare function syncArgs(options: LazykatokOptions, platform?: NodeJS.Platform): readonly string[];

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

@@ -0,0 +1,12 @@
+/**
+ * KakaoTalk datasource skill barrel.
+ *
+ * Re-exports the retrieval methods and skill plus the underlying client/types
+ * from sibling modules. Public source paths are path-opaque virtual paths of
+ * the form `/kakao/<instance-id>/chunks/<chunk-id>`.
+ */
+export { LazykatokClient } from "./client.js";
+export { LazykatokBm25Method, type LazykatokMethodOptions, type LazykatokSearchClient, LazykatokSemanticMethod, } from "./methods.js";
+export { LazykatokSkill, type LazykatokSkillClient, type LazykatokSkillOptions } from "./skill.js";
+export type { LazykatokChunkResult, LazykatokDoctorResult, LazykatokFailureReason, LazykatokHit, LazykatokIndexResult, LazykatokOptions, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSyncResult, } from "./types.js";
+export { DEFAULT_LAZYKATOK_OPTIONS } from "./types.js";

package/dist/datasource/skills/{katok → lazykatok}/methods.d.ts

@@ -1,42 +1,42 @@
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
-import type { KatokSearchMode, KatokSearchOptions, KatokSearchResult } from "./types.js";
+import type { LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult } from "./types.js";
 /**
  * Narrow client surface required by the KakaoTalk retrieval methods.
- * The real {@link KatokClient} satisfies this structurally; tests may stub it.
+ * The real {@link LazykatokClient} satisfies this structurally; tests may stub it.
  */
-export interface KatokSearchClient {
-    search(mode: KatokSearchMode, query: string, options?: KatokSearchOptions): Promise<KatokSearchResult>;
+export interface LazykatokSearchClient {
+    search(mode: LazykatokSearchMode, query: string, options?: LazykatokSearchOptions): Promise<LazykatokSearchResult>;
 }
-export interface KatokMethodOptions {
-    readonly client: KatokSearchClient;
+export interface LazykatokMethodOptions {
+    readonly client: LazykatokSearchClient;
     readonly instanceId: string;
     readonly tags?: readonly string[];
 }
 /**
  * Lexical (BM25) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in keyword mode. Katok does not expose source scopes; access is
+ * `lazykatok` CLI in keyword mode. Lazykatok 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 {
+export declare class LazykatokBm25Method implements RetrievalMethod {
     private readonly client;
     private readonly instanceId;
     private readonly tags;
-    constructor(options: KatokMethodOptions);
+    constructor(options: LazykatokMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
 /**
  * Semantic (vector) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in semantic mode. Katok does not expose source scopes; access is
+ * `lazykatok` CLI in semantic mode. Lazykatok 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 {
+export declare class LazykatokSemanticMethod implements RetrievalMethod {
     private readonly client;
     private readonly instanceId;
     private readonly tags;
-    constructor(options: KatokMethodOptions);
+    constructor(options: LazykatokMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }

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

@@ -0,0 +1,40 @@
+/**
+ * Path helpers for the KakaoTalk (`lazykatok`) datasource skill.
+ *
+ * All paths are workspace-relative and live under
+ * `<workspaceRoot>/.autorag/datasources/lazykatok`. The client never exposes raw
+ * filesystem paths to callers; chunk identifiers are surfaced as opaque
+ * slash-hierarchical sources of the form
+ * `/kakao/<instance-id>/chunks/<chunk-id>`.
+ */
+export declare const AUTORAG_DIRNAME = ".autorag";
+export declare const DATASOURCES_DIRNAME = "datasources";
+export declare const LAZYKATOK_DATASOURCE_DIRNAME = "lazykatok";
+/** Logical datasource kind for source identifiers. */
+export declare const LAZYKATOK_SOURCE_KIND: "kakao";
+/**
+ * Root directory for lazykatok-managed state under a workspace. This is where the
+ * external `lazykatok` CLI stores its index, chunks, and sync state.
+ */
+export declare function lazykatokDatasourceRoot(workspaceRoot: string): string;
+/** Directory holding the lazykatok chunk index. */
+export declare function lazykatokIndexPath(workspaceRoot: string): string;
+/** Directory holding materialized lazykatok chunks. */
+export declare function lazykatokChunksPath(workspaceRoot: string): string;
+/** Directory holding lazykatok sync state. */
+export declare function lazykatokSyncPath(workspaceRoot: string): string;
+/**
+ * Builds the path-opaque, slash-hierarchical source identifier for a single
+ * lazykatok chunk. Callers (the LazykatokSkill methods) use this to populate
+ * `RetrievalResult.source` so no real filesystem path ever leaks.
+ */
+export declare function lazykatokSourcePath(instanceId: string, chunkId: string): string;
+/**
+ * Parses a lazykatok source identifier back into its `{ instanceId, chunkId }`
+ * components. Returns `undefined` for malformed or non-kakao sources so that
+ * deny decisions remain explicit rather than undefined-as-deny.
+ */
+export declare function parseLazykatokSourcePath(source: string): {
+    readonly instanceId: string;
+    readonly chunkId: string;
+} | undefined;

package/dist/datasource/skills/{katok → lazykatok}/skill.d.ts

@@ -1,28 +1,28 @@
 import type { RetrievalMethod } from "../../../retrieval/types.js";
 import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
-import { type KatokSearchClient } from "./methods.js";
-import type { KatokDoctorResult, KatokIndexResult, KatokSyncResult } from "./types.js";
-export interface KatokSkillClient extends KatokSearchClient {
-    doctor(): Promise<KatokDoctorResult>;
-    sync(): Promise<KatokSyncResult>;
-    index(): Promise<KatokIndexResult>;
+import { type LazykatokSearchClient } from "./methods.js";
+import type { LazykatokDoctorResult, LazykatokIndexResult, LazykatokSyncResult } from "./types.js";
+export interface LazykatokSkillClient extends LazykatokSearchClient {
+    doctor(): Promise<LazykatokDoctorResult>;
+    sync(): Promise<LazykatokSyncResult>;
+    index(): Promise<LazykatokIndexResult>;
 }
-export interface KatokSkillOptions {
-    readonly client: KatokSkillClient;
+export interface LazykatokSkillOptions {
+    readonly client: LazykatokSkillClient;
     readonly instanceId?: string;
     readonly instances?: readonly string[];
     readonly pollingIntervalMs?: number;
     readonly tags?: readonly string[];
     readonly lastIndexedAt?: number;
 }
-export declare class KatokSkill implements DatasourceSkill {
+export declare class LazykatokSkill implements DatasourceSkill {
     private readonly client;
     private readonly instanceId;
     private readonly instances;
     private readonly pollingIntervalMs;
     private readonly tags;
     private lastIndexedAt;
-    constructor(options: KatokSkillOptions);
+    constructor(options: LazykatokSkillOptions);
     describe(): DatasourceSkillDescriptor;
     polling(): PollingMetadata;
     index(): Promise<DatasourceIndexResult>;

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

@@ -0,0 +1,134 @@
+import type { RetrievalOptions } from "../../../retrieval/types.js";
+/**
+ * Search modes accepted by the external `lazykatok search` subcommand.
+ *
+ * - `semantic` — dense vector similarity over indexed chunks.
+ * - `keyword`  — exact / tokenized keyword matching.
+ * - `hybrid`   — fused semantic + keyword scores.
+ */
+export type LazykatokSearchMode = "semantic" | "keyword" | "hybrid";
+/**
+ * Configuration for {@link LazykatokClient}. All fields optional; sensible defaults
+ * mirror the jikji client. The client spawns the `lazykatok` binary as a child
+ * process — it never opens the KakaoTalk database directly.
+ */
+export interface LazykatokOptions {
+    /** Explicit path to the `lazykatok` binary. Defaults to a bare `lazykatok` PATH lookup. */
+    readonly binaryPath?: string;
+    /** Spawn timeout in milliseconds. Default 60_000 (sync/index over large archives can be slow). */
+    readonly timeoutMs?: number;
+    /** Max stdout/stderr bytes retained. Default 16 MiB (an `index --json` report alone is multiple MB on a real archive). */
+    readonly maxBufferBytes?: number;
+    /** Explicit native lazykatok data directory, passed as `--data-dir`. */
+    readonly workspacePath?: string;
+    /** Explicit operator-owned configuration/workspace transport. */
+    readonly configPath?: string;
+    /**
+     * Source adapter passed to `sync --source`. Without it the CLI falls back to its
+     * config file, whose default adapter is `fixture` and fails without a JSONL path.
+     * AutoRAG names the live adapter (`macos`) on macOS and passes no flag elsewhere,
+     * so a non-macOS operator's own CLI config still decides; set this to use another
+     * adapter (`kakaocli`, `fixture`, …).
+     */
+    readonly source?: string;
+    /** Environment overrides merged on top of `process.env` for the child. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export declare const DEFAULT_LAZYKATOK_BINARY = "lazykatok";
+export declare const DEFAULT_LAZYKATOK_TIMEOUT_MS = 60000;
+/** The live macOS adapter `sync` names by default on darwin. */
+export declare const DEFAULT_LAZYKATOK_SOURCE = "macos";
+export declare const DEFAULT_LAZYKATOK_MAX_BUFFER_BYTES: number;
+export declare const DEFAULT_LAZYKATOK_OPTIONS: {
+    readonly binaryPath: "lazykatok";
+    readonly timeoutMs: 60000;
+    readonly maxBufferBytes: number;
+};
+/**
+ * Reasons a lazykatok CLI invocation can fail. The client never throws for these —
+ * 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";
+/** Common failure payload shared by every method result union. */
+export interface LazykatokFailure {
+    readonly ok: false;
+    readonly reason: LazykatokFailureReason;
+    /** Raw stdout captured (may be partial / empty). Never a binary path. */
+    readonly stdout: string;
+    /** Raw stderr captured (may be partial / empty). Never a binary path. */
+    readonly stderr: string;
+    /** Exit code, or `null` when the process never exited normally. */
+    readonly code: number | null;
+    readonly hits?: readonly unknown[];
+}
+/** A single indexed chat chunk returned by the lazykatok CLI. */
+export interface LazykatokChunk {
+    readonly chunkId: string;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** A scored search hit. */
+export interface LazykatokSearchHit {
+    readonly chunkId: string;
+    readonly score: number;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly source?: string;
+}
+export type LazykatokHit = LazykatokSearchHit;
+/** Result of `lazykatok doctor`. */
+export interface LazykatokDoctorInfo {
+    readonly version?: string;
+    readonly ready: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Result of `lazykatok sync`. */
+export interface LazykatokSyncInfo {
+    readonly synced: boolean;
+    readonly messageCount?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Result of `lazykatok index`. */
+export interface LazykatokIndexInfo {
+    readonly chunkCount: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Context payload: the chunks surrounding a target chunk. */
+export interface LazykatokContext {
+    readonly chunks: readonly LazykatokChunk[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Discriminated ok-success shape carrying typed `data`. */
+export interface LazykatokOk<T> {
+    readonly ok: true;
+    readonly data: T;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export interface LazykatokSearchOk {
+    readonly ok: true;
+    readonly hits: readonly LazykatokSearchHit[];
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+    readonly data: {
+        readonly hits: readonly LazykatokSearchHit[];
+    };
+}
+export type LazykatokDoctorResult = LazykatokOk<LazykatokDoctorInfo> | LazykatokFailure;
+export type LazykatokSyncResult = LazykatokOk<LazykatokSyncInfo> | LazykatokFailure;
+export type LazykatokIndexResult = LazykatokOk<LazykatokIndexInfo> | LazykatokFailure;
+export type LazykatokSearchResult = LazykatokSearchOk | LazykatokFailure;
+export type LazykatokChunkResult = LazykatokOk<LazykatokChunk> | LazykatokFailure;
+export type LazykatokContextResult = LazykatokOk<LazykatokContext> | LazykatokFailure;
+/** The real `chunk parent --json` payload is a list of parent windows. */
+export type LazykatokParentResult = LazykatokOk<readonly LazykatokChunk[]> | LazykatokFailure;
+/**
+ * Search-specific options. Reuses the shared {@link RetrievalOptions} so the
+ * LazykatokSkill retrieval method can pass its options straight through. The
+ * client maps `topK` to the native CLI limit flag; other fields are handled
+ * by the retrieval layer or are not supported by lazykatok.
+ */
+export type LazykatokSearchOptions = RetrievalOptions;

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

@@ -10,6 +10,8 @@ export declare class MailcrawlClient implements MailcrawlSearchClient {
     constructor(options?: MailcrawlOptions);
     sync(signal?: AbortSignal): Promise<MailcrawlSyncResult>;
     search(mode: MailcrawlSearchMode, query: string, options?: MailcrawlSearchOptions): Promise<MailcrawlSearchResult>;
+    /** `sync`/`index` share the long non-interactive budget. */
+    private indexTimeoutMs;
     private run;
     index(signal?: AbortSignal): Promise<MailcrawlOk<MailcrawlIndexInfo> | MailcrawlFailure>;
 }