@hy-sde-org/dsh-tool-fs-internal-urls 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 hy-sde
+
+This repository ports the FS-shaped internal-URL system (conflict://, issue://,
+pr:// — one resolver registry behind read/grep/write) from oh-my-pi's
+coding-agent internal-urls and conflict-detect modules, adapted to the
+DeepSeek Harness file-services seam. Ported portions are distributed under the
+same MIT license with their original copyright held by their respective
+authors:
+
+  Copyright (c) 2025 Mario Zechner
+  Copyright (c) 2025-2026 Can Bölük
+
+See THIRD-PARTY-NOTICES.md for full provenance per module.
+
+Parts of this repository are derived from DeepSeek Harness
+(https://github.com/deepseek-ai/deepseek-harness), MIT License,
+Copyright (c) 2026 DeepSeek.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @hy-sde-org/dsh-tool-fs-internal-urls
+
+The `read` / `write` / `edit` filesystem tool suite for DeepSeek Harness with
+**internal-URL routing built in**: when `ctx.internalUrls` is mounted, these
+tools resolve `conflict://`, `pr://`, `issue://` URLs (and `<path>:conflicts`
+selectors) through the registry instead of a filesystem path, and scan plain
+filesystem reads for git conflict blocks — registering them with the session
+history and appending a resolution notice. This is the hy-sde fork's
+`dsh-tool-fs` (with `src/internal-routing.ts` + the `read.ts`/`write.ts`
+hunks) shipped as an agent-scope shadow so it works on **stock** DeepSeek
+Harness releases (`dsh-v0.1.1-rc.2` and later).
+
+Mount it in an agent preset (see `examples/agent-preset/` in
+`@hy-sde-org/dsh-internal-urls`): agent-scope shadowing makes these THE
+`read`/`write`/`edit` for that session, while plain filesystem behavior is
+identical to the stock tools. Without a mounted `ctx.internalUrls` registry
+the routing branch never triggers and the tools are stock-equivalent.
+
+- `read` — line-numbered windows (caps: `readLimit` 2000 lines,
+  `readMaxLineLength` 2000 chars, `readMaxBytes` 50 KiB, stream threshold
+  10 MiB), `fs/observed` emission, internal-URL virtual reads, conflict
+  surfacing + notice.
+- `write` — create/overwrite with sandbox-policy escalation
+  (`fs/write-intent` waterfall, error remediation). Internal-URL writes
+  (`conflict://<N>` resolution) dispatch to the handler with the session
+  context and the resolved policy so the backing-file splice stays fenced.
+- `edit` — literal single-match (or replace-all) edits over `ctx.fs` with
+  guard + remediation, unchanged from the harness (this package keeps the
+  trio together).
+- `read_image` — registers only while `attachments` is mounted, unchanged.
+
+## Install
+
+As a routing surface this package is useless without
+`@hy-sde-org/dsh-internal-urls`; follow that package's README — all three
+packages install together:
+
+```bash
+dsh plugin --profile web add @hy-sde-org/dsh-internal-urls \
+  @hy-sde-org/dsh-tool-fs-internal-urls \
+  @hy-sde-org/dsh-tool-fs-search-internal-urls
+```
+
+Then copy the preset from `packages/internal-urls/examples/agent-preset/` in
+this repo (or the installed package) to `~/.dsh/.agent-presets/<id>/` — its
+`tool-fs-internal-urls` row is this package.
+
+## Defaults & caps
+
+| Key | Default | Meaning |
+|---|---|---|
+| `readLimit` | `2000` | lines per `read` call |
+| `readMaxLineLength` | `2000` | chars per returned line |
+| `readMaxBytes` | `50 KiB` | bytes of selected output |
+| `readStreamMinSize` | `10 MiB` | stream files at/above this size |
+| `enableEdit` | `true` | set `false` to leave `edit` to another provider |

package/dist/diff.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 @hy-sde-org/dsh-tool-fs-internal-urls/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. 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[];
+};
+/**
+ * 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/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEtD,2DAA2D;AAC3D,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,CAAA;AAE9C;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAwBxF;AAWD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,EAAE,GAAG,SAAS,CAKnE"}

package/dist/diff.js

@@ -0,0 +1,71 @@
+/**
+ * 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 @hy-sde-org/dsh-tool-fs-internal-urls/src/diff
+ */
+import { structuredPatch } from 'diff';
+/** Context lines shown on each side of an applied hunk. */
+export const DIFF_CONTEXT = 3;
+/**
+ * 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 function computeHunkDiffs(path, before, after) {
+    const patch = structuredPatch('', '', before, after, undefined, undefined, { context: DIFF_CONTEXT });
+    const diffs = [];
+    for (const hunk of patch.hunks) {
+        const oldLines = [];
+        const newLines = [];
+        for (const line of hunk.lines) {
+            // The unified-diff marker for a missing trailing newline annotates the
+            // patch, not the content — skip it so it never leaks into a diff block.
+            if (line.startsWith('\\'))
+                continue;
+            const text = line.slice(1);
+            if (line.startsWith('-')) {
+                oldLines.push(text);
+            }
+            else if (line.startsWith('+')) {
+                newLines.push(text);
+            }
+            else {
+                // A context (unchanged) line appears on both sides.
+                oldLines.push(text);
+                newLines.push(text);
+            }
+        }
+        diffs.push({ path, oldText: oldLines.length > 0 ? oldLines.join('\n') : null, newText: newLines.join('\n') });
+    }
+    return diffs;
+}
+/** Whether `value` is a valid {@link FileDiff} (defensive narrowing from opaque `meta`). */
+function isFileDiff(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const { path, oldText, newText } = value;
+    return typeof path === 'string'
+        && (oldText === null || typeof oldText === 'string')
+        && typeof newText === 'string';
+}
+/**
+ * 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 function diffsFromMeta(meta) {
+    if (typeof meta !== 'object' || meta === null || Array.isArray(meta))
+        return undefined;
+    const diffs = meta.diffs;
+    if (!Array.isArray(diffs) || diffs.length === 0 || !diffs.every(isFileDiff))
+        return undefined;
+    return diffs;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAGtC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAA;AAW7B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,MAAc,EAAE,KAAa;IAC1E,MAAM,KAAK,GAAG,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAA;IACrG,MAAM,KAAK,GAAe,EAAE,CAAA;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAa,EAAE,CAAA;QAC7B,MAAM,QAAQ,GAAa,EAAE,CAAA;QAC7B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,uEAAuE;YACvE,wEAAwE;YACxE,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,SAAQ;YACnC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YAC1B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACrB,CAAC;iBAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAChC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACrB,CAAC;iBAAM,CAAC;gBACN,oDAAoD;gBACpD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACnB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACrB,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC/G,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,4FAA4F;AAC5F,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACrF,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAgC,CAAA;IACnE,OAAO,OAAO,IAAI,KAAK,QAAQ;WAC1B,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC;WACjD,OAAO,OAAO,KAAK,QAAQ,CAAA;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAA;IACtF,MAAM,KAAK,GAAI,IAAgC,CAAC,KAAK,CAAA;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAA;IAC7F,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/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 @hy-sde-org/dsh-tool-fs-internal-urls/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 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/dist/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEvD,mDAAmD;AACnD,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB;AAgBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAUnI;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,CAIjF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CA4F9E"}

package/dist/edit.js

@@ -0,0 +1,137 @@
+/**
+ * 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 @hy-sde-org/dsh-tool-fs-internal-urls/src/edit
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { computeHunkDiffs, diffsFromMeta } from "./diff.js";
+import { remediateFsError } from "./error.js";
+import { sessionResolveOptions } from "./session-cwd.js";
+/**
+ * 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 function parseEditArgs(args) {
+    if (args.file_path.trim().length === 0)
+        throw new Error('file_path must be a non-empty string');
+    if (args.old_string.length === 0)
+        throw new Error('old_string must be a non-empty string');
+    if (args.old_string === args.new_string)
+        throw new Error('old_string and new_string must differ');
+    return {
+        filePath: args.file_path,
+        oldString: args.old_string,
+        newString: args.new_string,
+        replaceAll: args.replace_all ?? false,
+    };
+}
+/**
+ * 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 function formatEditOutput(displayPath, replaceAll) {
+    return replaceAll
+        ? `The file ${displayPath} has been updated. All occurrences were successfully replaced.`
+        : `The file ${displayPath} has been updated successfully.`;
+}
+/**
+ * Register the `edit` tool and its 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 function applyEditTool(ctx, sandbox) {
+    ctx.systemPrompt.section({
+        name: 'tool:edit',
+        order: 102,
+        text: 'Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-observation-policy requires it), unless you just created or edited it in this session.',
+    });
+    ctx.tools.register(defineTool({
+        name: 'edit',
+        description: 'Edit an existing UTF-8 text file by replacing literal text.',
+        parameters: {
+            file_path: { type: 'string', required: true, description: 'Path to edit, resolved by the filesystem backend.' },
+            old_string: { type: 'string', required: true, description: 'Literal text to replace. Must match exactly.' },
+            new_string: { type: 'string', required: true, description: 'Literal replacement text. Use an empty string to delete the match.' },
+            replace_all: { type: 'boolean', description: 'Replace all matches. Defaults to false; when false, old_string must appear exactly once.' },
+            ...sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {},
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    before: { type: 'string', required: true },
+                    after: { type: 'string', required: true },
+                },
+            },
+            render: (args, value) => [{
+                    type: 'text',
+                    text: formatEditOutput(value.path, args.replace_all ?? false),
+                }],
+            presentationMeta: (args, value) => ({
+                diffs: computeHunkDiffs(args.file_path, value.before, value.after)
+                    .map(({ path, oldText, newText }) => ({ path, oldText, newText })),
+            }),
+        },
+        async execute(args, exec) {
+            const input = parseEditArgs(args);
+            // Resolve the per-call sandbox policy (approved mode > session override
+            // > backend default, plus the session cwd root) BEFORE anything executes.
+            const sandboxPolicy = await sandbox.resolvePolicy('edit', args, exec);
+            const target = await ctx.fs.resolve(input.filePath, sessionResolveOptions(exec, input.filePath, sandboxPolicy?.workspaceRoot));
+            // Single-slot decision: the policy plugin returns { version: vObserved } or
+            // throws FS_NOT_OBSERVED; the bare default is undefined (unconditional edit).
+            // No stat — the bare default never manufactures a version basis. The intent
+            // slot itself can throw FS_NOT_OBSERVED for an unread target, so it sits
+            // inside the try: both that refusal and the provider's guarded-mutation
+            // failure get the model-facing remedy below.
+            let outcome;
+            try {
+                const intent = await ctx.waterfall('fs/edit-intent', target, exec, () => undefined);
+                outcome = await ctx.fs.editText(target, { oldString: input.oldString, newString: input.newString, replaceAll: input.replaceAll }, intent, exec.signal, sandboxPolicy);
+            }
+            catch (error) {
+                // A sandbox denial becomes the shared [sandbox: …] marker (the model
+                // recognizes it from bash); stale/not-observed failures gain their
+                // model-facing remedy; anything else passes through.
+                throw remediateFsError(sandbox.mapError(error, sandboxPolicy));
+            }
+            // Record the present observation (a no-op when no policy plugin listens).
+            ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec);
+            return {
+                path: target.displayPath,
+                before: outcome.before,
+                after: outcome.after,
+            };
+        },
+        // Pure display: a diff card of the literal replacement (old_string → new_string), derived
+        // from the call args. `oldText: old_string || null` matches claude-agent-acp's Edit arm;
+        // new_string is a required arg here, so it maps straight to newText.
+        presentCall(args) {
+            return {
+                card: 'diff',
+                title: `Edit ${args.file_path}`,
+                diffs: [{ path: args.file_path, oldText: args.old_string || null, newText: args.new_string }],
+                locations: [{ path: args.file_path }],
+            };
+        },
+        // Applied metadata replaces the call-time snippet; errors or malformed replay metadata use
+        // the generic result rendering.
+        presentResult(args, result) {
+            if (result.isError)
+                return undefined;
+            const diffs = diffsFromMeta(result.meta);
+            if (diffs === undefined)
+                return undefined;
+            return { card: 'diff', title: `Edit ${args.file_path}`, diffs };
+        },
+    }));
+}
+//# sourceMappingURL=edit.js.map

package/dist/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../src/edit.ts"],"names":[],"mappings":"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"}

package/dist/error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Model-facing remediation for guarded-mutation failures. The provider's
+ * `FS_STALE_VERSION` and `FS_NOT_OBSERVED` messages state the condition but
+ * not the only correct recovery (re-read / read the file), so this package
+ * appends the remedy at the model boundary; provider messages stay
+ * machine-oriented and unchanged.
+ * @module @hy-sde-org/dsh-tool-fs-internal-urls/src/error
+ */
+/**
+ * Append the correct recovery instruction to a guarded-mutation failure's
+ * message. `FS_STALE_VERSION` (the file changed since this session's last
+ * observation, including a missing target) recovers only by re-reading;
+ * `FS_NOT_OBSERVED` (no prior read by this session) by reading. The `FsError`
+ * code is preserved so retry/permission/UI layers keep routing on it, and the
+ * original error chains as `cause`. Anything else passes through untouched.
+ * @param error - the caught value from a write/edit execution.
+ * @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+ */
+export declare function remediateFsError(error: unknown): unknown;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxD"}

package/dist/error.js

@@ -0,0 +1,33 @@
+/**
+ * Model-facing remediation for guarded-mutation failures. The provider's
+ * `FS_STALE_VERSION` and `FS_NOT_OBSERVED` messages state the condition but
+ * not the only correct recovery (re-read / read the file), so this package
+ * appends the remedy at the model boundary; provider messages stay
+ * machine-oriented and unchanged.
+ * @module @hy-sde-org/dsh-tool-fs-internal-urls/src/error
+ */
+import { FsError } from '@deepseek-ai/dsh-fs';
+/** The remedy appended to each remediable failure code's message. */
+const REMEDIES = {
+    FS_STALE_VERSION: 're-read the file, then retry',
+    FS_NOT_OBSERVED: 'read the file, then retry',
+};
+/**
+ * Append the correct recovery instruction to a guarded-mutation failure's
+ * message. `FS_STALE_VERSION` (the file changed since this session's last
+ * observation, including a missing target) recovers only by re-reading;
+ * `FS_NOT_OBSERVED` (no prior read by this session) by reading. The `FsError`
+ * code is preserved so retry/permission/UI layers keep routing on it, and the
+ * original error chains as `cause`. Anything else passes through untouched.
+ * @param error - the caught value from a write/edit execution.
+ * @returns a remediated `FsError` for the two guarded-mutation codes, else the original value.
+ */
+export function remediateFsError(error) {
+    if (!(error instanceof FsError))
+        return error;
+    const remedy = REMEDIES[error.code];
+    if (!remedy)
+        return error;
+    return new FsError(`${error.message} — ${remedy}`, error.code, { cause: error });
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAG7C,qEAAqE;AACrE,MAAM,QAAQ,GAAyC;IACrD,gBAAgB,EAAE,8BAA8B;IAChD,eAAe,EAAE,2BAA2B;CAC7C,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,CAAC,KAAK,YAAY,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IAC7C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACzB,OAAO,IAAI,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,MAAM,MAAM,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;AAClF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 @hy-sde-org/dsh-tool-fs-internal-urls
+ */
+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;
+    /** Register the literal `edit` tool. Set false when a rich editor replaces it; default true. */
+    enableEdit?: boolean;
+}
+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/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AASxC,qDAAqD;AACrD,eAAO,MAAM,IAAI,YAAY,CAAA;AAE7B,sDAAsD;AACtD,eAAO,MAAM,MAAM,UAAkC,CAAA;AAErD,qEAAqE;AACrE,MAAM,WAAW,MAAM;IACrB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,gGAAgG;IAChG,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAM3B,CAAA;AAYF,uHAAuH;AACvH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAyBxD"}

package/dist/index.js

@@ -0,0 +1,59 @@
+/**
+ * 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 @hy-sde-org/dsh-tool-fs-internal-urls
+ */
+import z from '@deepseek-ai/schemastery';
+import { applyReadTool, READ_LIMIT, STREAM_MIN_SIZE } from "./read.js";
+import { applyWriteTool } from "./write.js";
+import { applyEditTool } from "./edit.js";
+import { applyReadImageTool } from "./read-image.js";
+import { READ_MAX_BYTES, READ_MAX_LINE_LENGTH } from "./read-render.js";
+import { FsSandboxController } from "./sandbox.js";
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'tool-fs';
+/** Services required by the filesystem tool suite. */
+export const inject = ['tools', 'fs', 'systemPrompt'];
+export const Config = z.object({
+    readLimit: z.number().default(READ_LIMIT),
+    readMaxLineLength: z.number().default(READ_MAX_LINE_LENGTH),
+    readMaxBytes: z.number().default(READ_MAX_BYTES),
+    readStreamMinSize: z.number().default(STREAM_MIN_SIZE),
+    enableEdit: z.boolean().default(true),
+});
+/** Every read cap counts lines/chars/bytes — a positive integer, or windowing arithmetic misbehaves silently. */
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`tool-fs: ${name} must be a positive integer`);
+    }
+}
+/** Register the full `read`/`write`/`edit` filesystem tool suite, plus `read_image` while `attachments` is mounted. */
+export function apply(ctx, config) {
+    // schemastery (Config) has already filled every defaulted field.
+    const resolved = config;
+    assertPositiveInteger('readLimit', resolved.readLimit);
+    assertPositiveInteger('readMaxLineLength', resolved.readMaxLineLength);
+    assertPositiveInteger('readMaxBytes', resolved.readMaxBytes);
+    assertPositiveInteger('readStreamMinSize', resolved.readStreamMinSize);
+    applyReadTool(ctx, {
+        limit: resolved.readLimit,
+        maxLineLength: resolved.readMaxLineLength,
+        maxBytes: resolved.readMaxBytes,
+        streamMinSize: resolved.readStreamMinSize,
+    });
+    // read_image is composition-conditional: without a mounted attachment store
+    // the deployment cannot durably commit image bytes, so the tool never
+    // registers; the execute body keeps a defensive re-check for direct callers.
+    ctx.inject(['attachments'], (imageCtx) => {
+        applyReadImageTool(imageCtx);
+    });
+    // One escalation API shared by both mutating tools: advertisement gating,
+    // per-call policy resolution, and denial-marker mapping, all keyed off whether
+    // the mounted ctx.fs confines (ctx.fs.sandboxMode).
+    const sandbox = new FsSandboxController(ctx);
+    applyWriteTool(ctx, sandbox);
+    if (resolved.enableEdit)
+        applyEditTool(ctx, sandbox);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAElD,qDAAqD;AACrD,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAA;AAE7B,sDAAsD;AACtD,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,cAAc,CAAC,CAAA;AAgBrD,MAAM,CAAC,MAAM,MAAM,GAAc,CAAC,CAAC,MAAM,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC;IACzC,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,oBAAoB,CAAC;IAC3D,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC;IAChD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC;IACtD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACtC,CAAC,CAAA;AAKF,iHAAiH;AACjH,SAAS,qBAAqB,CAAC,IAAY,EAAE,KAAa;IACxD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,6BAA6B,CAAC,CAAA;IAChE,CAAC;AACH,CAAC;AAED,uHAAuH;AACvH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,MAAc;IAChD,iEAAiE;IACjE,MAAM,QAAQ,GAAG,MAAwB,CAAA;IACzC,qBAAqB,CAAC,WAAW,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;IACtD,qBAAqB,CAAC,mBAAmB,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACtE,qBAAqB,CAAC,cAAc,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;IAC5D,qBAAqB,CAAC,mBAAmB,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACtE,aAAa,CAAC,GAAG,EAAE;QACjB,KAAK,EAAE,QAAQ,CAAC,SAAS;QACzB,aAAa,EAAE,QAAQ,CAAC,iBAAiB;QACzC,QAAQ,EAAE,QAAQ,CAAC,YAAY;QAC/B,aAAa,EAAE,QAAQ,CAAC,iBAAiB;KAC1C,CAAC,CAAA;IACF,4EAA4E;IAC5E,sEAAsE;IACtE,6EAA6E;IAC7E,GAAG,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE;QACvC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IAC9B,CAAC,CAAC,CAAA;IACF,0EAA0E;IAC1E,+EAA+E;IAC/E,oDAAoD;IACpD,MAAM,OAAO,GAAG,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAA;IAC5C,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IAC5B,IAAI,QAAQ,CAAC,UAAU;QAAE,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;AACtD,CAAC"}

package/dist/internal-routing.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The read tool's internal-URL routing: when `ctx.internalUrls` is mounted and
+ * the requested path is a handled `scheme://` URL (or a `<path>:conflicts`
+ * selector), the read resolves through the registry instead of the filesystem,
+ * renders the virtual content as a line-numbered window, and — for regular
+ * filesystem reads — scans the surfaced lines for git conflict blocks,
+ * registering them with the session history and appending a resolution notice.
+ * @module @hy-sde-org/dsh-tool-fs-internal-urls/internal-routing
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsTarget } from '@deepseek-ai/dsh-fs';
+import type { InternalUrlsService } from '@hy-sde-org/dsh-internal-urls';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { FileTextLine } from './read-render.ts';
+/** The subset of read caps the routing needs to build a bounded window. */
+export interface InternalReadCaps {
+    maxLineLength: number;
+    maxBytes: number;
+}
+/** Tool-owned window request (validated read args). */
+export interface ReadRequest {
+    filePath: string;
+    offset: number;
+    limit: number;
+}
+/** A fully-formed read outcome, virtual or filesystem-backed. */
+export interface InternalReadOutcome {
+    /** Model-facing path (the internal URL for virtual reads). */
+    path: string;
+    offset: number;
+    lines: FileTextLine[];
+    totalLines: number;
+    /** Optional conflict-resolution notice, rendered after the file body. */
+    notice?: string;
+}
+/** The calling agent's session id, used to key session-scoped handler state. */
+export declare function sessionKeyOf(exec: ToolExecution): string | undefined;
+/** Build a {@link ResolveContext} for the calling tool execution. */
+export declare function resolveContextOf(exec: ToolExecution, path: string): {
+    cwd?: string;
+    signal: AbortSignal;
+    sessionKey?: string;
+};
+/**
+ * Resolve a scheme URL (or `<path>:conflicts` selector) into a virtual window.
+ * Returns `undefined` when the path is not an internal URL, so the caller
+ * falls through to the filesystem path untouched.
+ */
+export declare function tryReadInternal(ctx: Context, iu: InternalUrlsService, exec: ToolExecution, request: ReadRequest, caps: InternalReadCaps): Promise<InternalReadOutcome | undefined>;
+/**
+ * Scan a completed filesystem read's window for conflict blocks, register them
+ * with the calling session's history (id reuse by path+start line), and render
+ * the resolution notice. Returns `undefined` when nothing to report or no
+ * session key / registry are available.
+ */
+export declare function conflictNoticeForRead(ctx: Context, iu: InternalUrlsService, exec: ToolExecution, target: FsTarget, outcome: {
+    path: string;
+    offset: number;
+    lines: FileTextLine[];
+}): string | undefined;
+//# sourceMappingURL=internal-routing.d.ts.map

package/dist/internal-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-routing.d.ts","sourceRoot":"","sources":["../src/internal-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AAQxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAGpD,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ9H;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,OAAO,EACZ,EAAE,EAAE,mBAAmB,EACvB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAmB1C;AAqCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,EAAE,EAAE,mBAAmB,EACvB,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,GAC/D,MAAM,GAAG,SAAS,CAapB"}