@dikolab/kbdb 0.2.2 → 0.3.1

package/dist/src/shared/cli/functions/dispatch-command.function.d.ts

@@ -18,6 +18,8 @@ import type { AgentCreateClient } from './run-agent-create.function.ts';
 import type { AgentListClient } from './run-agent-list.function.ts';
 import type { AgentGetClient } from './run-agent-get.function.ts';
 import type { AgentDeleteClient } from './run-agent-delete.function.ts';
+import type { RecallClient } from './run-recall.function.ts';
+import type { ExportClient } from './run-export.function.ts';
 /**
  * Intersection of all data-command client interfaces.
  *
@@ -25,7 +27,7 @@ import type { AgentDeleteClient } from './run-agent-delete.function.ts';
  * intersection combines them so `dispatchCommand` can route
  * to any command handler with full type safety.
  */
-export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient;
+export type DispatchClient = SearchClient & LearnClient & UnlearnClient & ContentClient & CheckClient & GcClient & RebuildClient & StatusClient & DbMigrateClient & SkillLearnClient & SkillListClient & SkillGetClient & SkillDeleteClient & AgentCreateClient & AgentListClient & AgentGetClient & AgentDeleteClient & RecallClient & ExportClient;
 /**
  * Routes a parsed CLI command to the appropriate handler and
  * returns a `CommandResult` without touching process globals.

package/dist/src/shared/cli/functions/format-mcp-output.function.d.ts

@@ -0,0 +1,9 @@
+import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
+/**
+ * Formats a paged search result as a JSON string compatible
+ * with the MCP (Model Context Protocol) `text` content block.
+ *
+ * @param paged - paginated search results to serialise
+ * @returns MCP-compatible JSON string ready for stdout
+ */
+export declare function formatMcpOutput(paged: PagedSearchDisplay): string;

package/dist/src/shared/cli/functions/format-text-output.function.d.ts

@@ -0,0 +1,9 @@
+import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
+/**
+ * Formats a paged search result as a numbered human-readable
+ * text list with a paging footer and optional "more" hint.
+ *
+ * @param paged - paginated search results to render
+ * @returns formatted string ready for stdout
+ */
+export declare function formatTextOutput(paged: PagedSearchDisplay): string;

package/dist/src/shared/cli/functions/generate-group-help.function.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generates the level-2 help text for a group command.
+ *
+ * Lists all subcommands with their descriptions and
+ * includes a footer pointing to per-subcommand help.
+ *
+ * @param group - the group command name (e.g. `'db'`, `'skill'`)
+ * @param subs - ordered list of `[name, description]` pairs
+ * @returns formatted help string for the group command
+ */
+export declare function generateGroupHelp(group: string, subs: readonly (readonly [string, string])[]): string;

package/dist/src/shared/cli/functions/handle-data-command.function.d.ts

@@ -0,0 +1,16 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+/**
+ * Handles data commands (search, learn, recall, etc.) by finding or
+ * creating the database, running the version gate, and dispatching to
+ * the appropriate command handler.
+ *
+ * When the database is not found in non-TTY mode, returns an error.
+ * In TTY mode, prompts the user to create a new database.
+ *
+ * @param options - parsed CLI options with command and args
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` from the dispatched command
+ */
+export declare function handleDataCommand(options: CliOptions, deps: CliDeps): Promise<CommandResult>;

package/dist/src/shared/cli/functions/handle-mcp.function.d.ts

@@ -0,0 +1,15 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+/**
+ * Handles the `mcp` command sub-flow.
+ *
+ * Resolves the database directory, creates a worker client, runs
+ * the version gate, and starts the MCP server. Disconnects the
+ * worker client when finished.
+ *
+ * @param options - parsed CLI options (uses `dbPath` and env fallback)
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` with `exitCode: 0` on success
+ */
+export declare function handleMcp(options: CliOptions, deps: CliDeps): Promise<CommandResult>;

