@sparkelf/dsh-knowledge-base 0.1.5 → 0.1.20

package/lib/types/client/workflows/modelChoice.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Model choices for the workflow subscription dialog.
+ *
+ * The Host owns the catalog (`remote.session.modelCatalog()`); this module only narrows
+ * it for rendering and remembers the reader's last pick. Keeping the mapping pure makes
+ * the "catalog unavailable" fallback testable without a browser or a Host.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/workflows/modelChoice
+ */
+/** One exact model route the Host can serve. */
+export interface WorkflowModelSelection {
+    readonly provider: string;
+    readonly model: string;
+    readonly reasoningEffort?: string;
+}
+/** One reasoning level an adapter exposes for a model. */
+export interface WorkflowReasoningEffort {
+    readonly id: string;
+    readonly name: string;
+}
+/** One model row rendered inside its provider group. */
+export interface WorkflowModelOption extends WorkflowModelSelection {
+    /** Stable `<optgroup>`/`<option>` key: provider + model. */
+    readonly key: string;
+    readonly providerName: string;
+    readonly modelName: string;
+    readonly description?: string;
+    readonly reasoningEfforts: readonly WorkflowReasoningEffort[];
+    /** The effort the Host would use when none is chosen. */
+    readonly defaultEffort?: string;
+}
+/** One provider group. */
+export interface WorkflowModelGroup {
+    readonly provider: string;
+    readonly providerName: string;
+    readonly models: readonly WorkflowModelOption[];
+}
+/** The catalog as the dialog consumes it. */
+export interface WorkflowModelCatalogView {
+    readonly default?: WorkflowModelSelection;
+    readonly groups: readonly WorkflowModelGroup[];
+    /** Providers whose catalog could not be loaded; shown as a quiet fallback note. */
+    readonly failures: readonly {
+        readonly provider: string;
+        readonly message: string;
+    }[];
+}
+/** The raw shape `remote.session.modelCatalog()` returns (narrowed structurally). */
+export interface RawModelCatalog {
+    readonly default?: WorkflowModelSelection;
+    readonly groups?: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly models: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly description?: string;
+            readonly reasoning?: {
+                readonly efforts: readonly WorkflowReasoningEffort[];
+                readonly defaultEffort?: string;
+            };
+        }[];
+    }[];
+    readonly failures?: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly message: string;
+    }[];
+}
+/** The localStorage key; per browser profile, which is the DSH workspace's boundary. */
+export declare const WORKFLOW_MODEL_STORAGE_KEY = "dsh-kb-workflow-model";
+/** Stable key for one provider/model pair. */
+export declare const modelKeyOf: (selection: WorkflowModelSelection) => string;
+/** Narrow a Host catalog into renderable groups. */
+export declare function toWorkflowModelCatalog(raw: RawModelCatalog | undefined): WorkflowModelCatalogView;
+/** Find one option by its key. */
+export declare function findModelOption(catalog: WorkflowModelCatalogView, key: string): WorkflowModelOption | undefined;
+/** Find the option matching a remembered/default selection, when the catalog still serves it. */
+export declare function findSelection(catalog: WorkflowModelCatalogView, selection: WorkflowModelSelection | undefined): WorkflowModelOption | undefined;
+/**
+ * Whether a route is one of the known-bad providers that made the old default fail.
+ *
+ * `tokensfree_ds` was the concrete 502 in the report: its models are listed, but a
+ * subscription whose first turn runs there fails. The check is intentionally narrow
+ * (provider/model id contains "tokensfree") rather than a general health probe; a
+ * catalog that stops listing the route is already handled by `findSelection`.
+ */
+export declare function isObviousBadProvider(selection: WorkflowModelSelection): boolean;
+/**
+ * Initial selection for a dialog open.
+ *
+ * Priority is **workspace default → remembered choice → first usable model**. The
+ * workspace default must win over a browser memory: the reported bug was a remembered
+ * `tokensfree_ds` selection silently overriding a healthy `dashscope` default and
+ * reproducing the 502. A remembered route is only considered while it still exists in
+ * the catalog and is not a known-bad provider; a bad workspace default is skipped for
+ * a usable remembered route, and only used when there is nothing better.
+ *
+ * Returns undefined when the catalog is empty, which the dialog renders as
+ * "workspace default".
+ */
+export declare function initialModelOption(catalog: WorkflowModelCatalogView, remembered: WorkflowModelSelection | undefined): WorkflowModelOption | undefined;
+/** Read the last choice this browser made. Never throws (storage can be disabled). */
+export declare function readRememberedModel(storage?: Pick<Storage, 'getItem'>): WorkflowModelSelection | undefined;
+/** Remember one choice for the next dialog open. Never throws. */
+export declare function rememberModel(selection: WorkflowModelSelection, storage?: Pick<Storage, 'setItem'>): void;

