@qlzt/dsh-tool-fs 0.0.0-stage → 0.2.1-alpha.3

package/lib/types/diff.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 @qlzt/dsh-tool-fs/src/diff
+ */
+import type { FileDiff } from '@qlzt/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;
+/**
+ * Read the operation's file path even when the applied diff is empty.
+ * @param meta - opaque persisted result metadata.
+ * @returns the recorded path, or undefined for old or malformed metadata.
+ */
+export declare function pathFromMeta(meta: unknown): string | undefined;
+//# sourceMappingURL=diff.d.ts.map

package/lib/types/edit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ * @module @qlzt/dsh-tool-fs/src/edit
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsSandboxController } from './sandbox.ts';
+/** 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).
+ */
+export declare function applyEditTool(ctx: Context, sandbox: FsSandboxController): 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 @qlzt/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,27 @@
+/**
+ * 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 @qlzt/dsh-tool-fs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** 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;
+}
+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/mutation-result.d.ts

@@ -0,0 +1,18 @@
+/** Shared observation and result fields for successful file mutations. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsTarget, FsVersion } from '@qlzt/dsh-fs';
+import type { ToolExecution } from '@qlzt/dsh-tools';
+/**
+ * Record the new file version and expose the mutation result with its canonical path.
+ * @param ctx - filesystem and observation event owner.
+ * @param target - resolved file that was mutated.
+ * @param outcome - successful provider result; its version stays in the observation event.
+ * @param exec - calling tool execution.
+ * @returns the provider's result fields without the version, plus the canonical absolute path.
+ */
+export declare function mutationResult<T extends {
+    version: FsVersion;
+}>(ctx: Context, target: FsTarget, outcome: T, exec: ToolExecution): Omit<T, 'version'> & {
+    path: string;
+};
+//# sourceMappingURL=mutation-result.d.ts.map

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

@@ -0,0 +1,81 @@
+/**
+ * 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 @qlzt/dsh-tool-fs/src/read-image
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImageAttachmentRef, ImageMediaType } from '@qlzt/dsh-attachment';
+import type { ToolExecution } from '@qlzt/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 {
+    /** Canonical absolute path in the filesystem provider's execution world. */
+    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,111 @@
+/**
+ * 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 @qlzt/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;
+}
+/**
+ * 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 plus a continuation or end-of-file footer.
+ */
+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 `@qlzt/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 '@qlzt/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,19 @@
+/**
+ * Shared path resolution and regular-file validation for model-facing read tools.
+ * @module @qlzt/dsh-tool-fs/src/read-target
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsInfo, FsTarget } from '@qlzt/dsh-fs';
+import type { ToolExecution } from '@qlzt/dsh-tools';
+/**
+ * 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 the owning Agent 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;
+}>;
+//# sourceMappingURL=read-target.d.ts.map

package/lib/types/read.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 @qlzt/dsh-tool-fs/src/read
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 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;
+}
+/** Validated `read` arguments after defaulting. */
+interface ReadInput {
+    filePath: string;
+    offset: number;
+    limit: number;
+}
+/**
+ * Validate value constraints the schema DSL can't express. `maxLimit` is the deployment's line cap.
+ * @param args - the schema-validated raw tool arguments; `offset`/`limit` must be positive integers when given.
+ * @param maxLimit - the configured line cap: both the default `limit` and the largest one accepted.
+ * @returns the validated input with `offset` defaulted to 1 and `limit` to `maxLimit`.
+ */
+export declare function parseReadArgs(args: {
+    file_path: string;
+    offset?: number;
+    limit?: number;
+}, maxLimit: number): 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).
+ */
+export declare function applyReadTool(ctx: Context, caps: ReadToolCaps): void;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/lib/types/sandbox.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 `@qlzt/dsh-sandbox` (the same pieces `@qlzt/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 @qlzt/dsh-tool-fs/sandbox
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@qlzt/dsh-tools';
+import type { SandboxExecutionPolicy, SandboxMode } from '@qlzt/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';
+        enum: string[];
+        description: string;
+    };
+    justification: {
+        type: 'string';
+        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 workspace root is the original Session
+     * directory, or the deployment fallback when absent. 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

package/lib/types/session-cwd.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolution options for filesystem calls in the Session's current directory.
+ * Non-agent calls leave directory defaults to the filesystem provider.
+ * @module @qlzt/dsh-tool-fs/session-cwd
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@qlzt/dsh-tools';
+/**
+ * Resolve the current directory and cancellation for a filesystem call.
+ * @param ctx - context containing the working-directory service.
+ * @param exec - tool execution supplying the agent and cancellation.
+ * @returns filesystem resolution options for this call.
+ */
+export declare function sessionResolveOptions(ctx: Context, exec: ToolExecution): Promise<{
+    cwd?: string;
+    signal?: AbortSignal;
+}>;
+//# sourceMappingURL=session-cwd.d.ts.map

package/lib/types/write.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+ * `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+ * unconditional atomic create-or-overwrite.
+ * @module @qlzt/dsh-tool-fs/src/write
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsWriteOutcome } from '@qlzt/dsh-fs';
+import type { FsSandboxController } from './sandbox.ts';
+/**
+ * Validate value constraints the schema DSL can't express: only a non-blank
+ * `file_path` — an empty `content` is legitimate (it writes an empty file).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input; `content` passes through untouched.
+ */
+export declare function parseWriteArgs(args: {
+    file_path: string;
+    content: string;
+}): {
+    filePath: string;
+    content: string;
+};
+/**
+ * Format a write outcome as one model-facing text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
+ * @returns the model-facing confirmation envelope (no file content is echoed back).
+ */
+export declare function formatWriteOutput(displayPath: string, outcome: Pick<FsWriteOutcome, 'operation'>): string;
+/**
+ * Register the `write` 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).
+ */
+export declare function applyWriteTool(ctx: Context, sandbox: FsSandboxController): void;
+//# sourceMappingURL=write.d.ts.map

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@qlzt/dsh-tool-fs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
+  "version": "0.2.1-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zsping1989/deepseek-harness.git",
+    "directory": "packages/fs/tool-fs"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "diff": "^9.0.0",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
+    "@qlzt/dsh-util-code-language": "0.2.1-alpha.3"
+  },
+  "peerDependencies": {
+    "@qlzt/dsh-attachment": "0.2.1-alpha.3",
+    "@qlzt/dsh-fs": "0.2.1-alpha.3",
+    "@qlzt/dsh-llm": "0.2.1-alpha.3",
+    "@qlzt/dsh-sandbox": "0.2.1-alpha.3",
+    "@qlzt/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@qlzt/dsh-session": "0.2.1-alpha.3",
+    "@qlzt/dsh-system-prompt": "0.2.1-alpha.3",
+    "@qlzt/dsh-tools": "0.2.1-alpha.3",
+    "@qlzt/dsh-user-approval": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@qlzt/dsh-working-directory": "0.2.1-alpha.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs-local": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-alpha.3",
+    "@deepseek-ai/dsh-working-directory": "0.2.1-alpha.3"
+  },
+  "dsh": {}
+}