package/dist/src/shared/cli/functions/handle-migrate.function.d.ts

@@ -0,0 +1,15 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { CliDeps } from '../typings/cli-deps.interface.ts';
+/**
+ * Handles the `migrate` / `db-migrate` command sub-flow.
+ *
+ * Resolves the database directory, creates a worker client,
+ * checks the version, and runs migrations when needed. Disconnects
+ * the worker client when finished.
+ *
+ * @param options - parsed CLI options (uses `dbPath`)
+ * @param deps - injectable CLI dependencies
+ * @returns a `CommandResult` with migration output or an error
+ */
+export declare function handleMigrate(options: CliOptions, deps: CliDeps): Promise<CommandResult>;

package/dist/src/shared/cli/functions/hydrate-search-previews.function.d.ts

@@ -0,0 +1,14 @@
+import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
+import type { ContentClient } from './run-content.function.ts';
+/**
+ * Hydrates each result's `preview` field with the actual section
+ * content fetched from the client.
+ *
+ * Failures for individual results are caught and suppressed so that
+ * one unavailable section does not prevent other previews from
+ * being returned.
+ *
+ * @param client - content client used to fetch section text
+ * @param paged - mutable search display records to hydrate
+ */
+export declare function hydrateSearchPreviews(client: ContentClient, paged: PagedSearchDisplay): Promise<void>;

package/dist/src/shared/cli/functions/install-default-skills.function.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Writes the two default skills (`query-guidance` and
+ * `memory-protocol`) as section files directly into the `.kbdb`
+ * directory scaffold.
+ *
+ * Called by `runInit` after the directory scaffold is created.
+ * Does not require a running worker daemon. Skips any skill whose
+ * section file already exists so user modifications are preserved.
+ *
+ * @param dbDir - absolute path to the `.kbdb` directory
+ */
+export declare function installDefaultSkills(dbDir: string): void;

package/dist/src/shared/cli/functions/resolve-skill-names.function.d.ts

@@ -0,0 +1,16 @@
+import type { AgentGetClient, AgentDocumentSection } from '../typings/agent-get-client.interface.ts';
+/**
+ * Resolves skill names by reading each skill section's JSON content.
+ *
+ * Returns `null` for any reference whose section no longer exists
+ * (dangling reference) or whose content cannot be parsed.
+ *
+ * @param client - client used to fetch section records
+ * @param skillRefs - ordered section references to resolve
+ * @returns list of resolved skill entries with name and position
+ */
+export declare function resolveSkillNames(client: AgentGetClient, skillRefs: AgentDocumentSection[]): Promise<{
+    kbid: string;
+    name: string | null;
+    position: number;
+}[]>;

package/dist/src/shared/cli/functions/run-check.function.d.ts

@@ -17,6 +17,16 @@ interface IntegrityError {
     /** Human-readable description of the specific problem. */
     readonly detail: string;
 }
+/**
+ * A single entry in the divergent-content map.
+ * Groups kbids under a common source key.
+ */
+interface DivergentContentEntry {
+    /** Source key that has multiple divergent content versions. */
+    readonly sourceKey: string;
+    /** Kbids of sections sharing this source key but with different content. */
+    readonly kbids: string[];
+}
 /**
  * Integrity check report returned by the daemon.
  */