package/lib/types/client/workflows/published.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Approved workflows from the profile-local publish store, as plaza cards.
+ *
+ * The server decides what is public; this module only turns an approved record into the
+ * same inert definition the built-ins use. Keeping it pure makes the merge testable
+ * without a browser, and keeps the plaza from knowing where the store lives.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/workflows/published
+ */
+import { type WorkflowDefinition } from './registry.ts';
+/** One approved workflow as the HTTP route reports it. */
+export interface PublishedWorkflowView {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly instruction: string;
+    readonly cronHint: string;
+    readonly category: string;
+    readonly authorId?: string;
+    readonly authorName?: string;
+    readonly createdAt?: string;
+    readonly status?: 'pending' | 'approved' | 'rejected' | 'unpublished';
+    readonly reviewStatus?: 'pending' | 'approved' | 'rejected';
+    readonly reviewedByName?: string;
+    readonly reviewNote?: string;
+    readonly visibility?: 'global' | 'department' | 'private';
+    readonly departmentCode?: string | null;
+    readonly departmentName?: string | null;
+    readonly updatedAt?: string;
+    readonly reviewedAt?: string;
+    readonly unpublishedAt?: string | null;
+    readonly submittedAt?: string;
+    readonly ownerId?: string;
+}
+/**
+ * Turn one approved record into a plaza definition.
+ *
+ * The record id is the identity: the subscription marker embeds it, so a re-reviewed
+ * record keeps its dedupe identity while its copy can change.
+ */
+export declare function publishedDefinition(record: PublishedWorkflowView): WorkflowDefinition;
+/** Merge built-ins with approved records, keeping built-ins first and ids unique. */
+export declare function mergePublishedWorkflows(builtIns: readonly WorkflowDefinition[], approved: readonly PublishedWorkflowView[]): WorkflowDefinition[];

