ChatGPTClaudeGrok / X / CursorGemini

DSH plugin filesystem: opaque targets, patches, and guards

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessFilesystemPatchWrite guards
DSH plugin filesystem seam: opaque FsTarget identity, patch syntax and failures, write and edit guards, and how fs policy events stay optional.

A patch that will not apply, or a guard that will not block, is usually not a matching problem — it is opaque identity treated as a path. DSH plugin's filesystem seam turns paths into FsTarget through resolve(), and every operation afterward honors that identity only. Understanding that boundary beats tuning patch context.

Three roles plus one optional policy

Filesystem is an optional capability; swapping backends changes neither policy nor tool schemas.(source)

The roles:

  1. dsh-fs — owns ctx.fs and the guarded mutation operations;
  2. dsh-fs-local — implements the local disk backend;
  3. dsh-fs-observation-policy — records observed presence or absence and adds freshness rules through events rather than the service;
  4. dsh-tool-fs — runs model-facing read/write/edit and renders windows.

The pure library dsh-fs-patch provides patch parsing and text application. The whole capability sits outside the agent loop trunk, so replacing a backend changes neither tool schemas nor policy behavior.

The policy plugin is optional: without it, the FileSystem service definition, one provider, and dsh-tool-fs form a complete, unconstrained seam — write creates or overwrites unconditionally, edit replaces literal text unconditionally. Enable it and operations pass through an fs/* waterfall. In the shipped bundle, dsh-base's fs-observation-policy line reads disabled: true; deployments wanting read-before-write/edit flip it to disabled: false.

Removing the policy plugin never breaks tools, because tools call ctx.fs and dispatch events rather than invoking policy methods. Policy is a pluggable decoration, not a hard dependency.

The target is opaque identity

displayPath may be shown; neither targetKey nor FsVersion may be parsed.(source)

Every operation first resolves a user-supplied path into an opaque backend target. Consumers may display displayPath but must never parse targetKey — a local backend uses a realpath-like string while a remote backend may use a workspace URI or file id.

Consumers sharing the execution world with the filesystem should obtain coordinates through the provider instead of interpreting identity: processPath(target) returns a canonical absolute path a subprocess can open; processPathFromHostPath(hostPath) maps only when the corresponding host file is shared; fileUrl(target) returns a file: URI in the provider platform's syntax; contains(parent, child) checks identity equality or descendant containment.

stat returns metadata only, never content, and undefined when the target is missing. Its three fields each serve a purpose: version is the freshness token; type lets consumers reject directories and special files before reading; size lets text consumers choose readText versus streamText without probing by failure.

Raw byte consumers use readBytes(target, signal, maxBytes), whose required full-content cap makes known or discovered overruns fail with FS_TOO_LARGE rather than truncating a result or buffering without bound.

lstat is the trust-boundary check before resolve

resolve() follows symlinks and lstat does not, which is exactly why both exist.(source)

lstat is the path-level metadata primitive that does not follow the final component. It takes a path rather than an FsTarget, because resolve() intentionally follows symlinks to produce a stable identity.

That gap is the entry point for consumers needing trust-boundary rules: lstat before resolving and reject on type: 'symlink'. The guard section says the same — the target has already followed symlinks, so callers wanting to reject symlinked sources must check before resolve.

listDir returns direct children in stable name order, each with a basename, type, resolved target, and cheap metadata. It never reads content, so size is meaningful only for regular files; broken or vanished children may come back as other without metadata, while permission or backend I/O failures fail the whole listing with FS_PERMISSION_DENIED or FS_IO_ERROR.

Patch parsing and applying is a pure library

Parsing yields serializable operations; applying returns either the full new text or a structured failure.(source)

dsh-fs-patch parses complete patch text into serializable operations, leaving paths as unresolved strings; applyHunks applies hunks to caller-provided LF-normalized text, returning the complete new text or a structured match failure.

Map each PatchHunk field: lineNumber is the one-based line number from the patch input; context is the text after @@ , used as the search anchor; oldLines and newLines exclude prefixes and line endings; isEndOfFile means *** End of File follows.

PatchOperation has only three forms: add, delete, update. A move is an update carrying moveTo, not a fourth operation. add's content joins lines with LF, each new line ending in LF.

The failure shape is HunkApplyFailure: hunkLineNumber, stage (context or oldLines), searchStart, and pattern. The failure branch of ApplyHunksResult carries no partial updated text — callers never roll back half a result themselves.

Write and edit guards

Same-name guards cover patch, delete, and move, but each observes a different stage.(source)

OperationIntent eventSuccess observation
patchTextfs/edit-intentTarget exists at the returned version
deleteFilefs/delete-intentSource absent
moveFile sourcefs/edit-intentSource absent recorded only when sourceDeleted is true
moveFile targetfs/write-intentTarget exists at destination.version

Hard rules: patch, delete, and move sources must be regular files; a missing source or stale version reports FS_STALE_VERSION; patches match LF-normalized text inside the mutation lock and report FS_PATCH_MISMATCH with hunk line number and stage on failure; a move rejects identical target keys with FS_SAME_TARGET, applies a write guard to the destination, and preserves the source's line-ending style and mode.

A move is two effects, not one: the destination may publish while source deletion fails, returning sourceDeleted: false with sourceFailure. Local moves check cancellation before staging the destination, then the provider completes both effects and reports the result.

Version guards on writeText and editText are both optional. Omitting the guard performs a bare provider mutation; providing one makes the check conditional. FsWriteIntent has exactly two branches: createIfAbsent rejects with FS_NOT_OBSERVED when the target already exists — even if it appeared after the provider's initial probe, because publication must never replace — and replaceIfVersion reports FS_STALE_VERSION when missing or version-mismatched.

"No guard" is expressed by omitting expected, not by a third union branch. FsWriteOutcome.before is LF-normalized stored text, not a diff; it is null when the file does not exist or the backend refuses a context base (binary, non-UTF-8, either side at the exclusive cap), and consumers fall back to a full-file diff.

editText is a provider-level mutation, not a read plus write composed elsewhere. With a guard it validates the expected version before literal matching, so editing stale content reports FS_STALE_VERSION rather than a match failure on newer content; without a guard it edits current content. Both paths complete matching, line-ending handling, staleness checks, and atomic replacement inside one mutation critical section, and both report FS_STALE_VERSION when the target is missing.

Policy events make read-before-write optional

The policy plugin decides through an fs/* waterfall; it never replaces methods.(source)

dsh-fs-observation-policy records observed presence or absence and adds freshness rules through events. It changes whether this operation passes, never how tools are invoked.

That suggests a debugging order: first confirm the tool really calls ctx.fs rather than writing to disk behind the seam, then confirm the policy plugin is enabled, and only then inspect guard decisions. dsh-base disables it by default, so "guards did nothing" is almost always configuration.

The same rule explains why swapping backends never changes policy: policy hangs on events while the backend only resolves identity and executes mutations.

Verification: an applied patch and a rejected write

Cover the patch failure structure and the guard rejection paths, not just happy samples.(source)

  1. resolve() a file path, assert you receive targetKey and displayPath, and use only the former afterward.
  2. Apply a patch with mismatched context and assert ok is false, stage names the failing phase, and no partial text appears.
  3. Write an existing file with createIfAbsent and assert FS_NOT_OBSERVED.
  4. Call replaceIfVersion with a stale version and assert FS_STALE_VERSION.
  5. Call guarded editText on stale content and assert FS_STALE_VERSION, not a match failure.
  6. Move onto a target key identical to the source and assert FS_SAME_TARGET with the source file intact.

If step 2's stage differs from expectation, inspect pattern and searchStart: anchor search and old-line search are two phases, and judging them together misleads.

For the boundary with sandbox policy, see sandbox per-call policy; for the full backend replacement contract, see the filesystem seam overview.

One line to close: identity is opaque and paths are for display, patch failures carry no half result, guards express "no guard" by omission, and policy hangs on events rather than methods.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin targetKey be used as a local path?

No. DSH plugin forbids parsing it. DSH plugin's targetKey is an opaque branded id: a local backend uses a realpath-like string, a remote one may use a workspace URI or file id. Use displayPath to show and processPath to operate.

What happens when DSH plugin writeText omits the guard?

DSH plugin performs an unconditional bare provider mutation, creating or overwriting. DSH plugin expresses no guard by omitting expected rather than adding a third union branch.

Which error does DSH plugin report on stale content?

DSH plugin reports FS_STALE_VERSION rather than a match failure. DSH plugin's editText validates the expected version before literal matching, so stale content is caught by the version check first.

Do DSH plugin tools work without the policy plugin?

Yes. DSH plugin tools call ctx.fs and dispatch events, not policy methods. Without the policy plugin DSH plugin writes unconditionally and edits literal text unconditionally.

Related Terms

FsTarget
FsTarget is a backend-resolved stable identity with an opaque targetKey and a displayPath for presentation.— packages/fs/fs/src/types.ts
FsVersion
FsVersion is an opaque file version token, the freshness credential guards compare, and consumers must not interpret its contents.— packages/fs/fs/src/types.ts
FsWriteIntent
FsWriteIntent is a guarded write intent with exactly two forms: createIfAbsent and replaceIfVersion.— packages/fs/fs/src/types.ts
ApplyHunksResult
ApplyHunksResult is the patch outcome: either the complete new text or a match failure carrying no partial text.— packages/fs/fs/src/types.ts

Sources