@@ -33,6 +43,37 @@ interface IntegrityCheckResult {
     readonly references_checked: number;
     /** Time taken to complete the check, in milliseconds. */
     readonly elapsed_ms: number;
+    /**
+     * Sections that share a source key but have divergent content.
+     * Each entry groups the kbids under a common source key.
+     * Empty when no divergent content is found.
+     */
+    readonly divergent_content: DivergentContentEntry[];
+}
+/** Raw daemon response from `integrityCheck`. */
+interface RawIntegrityCheckResult {
+    /** `true` when all checks passed and no errors were found. */
+    readonly ok: boolean;
+    /** All integrity errors found; empty when `ok` is `true`. */
+    readonly errors: IntegrityError[];
+    /** Total number of sections examined. */
+    readonly sections_checked: number;
+    /** Total number of documents examined. */
+    readonly documents_checked: number;
+    /** Total number of marker references checked. */
+    readonly references_checked: number;
+    /** Time taken to complete the check, in milliseconds. */
+    readonly elapsed_ms: number;
+    /**
+     * Encoded divergent-content map.
+     *
+     * Format: `sk1:kbid1,kbid2;sk2:kbid3,kbid4`
+     *
+     * Each semicolon-separated segment is a source key followed by
+     * a colon and a comma-separated list of kbids. Absent when no
+     * divergent content exists.
+     */
+    readonly divergent_content?: string;
 }
 /**
  * Minimal client interface required by `runCheck`.
@@ -47,18 +88,19 @@ export interface CheckClient {
      * @returns a report of all issues found; `ok` is `true` when
      *   no errors were detected
      */
-    integrityCheck(): Promise<IntegrityCheckResult>;
+    integrityCheck(): Promise<RawIntegrityCheckResult>;
 }
 /**
  * Runs an integrity check on the database and returns the report.
  *
- * Delegates to `client.integrityCheck()`. The caller is responsible
- * for printing the result to stdout and setting the process exit code
- * based on `result.ok`.
+ * Delegates to `client.integrityCheck()`, then parses the encoded
+ * `divergent_content` field into structured form. The caller is
+ * responsible for printing the result to stdout and setting the
+ * process exit code based on `result.ok`.
  *
  * @param client - check client to delegate to
  * @param _options - parsed CLI options (unused; reserved for future flags)
- * @returns the integrity check report from the daemon
+ * @returns the integrity check report with parsed `divergent_content`
  */
 export declare function runCheck(client: CheckClient, _options: CliOptions): Promise<IntegrityCheckResult>;
 export {};

package/dist/src/shared/cli/functions/run-export.function.d.ts

@@ -0,0 +1,34 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { ExportResult } from '../../worker-client/typings/export-result.model.ts';
+/**
+ * Minimal client interface required by `runExport`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface ExportClient {
+    /**
+     * Exports the database to the given directory path.
+     *
+     * @param params - optional target path; the daemon defaults to
+     *   `./kbdb-export/` when `path` is `undefined`
+     * @returns export report with the resolved path and file counts
+     */
+    export(params: {
+        path?: string;
+    }): Promise<ExportResult>;
+}
+/**
+ * Exports the knowledge-base database to a target directory via the
+ * provided client.
+ *
+ * The target path is taken from `options.args[0]`. When no argument
+ * is given the daemon resolves its own default (`./kbdb-export/`).
+ *
+ * @param client - export client to delegate to
+ * @param options - parsed CLI options whose first positional
+ *   argument, if present, is the target directory path
+ * @returns the export result containing the resolved path and file
+ *   counts
+ */
+export declare function runExport(client: ExportClient, options: CliOptions): Promise<ExportResult>;

package/dist/src/shared/cli/functions/run-gc.function.d.ts

