@autorag/librarian 2.0.0

package/dist/cli/output.d.ts

@@ -0,0 +1,32 @@
+import type { AutoRAGRefreshResult, AutoRAGRefreshStatus } from "../agent/agent.js";
+import type { SearchDocumentsResponse } from "../agent/search-documents.js";
+import type { MemorySchemaV4 } from "../memory/memory.js";
+import type { HealthReportV1 } from "./commands/health.js";
+import type { SearchHealthHint } from "./commands/search.js";
+export interface RenderOptions {
+    json?: boolean;
+    debug?: boolean;
+    hint?: SearchHealthHint;
+}
+export declare function renderRefresh(result: AutoRAGRefreshResult, opts: RenderOptions): string;
+export declare function renderStatus(status: AutoRAGRefreshStatus, opts: RenderOptions): string;
+export declare function renderSearch(resp: SearchDocumentsResponse, opts: RenderOptions): string;
+export declare function renderMemory(schema: MemorySchemaV4, opts: RenderOptions): string;
+export declare function renderFeedback(result: {
+    applied: boolean;
+    sessionId: string;
+}, opts: RenderOptions): string;
+export declare function renderIndex(result: {
+    action: "reset" | "rebuild";
+    removed: string[];
+    rebuilt?: AutoRAGRefreshResult;
+}, opts: RenderOptions): string;
+export declare function renderError(err: unknown, opts: RenderOptions): string;
+/**
+ * Render a {@link HealthReportV1} as stable JSON or safe human text.
+ *
+ * The JSON envelope is the full report object; the health command already
+ * sanitizes all messages, base URLs, and metadata, so nothing here re-parses
+ * for secrets/paths. Human output stays path/secret/stack-free.
+ */
+export declare function renderHealth(report: HealthReportV1, opts: RenderOptions): string;

package/dist/config/home.d.ts

@@ -0,0 +1,2 @@
+export declare const AUTORAG_HOME_ENV = "AUTORAG_HOME";
+export declare function resolveAutoRAGHome(env?: NodeJS.ProcessEnv): string;

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

@@ -0,0 +1,49 @@
+/**
+ * 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`).
+ */
+import type { DatasourceAccessible } from "./types.js";
+export interface DatasourceAccessContextOptions {
+    /** Trusted allow-tags. Undefined or empty ⇒ default-deny (isDenyAll). */
+    readonly allowedTags?: readonly string[];
+    /** Trusted allow-scopes as slash-hierarchical paths or globs. */
+    readonly allowedScopes?: readonly string[];
+}
+/**
+ * Access context for gating datasource descriptors and sources.
+ *
+ * Non-datasource descriptors (those without a `datasourceId`) are NOT gated
+ * by this context: {@link isAccessible} returns `true` for them so plain
+ * retrieval methods (e.g. `posix`) pass through unchanged.
+ */
+export declare class DatasourceAccessContext {
+    readonly allowedTags: readonly string[];
+    readonly allowedScopes: readonly string[];
+    private readonly denyAll;
+    constructor(options?: DatasourceAccessContextOptions);
+    /** True when the context denies everything (no trusted allow-tags). */
+    get isDenyAll(): boolean;
+    /**
+     * Whether a descriptor is accessible.
+     *
+     * Non-datasource descriptors (no `datasourceId`) pass through (`true`) —
+     * they are not gated by this context. Datasource descriptors require at
+     * least one tag intersecting the trusted allow-tags.
+     */
+    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.
+     */
+    allowedSourcesPredicate(userScope?: string): (source: string) => boolean;
+}