package/lib/types/client/workflows/registry.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The built-in workflow registry behind the 「工作流广场」 tab.
+ *
+ * A workflow is a TEMPLATE, not a scheduler. Every field here is static data: the
+ * plaza renders these cards, and subscribing turns one of them into an ordinary DSH
+ * Schedule using the existing `schedule_create` tool. Nothing in this module runs
+ * anything, parses a cron expression, or talks to a server -- keeping the definitions
+ * inert is what makes the plaza cheap to extend and impossible to break by adding a
+ * card.
+ *
+ * ## Why the definitions live in this plugin
+ *
+ * DataOps owns sharing: which buckets a person can see. It does not schedule work and
+ * does not execute it, so it has no say in what a workflow is. A workflow that needs
+ * to read or write knowledge documents still goes through the knowledge API at run
+ * time, which is where DataOps' permissions already apply.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/workflows/registry
+ */
+/** Which icon a plaza card shows. Mapped to a concrete glyph by the component. */
+export type WorkflowIcon = 'organize' | 'index' | 'archive';
+/** One frequency shortcut offered in the subscribe dialog. */
+export interface WorkflowFrequency {
+    /**
+     * Stable id, also used as the radio button's DOM hook.
+     *
+     * `everyHours` / `everyMinutes` are interval shortcuts: their expression depends on a
+     * count the reader edits, so they carry no `cron` here and are resolved by `cron.ts`
+     * from `INTERVAL_SPECS` instead.
+     */
+    readonly id: 'daily' | 'weekly' | 'monthly' | 'everyHours' | 'everyMinutes' | 'custom';
+    /** The cron expression this shortcut fills in, or `undefined` for `custom`. */
+    readonly cron?: string;
+}
+/** One built-in workflow, as the plaza renders and subscribes it. */
+export interface WorkflowDefinition {
+    /**
+     * Stable identity, and the ONLY thing deduplication is allowed to key on.
+     *
+     * Titles are copy and will be edited; ids are the contract. A subscribed task is
+     * recognised by this string appearing in its prompt, so changing an id orphans
+     * existing subscriptions -- treat the value as frozen once shipped.
+     */
+    readonly id: string;
+    /** Locale key for the card title. */
+    readonly titleKey: string;
+    /** Locale key for the card description. */
+    readonly descriptionKey: string;
+    /** Card glyph. */
+    readonly icon: WorkflowIcon;
+    /** Published records carry their own copy; built-ins resolve it from locale keys. */
+    readonly title?: string;
+    readonly description?: string;
+    /** Category/author shown on a published card; absent for built-ins. */
+    readonly category?: string;
+    readonly authorName?: string;
+    /** Cron prefilled in the subscribe dialog before the reader touches anything. */
+    readonly defaultCron: string;
+    /** Frequency shortcuts, in the order the dialog shows them. */
+    readonly frequencies: readonly WorkflowFrequency[];
+    /**
+     * What the scheduled session should actually do.
+     *
+     * This is the body of the prompt handed to a new session, and it becomes the
+     * Schedule's own prompt, so it must read as a standing instruction rather than as
+     * a one-off request: it runs again every time the schedule fires.
+     */
+    readonly instruction: string;
+}
+/**
+ * The marker a subscribed task carries, so its workflow can be recognised later.
+ *
+ * Deliberately plain text inside the prompt: DSH Schedules have no user-data field,
+ * and the prompt is the one part of a Schedule this plugin controls. A marker that is
+ * visible in the prompt is also honest -- opening the task detail shows which workflow
+ * produced it.
+ *
+ * @param id - workflow id to mark.
+ * @returns the marker string, e.g. `[workflow:kb-organize-personal]`.
+ */
+export declare function workflowMarker(id: string): string;
+/** Frequency shortcuts every built-in workflow offers. */
+export declare const STANDARD_FREQUENCIES: readonly WorkflowFrequency[];
+/**
+ * The built-in workflows, in the order the plaza shows them.
+ *
+ * Each one names a capability the knowledge plugin already has, so subscribing cannot
+ * promise something the deployment cannot do. Adding a card means adding a definition
+ * here and its copy keys; no other wiring is required.
+ */
+export declare const BUILT_IN_WORKFLOWS: readonly WorkflowDefinition[];
+/**
+ * Find one built-in workflow by id.
+ *
+ * @param id - workflow id to look up.
+ * @returns the definition, or undefined when no such workflow is built in.
+ */
+export declare function findWorkflow(id: string): WorkflowDefinition | undefined;