@@ -9,6 +9,12 @@ interface GcResult {
     readonly removed_bytes: number;
     /** Time taken to complete garbage collection, in milliseconds. */
     readonly elapsed_ms: number;
+    /**
+     * Number of sections whose `source_path` file no longer
+     * contains their heading text (advisory; not auto-removed).
+     * Absent on older daemon versions.
+     */
+    readonly stale_sources?: number;
 }
 /**
  * Minimal client interface required by `runGc`.

package/dist/src/shared/cli/functions/run-learn.function.d.ts

@@ -1,5 +1,28 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { LearnResult } from '../typings/learn-result.model.ts';
+/** Enriched add-section result returned by the daemon. */
+interface AddSectionResult {
+    /** Knowledge-base identifier assigned to the new section. */
+    readonly kbid: string;
+    /**
+     * Kbid of the section superseded via `--replace`,
+     * or `null` / `undefined` when none.
+     */
+    readonly superseded?: string | null;
+    /**
+     * Advisory warning strings (e.g. `"heading_missing"`).
+     * May be absent from older daemon versions.
+     */
+    readonly warnings?: string[];
+    /**
+     * Near-duplicate sections with similarity >= 0.85.
+     * May be absent from older daemon versions.
+     */
+    readonly near_duplicates?: {
+        readonly kbid: string;
+        readonly similarity: number;
+    }[];
+}
 /**
  * Minimal client interface required by `runLearn`.
  *
@@ -10,9 +33,9 @@ export interface LearnClient {
     /**
      * Ingests a content section into the knowledge base.
      *
-     * @param params - section type label and raw text content
-     * @returns result object containing the knowledge-base identifier
-     *   assigned to the section
+     * @param params - section metadata and raw text content
+     * @returns enriched result containing the new kbid plus
+     *   optional supersession, warnings, and near-duplicate info
      */
     addSection(params: {
         sectionType: string;
@@ -20,9 +43,14 @@ export interface LearnClient {
         title?: string;
         description?: string;
         docid?: string;
-    }): Promise<{
-        kbid: string;
-    }>;
+        tags?: string[];
+        replace?: boolean;
+        /**
+         * Absolute path to the source file. Required for supersession
+         * via source key when `replace` is `true`.
+         */
+        sourcePath?: string;
+    }): Promise<AddSectionResult>;
 }
 /** Injectable I/O for testing without real stdin. */
 export interface LearnIO {
@@ -44,3 +72,4 @@ export interface LearnIO {
  * @returns one `LearnResult` per file successfully ingested
  */
 export declare function runLearn(client: LearnClient, options: CliOptions, io?: LearnIO): Promise<LearnResult[]>;
+export {};

package/dist/src/shared/cli/functions/run-recall.function.d.ts

@@ -0,0 +1,45 @@
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { RecallResult } from '../../worker-client/typings/recall-result.model.ts';
+/**
+ * Minimal client interface required by `runRecall`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface RecallClient {
+    /**
+     * Retrieves full content and context for one or more sections
+     * by their knowledge-base identifiers.
+     *
+     * @param params - section identifier(s) and optional expansion
+     *   depth (0--3)
+     * @returns a single `RecallResult` when `kbid` is supplied, or
+     *   a `RecallResult[]` when `kbids` is supplied
+     */
+    recall(params: {
+        kbid?: string;
+        kbids?: string[];
+        depth?: number;
+    }): Promise<RecallResult | RecallResult[]>;
+}
+/**
+ * Retrieves full content and progressive context for one or more
+ * sections by kbid via the provided client.
+ *
+ * Returns an error result when no kbids are provided in
+ * `options.args`. For a single kbid, calls `client.recall` with the
+ * `kbid` parameter and returns the single `RecallResult`. For
+ * multiple kbids, calls `client.recall` with the `kbids` array.
+ *
+ * The `depth` option is read from `options.depth`, defaulting to 0
+ * and clamped to the range 0--3.
+ *
+ * @param client - recall client to delegate to
+ * @param options - parsed CLI options supplying kbids in `args` and
+ *   expansion depth in `depth`
+ * @returns the `RecallResult` or `RecallResult[]` from the client,
+ *   or an error object when no kbids are provided
+ */
+export declare function runRecall(client: RecallClient, options: CliOptions): Promise<RecallResult | RecallResult[] | {
+    error: string;
+}>;

package/dist/src/shared/cli/functions/run-search.function.d.ts

@@ -1,5 +1,55 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { PagedSearchDisplay } from '../typings/search-display.model.ts';
+/** A single raw search result item returned by the daemon. */
+interface RawSearchItem {
+    /** Knowledge-base identifier of the matched section. */
+    readonly kbid: string;
+    /** Section heading, or null when untitled. */
+    readonly heading: string | null;
+    /** MIME type of the section content. */
+    readonly type: string;
+    /** Document IDs this section belongs to. */
+    readonly docids: readonly string[];
+    /** Relevance score from the ranking engine. */
+    readonly score: number;
+    /** KWIC excerpt centered on the highest-scoring matched term. */
+    readonly snippet: string;
+    /** Query terms that matched within this section. */
+    readonly matched_terms: readonly string[];
+    /**
+     * Fields that contained at least one match.
+     * May be absent from older daemon versions.
+     */
+    readonly matched_fields?: readonly string[];
+    /**
+     * Normalised confidence score (0.0-1.0) relative to the top result.
+     * May be absent from older daemon versions.
+     */
+    readonly confidence?: number;
+    /**
+     * ISO 8601 creation timestamp of the section.
+     * May be absent from older daemon versions.
+     */
+    readonly created_at?: string;
+}
+/** Raw paginated search response from the daemon. */
+interface RawSearchResponse {
+    /** Result items for the current page. */
+    readonly items: readonly RawSearchItem[];
+    /** Total number of matches across all pages. */
+    readonly total: number;
+    /** Number of results skipped. */
+    readonly offset: number;
+    /** Maximum results per page. */
+    readonly limit: number;
+    /** Whether more results exist beyond this page. */
+    readonly has_more: boolean;
+    /**
+     * When `true`, the engine relaxed the query to produce results.
+     * May be absent from older daemon versions.
+     */
+    readonly relaxed?: boolean;
+}
 /**
  * Minimal client interface required by `runSearch`.
  *
@@ -17,21 +67,8 @@ export interface SearchClient {
         mode?: string;
         limit?: number;
         offset?: number;
-    }): Promise<{
-        readonly items: readonly {
-            readonly kbid: string;
-            readonly heading: string | null;
-            readonly type: string;
-            readonly docids: readonly string[];
-            readonly score: number;
-            readonly snippet: string;
-            readonly matched_terms: readonly string[];
-        }[];
-        readonly total: number;
-        readonly offset: number;
-        readonly limit: number;
-        readonly has_more: boolean;
-    }>;
+        algo?: string;
+    }): Promise<RawSearchResponse>;
 }
 /**
  * Executes a search query via the provided client and maps the
@@ -46,3 +83,4 @@ export interface SearchClient {
  *   search parameters
  */
 export declare function runSearch(client: SearchClient, options: CliOptions): Promise<PagedSearchDisplay>;
+export {};

package/dist/src/shared/cli/functions/version-gate.function.d.ts

@@ -0,0 +1,15 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+import type { DisconnectableClient } from '../typings/disconnectable-client.interface.ts';
+/**
+ * Checks the database version and returns a `CommandResult` error
+ * when the version is incompatible, or `null` when it is compatible.
+ *
+ * - `'needs_migration'`: prompts the user to run `kbdb --migrate`
+ * - `'too_new'`: informs the user to upgrade kbdb
+ * - `'compatible'`: returns `null` (no gate triggered)
+ *
+ * @param client - disconnectable client with version-check capability
+ * @param dbDir - absolute path to the `.kbdb` database root
+ * @returns error `CommandResult` when blocked, or `null` when clear
+ */
+export declare function versionGate(client: DisconnectableClient, dbDir: string): Promise<CommandResult | null>;

package/dist/src/shared/cli/functions/wrap-command.function.d.ts

@@ -0,0 +1,15 @@
+import type { CommandResult } from '../typings/command-result.model.ts';
+/**
+ * Wraps an async command handler in a standard try/catch envelope.
+ *
+ * On success, serialises the result with `JSON.stringify` and
+ * returns `exitCode: 0`. On failure, returns an error message
+ * prefixed with `<label> failed:` and `exitCode: 1`.
+ *
+ * @param label - command name used in the error prefix
+ * @param handler - async function that produces the command result
+ * @param exitCodeSelector - optional function to derive `exitCode`
+ *   from the successful result; defaults to always returning 0
+ * @returns a `CommandResult` with output or error
+ */
+export declare function wrapCommand<T>(label: string, handler: () => Promise<T>, exitCodeSelector?: (result: T) => number): Promise<CommandResult>;

package/dist/src/shared/cli/index.d.ts

@@ -1,6 +1,8 @@
 export { parseArgs } from './functions/parse-args.function.ts';
 export { formatOutput } from './functions/format-output.function.ts';
 export { runSearch } from './functions/run-search.function.ts';
+export { runRecall } from './functions/run-recall.function.ts';
+export { runExport } from './functions/run-export.function.ts';
 export { runLearn } from './functions/run-learn.function.ts';
 export { runUnlearn } from './functions/run-unlearn.function.ts';
 export { runContent } from './functions/run-content.function.ts';
@@ -21,6 +23,8 @@ export type { CliOptions, OutputFormat, SearchMode, } from './typings/cli-option
 export type { LearnResult } from './typings/learn-result.model.ts';
 export type { SearchDisplay, PagedSearchDisplay, } from './typings/search-display.model.ts';
 export type { SearchClient } from './functions/run-search.function.ts';
+export type { RecallClient } from './functions/run-recall.function.ts';
+export type { ExportClient } from './functions/run-export.function.ts';
 export type { LearnClient } from './functions/run-learn.function.ts';
 export type { UnlearnClient, UnlearnResult, } from './functions/run-unlearn.function.ts';
 export type { ContentClient } from './functions/run-content.function.ts';

package/dist/src/shared/cli/typings/agent-create-client.interface.d.ts

@@ -0,0 +1,42 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+/**
+ * Minimal client interface required by `runAgentCreate`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentCreateClient {
+    /**
+     * Ingests a content section into the knowledge base.
+     *
+     * @param params - section type label, raw content, and optional
+     *   metadata
+     * @returns result object containing the assigned knowledge-base
+     *   identifier
+     */
+    addSection(params: {
+        readonly sectionType: string;
+        readonly content: string;
+        readonly title?: string;
+        readonly description?: string;
+    }): Promise<AddSectionResult>;
+    /**
+     * Groups a set of sections under a named document.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @param docType - application-level document type tag; omit or
+     *   pass an empty string for untagged documents
+     * @returns the assigned document identifier
+     */
+    groupSections(title: string, kbids: string[], docType?: string): Promise<string>;
+    /**
+     * Retrieves one or more sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections found; missing kbids are omitted from the result
+     */
+    readSections(kbids: string[]): Promise<{
+        kbid: string;
+    }[]>;
+}

package/dist/src/shared/cli/typings/agent-get-client.interface.d.ts

@@ -0,0 +1,36 @@
+/** A document section reference as returned by `retrieveDocument`. */
+export interface AgentDocumentSection {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Zero-based position of the section within the document. */
+    readonly position: number;
+}
+/** A section record as returned by `readSections`. */
+export interface AgentSectionRecord {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Raw text content stored in the section. */
+    readonly content: string;
+}
+/**
+ * Minimal client interface required by `runAgentGet`.
+ *
+ * Decouples the CLI function from the concrete `WorkerClient`
+ * implementation, making it straightforward to test with mocks.
+ */
+export interface AgentGetClient {
+    /**
+     * Retrieves a full document record including its ordered sections.
+     *
+     * @param docid - identifier of the document to retrieve
+     * @returns the document record
+     */
+    retrieveDocument(docid: string): Promise<unknown>;
+    /**
+     * Retrieves one or more sections by their identifiers.
+     *
+     * @param kbids - list of knowledge-base identifiers to fetch
+     * @returns sections found; missing kbids are omitted from the result
+     */
+    readSections(kbids: string[]): Promise<AgentSectionRecord[]>;
+}