package/dist/datasource/diagnostics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Diagnostic mapping for the datasource layer.
+ *
+ * Datasource operations surface {@link DatasourceDiagnostic} entries (with
+ * datasource-specific codes). The agent/search pipeline consumes
+ * {@link RetrievalDiagnostic}; these helpers bridge the two. Messages and
+ * sources are passed through verbatim.
+ */
+import type { RetrievalDiagnostic } from "../retrieval/types.js";
+import type { DatasourceDiagnostic } from "./types.js";
+/**
+ * Map a single {@link DatasourceDiagnostic} to a {@link RetrievalDiagnostic}.
+ *
+ * The original datasource code is preserved as a `[datasource:<code>]` prefix
+ * in the message (datasource codes collapse onto the generic
+ * `retrieval-method-failed` code in the retrieval stream's closed union).
+ */
+export declare function mapDatasourceDiagnostic(ds: DatasourceDiagnostic): RetrievalDiagnostic;
+/** Map a list of datasource diagnostics to retrieval diagnostics. */
+export declare function mapDatasourceDiagnostics(diagnostics: readonly DatasourceDiagnostic[]): RetrievalDiagnostic[];

package/dist/datasource/index.d.ts

@@ -0,0 +1,9 @@
+export { DatasourceAccessContext, type DatasourceAccessContextOptions } from "./access-context.js";
+export { mapDatasourceDiagnostic, mapDatasourceDiagnostics } from "./diagnostics.js";
+export { type CronParseResult, isDue, parseCronExpr } from "./polling.js";
+export { DatasourceSkillRegistry, type RegisteredDatasourceSkill } from "./registry.js";
+export { DatasourceResultFilter, type ResultsByMethod } from "./result-filter.js";
+export { buildDatasourceChunkSource, buildDatasourceInstanceSource, DATASOURCE_CHUNKS_SEGMENT, datasourceSourceHasFragment, datasourceSourcePath, isDatasourceSource, matchesDatasourceScope, matchesVirtualPathScope, normalizeVirtualPath, } from "./scope.js";
+export 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 type { DatasourceAccessible, DatasourceDiagnostic, DatasourceDiagnosticCode, DatasourceIndexFail, DatasourceIndexOk, DatasourceIndexResult, DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription, } from "./types.js";

package/dist/datasource/polling.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Polling helpers for datasource skills.
+ *
+ * v1 supports a simple interval-based `poll` mode plus a cron-expression
+ * validator. Cron is **descriptor-only**: {@link parseCronExpr} validates
+ * syntax so a skill descriptor can declare a schedule, but this module never
+ * schedules or fires jobs — scheduling is a caller/server concern.
+ */
+import type { PollingMetadata } from "./types.js";
+/**
+ * Whether a datasource skill/instance is due for a poll/index at `now`.
+ *
+ * Rules (v1, poll mode only):
+ *  - `mode !== "poll"` ⇒ never due (no automatic polling).
+ *  - `intervalMs` missing or non-positive ⇒ never due (misconfigured).
+ *  - never indexed (`lastIndexedAt` unknown) ⇒ due immediately.
+ *  - otherwise due iff `now - lastIndexedAt >= intervalMs`.
+ *
+ * `lastIndexedAt` is taken from the explicit argument when provided,
+ * otherwise from {@link PollingMetadata.lastIndexedAt}; this lets a caller
+ * pass an authoritative value that may differ from stale metadata.
+ */
+export declare function isDue(metadata: PollingMetadata, now: number, lastIndexedAt?: number): boolean;
+/** Successful cron parse result. */
+export interface CronParseOk {
+    readonly ok: true;
+    /** The normalized (trimmed) expression. */
+    readonly expr: string;
+}
+/** Failed cron parse result with a human-readable error. */
+export interface CronParseFail {
+    readonly ok: false;
+    readonly error: string;
+}
+/** Result of {@link parseCronExpr}. */
+export type CronParseResult = CronParseOk | CronParseFail;
+/**
+ * Validate a 5-field cron expression.
+ *
+ * Fields: `minute hour day-of-month month day-of-week`.
+ *
+ * Supported syntax per field: star, star-slash-n, n, a-b, a-b-slash-n,
+ * and comma lists of the above (e.g. 1,15,30). Extended forms (L, W, ?,
+ * NOT supported and will fail validation.
+ *
+ * Ranges: minute 0–59, hour 0–23, day-of-month 1–31, month 1–12, day-of-week
+ * 0–7 (where both 0 and 7 denote Sunday).
+ *
+ * This function only validates syntax. It does not schedule anything.
+ */
+export declare function parseCronExpr(expr: string): CronParseResult;

