@yadsh/dsh-documents

Managed document pipeline for the DeepSeek Harness: the agent writes Markdown and receives DOCX/PDF, hands over a DOCX/PDF and receives Markdown, or stores the text of an online source — a wiki attachment, a document behind an authenticated fetch provider — as an artifact it can work with.

It also tells two revisions of a document apart, deterministically and in the process: an OOXML package is read natively — paragraphs, tables, numbering, headers, footnotes, tracked revisions — and the diff, not the model, decides what changed. The model is given a change set with stable ids and interprets it.

The plugin owns every backend command line, keeps the source, the assets, the outputs and a manifest.json in one artifact bundle, and exposes seven semantic tools. An agent never calls pandoc, LibreOffice, Docling or a converter flag directly, so a deployment can replace a backend without touching a prompt, a skill or a workflow.

It is deliberately not part of @yadsh/dsh-qa-surface: it reads the calling session's working directory, registers plain agent tools, and asks the deployment's web provider for online sources. Any agent composition can use it, and a QA chat reaches it through the same names it always did.

Installation

npm install @yadsh/dsh-documents
# or, into a profile:
dsh plugin --profile <profile> add @yadsh/dsh-documents

The package ships cordis.patch.yml, so the DSH plugin manager inserts its row into the profile bundle; add it to dsh.profile.bundles if your deployment lists bundles explicitly.

Tools

For customer-specific proposals and specifications, the bundled grounded-documents skill uses document_workflow_start/read/update/draft/review/export and document_calculate. Requirements, facts, exclusions and Markdown revisions survive interruption. Independent review and authenticated human approval refer to the exact draft hash. A changed draft or template must be reviewed again. An active managed workflow refuses finalisation through the general converters.

