@dikolab/kbdb 0.2.2 → 0.3.1

package/dist/src/shared/embedding/typings/vector-search-result.model.d.ts

@@ -0,0 +1,7 @@
+/** Result from a vector similarity search. */
+export interface VectorSearchResult {
+    /** Knowledge base ID of the matched section. */
+    readonly kbid: string;
+    /** Cosine similarity score (0.0 to 1.0). */
+    readonly score: number;
+}

package/dist/src/shared/mcp/classes/mcp-server.class.d.ts

@@ -52,4 +52,12 @@ export declare class McpServer {
     private processLine;
     private handleRequest;
     private send;
+    /**
+     * Runs an integrity check immediately after the MCP handshake
+     * completes. Emits a `notifications/message` warning when the
+     * check detects issues so the connected agent is aware before
+     * making requests. The server continues operating regardless of
+     * the result.
+     */
+    private runStartupHealthCheck;
 }

package/dist/src/shared/mcp/constants/tool-agent-create.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `agent-create` operation. */
+export declare const TOOL_AGENT_CREATE: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-agent-delete.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `agent-delete` operation. */
+export declare const TOOL_AGENT_DELETE: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-agent-get.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `agent-get` operation. */
+export declare const TOOL_AGENT_GET: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-agent-list.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `agent-list` operation. */
+export declare const TOOL_AGENT_LIST: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-auto-capture-review.constant.d.ts

@@ -0,0 +1,8 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/**
+ * MCP tool definition for the `auto-capture-review` operation.
+ *
+ * Allows agents to list, approve, or reject pending
+ * auto-captured knowledge entries before they are persisted.
+ */
+export declare const TOOL_AUTO_CAPTURE_REVIEW: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-check.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `check` operation. */
+export declare const TOOL_CHECK: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-content.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `content` operation. */
+export declare const TOOL_CONTENT: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-export.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `export` operation. */
+export declare const TOOL_EXPORT: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-gc.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `gc` operation. */
+export declare const TOOL_GC: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-learn.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `learn` operation. */
+export declare const TOOL_LEARN: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-rebuild.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `rebuild` operation. */
+export declare const TOOL_REBUILD: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-recall.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `recall` operation. */
+export declare const TOOL_RECALL: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-retrieve.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `retrieve` operation. */
+export declare const TOOL_RETRIEVE: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-search.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `search` operation. */
+export declare const TOOL_SEARCH: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-skill-delete.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `skill-delete` operation. */
+export declare const TOOL_SKILL_DELETE: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-skill-get.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `skill-get` operation. */
+export declare const TOOL_SKILL_GET: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-skill-learn.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `skill-learn` operation. */
+export declare const TOOL_SKILL_LEARN: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-skill-list.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `skill-list` operation. */
+export declare const TOOL_SKILL_LIST: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-status.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `status` operation. */
+export declare const TOOL_STATUS: McpToolDefinition;

package/dist/src/shared/mcp/constants/tool-unlearn.constant.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from '../typings/mcp-types.interface.ts';
+/** MCP tool definition for the `unlearn` operation. */
+export declare const TOOL_UNLEARN: McpToolDefinition;

package/dist/src/shared/mcp/functions/as-boolean-or-undefined.function.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrows an `unknown` value to a boolean, returning `undefined`
+ * when the value is not a boolean.
+ *
+ * @param value - the value to narrow
+ */
+export declare function asBooleanOrUndefined(value: unknown): boolean | undefined;

package/dist/src/shared/mcp/functions/as-string-array-or-undefined.function.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrows an `unknown` value to a `string[]`, returning `undefined`
+ * when the value is not an array of strings.
+ *
+ * @param value - the value to narrow
+ */
+export declare function asStringArrayOrUndefined(value: unknown): string[] | undefined;

package/dist/src/shared/mcp/functions/as-string-array.function.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Narrows an `unknown` value to a `string[]`, returning an empty
+ * array when the value is not an array of strings.
+ *
+ * @param value - the value to narrow
+ */
+export declare function asStringArray(value: unknown): string[];