package/lib/types/client/workflows/subscribe.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Turning one plaza card into a real DSH Schedule.
+ *
+ * ## Why this goes through a Session
+ *
+ * DSH exposes Schedules to the browser as list-and-delete only; creating one is an
+ * agent tool (`schedule_create`). That is deliberate -- the task manager page says so
+ * in its own type docs ("Start a new Session, where a reminder is created by asking
+ * the model to schedule it. The page deliberately has no creation form of its own.")
+ * -- so subscribing follows exactly the path the product already uses for its own
+ * 「新建任务」 button: create a Session, ask the model to schedule the work, then confirm
+ * it actually happened.
+ *
+ * ## Why the result is verified instead of assumed
+ *
+ * The model is a participant, not a function call. It can misread the request, ask a
+ * clarifying question, or reply with prose and call nothing. Reporting "subscribed" on
+ * the back of a successful `prompt` would be reporting that a message was delivered,
+ * not that a task exists. So the last step re-reads the authoritative task list and
+ * only then reports success; anything else is a failure with a reason the reader can
+ * act on.
+ *
+ * Every dependency is injected, because the interesting part is the decision sequence
+ * and a test should be able to drive it without a browser, a model, or a clock.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/workflows/subscribe
+ */
+import { type SubscribedTaskView } from './dedupe.ts';
+import type { WorkflowModelSelection } from './modelChoice.ts';
+import { type WorkflowDefinition } from './registry.ts';
+/** Where a subscription attempt currently is. */
+export type SubscribePhase = 'idle' | 'creating-session' | 'selecting-model' | 'prompting' | 'verifying' | 'opened' | 'subscribed' | 'cancelling' | 'cancelled' | 'failed';
+/** Why an attempt failed, in terms the dialog can explain. */
+export type SubscribeFailure = 
+/** The workflow already has a task; nothing was created. */
+'already-subscribed'
+/** The Host refused to create a Session. */
+ | 'session-failed'
+/** The new Session could not be addressed, so no prompt could be sent. */
+ | 'session-unaddressable'
+/** The prompt was refused (e.g. the Session was not ready to accept it). */
+ | 'prompt-failed'
+/** The selected model could not be installed on the new Session. */
+ | 'model-failed'
+/** The prompt was accepted but no matching task appeared within the budget. */
+ | 'not-created'
+/** Removing the task failed. */
+ | 'cancel-failed';
+/** One snapshot of an attempt. */
+export interface SubscribeState {
+    readonly phase: SubscribePhase;
+    /** Set when `phase` is `failed`. */
+    readonly failure?: SubscribeFailure;
+    /** The task representing the subscription, once known. */
+    readonly taskId?: string;
+    /** The Session created for the attempt, so a failed attempt can say where it went. */
+    readonly sessionId?: string;
+}
+/** Everything the orchestration needs from the outside world. */
+export interface SubscribeDeps<T extends SubscribedTaskView> {
+    /** Read the authoritative task list. */
+    readonly listTasks: () => Promise<readonly T[]>;
+    /** Create a Session and return its id. */
+    readonly createSession: () => Promise<string>;
+    /** Send one text prompt into a Session. Resolves false when it was refused. */
+    readonly sendPrompt: (sessionId: string, text: string) => Promise<boolean>;
+    /** Remove one task (unsubscribe). */
+    /**
+     * Remove one task. The owning Session travels with the id because a Schedule belongs
+     * to the Session that created it, and the Host routes deletion through that binding.
+     */
+    readonly removeTask: (taskId: string, sessionId: string) => Promise<boolean>;
+    /**
+     * The Session's own failure, once its turn has one; undefined while it is still working.
+     *
+     * A turn that ended in an error (an expired provider key, a 5xx from the route, a model
+     * that never called the tool) can never produce a task, so waiting out the whole budget
+     * only delays a failure the Session already knows about. Optional so a caller without a
+     * session face keeps the plain poll; the Host wiring supplies it.
+     */
+    readonly readSessionFailure?: (sessionId: string) => Promise<string | undefined>;
+    /** Wait for one poll interval; injected so tests do not sleep. */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Called on every state change, so the dialog can render progress. */
+    readonly onChange?: (state: SubscribeState) => void;
+}
+/** How a subscribe attempt ended. */
+export interface SubscribeOutcome {
+    readonly ok: boolean;
+    /** Present on success: the task that now exists. */
+    readonly taskId?: string;
+    /** Present on failure: why. */
+    readonly failure?: SubscribeFailure;
+    /** The Session created, when one was; useful for a failure message. */
+    readonly sessionId?: string;
+    /** Set when the Session was opened immediately (no verification wait). */
+    readonly opened?: boolean;
+    /**
+     * Present on `session-failed`: the message the Session's turn ended with, so a caller can
+     * show the real cause instead of pointing the reader at the new Session.
+     */
+    readonly detail?: string;
+}
+/**
+ * How long the verification waits for the model to create the task.
+ *
+ * The prompt has to reach the model, the model has to call `schedule_create`, and the catalog
+ * has to reflect it. Measured on 2026-10-23 against `dashscope/deepseek-v4.1-flash-1017`: the
+ * tool call landed 29 s after the prompt and the task was visible by 33-39 s. The previous
+ * 10 x 1 s budget therefore reported "not created" for subscriptions that succeeded moments
+ * later, which is the false negative the dialog used to show.
+ */
+export declare const VERIFY_ATTEMPTS = 30;
+export declare const VERIFY_INTERVAL_MS = 3000;
+/**
+ * The exact instruction handed to the new Session.
+ *
+ * Written as a repeatable order rather than a conversation opener: it names the tool,
+ * gives the cron, supplies the standing instruction, and quotes the marker line to
+ * reproduce. The marker is quoted as literal text because it is what later recognition
+ * keys on; a paraphrase would still be caught by the title fallback, but the reliable
+ * path is worth asking for directly.
+ *
+ * @param workflow - the workflow being subscribed.
+ * @param cron - the expression the reader chose.
+ * @returns the prompt text.
+ */
+export declare function subscriptionPrompt(workflow: WorkflowDefinition, cron: string): string;
+/**
+ * Subscribe one workflow.
+ *
+ * The sequence is: refuse early if already subscribed, create a Session, ask it to
+ * schedule the work, then prove the task exists. Success is only ever reported from a
+ * verified read.
+ *
+ * @param workflow - workflow to subscribe.
+ * @param cron - the expression chosen in the dialog.
+ * @param deps - injected Host operations.
+ * @returns the outcome, including the created task id on success.
+ */
+export declare function subscribeWorkflow<T extends SubscribedTaskView>(workflow: WorkflowDefinition, cron: string, deps: SubscribeDeps<T>): Promise<SubscribeOutcome>;
+/**
+ * Everything the immediate-open subscription needs.
+ *
+ * Deliberately no `sleep`/`readSessionFailure`: this path never waits for the task. It
+ * ends as soon as the prompt is accepted and the Session is opened; the turn continues
+ * in the conversation and the plaza re-reads the catalog when the reader returns.
+ */
+export interface CreateSubscriptionDeps<T extends SubscribedTaskView> extends Omit<SubscribeDeps<T>, 'sleep' | 'readSessionFailure'> {
+    /** Install the chosen model on the new Session, before the prompt is sent. */
+    readonly selectModel?: (sessionId: string, selection: WorkflowModelSelection) => Promise<boolean>;
+    /** Focus the new Session immediately. */
+    readonly openSession?: (sessionId: string) => void;
+}
+/**
+ * Create the subscription Session and open it without waiting for the task.
+ *
+ * The old flow verified `schedule_create` inside the dialog, which kept "订阅中…" on
+ * screen for up to 90 s and made a slow model look like a failed subscription. This
+ * path does only what the reader asked for: create the Session, install the chosen
+ * model, deliver the scheduling prompt, then open the conversation. The task appears
+ * there; the plaza's next catalog read turns the card into 「退订」.
+ *
+ * @param workflow - workflow to subscribe.
+ * @param cron - the frequency chosen in the dialog.
+ * @param model - the selected model, or undefined to keep the workspace default.
+ * @param deps - injected Host operations.
+ * @returns `ok` once the prompt was accepted; no verification wait.
+ */
+export declare function createSubscriptionSession<T extends SubscribedTaskView>(workflow: WorkflowDefinition, cron: string, model: WorkflowModelSelection | undefined, deps: CreateSubscriptionDeps<T>): Promise<SubscribeOutcome>;
+/**
+ * Unsubscribe one workflow by removing the task that represents it.
+ *
+ * @param taskId - task to remove, from a previous {@link findSubscription}.
+ * @param sessionId - Session that owns the task.
+ * @param deps - injected Host operations (only `removeTask` is used).
+ * @returns whether the task was removed.
+ */
+export declare function unsubscribeWorkflow<T extends SubscribedTaskView>(taskId: string, sessionId: string, deps: Pick<SubscribeDeps<T>, 'removeTask' | 'onChange'>): Promise<boolean>;

package/lib/types/embeddings.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Embedding provider calls for optional vector retrieval.
+ *
+ * The provider is deliberately small and deployment-owned: an OpenAI-compatible
+ * `/v1/embeddings` endpoint or an Ollama `/api/embeddings` endpoint. The API key is
+ * never part of configuration or a stored record; callers pass the resolved value for
+ * one request, and the settings page only ever shows the credential reference.
+ *
+ * @module @sparkelf/dsh-knowledge-base/embeddings
+ */
+/** Providers this plugin can call. */
+export type EmbeddingProvider = 'openai-compatible' | 'ollama';
+/** Vector retrieval settings. Every switch defaults off. */
+export interface VectorRetrievalConfig {
+    /** Whether vector retrieval and background embedding are enabled. */
+    enabled: boolean;
+    /** Embedding API shape. */
+    provider: EmbeddingProvider;
+    /** Provider base URL, without a trailing slash requirement. */
+    baseUrl: string;
+    /** Embedding model name. */
+    model: string;
+    /** Expected vector width; `0` accepts and records the provider's width. */
+    dimensions: number;
+    /** Credential-store reference for an API key; never the key itself. */
+    credentialRef: string;
+    /** RRF constant used by hybrid fusion. */
+    rrfK: number;
+    /** How many FTS and vector candidates each side contributes before fusion. */
+    candidateK: number;
+    /** RRF weight of the FTS component. */
+    ftsWeight: number;
+    /** RRF weight of the vector component. */
+    vectorWeight: number;
+}
+/** Defaults: no network calls, no vector storage, and the standard RRF shape. */
+export declare const DEFAULT_VECTOR_RETRIEVAL: VectorRetrievalConfig;
+/** A structured provider failure that callers can report without exposing a key. */
+export declare class EmbeddingProviderError extends Error {
+    readonly status?: number | undefined;
+    readonly name = "EmbeddingProviderError";
+    constructor(message: string, status?: number | undefined);
+}
+/** Normalize a base URL and append the provider's embedding path. */
+export declare function embeddingEndpoint(config: Pick<VectorRetrievalConfig, 'provider' | 'baseUrl'>): string;
+/**
+ * Embed one batch of texts.
+ *
+ * OpenAI-compatible providers accept a batch and return one row per input. Ollama's
+ * documented `/api/embeddings` endpoint is singular, so its inputs are requested in
+ * order; callers still control the batch size and keep provider concurrency bounded.
+ */
+export declare function embedTexts(config: Pick<VectorRetrievalConfig, 'provider' | 'baseUrl' | 'model' | 'dimensions'>, texts: readonly string[], apiKey?: string): Promise<number[][]>;
+/**
+ * Validate one stored retrieval object.
+ *
+ * Unknown values fall back field by field rather than invalidating the group, so a
+ * hand-edited file cannot switch a provider on with a half-valid configuration.
+ * @param raw - parsed settings value.
+ * @returns A complete, safe vector configuration.
+ */
+export declare function normalizeVectorRetrieval(raw: unknown): VectorRetrievalConfig;

package/lib/types/externalChange.d.ts

@@ -0,0 +1,25 @@
+/** Record a path this process is about to write, so the watcher can ignore its event. */
+export declare const markInternalMutation: (relPath: string) => void;
+/** Whether an event belongs to a write this process already audited. */
+export declare const isInternalMutation: (relPath: string, now?: number) => boolean;
+/** Clear the suppression map between tests. */
+export declare const resetInternalMutationsForTests: () => void;
+export type ExternalChangeDetail = 'updated' | 'renamed' | 'deleted';
+export interface ExternalChangeWatcherOptions {
+    /** The authoritative tree, not the per-user view. */
+    actualRoot: string;
+    /** Called once per debounced path. May be async; rejections are logged, not thrown. */
+    onChange: (relPath: string, detail: ExternalChangeDetail) => void | Promise<void>;
+    /** Optional warning sink; defaults to silent. */
+    log?: (message: string) => void;
+    debounceMs?: number;
+    retryMs?: number;
+}
+/**
+ * Start observing the authoritative tree.
+ *
+ * Returns a disposer. The watcher retries when the root does not exist yet (the
+ * plugin can load before a workspace provisions its tree) and is closed on dispose.
+ * `persistent: false` keeps the watcher from holding the process alive on its own.
+ */
+export declare const startExternalChangeWatcher: (options: ExternalChangeWatcherOptions) => (() => void);

package/lib/types/extract.d.ts

@@ -33,6 +33,34 @@
 export declare const EXTRACTABLE_EXTENSIONS: readonly [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp", ".rtf"];
 /** One extractable extension. */
 export type ExtractableExtension = typeof EXTRACTABLE_EXTENSIONS[number];
+/**
+ * Formats that are already plain text, so there is nothing to extract.
+ *
+ * A `.md` document IS the Markdown an extraction would produce. Asking for one to be
+ * extracted is not a failure and not an unsupported format: the honest answer is that no
+ * work is needed. Without this list such a request fell through to "this type has no
+ * extractor", which told a reader their own Markdown file was unreadable.
+ */
+export declare const MARKDOWN_EXTENSIONS: readonly [".md", ".markdown", ".mdown", ".mkd"];
+/**
+ * Whether this path is already Markdown.
+ * @param relPath - the document's path.
+ * @returns Whether no extraction is needed.
+ */
+export declare function isAlreadyMarkdown(relPath: string): boolean;
+/** One MinerU layout block, normalized for the SQLite provenance tables. */
+export interface MineruBlock {
+    page: number;
+    bbox: [number, number, number, number];
+    text: string;
+    type: string;
+    blockIndex: number;
+    occurrence: number;
+    confidence?: number;
+    pageWidth?: number;
+    pageHeight?: number;
+    coordSpace: 'normalized' | 'points';
+}
 /** How one request to the extraction authorities ended. */
 export interface ExtractResult {
     /** Markdown text, when extraction produced any. */
@@ -48,6 +76,8 @@ export interface ExtractResult {
     via?: 'mineru' | 'mineru-ocr' | 'libreoffice' | 'python' | 'native';
     /** Why no markdown was produced. Present whenever {@link markdown} is absent. */
     reason?: string;
+    /** Layout blocks from MinerU (`middle_json`), used only for provenance metadata. */
+    blocks?: MineruBlock[];
 }
 /**
  * Whether this path names a document worth extracting.
@@ -107,6 +137,8 @@ export declare function prefersRemoteParser(ext: string): boolean;
  * @returns true when the answer is short enough that a classifier mistake is likely.
  */
 export declare function looksTooThinToSearch(markdown: string): boolean;
+/** Parse MinerU's middle_json pages/blocks into provenance rows. */
+export declare function parseMineruBlocks(value: unknown): MineruBlock[];
 /** Services and commands extraction may use, as configured for this deployment. */
 export interface ExtractOptions {
     /** MinerU base URL. Empty disables the remote parser. */

package/lib/types/extractionQueue.d.ts

@@ -17,13 +17,25 @@
  * @module @sparkelf/dsh-knowledge-base/extractionQueue
  */
 /** Lifecycle of one extraction task. */
-export type ExtractionState = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported';
+export type ExtractionState = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported'
+/**
+ * The document is already Markdown, so no extraction was needed.
+ *
+ * Distinct from `succeeded` (a sibling WAS written) and from `unsupported` (no reader
+ * exists for the format). Reporting a `.md` file as `unsupported` told a reader their own
+ * Markdown was unreadable, which is both wrong and alarming.
+ */
+ | 'already-markdown';
+/** The visible stage after the parser accepted a document. */
+export type ExtractionStep = 'parse' | 'chunk' | 'index' | 'done';
 /** One extraction task, as a reader observes it. */
 export interface ExtractionTask {
     /** Knowledge-relative path of the SOURCE document. */
     relPath: string;
     /** Where the task is in its lifecycle. */
     state: ExtractionState;
+    /** Current Agentic RAG stage: parse → chunk → index → done. */
+    step?: ExtractionStep;
     /** When the task was accepted, ISO-8601. */
     queuedAt: string;
     /** When the run started, ISO-8601. */
@@ -77,7 +89,7 @@ export interface ExtractionQueueOptions {
      * @param mineruBaseUrl - the caller's own parser address, when set.
      * @returns the terminal state of the run.
      */
-    run: (relPath: string, mineruBaseUrl: string | undefined) => Promise<ExtractionOutcome>;
+    run: (relPath: string, mineruBaseUrl: string | undefined, reportStep?: (step: ExtractionStep) => void) => Promise<ExtractionOutcome>;
     /**
      * Whether this path can be extracted at all.
      *
@@ -85,6 +97,15 @@ export interface ExtractionQueueOptions {
      * occupying the single worker slot to discover it has no reader.
      */
     isExtractable: (relPath: string) => boolean;
+    /**
+     * Whether this path is already Markdown, so no extraction is needed.
+     *
+     * Separate from `isExtractable` because the two answer different questions: `false`
+     * from `isExtractable` means "no reader exists" (a failure), while `true` here means
+     * "there is nothing to read" (a success). Collapsing them is what reported a reader's
+     * own `.md` file as an unreadable format.
+     */
+    isAlreadyMarkdown: (relPath: string) => boolean;
 }
 /** One extraction queue. One instance per plugin registration. */
 export interface ExtractionQueue {