Workflow state lives under $DSH_HOME/document-workflows (or the Host user's .dsh/document-workflows) outside the model-writable workspace. Include it in the deployment backup. Markdown drafts remain in the session workspace and are shown as file attachments in QA; the approval action beside a reviewed draft requests export through the existing agent.

Register a Markdown content template separately from Word styles:

templates:
  proposal:
    kind: proposal
    productVersion: "1.0"
    markdown: ./proposal.md
    docx: ./reference.docx
    requiredFacts: [customer, projectGoal, functionalScope]
    requiredSections: [Goal, Functional scope, Commercial terms]
  specification:
    kind: specification
    productVersion: "1.0"
    markdown: ./specification.md
    docx: ./reference.docx
    requiredFacts: [customer, projectGoal, functionalScope]
    requiredSections: [Goal, Functional requirements, Acceptance]

Point documents.templates.root at this read-only registry directory. A template for another document kind or product version is refused. Price and quantity inputs require explicit sources; totals use exact decimal arithmetic with half-up rounding per line to two decimals. No price or tax treatment is inferred.

| Tool | What it does | | --- | --- | | document_create | Markdown → DOCX and/or PDF through a registered template, as one artifact bundle | | document_to_markdown | DOCX/PDF → Markdown, with tables, assets and OCR policy | | document_from_url | Fetch an online document or attachment and store its text as an artifact | | document_convert | A supported document to another supported format (md → docx/pdf, docx → pdf/md, pdf → md) | | document_inspect | Type, metadata, page/heading/table counts, encryption and macro flags — without converting | | document_compare | Two documents → a deterministic comparison artifact, a summary and a bounded preview | | document_diff_read | Pages of a comparison's changes, filtered by section, kind and signal |

Each producing tool reports its files by their path inside the session workspace — .qa/artifacts/documents/<id>/report.docx — which is also the spelling its own input parameters accept, so a file reported by one call can be read back by the next. The pipeline works in absolute paths internally and a tool never hands one to the model: a deployment keeps every account in its own directory, so an absolute path prints that directory, and the account with it, into an answer a person reads.

Tool registration follows the configuration: documents.enabled: false (or a resolved enabled: false from the environment) leaves them unregistered rather than inert, and documents.comparison.enabled: false does the same for the comparison pair. Visibility to a chat is the deployment's decision, not the plugin's:

# profile settings of a deployment that wants the tools in a chat
lockdown:
  toolPolicy:
    allow:
      - document_create
      - document_to_markdown
      - document_from_url
      - document_convert
      - document_inspect

Every name must exist in the session's tool catalog, so the plugin must be installed and enabled wherever the allow-list mentions it.

Comparing two revisions

document_inspect        what the two files are
document_compare        what changed — computed here, not by the model
document_diff_read      every change, paged and filtered

document_compare reads both sides itself: DOCX (through its own OOXML reader, no converter in between), Markdown and plain text natively, and PDF through the deployment's extraction backend. It answers with a comparisonId, the change summary, the extraction quality and a short preview; the artifact holds the rest:

.qa/artifacts/documents/cmp_01J…/
├── manifest.json       kind: document-comparison, both hashes, engine, options, quality
├── inputs/left.docx    the bytes that were compared
├── normalized/*.json   the canonical IR of each side
└── diff/
    ├── changes.jsonl   one change per line
    ├── summary.json
    └── report.md       the model-free human report

Every change carries a stable id, a location, the exact text before and after, and the deterministic signals the text supports — a changed number, amount, percentage, date, duration, negation, party, or obligation/permission/prohibition vocabulary. The plugin reports facts; risk is the model's business, and the contract-review skill (shipped with the package) states the rule: semantic analysis must rest on document_compare results, and a difference without a changeId does not exist.

A contract-review chat needs no shell and no Markdown extraction — three tools are enough:

lockdown:
  toolPolicy:
    allow:
      - document_inspect
      - document_compare
      - document_diff_read

Refusals carry codes instead of degrading: COMPARE_UNSUPPORTED_FORMAT, COMPARE_PARSE_FAILED, COMPARE_ENCRYPTED_DOCUMENT, COMPARE_INPUT_TOO_LARGE, COMPARE_TOO_MANY_NODES, COMPARE_TIMEOUT, COMPARE_DIFF_LIMIT_EXCEEDED, COMPARE_LOW_EXTRACTION_QUALITY, COMPARE_ARTIFACT_NOT_FOUND. There is no fallback to a shell and no request that the model compare the documents itself.

Configuration

The namespace is documents, edited in the plugin's own card — the configuration of this plugin's row on the host Plugins page — or declaratively:

- id: documents
  name: '@yadsh/dsh-documents'
  config:
    enabled: true
    storage:
      root: null            # null = <session workspace>/.qa/artifacts/documents
      retainSource: true
      retainInputs: true
    extraction:
      defaultMode: accurate # auto | fast | accurate
      ocr: auto             # auto | off | force
      extractImages: true
      maxInlineChars: 200000
    docling:
      enabled: true
      baseUrl: http://docling:5001
    pandoc:
      executable: pandoc
    libreoffice:
      executable: libreoffice
    retention:
      enabled: true
      maxAgeDays: 30
    limits:
      maxInputBytes: 52428800
      maxPages: 1000
    comparison:
      enabled: true
      defaultMode: contract    # contract | default
      detectMoves: true
      includeHeaders: true
      includeFooters: true
      includeFootnotes: true
      ignoreWhitespace: true
      ignoreFormatting: true
      maxNodes: 100000
      maxChanges: 50000
      timeoutMs: 120000
      inlineChanges: 20

What the defaults assume:

• pandoc and a headless libreoffice exist in the deployment image. A missing executable is answered at boot by the documents.installed record, which names every program the check covered and repeats the absent ones as a documents.programs.missing warning; in a call it surfaces as BACKEND_UNAVAILABLE, never worked around;
• docling is reachable at http://docling:5001 — the default of the docling-serve container — and is the backend that reads PDF and DOCX into Markdown. docling.enabled: false turns that path off;
• typst and markitdown are disabled. Requesting pdfMode: typst without typst.enabled is refused instead of silently rendering another layout; markitdown is the optional fast fallback when Docling is unavailable. This adapter extracts embedded text; it does not advertise OCR and refuses forced OCR. Scanned documents need a separately provisioned OCR backend.

Artifacts and sizes

Each operation writes a bundle under <session workspace>/.qa/artifacts/documents/<id> containing manifest.json, the Markdown source, the assets and the produced files. storage.root pins one absolute root instead (a mounted volume); retention cleanup runs only in that layout, because with per-session directories the plugin cannot enumerate other sessions' workspaces.

The limits are configuration, not constants: limits.maxInputBytes (input file), limits.maxMarkdownChars (Markdown the pipeline will hold), limits.maxPages, limits.maxExtractedImages, limits.maxAssetBytes, and extraction.maxInlineChars (how much extracted Markdown is returned to the model — the artifact always keeps the whole text).

document_from_url opens no socket of its own: it asks the deployment's web provider for the URL, so the fetch rules, credentials, address policy and byte/char caps configured there decide what may be read (in practice @yadsh/dsh-web-fetch-authenticated, including its Confluence attachment support). Without a web provider the tool answers BACKEND_UNAVAILABLE instead of guessing.

The pipeline writes its bundles with its own file-system calls, so a read-only sandbox does not stop a document from being created. The allow-list is the switch that decides whether a chat can write documents at all, and storage.root decides where they land.

Environment overrides

Environment wins over the settings namespace at startup, which is how a container pins a shared volume or a service address without editing settings:

| Variable | Effect | | --- | --- | | DSH_DOCUMENTS_ENABLED | enable/disable the pipeline | | DSH_DOCUMENTS_STORAGE_ROOT | absolute artifact root | | DSH_DOCUMENTS_TEMPLATES_ROOT | absolute template root | | DSH_DOCUMENTS_DOCLING_BASE_URL | docling-serve address | | DSH_DOCUMENTS_DOCLING_TIMEOUT_MS | Docling request timeout | | DSH_DOCUMENTS_PANDOC_EXECUTABLE | pandoc binary | | DSH_DOCUMENTS_LIBREOFFICE_EXECUTABLE | LibreOffice binary | | DSH_DOCUMENTS_MARKITDOWN_EXECUTABLE | markitdown binary | | DSH_DOCUMENTS_OCR_LANGUAGES | comma-separated OCR languages | | DSH_DOCUMENTS_MAX_INPUT_BYTES | input file cap |

The card shows what the browser wrote; the Host logs the values it resolved.

Migrating from dsh-qa-surface

The pipeline used to live inside the QA surface. The move changes configuration and nothing else:

• tool names and the artifact layout are unchanged, so allow-lists and existing artifacts keep working;
• the documents section moves from the qa-surface namespace to this plugin's documents namespace, and QA_DOCUMENTS_* / QA_DOCLING_* / QA_PANDOC_* / QA_LIBREOFFICE_* / QA_MARKITDOWN_* become the DSH_DOCUMENTS_* names above;
• a leftover documents: section under qa-surface is ignored, and the QA surface logs documents.moved once per configuration change so the leftover does not silently take the Docling endpoint with it;
• deployments that allow-list the tools must install this plugin, otherwise the names are missing from the session catalog and attestation fails closed.

Design

The pipeline's design — provider interfaces, extraction routes, artifact manifest, security and resource limits — is in docs/specs/document-pipeline.md, deterministic comparison in docs/specs/document-comparison.md, and the plugin surface itself in SPEC.md.

License

MIT