package/dist/src/shared/mcp/functions/as-string.function.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Narrows an `unknown` value to a string, returning the fallback
+ * when the value is not already a string.
+ *
+ * @param value - the value to narrow
+ * @param fallback - returned when `value` is not a string
+ */
+export declare function asString(value: unknown, fallback: string): string;

package/dist/src/shared/mcp/functions/build-skills-text.function.d.ts

@@ -0,0 +1,18 @@
+/** Minimal section shape for building the skills listing text. */
+export interface SkillSection {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Raw JSON content of the skill section. */
+    readonly content: string;
+}
+/**
+ * Builds a human-readable skills listing from an array of skill
+ * section records.
+ *
+ * Sections whose JSON is not parseable or whose `name` field is
+ * absent are silently omitted. Returns `null` when no valid skills
+ * remain after filtering.
+ *
+ * @param skillSections - array of section records to summarise
+ */
+export declare function buildSkillsText(skillSections: SkillSection[]): string | null;

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

@@ -0,0 +1,14 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
+/**
+ * Handles an MCP `prompts/get` request for an agent prompt.
+ *
+ * Reads the agent document, extracts its persona from the metadata
+ * section, then reads all skill sections and composes the response.
+ * Returns an assistant message with the persona and, when skills
+ * exist, a user message listing them.
+ *
+ * @param name - prompt name with `agent:` prefix
+ * @param client - worker client used to access the knowledge base
+ */
+export declare function handleAgentPrompt(name: string, client: McpWorkerClient): Promise<McpPromptMessage[]>;

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

@@ -0,0 +1,14 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpRequest, McpResponse } from '../typings/mcp-types.interface.ts';
+import type { McpServerState } from '../typings/mcp-server-state.interface.ts';
+/**
+ * Routes an MCP JSON-RPC request to the appropriate handler and
+ * returns the JSON-RPC response. Mutates `state` for methods that
+ * update server-side configuration (logging level, subscriptions,
+ * capabilities).
+ *
+ * @param request - the parsed MCP request
+ * @param client - worker client for knowledge-base operations
+ * @param state - mutable server state shared with `McpServer`
+ */
+export declare function handleMcpRequest(request: McpRequest, client: McpWorkerClient, state: McpServerState): Promise<McpResponse>;

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

@@ -10,9 +10,10 @@ import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
  * substitutes `{{argName}}` placeholders in the body, and returns a
  * single user message.
  *
- * For agent prompts: reads the agent document via `retrieveDocument`,
- * builds an assistant message from the persona section, and (when
- * skills exist) a user message listing their names and descriptions.
+ * For agent prompts: looks up the agent by title via
+ * `listDocumentsByType('agent')`, builds an assistant message from
+ * the persona section, and (when skills exist) a user message
+ * listing their names and descriptions.
  *
  * @param name - prompt name from the MCP request
  * @param promptArgs - argument key-value map from the MCP request

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

@@ -0,0 +1,16 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { McpPromptMessage } from '../typings/prompt-types.interface.ts';
+/**
+ * Handles an MCP `prompts/get` request for a skill prompt.
+ *
+ * Looks up the skill by name in the `listByType('skill')` results,
+ * picks the most recent match (last occurrence), parses its body,
+ * and substitutes `{{argName}}` placeholders from `promptArgs`.
+ * Unresolved placeholders are left as-is.
+ *
+ * @param name - skill prompt name to look up
+ * @param promptArgs - argument key-value map from the MCP request
+ * @param client - worker client used to access the knowledge base
+ * @throws {Error} when no skill with the given name is found
+ */
+export declare function handleSkillPrompt(name: string, promptArgs: Record<string, string>, client: McpWorkerClient): Promise<McpPromptMessage[]>;

package/dist/src/shared/mcp/functions/handle-tool-auto-capture-review.function.d.ts

