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

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

@@ -1,129 +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

@@ -1,33 +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

@@ -1,82 +1,82 @@
-/**
- * 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;
@@ -89,62 +89,62 @@ export interface ReadRepairTuning {
             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
+ 

package/lib/types/sandbox.d.ts

@@ -1,23 +1,23 @@
-/**
- * The sandbox-escalation API shared by the `write` and `edit` tools: the
- * per-call policy resolution, the advertised escalation fields, and the denial-marker
- * mapping — all delegating the vocabulary and the fail-closed approval
- * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
- * uses), so bash and fs escalate identically. Built ONCE per plugin from
- * `ctx.fs.sandboxMode` (the capability fact — is a confining backend mounted?)
- * and shared by both mutating tools.
- *
- * @module @deepseek-ai/dsh-tool-fs/sandbox
- */
+
+
+
+
+
+
+
+
+
+
+
 import type { Context } from '@deepseek-ai/cordis';
 import type { ToolExecution } from '@deepseek-ai/dsh-tools';
 import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
-/** The two escalation arguments a mutating tool may carry (advertised only under a confining backend). */
+ 
 export interface FsEscalationArgs {
     sandbox_permissions?: string;
     justification?: string;
 }
-/** The schema fields for the escalation arguments, spread into a tool's `parameters` when a confining backend is mounted. */
+ 
 export interface EscalationSchemaFields {
     sandbox_permissions: {
         type: 'string';
@@ -29,54 +29,54 @@ export interface EscalationSchemaFields {
         description: string;
     };
 }
-/**
- * The filesystem escalation API: advertisement gating, per-call policy
- * resolution, the one-approved wider retry, and denial-marker mapping. A pure
- * product of `ctx` at plugin apply time.
- */
+
+
+
+
+
 export declare class FsSandboxController {
     private readonly ctx;
-    /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+     
     readonly escalationModes: readonly SandboxMode[];
-    /** Shared per-session policy resolver, required by a confining backend. */
+     
     private readonly policy;
     constructor(ctx: Context);
-    /**
-     * The escalation schema fields for a mutating tool's `parameters`. Call it
-     * only under a confining backend (guard on {@link escalationModes}); the
-     * enum pins the closed target vocabulary, the strict-wider check happens per
-     * call at execution.
-     * @returns the two escalation parameter specs.
-     */
+    
+
+
+
+
+
+
     schemaFields(): EscalationSchemaFields;
-    /**
-     * The policy to stamp onto this mutation: an approved escalation grant (a
-     * strictly wider retry resolved through `ctx.approval` before anything
-     * executes), else the session's standing mode. Repeating the standing mode
-     * requires no approval. The calling session's cwd is
-     * always carried as the workspace root. Validates the escalation argument
-     * pairing first.
-     * @param toolName - the mutating tool's name, for the approval audit trail.
-     * @param args - the call's escalation arguments.
-     * @param exec - the tool-execution context (agent, callId, signal).
-     * @returns the policy to pass to the mutation, or undefined for an
-     *   unsandboxed backend.
-     */
+    
+
+
+
+
+
+
+
+
+
+
+
+
     resolvePolicy(toolName: string, args: FsEscalationArgs, exec: ToolExecution): Promise<SandboxExecutionPolicy | undefined>;
-    /**
-     * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes a
-     * `FsError` whose text is the shared `[sandbox: …]` denial marker plus the
-     * same-turn escalation hint, so a policy denial reads identically to bash's
-     * WHILE keeping the structured `FS_SANDBOX_DENIED` code — `ToolRuntime`
-     * populates `result.error` only for `HarnessError` instances, so a plain
-     * `Error` would strip the code retry/observers key off. Any other error
-     * passes through unchanged. A `FS_SANDBOX_DENIED` only arises under a
-     * confining backend, which always advertises the escalation fields, so the
-     * hint always applies here.
-     * @param error - the error thrown by the mutation.
-     * @param policy - the policy stamped onto the call (names the mode in the marker).
-     * @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
-     */
+    
+
+
+
+
+
+
+
+
+
+
+
+
+
     mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown;
 }
-//# sourceMappingURL=sandbox.d.ts.map
+