@swoop111/dsh-tool-fs 0.0.0-stage → 0.2.0-rc.2

package/lib/types/completion.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Window completion for reads: the neighbouring lines that give a delivered
+ * window its structural boundaries. The head is the single line that opened
+ * the construct the window starts inside; the tail is the run of following
+ * lines that closes the construct the window ends inside. Neither ever
+ * modifies, reorders, or drops a delivered line — a window either gains
+ * context or stays exactly as the caller asked for it.
+ *
+ * The head is one line because everything between that opening line and the
+ * window is the content the caller chose to skip; the tail is a run because
+ * the construct cannot be called closed until its closer arrives.
+ * @module @deepseek-ai/dsh-tool-fs/completion
+ */
+import type { FileTextLine } from './read-render.ts';
+import type { CompletionRule } from './structure.ts';
+/** Fetches up to `count` lines of the file on one side of the window, in file order. */
+export type LineSupplier = (count: number) => Promise<FileTextLine[] | undefined>;
+/** Where a completion fetches the lines on each side of the window. */
+export interface CompletionLineSuppliers {
+    /**
+     * The lines immediately before the window, in file order; the last entry is
+     * the window's predecessor line. `undefined` signals that no such line exists.
+     */
+    preceding: LineSupplier;
+    /**
+     * The lines immediately after the window, in file order; the first entry is
+     * the window's successor line. `undefined` signals end of file.
+     */
+    following: LineSupplier;
+}
+/** Configuration for window completion; the only field is a hard cap. */
+export interface CompletionTuning {
+    /**
+     * Maximum lines appended to close the tail, and how far back the head search
+     * may reach for the line that opened the construct.
+     */
+    maxLines: number;
+}
+/** The neighbouring lines a window gained, and the rules that found them. */
+export interface CompletionResult {
+    /** The line that opened the construct the window starts inside; empty when the window starts at a boundary. */
+    head: FileTextLine[];
+    /** The lines that close the construct the window ends inside; empty when the tail is balanced. */
+    tail: FileTextLine[];
+    /** The rule that produced `head`; absent when nothing was prepended. */
+    headRule?: CompletionRule;
+    /** The rule that produced `tail`; absent when nothing was appended. */
+    tailRule?: CompletionRule;
+}
+/**
+ * Complete a window's structural boundaries.
+ * @param lines - the delivered window lines, in file order.
+ * @param supply - the line sources on each side of the window.
+ * @param tuning - the hard caps for the added lines.
+ * @returns the head and tail lines with the rules that produced them; `undefined` when neither side completes.
+ */
+export declare function completeWindow(lines: readonly FileTextLine[], supply: CompletionLineSuppliers, tuning: CompletionTuning): Promise<CompletionResult | undefined>;
+//# sourceMappingURL=completion.d.ts.map

package/lib/types/diff.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Result-time contextual diff presentation for write and edit. Storage returns before/after
+ * text; this model-facing layer derives one three-line-context card per applied hunk.
+ * @module @deepseek-ai/dsh-tool-fs/src/diff
+ */
+import type { FileDiff } from '@deepseek-ai/dsh-tools';
+/** Context lines shown on each side of an applied hunk. */
+export declare const DIFF_CONTEXT = 3;
+/**
+ * The `write`/`edit` tools' private `tool/result` `meta` payload: the applied
+ * contextual-diff hunks, and for `write` whether the call created or updated
+ * the file, which tells an empty hunk list of a create from one of an
+ * unchanged overwrite. Attached opaquely (as `unknown`) on the tool result and
+ * persisted with the session log — it must be JSON-serializable (the session
+ * validates this at `append`), so `presentResult` reproduces the diff card on
+ * replay. The producing tool owns and narrows this opaque shape.
+ */
+export type FsDiffMeta = {
+    diffs: FileDiff[];
+    operation?: 'create' | 'update';
+};
+/**
+ * Compute one {@link FileDiff} per hunk between `before` and `after`, each carrying the
+ * applied change plus {@link DIFF_CONTEXT} context lines. Pure insertions use `oldText: null`,
+ * patch-only no-newline markers are omitted, and scattered replacements remain separate hunks.
+ *
+ * @param path - the path stamped on every produced diff (the model-facing `file_path`; the
+ *   bridge relativizes it).
+ * @param before - the file text before the change (the backend's LF-normalized diff basis).
+ * @param after - the file text after the change, on the same basis.
+ * @returns one diff per applied hunk, in file order; empty when the texts are identical.
+ */
+export declare function computeHunkDiffs(path: string, before: string, after: string): FileDiff[];
+/**
+ * Narrow opaque live or replayed result metadata to non-empty file diffs. Malformed metadata
+ * returns `undefined` so presentation can fall back instead of throwing during replay.
+ * @param meta - result metadata.
+ * @returns validated hunks, or `undefined` for absent or malformed data.
+ */
+export declare function diffsFromMeta(meta: unknown): FileDiff[] | undefined;
+//# sourceMappingURL=diff.d.ts.map

