@apollo-music/dsh-file-reader

DeepSeek Harness bundle for session-scoped, source-neutral document reading and analysis. It always exposes six reader tools: file_reader_open, file_reader_outline, file_reader_read, file_reader_search, file_reader_render, and file_reader_close. When both ctx.fileAnalysisStore and the DSH subagent/agent services are available, it also exposes file_reader_analyze and file_reader_analysis_history.

The model never receives host paths, parser paths, content hashes, or parser filenames. Handles are 256-bit random values bound to a DSH session and reader instance. Workspace files are realpath-checked and copied through a no-follow descriptor into a private 0700 session directory; staged files use 0600 permissions. Trusted plugins may instead supply a bounded private ReadableStream with provenance.

Runtime

The TypeScript bundle requires Node 24 and targets DeepSeek Harness 0.1.1-rc.2; its DSH packages are declared as exact peer dependencies and must be upgraded together. Cordis remains pinned to 4.0.1. Its bundled parser requires Python 3.11–3.13 and the exact versions in parser/requirements.lock.

The plugin launches its bundled parser directly with Python isolated mode, a minimal environment, bounded stdout/stderr, per-operation deadlines, cancellation, and process-group cleanup. The parser receives only the private staged document path and bounded operation input. No Docker socket, OCI image, registry, runner service, or external parser configuration is required.

Install the bundle into a DSH profile:

dsh plugin --profile <profile> add @apollo-music/[email protected]

Static configuration only needs to declare whether the active model route accepts image input:

- name: @apollo-music/dsh-file-reader
  config:
    imageInputSupported: true

imageInputSupported must reflect the selected model route. On a text-only route, render fails with document_capability_unavailable and text reading remains available.

Legacy .doc, .xls, and .ppt inputs are converted privately to DOCX, XLSX, and PPTX with LibreOffice, then use the same bounded read/search/render path as native OOXML files. The converted artifact is scoped to the document handle, validated before parsing, reused by later operations, and removed with the handle or session. If LibreOffice is absent, opening a legacy file returns document_capability_unavailable; native PDF, DOCX, XLSX/XLSM, and PPTX text operations remain available. Compatible Word/PowerPoint rendering also requires LibreOffice.

LibreOffice must provide soffice or libreoffice on the DSH process PATH. Roll back by disabling or restoring the previous plugin version; Cordis disposal terminates active parser processes and removes staged and converted files.

Development

npm run build --workspace @apollo-music/dsh-file-reader
npm test --workspace @apollo-music/dsh-file-reader
npm run test:parser --workspace @apollo-music/dsh-file-reader
npm run test:package --workspace @apollo-music/dsh-file-reader

Analysis history provider

The package exports FileAnalysisStoreService, HttpFileAnalysisStore, and SqliteFileAnalysisStore. Production profiles resolve separate read/write/link credentials through FileAnalysisCredentialProvider and register the HTTP-backed service as ctx.fileAnalysisStore; DSH processes never receive a PostgreSQL connection. HTTP responses are bounded, redirects fail closed, credentials stay in headers, and provider/network errors are mapped to stable path-free errors.

SqliteFileAnalysisStore is only for local development and protocol tests. It refuses production mode and is never an automatic fallback when the PostgreSQL-backed API is absent or unhealthy.

Run creation defaults to cachePolicy: "prefer-cache". The returned disposition distinguishes a new reservation, a coalesced concurrent request, an exact cache hit, and an expired lease that requires terminal reconciliation. refresh and fresh always reserve independent runs; an expired run must be completed or failed from the child terminal fact before a replacement is created.

file_reader_analyze sends the caller's analysis input unchanged to a dedicated continuable DSH child. The child receives only a newly delegated document handle and the five non-open reader operations; the original caller handle is never shared. Trusted runtime context and bounded authorized history are injected separately from the user prompt. DEFAULT is the sole built-in analysis name and must be passed exactly; all other nonblank inputs are custom instructions.

prefer-cache reuses an exact completed result, refresh creates a new persisted result while allowing compatible history and child continuation, and fresh creates a history-free, non-continuing run. The service records the run before starting the child, binds the child session as soon as it is accepted, and records a completed or failed terminal state. file_reader_analysis_history is scoped to an already authorized document handle; previous revisions and explicitly linked sources are opt-in.