@@ -0,0 +1,12 @@
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `auto-capture-review` MCP tool call.
+ *
+ * Returns a stub response indicating no pending captures are
+ * available. Full implementation requires wiring the auto-capture
+ * controller into the MCP server state.
+ *
+ * @param _args - tool arguments; `action` may be list, approve,
+ *   or reject
+ */
+export declare function handleToolAutoCaptureReview(_args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `check` MCP tool call.
+ *
+ * Runs an integrity check on the knowledge base and returns the
+ * report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolCheck(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `content` MCP tool call.
+ *
+ * Composes a rendered Markdown document from the given identifiers
+ * and returns the result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolContent(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `export` MCP tool call.
+ *
+ * Exports the database as a self-contained directory snapshot.
+ * Passes the optional `path` argument when supplied.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolExport(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `gc` MCP tool call.
+ *
+ * Removes unreferenced sections from the knowledge base and returns
+ * the collection report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolGc(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `learn` MCP tool call.
+ *
+ * Validates that image content includes a title, then imports the
+ * content into the knowledge base via the worker client.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolLearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `rebuild` MCP tool call.
+ *
+ * Reconstructs all index files from section and document files and
+ * returns the rebuild report as formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolRebuild(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `retrieve` MCP tool call.
+ *
+ * Fetches a section by `kbid` or a document by `docid`. Returns an
+ * error when neither identifier is supplied.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolRetrieve(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

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

@@ -0,0 +1,13 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `search` MCP tool call.
+ *
+ * Forwards query parameters to the worker client and strips internal
+ * scoring fields (`score`, `confidence`) from each result item before
+ * returning.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolSearch(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/handle-tool-skill-delete.function.d.ts

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-delete` MCP tool call.
+ *
+ * Removes the skill section identified by `kbid` from the knowledge
+ * base and returns the result.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolSkillDelete(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/handle-tool-skill-get.function.d.ts

@@ -0,0 +1,13 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-get` MCP tool call.
+ *
+ * Looks up a skill by `kbid` first, then falls back to searching by
+ * `name`. Returns an error when neither identifier resolves to a
+ * known skill.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolSkillGet(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/handle-tool-skill-learn.function.d.ts

@@ -0,0 +1,13 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-learn` MCP tool call.
+ *
+ * Validates required arguments, extracts template placeholders from
+ * the body, serialises the skill, and stores it as a knowledge-base
+ * section.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolSkillLearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/handle-tool-skill-list.function.d.ts

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `skill-list` MCP tool call.
+ *
+ * Lists all skills stored in the knowledge base, including the
+ * argument count extracted from each skill's JSON content.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolSkillList(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,11 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `status` MCP tool call.
+ *
+ * Fetches database metadata from the worker client and returns it as
+ * formatted JSON.
+ *
+ * @param client - the worker client used to execute operations
+ */
+export declare function handleToolStatus(client: McpWorkerClient): Promise<ToolCallResult>;

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

@@ -0,0 +1,12 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+import type { ToolCallResult } from '../typings/tool-call-result.model.ts';
+/**
+ * Handles the `unlearn` MCP tool call.
+ *
+ * Removes the section identified by `kbid` from the knowledge base
+ * and returns the removal result as JSON.
+ *
+ * @param client - the worker client used to execute operations
+ * @param args - tool arguments from the MCP request
+ */
+export declare function handleToolUnlearn(client: McpWorkerClient, args: Record<string, unknown>): Promise<ToolCallResult>;

package/dist/src/shared/mcp/functions/parse-agent-meta.function.d.ts

@@ -0,0 +1,14 @@
+/** Parsed shape of an agent metadata section. */
+export interface AgentMeta {
+    /** Agent persona text. */
+    readonly persona: string;
+}
+/**
+ * Parses agent metadata from a raw JSON content string.
+ *
+ * Returns an object with an empty `persona` when parsing fails or
+ * the required field is absent or not a string.
+ *
+ * @param content - raw JSON content string of the agent metadata section
+ */
+export declare function parseAgentMeta(content: string): AgentMeta;

package/dist/src/shared/mcp/functions/parse-skill-arguments.function.d.ts

@@ -0,0 +1,11 @@
+import type { McpPromptArgument } from '../typings/prompt-types.interface.ts';
+/**
+ * Parses the `arguments` field from a skill's JSON content string.
+ *
+ * Returns the array of prompt argument definitions when the content
+ * is valid JSON with an `arguments` array, or `undefined` when JSON
+ * parsing fails or the field is absent.
+ *
+ * @param content - raw JSON string of the skill section content
+ */
+export declare function parseSkillArguments(content: string): readonly McpPromptArgument[] | undefined;

package/dist/src/shared/mcp/functions/read-agent-meta.function.d.ts

@@ -0,0 +1,17 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/**
+ * Reads the metadata JSON stored in the first section of an agent
+ * document and extracts `name`, `description`, and `persona`.
+ *
+ * Returns defaults when the section is absent or its content is
+ * not parseable as JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param metaKbid - kbid of the agent metadata section
+ * @param fallbackName - name returned when `name` is absent from JSON
+ */
+export declare function readAgentMeta(client: McpWorkerClient, metaKbid: string, fallbackName: string): Promise<{
+    name: string;
+    description: string;
+    persona: string;
+}>;

package/dist/src/shared/mcp/functions/resolve-skill-refs.function.d.ts

@@ -0,0 +1,23 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/** A section reference within an agent document. */
+export interface AgentSectionRef {
+    /** Knowledge-base identifier of the section. */
+    readonly kbid: string;
+    /** Zero-based position of the section within the document. */
+    readonly position: number;
+}
+/**
+ * Resolves skill names for a list of section references by reading
+ * each section's JSON content and extracting the `name` field.
+ *
+ * Returns `name: null` for references where the section no longer
+ * exists (dangling references) or whose content is not valid JSON.
+ *
+ * @param client - the worker client used to read sections
+ * @param skillRefs - ordered list of section references to resolve
+ */
+export declare function resolveSkillRefs(client: McpWorkerClient, skillRefs: AgentSectionRef[]): Promise<{
+    kbid: string;
+    name: string | null;
+    position: number;
+}[]>;

package/dist/src/shared/mcp/functions/run-startup-health-check.function.d.ts

@@ -0,0 +1,14 @@
+import type { McpWorkerClient } from '../typings/mcp-client.interface.ts';
+/**
+ * Runs an integrity check immediately after the MCP handshake
+ * completes.
+ *
+ * Calls `notify` with a `notifications/message` warning when the
+ * check detects issues so the connected agent is aware before making
+ * requests. Errors from the check itself are swallowed -- the server
+ * continues operating regardless.
+ *
+ * @param client - the worker client used to run the integrity check
+ * @param notify - callback used to send notifications to the host
+ */
+export declare function runStartupHealthCheck(client: McpWorkerClient, notify: (method: string, params: Record<string, unknown>) => void): Promise<void>;

package/dist/src/shared/mcp/typings/mcp-capabilities.interface.d.ts

@@ -0,0 +1,16 @@
+/** MCP capability flags advertised during initialization. */
+export interface McpCapabilities {
+    /** Indicates the server supports the tools capability. */
+    readonly tools?: Record<string, unknown>;
+    /** Indicates the server supports the resources capability. */
+    readonly resources?: Record<string, unknown>;
+    /** Indicates the server supports the prompts capability. */
+    readonly prompts?: Record<string, unknown>;
+    /** Indicates the server supports the logging capability. */
+    readonly logging?: Record<string, unknown>;
+    /**
+     * Indicates the server supports the completions capability,
+     * providing argument auto-completion for prompts and resources.
+     */
+    readonly completions?: Record<string, unknown>;
+}