package/lib/types/edit.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Model-facing literal edit, unique-match by default. It obtains an optional guard from the
+ * single intent slot, calls `ctx.fs.editText` without a separate stat, then records the observed
+ * version; no policy means an unconditional atomic edit. When the literal match fails or is
+ * ambiguous, the `@deepseek-ai/dsh-fs-edit-repair` engine re-anchors the pair before the error
+ * reaches the model.
+ * @module @deepseek-ai/dsh-tool-fs/src/edit
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { FsSandboxController } from './sandbox.ts';
+/** Repair tuning for failed `edit` matches; rules live in `@deepseek-ai/dsh-fs-edit-repair`. */
+export interface EditRepairConfig {
+    /** Disable the repair engine so failed matches always error (default enabled). */
+    enabled?: boolean;
+    /** Content length above which the line-window repair rules are skipped. */
+    maxFileChars?: number;
+    /** `old_string` line count above which the line-window repair rules are skipped. */
+    maxWindowLines?: number;
+}
+/**
+ * The edit repair tuning after defaulting, plus the session path-history
+ * source for missing-target re-anchoring.
+ */
+export interface EditRepairTuning {
+    /** Master switch: failed-match repair and missing-path re-anchoring. */
+    enabled: boolean;
+    /** Content length above which the line-window repair rules are skipped. */
+    maxFileChars: number;
+    /** `old_string` line count above which the line-window repair rules are skipped. */
+    maxWindowLines: number;
+    /**
+     * Absolute path arguments of the session's prior successful tool calls, most
+     * recent first — the missing-path re-anchor's history source.
+     */
+    priorPaths(session: Session | undefined, limit?: number): string[];
+}
+/** Validated `edit` arguments after defaulting. */
+interface EditInput {
+    filePath: string;
+    oldString: string;
+    newString: string;
+    replaceAll: boolean;
+}
+/**
+ * Validate value constraints the schema DSL can't express: a non-blank
+ * `file_path`, a non-empty `old_string`, and `old_string !== new_string`
+ * (an equal pair would be a guaranteed no-op edit).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input with `replace_all` defaulted to false.
+ */
+export declare function parseEditArgs(args: {
+    file_path: string;
+    old_string: string;
+    new_string: string;
+    replace_all?: boolean;
+}): EditInput;
+/**
+ * Format an edit success (single-match or replace-all) as a Claude-style model-facing message.
+ * @param displayPath - the backend-resolved path shown to the model.
+ * @param replaceAll - selects the all-occurrences wording over the single-replacement one.
+ * @returns the confirmation sentence the model sees as the tool result.
+ */
+export declare function formatEditOutput(displayPath: string, replaceAll: boolean): string;
+/**
+ * Register the `edit` tool and its scope-aware system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
+ * @param repair - the resolved tuning for the failed-match repair engine and missing-path re-anchoring.
+ */
+export declare function applyEditTool(ctx: Context, sandbox: FsSandboxController, repair: EditRepairTuning): void;
+export {};
+//# sourceMappingURL=edit.d.ts.map

