Preface

In the DeepSeek Harness (DSH) plugin ecosystem, granting an agent filesystem permissions creates an audit dilemma: you must prove what it did without leaking file contents. The jwilson411/dsh-mutation-receipt plugin solves this problem by generating append-only JSONL receipts. It records the operation path, operation type, and SHA256 hash value, but it does not record file contents.

Plugin Overview

This is a DeepSeek Harness function plugin. It converts filesystem operations into referenceable append-only JSONL receipts. Each line contains the path, operation type, and the SHA256 hash values before and after the operation.

Core Features

  • Append-only JSONL receipts: Each line records one file operation, including timestamp, session ID, operation type, path, SHA256 before, and SHA256 after.
  • Metadata recording: Records the path, operation type (op, such as create/update/delete), and SHA256 hash values.
  • Content-free design: The plugin does not store file contents, diffs, or previews.
  • Host-driven recording: It does not automatically traverse the filesystem. The host actively calls the recordMutation function when an operation occurs.
  • CLI tool: Provides the mutation-receipt show command for viewing receipts.

Installation and Activation

Use the official installation command:

dsh plugin --profile default add github:jwilson411/dsh-mutation-receipt

This plugin depends on @deepseek-ai/dsh-tools@0.1.1-rc.2 and @deepseek-ai/cordis@^4.0.1, and requires Node.js version >= 22.14.0.

Typical Usage

The host must actively call recordMutation to record operations. For update and delete operations, sha256_before must be provided.

import { recordMutation } from 'dsh-mutation-receipt'

// 在写入前计算 SHA256
const { sha256: before } = hashFile('notes/hello.txt', workspaceRoot)

recordMutation({
  workspaceRoot,                      // 必填：所有路径相对于此根目录
  receiptPath,                        // 必填：追加式 JSONL 文件路径
  sessionId: 'sess-1',                // 可选
  op: 'update',                       // 'create' | 'update' | 'delete'
  path: 'notes/hello.txt',            // 相对路径
  sha256_before: before,              // 更新和删除操作必填
  sha256_after: '...',                // 可选，若不提供则从磁盘读取
})

Use the CLI tool to view receipts:

mutation-receipt show --receipt ./mutation-receipt.jsonl --root /path/to/workspace -n 10 --json

Use Cases and Considerations

  • Use cases: Auditing agent file operations, compliance tracking, and content-free audit logging.
  • Important limitations:
    • Not a backup: Only hash values prove that a file once existed or was modified; contents cannot be restored.
    • Not DLP as a service: It does not scan, classify, or block, and cannot determine whether data is sensitive.
    • Local runtime: File contents, receipts, and paths never leave the machine, and there are no network requests.
    • Non-automatic scanning: It does not traverse the filesystem; only invoked recordMutation calls are recorded.
    • Required hashes: Update and delete operations must provide sha256_before, otherwise an error is reported.
    • Safety checks: The plugin validates paths, rejects absolute paths or paths containing .., and ensures receipts do not leak the machine’s real paths.

Conclusion

This plugin provides a balance between auditing and privacy by recording only metadata and hash values. It does not store contents, and it does not leave the local machine. To view more details or submit issues, visit the GitHub repository.