package/dist/datasource/registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Server-bound registry of datasource skills.
+ *
+ * Skills are constructed from trusted, server-supplied configuration and
+ * registered here so the retrieval pipeline can enumerate them, look them up
+ * by tag, and resolve the concrete instances a given access context permits.
+ *
+ * The registry never grants access: {@link resolveInstances} only *narrows*
+ * the registered skills to those a {@link DatasourceAccessContext} already
+ * allows. Model/tool arguments are not consulted.
+ */
+import type { RetrievalMethod } from "../retrieval/types.js";
+import type { DatasourceAccessContext } from "./access-context.js";
+import type { DatasourceInstance, DatasourceSkill, DatasourceSkillDescriptor } from "./types.js";
+/** A registered skill paired with its cached descriptor. */
+export interface RegisteredDatasourceSkill {
+    readonly skill: DatasourceSkill;
+    readonly descriptor: DatasourceSkillDescriptor;
+}
+/**
+ * Registry of {@link DatasourceSkill}s keyed by stable skill id
+ * ({@link DatasourceSkillDescriptor.name}).
+ */
+export declare class DatasourceSkillRegistry {
+    private readonly skills;
+    /**
+     * Register a datasource skill. Throws if a skill with the same
+     * {@link DatasourceSkillDescriptor.name} is already registered.
+     */
+    register(skill: DatasourceSkill): void;
+    /** All registered skills in insertion order. */
+    list(): readonly RegisteredDatasourceSkill[];
+    /** Skills whose descriptor carries the given tag. */
+    byTag(tag: string): readonly RegisteredDatasourceSkill[];
+    /** Look up a registered skill by id, or `undefined`. */
+    get(id: string): RegisteredDatasourceSkill | undefined;
+    /**
+     * Resolve the concrete datasource instances reachable under `ctx`.
+     *
+     * Only skills whose descriptor {@link DatasourceAccessContext.isAccessible}
+     * allows contribute instances, and only their declared instance ids are
+     * materialized. Each instance carries its opaque slash-hierarchical
+     * {@link DatasourceInstance.sourcePath} (e.g. `/kakao/acct-1`), built from
+     * the trusted skill name and instance id — never from model input.
+     */
+    resolveInstances(ctx: DatasourceAccessContext): readonly DatasourceInstance[];
+    /**
+     * Convenience: all retrieval methods exposed by accessible skills, for
+     * feeding the shared retriever. Methods from denied skills are excluded.
+     */
+    accessibleMethods(ctx: DatasourceAccessContext): readonly RetrievalMethod[];
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Result filter that applies datasource access gating to the shared retrieval
+ * result stream.
+ *
+ * The filter sits *after* {@link ParallelRetriever} and *before* merging: it
+ * 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.
+ *
+ * Non-datasource methods (those whose descriptor has no `datasourceId`) pass
+ * through completely untouched — they are gated by their own retrieval
+ * pipeline, not by the datasource access context.
+ *
+ * Security invariants:
+ *  - Deny is always an explicit `false` (an empty result array), never
+ *    `undefined`-as-deny. {@link DatasourceAccessContext} itself returns
+ *    explicit booleans from its predicate; this filter never passes
+ *    `undefined` to `matchesVirtualPathScope` as a deny signal.
+ *  - The filter never grants access. It only narrows results using the
+ *    trusted, server-supplied {@link DatasourceAccessContext}; model/tool
+ *    arguments (such as `userScope`) can only *further restrict* the trusted
+ *    allow-scopes, never widen them.
+ */
+import type { RetrievalMethod, RetrievalResult } from "../retrieval/types.js";
+import type { DatasourceAccessContext } from "./access-context.js";
+/** Per-method retrieval results keyed by method name. */
+export type ResultsByMethod = Map<string, RetrievalResult[]>;
+/**
+ * Applies datasource access gating to a per-method result map.
+ *
+ * The instance form lets callers wire a {@link DatasourceSkillRegistry} for
+ * future descriptor enrichment; the v1 filter only needs the
+ * {@link RetrievalMethodDescriptor} carried by each method, which already
+ * satisfies {@link DatasourceAccessible} structurally (`datasourceId?` +
+ * `tags?`).
+ */
+export declare class DatasourceResultFilter {
+    /**
+     * Filter `byMethod` according to datasource access rules.
+     *
+     * For each method present in both `byMethod` and `methods`:
+     *  - non-datasource methods (`descriptor.datasourceId` unset) are passed
+     *    through with their result array unchanged;
+     *  - datasource methods whose descriptor is denied by `ctx` are reduced to
+     *    an empty result array (`[]` — explicit deny, never `undefined`);
+     *  - datasource methods whose descriptor is allowed are filtered so only
+     *    sources matching `ctx.allowedSourcesPredicate(userScope)` survive.
+     *
+     * Result entries for methods not present in `methods` are passed through
+     * unchanged (the filter cannot classify them and must not fabricate a
+     * descriptor). A new {@link ResultsByMethod} is returned; the input map is
+     * not mutated.
+     *
+     * @param byMethod   Per-method results from the retriever.
+     * @param methods    The {@link RetrievalMethod}s that produced them.
+     * @param ctx        Trusted, server-supplied access context.
+     * @param userScope  Optional user/model-requested scope; when provided it
+     *   is intersected with the trusted allow-scopes and can only narrow
+     *   results. `undefined` means "no extra user restriction".
+     */
+    filter(byMethod: ResultsByMethod, methods: readonly RetrievalMethod[], ctx: DatasourceAccessContext, userScope?: string): ResultsByMethod;
+}

package/dist/datasource/scope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Slash-hierarchical source-path helpers for the datasource layer.
+ *
+ * Datasource sources are opaque, slash-hierarchical paths such as
+ * `/kakao/<instance-id>` and `/kakao/<instance-id>/chunks/<chunk-id>`.
+ * `#` fragments are NEVER produced or matched — sources are pure path trees.
+ *
+ * Reuses {@link normalizeVirtualPath} and {@link matchesVirtualPathScope} from
+ * `src/retrieval/scope.ts` so datasource scopes compose with the existing
+ * retrieval scope grammar (globs, leading-slash normalization).
+ */
+/** Path segment separating an instance root from its chunk sub-namespace. */
+export declare const DATASOURCE_CHUNKS_SEGMENT = "chunks";
+/**
+ * Build the opaque root source for a datasource instance, e.g.
+ * `/kakao/acct-1`.
+ */
+export declare function buildDatasourceInstanceSource(skillName: string, instanceId: string): string;
+/**
+ * Build the opaque source for a single datasource chunk, e.g.
+ * `/kakao/acct-1/chunks/c-42`.
+ */
+export declare function buildDatasourceChunkSource(skillName: string, instanceId: string, chunkId: string): string;
+export declare function datasourceSourcePath(skillName: string, instanceId: string, chunkId?: string): string;
+/** True when a source string contains a `#` fragment (always invalid here). */
+export declare function datasourceSourceHasFragment(source: string): boolean;
+/**
+ * Whether a string is a valid datasource source: a non-root, normalized,
+ * slash-hierarchical path with no `#` fragment.
+ */
+export declare function isDatasourceSource(source: string): boolean;
+/**
+ * Match a datasource source against a scope. Returns `false` when the source
+ * contains a `#` fragment; otherwise delegates to the shared retrieval
+ * scope matcher so globs and leading-slash normalization behave identically.
+ */
+export declare function matchesDatasourceScope(source: string, scope: string | undefined): boolean;
+export { matchesVirtualPathScope, normalizeVirtualPath } from "../retrieval/scope.js";

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

@@ -0,0 +1,24 @@
+import type { KatokChunkResult, KatokContextResult, KatokDoctorResult, KatokIndexResult, KatokOptions, KatokParentResult, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSyncResult } from "./types.js";
+/**
+ * Thin external `katok` CLI wrapper. Every method spawns the `katok` binary as
+ * a child process, parses JSON from stdout, and returns a discriminated ok/fail
+ * union. No method throws for expected failures (missing binary, rejected
+ * remote-embedding config, CLI nonzero exit, timeout, oversized output, or
+ * invalid JSON). The client never opens the KakaoTalk database directly.
+ *
+ * Remote-embedding configuration is rejected before spawn, case-insensitively,
+ * so the spawned process can never egress embeddings to a remote endpoint.
+ */
+export declare class KatokClient {
+    private readonly options;
+    constructor(options?: KatokOptions);
+    doctor(signal?: AbortSignal): Promise<KatokDoctorResult>;
+    sync(signal?: AbortSignal): Promise<KatokSyncResult>;
+    index(signal?: AbortSignal): Promise<KatokIndexResult>;
+    search(mode: KatokSearchMode, query: string, options?: KatokSearchOptions): Promise<KatokSearchResult>;
+    chunkGet(chunkId: string, signal?: AbortSignal): Promise<KatokChunkResult>;
+    context(chunkId: string, signal?: AbortSignal): Promise<KatokContextResult>;
+    parent(chunkId: string, signal?: AbortSignal): Promise<KatokParentResult>;
+    /** Single retrieval pipeline: build env, gate remote embeddings, spawn, parse-free raw result. */
+    private run;
+}

package/dist/datasource/skills/katok/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 { KatokClient } from "./client.js";
+export { KatokBm25Method, type KatokMethodOptions, type KatokSearchClient, KatokSemanticMethod } from "./methods.js";
+export { KatokSkill, type KatokSkillClient, type KatokSkillOptions } from "./skill.js";
+export type { KatokChunkResult, KatokDoctorResult, KatokFailureReason, KatokHit, KatokIndexResult, KatokOptions, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSyncResult, } from "./types.js";
+export { DEFAULT_KATOK_OPTIONS } from "./types.js";

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

@@ -0,0 +1,40 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { KatokSearchMode, KatokSearchOptions, KatokSearchResult } from "./types.js";
+/**
+ * Narrow client surface required by the KakaoTalk retrieval methods.
+ * The real {@link KatokClient} satisfies this structurally; tests may stub it.
+ */
+export interface KatokSearchClient {
+    search(mode: KatokSearchMode, query: string, options?: KatokSearchOptions): Promise<KatokSearchResult>;
+}
+export interface KatokMethodOptions {
+    readonly client: KatokSearchClient;
+    readonly instanceId: string;
+    readonly tags?: readonly string[];
+}
+/**
+ * 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.
+ */
+export declare class KatokBm25Method implements RetrievalMethod {
+    private readonly client;
+    private readonly instanceId;
+    private readonly tags;
+    constructor(options: KatokMethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+/**
+ * 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.
+ */
+export declare class KatokSemanticMethod implements RetrievalMethod {
+    private readonly client;
+    private readonly instanceId;
+    private readonly tags;
+    constructor(options: KatokMethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Path helpers for the KakaoTalk (`katok`) datasource skill.
+ *
+ * All paths are workspace-relative and live under
+ * `<workspaceRoot>/.autorag/datasources/katok`. 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 KATOK_DATASOURCE_DIRNAME = "katok";
+/** Logical datasource kind for source identifiers. */
+export declare const KATOK_SOURCE_KIND: "kakao";
+/**
+ * Root directory for katok-managed state under a workspace. This is where the
+ * external `katok` CLI stores its index, chunks, and sync state.
+ */
+export declare function katokDatasourceRoot(workspaceRoot: string): string;
+/** Directory holding the katok chunk index. */
+export declare function katokIndexPath(workspaceRoot: string): string;
+/** Directory holding materialized katok chunks. */
+export declare function katokChunksPath(workspaceRoot: string): string;
+/** Directory holding katok sync state. */
+export declare function katokSyncPath(workspaceRoot: string): string;
+/**
+ * Builds the path-opaque, slash-hierarchical source identifier for a single
+ * katok chunk. Callers (the KatokSkill methods) use this to populate
+ * `RetrievalResult.source` so no real filesystem path ever leaks.
+ */
+export declare function katokSourcePath(instanceId: string, chunkId: string): string;
+/**
+ * Parses a katok 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 parseKatokSourcePath(source: string): {
+    readonly instanceId: string;
+    readonly chunkId: string;
+} | undefined;

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

@@ -0,0 +1,33 @@
+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>;
+}
+export interface KatokSkillOptions {
+    readonly client: KatokSkillClient;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly pollingIntervalMs?: number;
+    readonly tags?: readonly string[];
+    readonly lastIndexedAt?: number;
+}
+export declare class KatokSkill implements DatasourceSkill {
+    private readonly client;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly pollingIntervalMs;
+    private readonly tags;
+    private lastIndexedAt;
+    constructor(options: KatokSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    private fail;
+}

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

@@ -0,0 +1,146 @@
+import type { RetrievalOptions } from "../../../retrieval/types.js";
+/**
+ * Search modes accepted by the external `katok search` subcommand.
+ *
+ * - `semantic` — dense vector similarity over indexed chunks.
+ * - `keyword`  — exact / tokenized keyword matching.
+ * - `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
+ * process — it never opens the KakaoTalk database directly.
+ */
+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. */
+    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.
+     */
+    readonly workspacePath?: string;
+    /** Workspace root used to compute the default katok workspace path. */
+    readonly root?: 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_MAX_BUFFER_BYTES = 1048576;
+export declare const DEFAULT_KATOK_SOURCE: KatokSourceKind;
+export declare const DEFAULT_KATOK_OPTIONS: {
+    readonly binaryPath: "katok";
+    readonly timeoutMs: 10000;
+    readonly maxBufferBytes: 1048576;
+    readonly source: "macos";
+};
+/**
+ * Reasons a katok 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 KatokFailureReason = "binary-missing" | "remote-embedding-rejected" | "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 KatokFailure {
+    readonly ok: false;
+    readonly reason: KatokFailureReason;
+    /** 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;
+    /**
+     * The offending environment key when `reason === "remote-embedding-rejected"`.
+     * A config key name (never a path, never the key's value).
+     */
+    readonly violatingKey?: string;
+    readonly hits?: readonly unknown[];
+}
+/** A single indexed chat chunk returned by the katok CLI. */
+export interface KatokChunk {
+    readonly chunkId: string;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** A scored search hit. */
+export interface KatokSearchHit {
+    readonly chunkId: string;
+    readonly score: number;
+    readonly content: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly source?: string;
+}
+export type KatokHit = KatokSearchHit;
+/** Result of `katok doctor`. */
+export interface KatokDoctorInfo {
+    readonly version?: string;
+    readonly ready: boolean;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Result of `katok sync`. */
+export interface KatokSyncInfo {
+    readonly synced: boolean;
+    readonly messageCount?: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Result of `katok index`. */
+export interface KatokIndexInfo {
+    readonly chunkCount: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Context payload: the chunks surrounding a target chunk. */
+export interface KatokContext {
+    readonly chunks: readonly KatokChunk[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Discriminated ok-success shape carrying typed `data`. */
+export interface KatokOk<T> {
+    readonly ok: true;
+    readonly data: T;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+}
+export interface KatokSearchOk {
+    readonly ok: true;
+    readonly hits: readonly KatokSearchHit[];
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly code: number;
+    readonly data: {
+        readonly hits: readonly KatokSearchHit[];
+    };
+}
+export type KatokDoctorResult = KatokOk<KatokDoctorInfo> | KatokFailure;
+export type KatokSyncResult = KatokOk<KatokSyncInfo> | KatokFailure;
+export type KatokIndexResult = KatokOk<KatokIndexInfo> | KatokFailure;
+export type KatokSearchResult = KatokSearchOk | KatokFailure;
+export type KatokChunkResult = KatokOk<KatokChunk> | KatokFailure;
+export type KatokContextResult = KatokOk<KatokContext> | KatokFailure;
+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.
+ */
+export type KatokSearchOptions = RetrievalOptions;