package/lib/types/error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model-facing diagnostics for guarded-mutation failures. Providers and
+ * policies retain operation-specific causes, while this package owns the
+ * stable message shown to the model.
+ * @module @deepseek-ai/dsh-tool-fs/src/error
+ */
+/**
+ * Render the stable model-facing diagnostic for a guarded-mutation failure.
+ * `FS_STALE_VERSION` keeps the provider's reason and appends its re-read
+ * remedy. `FS_NOT_OBSERVED` replaces operation-specific policy/provider text
+ * with one path-aware reason and read remedy. The original error remains the
+ * cause, and both diagnostics preserve its code for machine routing. Anything
+ * else passes through untouched.
+ * @param error - the caught value from a write/edit execution.
+ * @param displayPath - the resolved target path shown to the model.
+ * @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+ */
+export declare function remediateFsError(error: unknown, displayPath: string): unknown;
+//# sourceMappingURL=error.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Model-facing read, read_image, write, and edit tools over `ctx.fs`. This package owns schemas, validation,
+ * read windows, formatting, and observation events, never a concrete provider. An optional
+ * event policy supplies mutation guards; without one the tools use unconditional provider calls.
+ * @module @deepseek-ai/dsh-tool-fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ReadRepairConfig } from './read.ts';
+import type { WriteRepairConfig } from './write.ts';
+import type { EditRepairConfig } from './edit.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "tool-fs";
+/** Services required by the filesystem tool suite. */
+export declare const inject: string[];
+/** Plugin config (all optional — `Config` supplies the defaults). */
+export interface Config {
+    /** Default and maximum number of lines returned by one `read` call. */
+    readLimit?: number;
+    /** Maximum characters returned for a single line before truncation. */
+    readMaxLineLength?: number;
+    /** Maximum bytes returned for the selected lines of one `read` call. */
+    readMaxBytes?: number;
+    /** Files at or above this size stream instead of loading whole into memory. */
+    readStreamMinSize?: number;
+    /** Repair tuning applied when `edit`'s `old_string` fails to match verbatim (enabled by default). */
+    editRepair?: EditRepairConfig;
+    /** Repair tuning for the `read` tool's addressing and path failures (enabled by default). */
+    readRepair?: ReadRepairConfig;
+    /** Tuning for the `write` tool's drifted-path hint on creates (enabled by default). */
+    writeRepair?: WriteRepairConfig;
+}
+export declare const Config: z<Config>;
+/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/read-image.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. A path
+ * without a file extension is identified from its file signature, while the
+ * attachment service's full decode stays authoritative. The mounted `ctx.fs`
+ * backend owns path resolution and read access; names only declare media type.
+ *
+ * The route gate is deliberately stricter than the host upload preflight. An
+ * image-reading tool is useful only when the exact calling route can inspect
+ * its result, so unknown capability refuses instead of relying on an adapter
+ * failure after filesystem and attachment work.
+ * @module @deepseek-ai/dsh-tool-fs/src/read-image
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * Identify the media type declared by a supported image file signature.
+ * @param data - file bytes read through the current filesystem backend.
+ * @returns the detected supported media type, or undefined for other bytes.
+ */
+export declare function sniffImageMediaType(data: Uint8Array): ImageMediaType | undefined;
+/** The structured outcome declared by the `read_image` output schema. */
+export interface ImageReadValue {
+    path: string;
+    image: {
+        attachmentId: string;
+        mediaType: ImageMediaType;
+        bytes: number;
+        width: number;
+        height: number;
+        name?: string;
+        /** Orientation-applied file dimensions before normalization; present only when storage reduced it. */
+        originalDimensions?: {
+            width: number;
+            height: number;
+        };
+    };
+}
+/**
+ * Map a model-supplied path to its declared image media type by extension.
+ * @param filePath - the raw `file_path` argument (not yet resolved).
+ * @returns the declared media type, or undefined when the path does not claim an image.
+ */
+export declare function imageMediaTypeForPath(filePath: string): ImageMediaType | undefined;
+/**
+ * Enforce the strict image-capability gate for the calling route. Resolves the
+ * session's latest routed provider/model (request header config, then agent
+ * options) and requires the exact resolved route to declare `image` input explicitly.
+ * @param ctx - the plugin context used to resolve the optional `llm` service.
+ * @param exec - the tool-execution context supplying the calling agent.
+ * @param requestedPath - the raw, not-yet-resolved path rendered in refusal messages.
+ */
+export declare function assertImageCapableRoute(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<void>;
+/**
+ * Re-brand a structured image outcome into the durable attachment reference an
+ * `ImageBlock` carries.
+ * @param image - the image metadata from the output schema.
+ * @returns the branded attachment reference.
+ */
+export declare function imageRefFromValue(image: ImageReadValue['image']): ImageAttachmentRef;
+/**
+ * Format an image read as the model-facing envelope beside its image block.
+ * A downscaled read names the on-disk dimensions and the multiplier that maps
+ * coordinates measured on the attached image back onto the original file.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param image - the image metadata to summarize.
+ * @returns the model-facing envelope; the image itself rides the adjacent image block.
+ */
+export declare function formatImageReadOutput(displayPath: string, image: ImageReadValue['image']): string;
+/**
+ * Register the `read_image` tool into the given context. The composing plugin
+ * owns the attachments gate: `src/index.ts` calls this inside
+ * `ctx.inject(['attachments'], …)` so the tool exists only while a durable
+ * store is mounted. Execution still re-checks `ctx.get('attachments')` for
+ * direct callers and gates on the calling route's declared image input.
+ * @param ctx - the registration scope; execution uses its `fs` service plus
+ *   the optional `attachments`/`llm` services.
+ */
+export declare function applyReadImageTool(ctx: Context): void;
+//# sourceMappingURL=read-image.d.ts.map

package/lib/types/read-render.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure read presentation: turn provider-decoded text into a bounded, line-numbered window and
+ * model-facing envelope. Chunk scanning caps the current line, so even one newline-free giant
+ * line cannot grow memory without bound.
+ * @module @deepseek-ai/dsh-tool-fs/read-render
+ */
+/** Default maximum characters returned for a single line (the `readMaxLineLength` config). */
+export declare const READ_MAX_LINE_LENGTH = 2000;
+/** Default maximum bytes returned for selected file lines (the `readMaxBytes` config). */
+export declare const READ_MAX_BYTES: number;
+/** Resolved read window. The consumer applies its defaults/caps before calling. */
+export interface ReadWindow {
+    /** 1-based first line to return. */
+    offset: number;
+    /** Maximum number of lines to return. */
+    limit: number;
+    /** Maximum characters returned for a single line; overflow is truncated with a suffix. */
+    maxLineLength: number;
+    /** Maximum bytes of selected output; overflow stops the scan and marks `truncatedByBytes`. */
+    maxBytes: number;
+}
+/** One line returned from a text file. */
+export interface FileTextLine {
+    /** 1-based line number in the file. */
+    number: number;
+    /** Line text without its trailing newline. */
+    text: string;
+}
+/** The windowed result {@link buildWindow} produces from a file's decoded text. */
+export interface WindowResult {
+    /** Returned lines, already numbered. */
+    lines: FileTextLine[];
+    /** Exact total line count in the file. */
+    totalLines: number;
+    /** Whether selected output hit the byte cap. */
+    truncatedByBytes: boolean;
+}
+/** Outcome of a bounded text read — what {@link formatReadOutput} renders. */
+export interface FileReadOutcome {
+    /** 1-based first line requested. */
+    offset: number;
+    /** Returned lines, already numbered. */
+    lines: FileTextLine[];
+    /** Exact total line count in the file. */
+    totalLines: number;
+    /** Whether selected output hit the byte cap. */
+    truncatedByBytes?: true;
+    /** What read repair normalized, rendered after the footer; undefined when no repair fired. */
+    repairNote?: string;
+}
+/** The scan facts {@link parseOffsetOutOfRange} extracts from one offset-out-of-range failure. */
+export interface OffsetOutOfRange {
+    /** The 1-based start line the caller requested. */
+    requestedOffset: number;
+    /** Exact total line count the scan observed. */
+    totalLines: number;
+}
+/**
+ * Recognize this package's own offset-out-of-range `FsError` and return its scan
+ * facts, so the read tool can tail-anchor the window instead of erroring. The
+ * message and this parser live in the same module on purpose: the format is a
+ * package-internal contract, pinned by tests on both sides.
+ * @param error - the caught value from {@link buildWindow}.
+ * @returns the requested offset and observed line count, or `undefined` for any other failure.
+ */
+export declare function parseOffsetOutOfRange(error: unknown): OffsetOutOfRange | undefined;
+/**
+ * Build one window from streamed or whole-file chunks, enforcing line and byte caps while still
+ * scanning to an exact total line count, and throwing `FS_NOT_FOUND` when the requested offset is
+ * past EOF.
+ * @param chunks - decoded text chunks in file order; chunk boundaries carry no meaning.
+ * @param request - the resolved window; the caller has already applied its defaults and caps.
+ * @param displayPath - the caller-facing path used in the offset-out-of-range error.
+ * @returns the numbered window lines, the total line count seen, and the byte-cap truncation flag.
+ */
+export declare function buildWindow(chunks: AsyncIterable<string> | Iterable<string>, request: ReadWindow, displayPath: string): Promise<WindowResult>;
+/**
+ * Format a read outcome as one OpenCode-style line-numbered text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the windowed read to render.
+ * @returns the model-facing envelope: numbered lines, a continuation or end-of-file footer, and the repair disclosure when one fired.
+ */
+export declare function formatReadOutput(displayPath: string, outcome: FileReadOutcome): string;
+/**
+ * Derive the persisted `lang` hint from a read path's file extension. The shared
+ * table in `@deepseek-ai/dsh-util-code-language` owns the recognized suffixes and
+ * the path rules (both separators, a leading dot as the extension separator, and
+ * prototype-key safety); `readLangHintForPath` projects the read card's short ids
+ * over it, so a suffix whose value a recorded session already holds keeps it
+ * byte-identical while every other suffix uses its language's short name.
+ * @param path - the model-facing path the read reported.
+ * @returns the persisted language hint, or `undefined` when the extension maps to none.
+ */
+export { readLangHintForPath as langFromPath } from '@deepseek-ai/dsh-util-code-language';
+/**
+ * The `read` tool's private `tool/result` `meta` payload: the structured
+ * line-numbered window a capable UI renders as a code view. Attached opaquely (as
+ * `unknown`) on the tool result and persisted with the session log — it must be
+ * JSON-serializable (the session validates this at `append`), so `presentResult`
+ * reproduces the read card on replay when the raw structured output is no longer
+ * on the wire. The producing tool owns and narrows this opaque shape.
+ */
+export interface FsReadMeta {
+    /** The read file's model-facing path. */
+    path: string;
+    /** The 1-based first line the window requested, kept even when `lines` is empty. */
+    offset: number;
+    /** The returned window's lines, each keeping its file line number. */
+    lines: FileTextLine[];
+    /** Exact total line count in the file. */
+    totalLines: number;
+    /** Syntax-highlighting language hint from the extension, or omitted for plain text. */
+    lang?: string;
+}
+/**
+ * Narrow opaque live or replayed result metadata to a structured read window.
+ * Malformed metadata returns `undefined` so presentation can fall back to the
+ * generic text card instead of throwing during replay. Beyond shape, the
+ * semantic contract of a read window is enforced against replayed JSON that is
+ * well-typed but out of range: `offset` must be a 1-based integer, `totalLines`
+ * must be a non-negative integer, each line number must be a 1-based integer no
+ * less than `offset`, the line numbers must strictly increase, and no line number
+ * may exceed `totalLines`. Any violation declines to the generic fallback rather
+ * than emitting a card that misnumbers or overcounts.
+ * @param meta - result metadata.
+ * @returns the validated read window, or `undefined` for absent, malformed, or semantically invalid data.
+ */
+export declare function readMetaFromMeta(meta: unknown): FsReadMeta | undefined;
+//# sourceMappingURL=read-render.d.ts.map

package/lib/types/read-target.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared path resolution and regular-file validation for model-facing read tools.
+ * @module @deepseek-ai/dsh-tool-fs/src/read-target
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsInfo, FsTarget } from '@deepseek-ai/dsh-fs';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { MissingPathRepair } from '@deepseek-ai/dsh-fs-edit-repair';
+/**
+ * Resolve a model-supplied path, observe absence, and require a regular file.
+ * @param ctx - the plugin context providing filesystem resolution and observation events.
+ * @param exec - the current tool execution, including session cwd and cancellation.
+ * @param requestedPath - the raw path supplied to the tool.
+ * @returns the resolved target and its single stat result.
+ */
+export declare function resolveRegularReadTarget(ctx: Context, exec: ToolExecution, requestedPath: string): Promise<{
+    target: FsTarget;
+    info: FsInfo;
+}>;
+/**
+ * Attempt the engine's missing-path composition for a failed tool target: a
+ * unique match among the session's prior successful path arguments, then a
+ * unique directory-tree completion, each proven present before adoption. A
+ * tool never re-anchors on ambiguity, so a wrong guess cannot replace a real
+ * answer — the caller keeps its verbatim error when this returns `undefined`.
+ * @param ctx - the plugin context providing filesystem resolution and listing.
+ * @param exec - the current tool execution, including session cwd and cancellation.
+ * @param requestedPath - the raw path the model supplied.
+ * @param knownPaths - the session's prior successful path arguments, most recent first.
+ * @returns the verified replacement path with its disclosure, or `undefined`.
+ */
+export declare function repairTargetPath(ctx: Context, exec: ToolExecution, requestedPath: string, knownPaths: readonly string[]): Promise<MissingPathRepair | undefined>;
+//# sourceMappingURL=read-target.d.ts.map

