dsh-pathfix

📋 Table of Contents

• What It Fixes
• Guarantees
• Installation
• Configuration
• Observability & Telemetry
• Verification & Testing
• Contributing
• Links
• License

---

What It Fixes

Due to model tokenization and sampling variance, LLMs occasionally emit tool parameters with unexpected trailing newlines or edge whitespace (e.g. "file_path": "C:\\images\\_shot.png\n"). Because standard filesystem tools take parameters verbatim, this causes recurring, misleading tool failures:

Tool	Error when a trailing \n is in the parameter	What dsh-pathfix does
write	EINVAL: invalid argument, mkdir '...<filename>\n.<id>.tmpdir'	Trims whitespace; directory and file creation succeed.
glob	IO error / The filename, directory name, or volume label syntax is incorrect (os error 123)	Trims path whitespace; search succeeds.
grep	rg: the literal "\n" is not allowed in a regex	Strips \r/\n while preserving regex edge spaces.
read_image	Misleading read_image only accepts PNG/JPEG/WebP/GIF paths	Trims path; image extension check passes.
read	Misleading not found (file exists)	Trims path; file resolves and reads normally.

dsh-pathfix operates transparently at the host layer before tool dispatch. The model does not need to learn any replacement tool, and tool result prose is never modified.

Guarantees

• No-Op Guarantee: Clean arguments pass through completely untouched (fix(clean) === clean). If no repair is required, the original argument object reference is returned and no telemetry is emitted.
• Idempotency Guarantee: fix(fix(x)) === fix(x). Applying normalization multiple times yields the exact same state.
• Preserves Regex Edge Spaces: In pattern arguments (for grep and glob), only \r and \n characters are stripped. Spaces and tabs at pattern boundaries are preserved because they can be semantically significant in regular expressions.
• Zero Runtime Dependencies: Relies solely on host peer dependencies (@deepseek-ai/dsh-tools, @deepseek-ai/schemastery).

Installation

Install into your target DSH profile (e.g. web):

dsh plugin --profile web add file:/absolute/path/to/plugins/dsh-pathfix

Verify that the bundle is mounted in your profile:

dsh web --dump-config | Select-String -Pattern "pathfix" -Context 1,2

Expected output includes the patch layer:

# == dsh-pathfix
- id: pathfix
  name: dsh-pathfix

Configuration

dsh-pathfix is configurable via your profile's cordis.patch.yml or cordis configuration:

- id: pathfix
  name: dsh-pathfix
  config:
    enabled: true           # Enable or disable parameter normalization (default: true)
    tools:                  # List of tool names to inspect (default: fs tools)
      - read
      - read_image
      - write
      - edit
      - glob
      - grep
    stripLeading: true      # Strip leading whitespace in paths (default: true)
    logFixes: true          # Log repairs to session/console (default: true)

Observability & Telemetry

When a parameter is repaired, dsh-pathfix records the event in an internal telemetry tracker and emits an informational log message (if logFixes: true):

[dsh-pathfix] Repaired parameter "file_path" on tool "read_image": stripped trailing "\n" (value: "C:\\images\\_shot.png\n" -> "C:\\images\\_shot.png")

The repair event is also emitted as pathfix/repair on the Cordis context and tracked in ctx.pathfix.telemetry.

Verification & Testing

Verification (Check if Plugin is Mounted in Profile)

In Windows CMD (Command Prompt):

dsh web --dump-config | findstr /i "pathfix"

In PowerShell:

dsh web --dump-config | Select-String -Pattern "pathfix" -Context 1,2

Expected output:

# == dsh-pathfix
- id: pathfix
  name: dsh-pathfix

Acceptance Mount Check

Verify that the profile dependencies, bundle patch, and live Cordis normalization hook are fully active:

node acceptance/mount_check.mjs C:\Users\marti\.dsh\profiles\web

Or via npm:

npm run mount-check C:\Users\marti\.dsh\profiles\web

Automated Test Suite

Run unit and E2E tests using Node.js built-in test runner:

# Run all tests (unit + E2E)
npm test

# Run unit tests covering the 5 real-world error fixtures
npm run test:unit

# Run E2E test with real @deepseek-ai/dsh-tool-fs suite
npm run test:e2e

Or directly with Node:

node --test test/unit.test.mjs test/e2e.test.mjs

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on code invariants, test fixtures, and commit standards.

🔗 Links

• 📚 DeepSeek Harness
• 🐛 Issues
• 📦 NPM Package

License

MIT © loonylabs-dev

---