dsh-upload-plugin

dsh-upload-plugin

A DeepSeek Harness plugin that attaches photos and files from the chat composer.

Photos reach the model as real image content. Files reach it through a Context injection block. Your own message text stays yours — nothing is pasted into your draft, and no instruction is spliced into what you send.

---

Why this exists

A model can only read what it is given. Out of the box, the DSH composer has no attach affordance, and the obvious workaround — write the file's path into your message and ask the model to go read it — has three failure points and pollutes your own text.

This plugin adds the affordance, and picks the shortest correct route for each kind of attachment:

That asymmetry is deliberate. DSH's content-block vocabulary is text, reasoning, image, tool-call, tool-result — there is no file block — so a document cannot be handed over the way an image can, and needs the instruction path instead.

---

Features

Attaching

• 📷 Add photo (/photos) — pick one or many images (.png, .jpg, .jpeg, .webp, .gif). They are admitted as native draft images, so the model receives the image itself. Nothing is typed into your composer.
• 📄 Add file (/files) — pick one or many documents (.txt, .pdf, .json, .csv, source code, archives…). They are uploaded to the workspace and a reference chip is minted into your draft.
• 📂 Uploaded files (/uploads) — browse everything uploaded in this session and re-reference it with one click.
• Both [📷] and [📄] also sit directly on the composer toolbar, left of the model button, so you never have to open the + menu.
• The /photos command and the [📷] button run the same code path, so the two entry points cannot drift apart.

The attachment rail

• The rail draws exactly the files your live draft references, so it empties itself once you send. There is no separate plugin-side list to get out of sync.
• Removing an attachment with ✕ deletes only that chip. Text you have already typed is preserved.
• Photos do not appear on this rail — they are DSH's own native draft images, rendered and removed by the composer itself.

Injection: one shot per send

• The read instruction travels as a Context injection row, the same way DSH injects its own context — it is not part of your message.
• One shot per send. The live attachment set is handed to the host and consumed when the next turn starts, so the message after a send carries no instruction unless you attach again. There is no pending queue.
• A file-only message also carries one invisible zero-width character. That is not decoration: DSH silently refuses to send a message with no text and no images, and the chip's serialization is what keeps an attach-then-send alive.

Model + reasoning effort

• The composer keeps DSH's own model selector — this plugin does not take that seat over.
• An effort button sits to its left, offering the levels the model declares on the Host plus a Custom… row.
• Custom… adds a level. Pick one the menu does not list and the plugin writes it into that model's reasoningEfforts declaration — the same settings document the Models page owns — and then selects it. Adding a level by hand and adding it through Custom… are the same act.
• A model that declares nothing gets its first declaration from the menu. When the Host reports no levels for the active model and its row has no reasoningEfforts, the button offers the thinking levels; picking one writes { "off": null, "<level>": "<level>" } into the row and then selects it. That is the only case where a declaration can be written without restating anything — the Host reported no vocabulary for that model, so no catalog spelling is in play.
• A value outside the Host's vocabulary is refused in the menu, immediately, naming the levels that are allowed — rather than being accepted and then rejected later.
• The list is built from the Host's own vocabulary, so it can never offer a level the Host would reject. A model whose levels come from the installed catalog reports them, so it never takes the first-declaration path and its wire spellings are never touched — see Declaring reasoning levels.

Vision declarations

• Settings → Vision gives you one checkbox per model, grouped by provider, writing input: ["text", "image"] into that model's row. Turning one off removes the input key.
• The page writes into the same settings document the Models page owns, addressed at exactly providers.<id>.models, so every other field of the row and the provider survives — including fields this plugin knows nothing about.
• It reads the document back immediately before writing and sends an expectedRevision, so a concurrent edit is refused ("the configuration just changed elsewhere") rather than overwritten.
• It subscribes to settings/document-updated for its namespace, so it stays fresh when another surface changes the document.
• This is a declaration, not a probe. The page states that a model is declared able to read images; it never checks whether the upstream actually serves them.

---

Requirements

• DeepSeek Harness with the web profile.
• Node.js and pnpm for a source install.

---

Installation

From GitHub (recommended)

dsh plugin --profile web add github:danhcng3822f/dsh-upload-plugin

or with pnpm directly:

pnpm --prefix ~/.dsh/profiles/web add github:danhcng3822f/dsh-upload-plugin

DSH registers the plugin into the web profile for you — no hand-editing configuration files. Restart DSH or reload http://127.0.0.1:3080.

From a local checkout (development)

git clone https://github.com/danhcng3822f/dsh-upload-plugin.git
cd dsh-upload-plugin
pnpm install
pnpm run build
pnpm --prefix ~/.dsh/profiles/web add link:/path/to/dsh-upload-plugin

---

Configuration

Enabling vision for a model

For a model from a custom provider to be able to read images, its row needs the image modality:

{
  "id": "claude-opus-5-thinking",
  "name": "Claude Opus 5 Thinking",
  "input": ["text", "image"]
}

You can write that by hand, or use Settings → Vision in the UI.

A model that does not declare vision still accepts an attached photo — the plugin only warns. Because the photo now travels as real image content, the provider refuses that turn outright rather than the model quietly ignoring an instruction.

Declaring reasoning levels

A model declared by hand in your settings carries no reasoning metadata until you declare it, and the Host reports none — which is why the effort button can be absent on a model that plainly reasons.

The first declaration is made for you. When the Host reports no levels for the active model and the model's row has no reasoningEfforts, the effort button appears and offers the thinking levels. Picking one writes this into the row and then selects the level:

{
  "id": "your-model",
  "name": "Your Model",
  "input": ["text", "image"],
  "reasoningEfforts": { "off": null, "high": "high" }
}

Only the level you picked and off are declared. A level you did not ask for may not exist on the provider, and offering it is the failure this design avoids; off is the one companion that is always safe. Custom… extends the set afterwards, exactly as it extends a declaration you wrote by hand.

You can still write the whole declaration yourself:

• Each key is a level the menu offers; each value is the wire spelling sent to the provider.
• off may be null, meaning supported, send no parameter — for most providers not thinking is the parameter's absence.
• The levels the Host recognises are off, minimal, low, medium, high, xhigh, max. A level you leave out is simply not offered — Custom… can add one of them for you, using the level name as its wire spelling.
• off is not offered as a first declaration. A declaration that names only off is refused by the provider configuration — a model needs at least one level beyond it — so the menu offers the six thinking levels instead. Pick one, and off becomes an ordinary row of the menu, because the declaration now contains it.
• A model whose levels come from the installed catalog reports them, so its menu works from the start and nothing here rewrites its spellings.
• A model the Host reports no levels for whose row already declares something is left exactly as it is — including reasoningEfforts: false, which declares that the model does not reason.

---

Troubleshooting

The effort button does not appear. The button needs two facts, and it appears only when both hold: the Host reports no levels for the model, and the model's row declares no reasoningEfforts. If the row declares something — including reasoningEfforts: false, "this model does not reason" — nothing is offered, deliberately. If neither holds and you still see no button, the settings document could not be read, or the route serving the model has no row for it; check that the document is readable and that the model is declared under its provider.

Custom… refuses the level I typed. The Host recognises exactly seven level names — off, minimal, low, medium, high, xhigh, max — and the declaration's keys are validated against them, so a token budget or a provider-specific name cannot be used at all. If the menu names a different reason, the model's levels come from the installed catalog: its wire spellings are the catalog's and not the level names, so declare the model's real levels in Settings first and Custom… can extend them afterwards.

I set an effort and the turn failed with "does not support reasoning effort". The level was not in the model's declaration. This is the failure Custom… exists to prevent — it now declares a missing level before selecting it — so if you still see it, the declaration write did not land; check that the settings document is writable.

The model does not seem to see an attached photo. Check that the model's row declares input: ["text", "image"]. Then confirm the provider actually serves image content: this plugin states a declaration, it cannot probe the upstream for you.

A message with only a file attached does nothing when I press Enter. DSH refuses a message with no text and no images. The plugin keeps a zero-width character on the chip so this does not happen; if you have removed the chip by hand, type something or re-attach.

The instruction row appears on a message that has no attachment. It should not. The attachment set is consumed when a turn starts; if you see this, the client's sync and the host's consumption have gone out of step — please open an issue with what you did.

---

Development

pnpm install     # install dependencies
pnpm test        # Vitest — 167 unit tests over the pure logic
pnpm run build   # tsc for the host half, esbuild for the browser bundle

The suite runs in a plain node environment with no DOM, so it covers the pure logic — record arithmetic, the admission planner, the effort menu, the settings read-modify-write, the injection handler — while the rendered components are exercised by hand in a running harness.

---

Project structure

dsh-upload-plugin/
├── src/
│   ├── types.ts                   # Shared API and data types
│   ├── instruction.ts             # The read instruction — ONE definition, shared by host and client
│   ├── index.ts                   # Host entry (Cordis plugin, web server endpoints, context injection)
│   ├── host/
│   │   ├── endpoints.ts           # Vision check, upload, list, view and ref sync
│   │   ├── file-utils.ts          # File identity and unique path resolution
│   │   ├── refs-store.ts          # Live attachment set per session (host-held, client-pushed)
│   │   ├── context-injection.ts   # Injects the instruction into the next turn via `agent/pre-step`
│   │   └── llm-modules.d.ts       # Harness contracts the host half consumes
│   └── client/
│       ├── index.ts               # Client entry (loaded into the browser)
│       ├── commands.ts            # /photos, /files and /uploads registrations
│       ├── attachment-bar.ts      # The composer rail and the lightbox viewer
│       ├── attachments.ts         # Attachment records and pure list operations
│       ├── attachment-store.ts    # Per-session record store (localStorage)
│       ├── reference.ts           # The `vision` reference source and chip minting
│       ├── ref-sync.ts            # Pushes the live attachment set to the host as the draft changes
│       ├── intake.ts              # Native image admission, shared by 📷 and /photos
│       ├── effort.ts              # Builds the effort menu from the Host's metadata
│       ├── vision-setting.ts      # Read-modify-write of one model row's `input` field
│       ├── platform-modules.d.ts  # Types for platform modules that cannot be installed from npm
│       ├── composer/
│       │   ├── attach-buttons.tsx # The 📷 and 📄 toolbar buttons
│       │   ├── effort-control.tsx # The effort button, left of the model button
│       │   └── icons.tsx          # This plugin's own glyphs
│       ├── settings/
│       │   └── vision-section.tsx # The Settings → Vision page
│       └── uploader.ts            # File picker and upload
├── lib/
│   ├── index.js                   # Compiled host bundle
│   └── client.js                  # Compiled browser bundle
├── tests/                         # Vitest unit tests
├── cordis.patch.yml               # Cordis dependency-injection configuration
├── LICENSE                        # MIT
└── package.json

---

License

Released under the MIT License.