package/lib/types/read.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+ * streams large or size-unknown files, renders a bounded window, then emits the observation.
+ * @module @deepseek-ai/dsh-tool-fs/src/read
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReadArgRepair } from '@deepseek-ai/dsh-arg-repair';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { ReadDuplicateVerdict } from '@deepseek-ai/dsh-fs-edit-repair';
+/** Default and maximum number of lines returned by one `read` call (the `readLimit` config). */
+export declare const READ_LIMIT = 2000;
+/**
+ * Default streaming threshold (the `readStreamMinSize` config): files at or
+ * above this size stream; smaller files read whole into memory.
+ */
+export declare const STREAM_MIN_SIZE: number;
+/** Resolved read-tool caps — plugin config after defaulting (see `Config` in index.ts). */
+export interface ReadToolCaps {
+    /** Default and maximum number of lines returned by one call. */
+    limit: number;
+    /** Maximum characters returned for a single line. */
+    maxLineLength: number;
+    /** Maximum bytes returned for selected file lines. */
+    maxBytes: number;
+    /** Files at or above this size stream; smaller files read whole into memory. */
+    streamMinSize: number;
+}
+/**
+ * Repair and duplicate-read tuning for the `read` tool; rules live in `@deepseek-ai/dsh-arg-repair`
+ * and `@deepseek-ai/dsh-fs-edit-repair`.
+ */
+export interface ReadRepairConfig {
+    /** Disable the read repairs so invalid windows and missing paths always error (default enabled). */
+    enabled?: boolean;
+    /**
+     * Refuse a read fully covered by this session's recent window of the same
+     * file that no mutation, compaction, or step budget has invalidated — the
+     * model already holds that exact content. On by default.
+     */
+    duplicate?: {
+        /** Master switch for the duplicate-read refusal. */
+        enabled?: boolean;
+        /** Committed steps since the recorded window beyond which the model is assumed to have forgotten the content. */
+        maxSteps?: number;
+    };
+    /**
+     * Complete a window's structural boundaries from the neighbouring lines: the
+     * line that opened the construct the window starts inside, and the lines that
+     * close the construct it ends inside (markdown fence, bracket block, or
+     * indentation block). On by default.
+     */
+    completion?: {
+        /** Master switch for structural window completion. */
+        enabled?: boolean;
+        /** Maximum lines appended to close the tail, and how far back the head search may reach for the opening line. */
+        maxLines?: number;
+    };
+}
+/**
+ * Read repair tuning: the engine switch, the session path-history source, and
+ * the duplicate-read guard with its window projection.
+ * Disabled, every read failure keeps its verbatim error.
+ */
+export interface ReadRepairTuning {
+    /** Master switch for the read repair rules. */
+    enabled: boolean;
+    /**
+     * Absolute path arguments of the session's prior successful tool calls, most
+     * recent first — `repairMissingPath`'s history source.
+     */
+    priorPaths(session: Session | undefined, limit?: number): string[];
+    /**
+     * The duplicate-read guard: `judge` consults the session's window history
+     * before the read runs; `record` stores the delivered window after it.
+     * Disabled, every read runs unconditionally.
+     */
+    duplicate: {
+        enabled: boolean;
+        /** Committed steps since the recorded window beyond which the model is assumed to have forgotten the content. */
+        maxSteps: number;
+        judge(session: Session | undefined, path: string, version: string, window: {
+            offset: number;
+            endLine: number;
+        }): ReadDuplicateVerdict | undefined;
+        record(session: Session | undefined, path: string, observation: {
+            offset: number;
+            endLine: number;
+            totalLines: number;
+            version: string;
+        }): void;
+    };
+    /**
+     * Structural window completion: prepends the line that opened the construct
+     * the window starts inside, and appends the following lines that close the
+     * construct it ends inside (markdown fence, bracket block, indentation
+     * block). Disabled, windows carry exactly the lines the caps selected.
+     * Completion states nothing: the added lines carry their own numbers, so the
+     * model reads where the window starts and stops without being told.
+     */
+    completion: {
+        enabled: boolean;
+        maxLines: number;
+    };
+    /**
+     * Claim the right to state one procedural disclosure in this session.
+     * Normalizing a read argument is stated once per rule: the delivered window
+     * and its footer already carry the effective range, so repeating the sentence
+     * costs tokens without changing what the model can do.
+     * @param session - the reading call's session; `undefined` states every claim.
+     * @param key - the rule's stable id, one per rule rather than per value.
+     * @returns true when this call is the session's first claim of `key`.
+     */
+    claimDisclosure(session: Session | undefined, key: string): boolean;
+}
+/** Validated `read` arguments after defaulting. */
+interface ReadInput {
+    filePath: string;
+    offset: number;
+    limit: number;
+    /** Run the read even when the duplicate guard would intercept it. */
+    force: boolean;
+    /** What arg repair normalized before validation; absent when the raw args were already valid. */
+    repairs?: readonly ReadArgRepair[];
+}
+/**
+ * Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap.
+ * With repair enabled, the measured addressing failures are normalized first through
+ * {@link repairReadArgs}: a 0-based or negative start index and an over-cap or
+ * non-positive limit all carry unambiguous intent, so the value is substituted
+ * and the rule reported instead of erroring.
+ * @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given unrepairable shapes.
+ * @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+ * @param repairEnabled - the read repair engine's switch; disabled keeps the strict validation errors.
+ * @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`, plus the rules that fired.
+ */
+export declare function parseReadArgs(args: {
+    file_path: string;
+    force?: boolean;
+    offset?: number;
+    limit?: number;
+}, maxLimit: number, repairEnabled?: boolean): ReadInput;
+/**
+ * Register the `read` tool and its scope-aware system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param caps - the deployment's resolved read caps (plugin config after defaulting).
+ * @param repair - the read repair tuning; disabled keeps every failure's verbatim error.
+ */
+export declare function applyReadTool(ctx: Context, caps: ReadToolCaps, repair: ReadRepairTuning): void;
+export {};
+//# sourceMappingURL=read.d.ts.map